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

package/templates/Dockerfile.tmpl

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

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

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

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

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

package/templates/new/.claude/commands/publish.md

@@ -0,0 +1,226 @@
+---
+description: Prepare {{PACKAGE_NAME}} for npm publish — bump version, finalize CHANGELOG/README, build, test, commit
+argument-hint: rc|release|patch|minor|major
+---
+
+# /publish — prepare an npm release of {{PACKAGE_NAME}}
+
+You are preparing this package for `npm publish`. **Do not run `npm publish`** — the user logs in and publishes manually.
+
+This command follows the canonical `/publish` structure defined in the BlissFramework component guidelines at
+`web-components/publish-command.md`. Sections marked **[canonical]** are byte-identical across every
+component's `/publish`; sections marked **[per-repo]** are customized for this repo's layout, build, and tests.
+
+## Argument [canonical]
+
+The release type: **$ARGUMENTS**
+
+Must be one of:
+
+- `rc` — ship the WIP rc as-is. The topmost CHANGELOG heading (e.g. `## [1.10.0-rc02] - 2026-06-18`) gets ` [PUBLISHED]` appended.
+- `release` — promote a WIP rc to a final release. `X.Y.Z-rcN` → `X.Y.Z`. CHANGELOG heading is renamed to match the new version.
+- `patch` — SemVer patch bump. Drops any `-rc` suffix.
+- `minor` — SemVer minor bump. Drops `-rc`. Resets patch.
+- `major` — SemVer major bump. Drops `-rc`. Resets minor and patch.
+
+If missing or invalid, stop and ask the user which one to use (don't guess).
+
+## Repo layout [per-repo]
+
+Single-package repo, everything at root:
+
+- **`./package.json`** — `version` field is the source of truth.
+- **`./CHANGELOG.md`** — at the root. Topmost `## [X.Y.Z] - YYYY-MM-DD` heading **without** the `[PUBLISHED]` marker is the WIP section.
+- **`./README.md`** — at the root. Carries `## What's New in vX.Y.Z` sections near the top (one per release, the **two most recent** retained).
+- **`./dist/`** — gitignored. Produced by `npm run build` (custom-elements-manifest analyze + Vite). Never staged.
+- **`./custom-elements.json`, `./web-types.json`, `./vscode.html-custom-data.json`, `./vscode.css-custom-data.json`** — generated by `npm run analyze` (part of the build) and **committed** (custom-elements-manifest D-CEM-2 = A).
+- **`./component-variables.manifest.json`** — published with the package. Edit if the variable surface changes; `npm run check:vars` validates it.
+- **`./docs/`** — usage / theming / examples / accessibility, published with the package.
+
+## CHANGELOG convention in this repo [canonical]
+
+There is **no `## [Unreleased]` section**. The WIP section is the topmost `## [X.Y.Z] - YYYY-MM-DD` heading without a `[PUBLISHED]` tag. Already-released sections carry `[PUBLISHED]` at the end of their heading:
+
+```
+## [1.10.0-rc02] - 2026-06-18                  ← WIP, the one you're shipping
+### Added
+- ...
+
+## [1.9.0] - 2026-06-09 [PUBLISHED]
+### Added
+- ...
+```
+
+Publishing the WIP section means **appending ` [PUBLISHED]`** to its heading — exact format: `## [X.Y.Z] - YYYY-MM-DD [PUBLISHED]`. The next development cycle creates a fresh `## [next-version] - <date>` heading on its first CHANGELOG edit.
+
+## Resolve versions [canonical]
+
+Read `./package.json` `version` as `CURRENT_VERSION`.
+Read the topmost `## [X.Y.Z...]` heading from `./CHANGELOG.md` as `WIP_VERSION` (the version the latest WIP section is tagged for).
+
+Compute `NEW_VERSION`:
+
+| Argument | Logic |
+|---|---|
+| `rc` | If `CURRENT_VERSION` matches `X.Y.Z-rcN`, `NEW_VERSION = CURRENT_VERSION` (no bump — we're shipping what's already in package.json). If `CURRENT_VERSION` is not an rc, stop and ask the user (they probably wanted `release`/`patch`/etc.). |
+| `release` | If `CURRENT_VERSION` matches `X.Y.Z-rcN`, `NEW_VERSION = X.Y.Z`. Otherwise stop. |
+| `patch` | Strip any `-rcN`, then bump patch. |
+| `minor` | Strip any `-rcN`, then bump minor, reset patch. |
+| `major` | Strip any `-rcN`, then bump major, reset minor and patch. |
+
+If `WIP_VERSION` ≠ `NEW_VERSION` (e.g. the WIP is `X.Y.Z-rcN` but the user asked for `release`), the CHANGELOG heading rename in step 3 also re-tags the section to `NEW_VERSION` — call this out in the report so the user notices.
+
+## Steps (in order)
+
+### 1. Sanity checks [canonical]
+
+- Run `git status`. The repo intentionally keeps `.claude/`, `test-results/`, `playwright-report/` and `dist-examples/` untracked — those are fine. If there are **other** uncommitted changes that aren't `CHANGELOG.md`, `README.md`, or `package.json`, list them and ask the user before continuing. (Typical case: substantive source changes belonging in this release that haven't been committed yet — confirm they're intended for this version before bumping.)
+- **Verify the new version isn't already on npm.** Run `npm view {{PACKAGE_NAME}}@<NEW_VERSION> version 2>/dev/null` — if it returns the version string, that version is already published and **stop**: bumping over it would fail at publish time and pollute the commit.
+- **Verify the registry hasn't drifted past you.** Run `npm view {{PACKAGE_NAME}} version` to fetch the latest published version on the `latest` tag; if it's higher than `NEW_VERSION` (e.g. someone shipped from another machine, or there's a registry-vs-local mismatch from before the [PUBLISHED] convention landed), warn the user and ask before continuing.
+- Confirm the WIP CHANGELOG section has at least one bullet of substantive content under `### Added`, `### Changed`, `### Removed`, `### Fixed`, or `### Internal`. If empty, stop — there's nothing meaningful to release.
+- Confirm `./README.md` has a `## What's New in vWIP_VERSION` section. If it's missing, draft one from the CHANGELOG and present it to the user for approval before continuing:
+  - Read the WIP CHANGELOG section, distill it to 5–8 scannable bullets covering the Added/Changed themes (paraphrase, don't copy CHANGELOG bullets verbatim — those are exhaustive; What's New is the highlight reel). Pure internal refactors and Fixed-only entries don't need coverage, though headline bug fixes worth advertising are worth a bullet.
+  - **Follow the canonical "What's New" format** defined in the BlissFramework component guidelines (`web-components/readme-structure.md` → "`## What's New in vX.Y.Z` — canonical format"). Auto-check **C-RS-16** in `readme-structure.checks.sh` enforces it. Concretely:
+    - **Heading:** `## What's New in vNEW_VERSION` — lowercase `v`, no backticks around the version, no date.
+    - **Each bullet:** `- **<area or component> — <one-line headline>** — <engineer-level prose, 3–8 sentences>`. Bold-wrapped lead phrase, then a true em-dash (` — `, U+2014 with surrounding spaces), then a prose body explaining *what changed*, *why* (regression history / motivation), *what surface is affected* (concrete component / prop / file names listed inline), and *the mechanism* (the technique used). Plain hyphens or en-dashes fail the check.
+    - **No `### ` sub-headings** inside a What's New section — no `### Added` / `### Fixed` lifted from the CHANGELOG. It's a flat bullet list.
+    - **Reference implementation:** the `## What's New in v1.3.3` / `v1.3.2` sections at the top of `svelte-fluentui/README.md` are the canonical shape — mirror that voice and structure.
+  - Show the user the proposed draft as plain markdown in your reply. Ask whether to (a) insert as-is, (b) edit, or (c) abort so they can write it themselves.
+  - Only proceed past step 1 once the user approves the draft (or supplies their own). On approval, insert the section directly above the current top `## What's New in vX.Y.Z` heading in `./README.md`, then continue.
+  - Do not silently insert the draft without confirmation — release highlights are a writing call and the user owns the voice.
+
+### 2. Bump version (if needed) [canonical]
+
+If `NEW_VERSION` ≠ `CURRENT_VERSION`, edit `./package.json` and change `"version": "CURRENT_VERSION"` to `"version": "NEW_VERSION"`.
+
+For `rc` arg this is normally a no-op — version was bumped earlier in the development cycle.
+
+### 3. Finalize CHANGELOG [canonical]
+
+In `./CHANGELOG.md`:
+
+- If `WIP_VERSION` ≠ `NEW_VERSION` (e.g. promoting `X.Y.Z-rcN` → `X.Y.Z`), rename the WIP heading from `## [WIP_VERSION] - <date>` to `## [NEW_VERSION] - <today>` (today's date from system context).
+- If `WIP_VERSION` == `NEW_VERSION`, leave the bracketed version alone but update the date to today **if** the existing date is stale (more than a few days old). The WIP date is usually whatever day the section was opened; refresh it so the changelog reflects the actual ship date.
+- In either case, **append ` [PUBLISHED]`** to the heading so it reads exactly: `## [NEW_VERSION] - YYYY-MM-DD [PUBLISHED]`.
+- Leave all bullet content untouched.
+- **Do not** create an empty new WIP section — the next dev cycle's first CHANGELOG edit will create one.
+
+### 4. Update README "What's New" — only if version changed [canonical]
+
+In `./README.md`:
+
+- If the existing `## What's New in vWIP_VERSION` section's version differs from `NEW_VERSION` (e.g. promoting `X.Y.Z-rcN` → `X.Y.Z`), rename its heading to `## What's New in vNEW_VERSION`. (No content rewrites — the text was already curated for this release.)
+- Then count the `## What's New in vX.Y.Z` headings. If there are more than **two**, delete the oldest ones so only the **two most recent** remain (the just-finalized one plus the one before it).
+
+For `rc` arg this is normally a no-op on the heading itself — only trims if someone left an extra-old section behind.
+
+### 5. Validate README reflects the release [canonical]
+
+Read both the finalized CHANGELOG section and the matching `What's New in vNEW_VERSION` section. Every **Added** or **Changed** bullet in the CHANGELOG that represents a user-facing feature or behavior change should have a corresponding hit in the What's New section (paraphrased, not verbatim). Pure internal refactors and `Fixed`-only entries don't need coverage, though headline bug fixes worth advertising (e.g. "X used to silently fail; now works") are worth a bullet.
+
+If you find a significant CHANGELOG entry that isn't reflected in What's New, add a bullet for it. If the section ends up with more than ~8 bullets after this pass, condense — What's New should be scannable, not exhaustive.
+
+### 6. Validate CHANGELOG entries match recent work [canonical]
+
+Find the previous `[PUBLISHED]` tag in CHANGELOG (the version just before NEW_VERSION) and locate the commit that bumped to it — usually a commit whose subject starts with `v<previous-version>` or `- v<previous-version>`. Run `git log --oneline <previous-publish-commit>..HEAD` to list commits since.
+
+Also check `git diff` (or `git status`) for any uncommitted source/test work outside the files you're editing in this command.
+
+For every substantive commit or uncommitted change, verify the WIP CHANGELOG section mentions it. If something significant is missing, **stop and ask the user** before finalizing — don't invent entries on their behalf. Pure example/doc tweaks and trivial typo fixes don't need entries.
+
+### 7. Run tests [per-repo]
+
+Run `npm run test:e2e` (or equivalently `make test-e2e`). e2e tests via Playwright. All specs must pass.
+
+If anything fails, **stop and report**. Do not proceed to build/commit. The user fixes the regression (or decides to fixme the spec) before the publish flow can continue.
+
+If Playwright complains that chromium isn't installed, suggest `make test-e2e-install` and stop.
+
+### 8. Build the package [per-repo]
+
+Run `npm run build` (or `make build`). This:
+- Runs `npm run analyze` — regenerates `custom-elements.json`, `web-types.json` and the VS Code custom-data files.
+- Runs Vite to emit `dist/{{FILE_NAME}}.js`, `dist/{{FILE_NAME}}.umd.js`, `dist/style.css`, and the type declarations.
+
+If the build errors, stop and report.
+
+After build, do a quick smoke check on the emitted artifacts:
+- `dist/{{FILE_NAME}}.js` and `dist/{{FILE_NAME}}.umd.js` both exist and are non-empty.
+- `dist/style.css` exists.
+- `dist/index.d.ts` (or whatever the `types` field points to) exists.
+- `git status` shows the regenerated CEM files only if the element API changed — stage them in step 10 if so.
+
+### 9. Verify the package contents [per-repo]
+
+Run `npm pack --dry-run` and confirm the file list includes:
+
+- `dist/` (built JS + d.ts files + style.css)
+- `custom-elements.json`, `web-types.json`, `vscode.html-custom-data.json`, `vscode.css-custom-data.json`
+- `component-variables.manifest.json`
+- `docs/`
+- `README.md`
+- `LICENSE`
+- `package.json`
+
+If anything user-facing is missing or anything private leaked in (e.g. `test/`, `e2e/`, `examples-*.html`, `*.spec.ts`, `tsconfig.json`, `vite.config.ts`), stop and report — the `files` field in `package.json` controls this and the leak needs fixing before publish.
+
+### 10. Commit [canonical]
+
+Stage:
+
+- `./CHANGELOG.md`
+- `./README.md`
+- `./package.json`
+- `./custom-elements.json`, `./web-types.json`, `./vscode.html-custom-data.json`, `./vscode.css-custom-data.json` (if the build regenerated them)
+
+Do **not** stage `dist/` — it's gitignored.
+
+Commit message format:
+
+```
+vNEW_VERSION - <one-line summary of the headline change>
+
+<grouped bullets paraphrased from the CHANGELOG section — split into the same
+groups the CHANGELOG used: Added, Fixed, Changed, Internal, etc. Keep bullets
+terse; full prose lives in the CHANGELOG.>
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+```
+
+### 11. Report [canonical]
+
+Report back with:
+
+- The new version number
+- The commit SHA
+- The exact commands to publish. **Pick the right one for the arg type:**
+  - For `rc` (publishing a pre-release):
+    ```
+    npm login          # if not already logged in
+    npm publish --tag rc
+    ```
+    The `--tag rc` is critical — without it npm assigns the `latest` dist-tag, which would make the pre-release the default install for everyone running `npm install {{PACKAGE_NAME}}`. With `--tag rc`, the `latest` tag stays put and consumers opt in via `@rc` or pinning the exact version.
+  - For `release` / `patch` / `minor` / `major` (publishing a stable release):
+    ```
+    npm login          # if not already logged in
+    npm publish
+    ```
+    Or `make publish`. No `--tag` needed — it correctly lands as `latest`.
+- A reminder that the CHANGELOG `[PUBLISHED]` tag is now in place — if `npm publish` fails, the user should revert both the tag (CHANGELOG heading) and the version bump (`package.json`) before retrying, since the registry will refuse to re-publish the same version.
+
+## Things not to do [canonical]
+
+- **Do not run `npm publish`.** The user publishes manually after `npm login`.
+- **Do not push to git remote.** The commit stays local until the user pushes.
+- **Do not create an empty `[Unreleased]` or new WIP heading** in CHANGELOG after finalizing — the next dev cycle's first edit creates the next heading.
+- **Do not retro-fix older CHANGELOG sections** that are missing the `[PUBLISHED]` tag or carry legacy markers — only finalize the section you're shipping.
+- **Do not silently insert a drafted What's New section.** If you draft one in Step 1 because it's missing, you must present it and wait for explicit approval (or edits) before inserting — the writing voice is the user's call, even when you're handing them a starting point.
+- **Do not keep more than two `## What's New in vX.Y.Z` sections in the README.** Step 4 trims older ones; if you see three or more after Step 4, you missed one.
+- **Do not skip the build step** — without it `dist/` is stale and the publish would ship outdated artifacts (or fail entirely if `dist/` was wiped by `make clean`).
+- **Do not skip the test gate** if the repo has one — the gate is what catches regressions before they ship.
+- **Do not invent CHANGELOG entries** to cover commits you find; ask the user if something's missing.
+- **Do not bump if there's nothing meaningful in the WIP section** — stop and explain.
+
+### Repo-specific don'ts
+
+- **Do not stage `test/`, `e2e/`, `test-results/`, `playwright-report/` or `dist-examples/`** — they're either ignored or test artifacts.

package/templates/new/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [{{VERSION}}] - {{TODAY}}
+
+### Added
+
+- Initial scaffold (`kmwc new`, `@keenmate/web-components-devkit`): `<{{TAG}}>` element (`{{ELEMENT_CLASS}}`) over the `{{LOGIC_CLASS}}` logic class, `label` / `active` inputs, `change` event with the `onChange` property twin.
+- Canonical CSS set (`src/css/`, prefix `{{PREFIX}}`) with `@layer variables, component, overrides`, `--base-*` fallback chains and Strategy-B dark mode.
+- Custom Elements Manifest (`custom-elements.json`, `web-types.json`, VS Code custom data) and `component-variables.manifest.json`.
+
+### Internal
+
+- Intake: technology web-component · package `{{PACKAGE_NAME}}` · tag `<{{TAG}}>` · CSS prefix `{{PREFIX}}` (reserve it in BlissFramework `guidelines/web-components/base-variables.md`) · dev port {{DEV_PORT}}.

package/templates/new/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{YEAR}} Keenmate s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/new/README.md

@@ -0,0 +1,71 @@
+# {{PACKAGE_NAME}}
+
+> {{TAGLINE}}
+
+## What is it
+
+`{{PACKAGE_NAME}}` is a custom element (`<{{TAG}}>`) built on
+[`@keenmate/web-components-core`](https://www.npmjs.com/package/@keenmate/web-components-core).
+It works in any HTML page or framework that can render a custom element —
+React, Vue, Svelte, Blazor, plain HTML.
+
+It reads `--base-*` variables from the page when `@keenmate/theme-designer`
+is present, falls back to sensible light/dark defaults otherwise, and supports
+per-instance dark mode via `data-theme`.
+
+## What's New in v{{VERSION}}
+
+- **`<{{TAG}}>` — initial release** — First version, scaffolded with `kmwc new` from `@keenmate/web-components-devkit`. Ships the Element / Logic / Side-layer split, the canonical eight-file CSS set with `@layer variables, component, overrides`, light/dark defaults through `light-dark()` fallbacks, a Custom Elements Manifest for editor tooling, and a `change` event with an `onChange` property twin. See [CHANGELOG.md](./CHANGELOG.md).
+
+## Demos & docs
+
+- 🚀 [Live demo](https://demos.keenmate.com/{{ID}})
+- 📘 [Usage / API reference](./docs/usage.md)
+- 🎨 [Theming contract](./docs/theming.md)
+- 📚 [Examples / cookbook](./docs/examples.md)
+- ♿ [Accessibility](./docs/accessibility.md)
+
+## Install
+
+```bash
+npm install {{PACKAGE_NAME}}
+```
+
+## Quick start
+
+```html
+<script type="module">
+  import '{{PACKAGE_NAME}}';
+</script>
+
+<{{TAG}} label="Hello"></{{TAG}}>
+```
+
+Clicking toggles the `active` state and dispatches a `change` event
+(`event.detail.isActive`). See [usage.md](./docs/usage.md) for the full API.
+
+## Browser support
+
+Modern evergreen browsers (Chrome, Edge, Firefox, Safari) — anything with
+native `customElements`, CSS `@layer` and `light-dark()` support. No polyfills
+shipped.
+
+## About
+
+Authored and maintained by [Keenmate s.r.o.](https://keenmate.com/).
+The component ships standalone with sensible light/dark defaults;
+when mounted inside [Pure Admin](https://pureadmin.io/) — or any
+host that publishes the `--base-*` taxonomy via
+[`@keenmate/theme-designer`](https://www.npmjs.com/package/@keenmate/theme-designer) — it adopts the host's colors,
+typography, and sizing automatically. There is no runtime
+dependency on Pure Admin; the integration is opt-in via CSS
+variables.
+
+## Built with BlissFramework
+
+Follows the [BlissFramework component guidelines](https://blissframework.dev/)
+for structure, theming, color-scheme, and accessibility.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/templates/new/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+dist-examples/
+test-results/
+playwright-report/
+*.tgz
+.makefile.env

package/templates/new/component-variables.manifest.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://raw.githubusercontent.com/keenmate/schemas/main/component-variables.schema.json",
+  "component": "{{PACKAGE_NAME}}",
+  "prefix": "{{PREFIX}}",
+  "baseVariables": [
+    { "name": "base-main-bg", "required": false, "usage": "Component surface" },
+    { "name": "base-text-color-1", "required": false, "usage": "Label text" },
+    { "name": "base-border-color", "required": false, "usage": "Button border" },
+    { "name": "base-accent-color", "required": false, "usage": "Active state fill, focus outline" },
+    { "name": "base-text-color-on-accent", "required": false, "usage": "Label text in the active state" },
+    { "name": "base-hover-bg", "required": false, "usage": "Hover background (falls back to a text/surface color-mix)" },
+    { "name": "base-font-family", "required": false, "usage": "Font family" },
+    { "name": "base-font-size-base", "required": false, "usage": "Font size (multiplier × --{{PREFIX}}-rem)" },
+    { "name": "base-border-radius-md", "required": false, "usage": "Corner radius (multiplier × --{{PREFIX}}-rem)" },
+    { "name": "base-input-size-md-height", "required": false, "usage": "Minimum height (multiplier × --{{PREFIX}}-rem)" }
+  ],
+  "componentVariables": [
+    { "name": "{{PREFIX}}-rem", "category": "spacing", "usage": "Base unit for every size (default 10px; 1rem follows the page font size)" },
+    { "name": "{{PREFIX}}-bg", "category": "surface", "usage": "Component surface" },
+    { "name": "{{PREFIX}}-text-color-1", "category": "text", "usage": "Label text" },
+    { "name": "{{PREFIX}}-border-color", "category": "border", "usage": "Button border" },
+    { "name": "{{PREFIX}}-accent-color", "category": "accent", "usage": "Active state fill, focus outline" },
+    { "name": "{{PREFIX}}-text-color-on-accent", "category": "text", "usage": "Label text in the active state" },
+    { "name": "{{PREFIX}}-hover-bg", "category": "state", "usage": "Hover background" },
+    { "name": "{{PREFIX}}-font-family", "category": "typography", "usage": "Font family" },
+    { "name": "{{PREFIX}}-font-size-base", "category": "typography", "usage": "Font size" },
+    { "name": "{{PREFIX}}-root-border-radius", "category": "radius", "usage": "Corner radius" },
+    { "name": "{{PREFIX}}-root-min-height", "category": "spacing", "usage": "Minimum height" },
+    { "name": "{{PREFIX}}-root-padding-block", "category": "spacing", "usage": "Vertical padding" },
+    { "name": "{{PREFIX}}-root-padding-inline", "category": "spacing", "usage": "Horizontal padding" }
+  ]
+}

package/templates/new/custom-elements-manifest.config.mjs

@@ -0,0 +1,23 @@
+import { blissAnalyzerConfig, cssVariablesFromManifestPlugin } from '@keenmate/web-components-core/cem';
+import { customElementVsCodePlugin } from 'custom-element-vs-code-integration';
+import { customElementJetBrainsPlugin } from 'custom-element-jet-brains-integration';
+
+/**
+ * Custom Elements Manifest (custom-elements-manifest.md). Core's
+ * blissAnalyzerConfig() reads the `static inputs` / `static events` tables
+ * (ATTRIBUTE_TABLE) straight from the AST, so attributes, properties and events
+ * in custom-elements.json come from the same table the runtime uses.
+ * cssVariablesFromManifestPlugin() adds the --{{PREFIX}}-* surface from
+ * component-variables.manifest.json; the editor plugins then emit
+ * vscode.html-custom-data.json / vscode.css-custom-data.json / web-types.json.
+ */
+export default blissAnalyzerConfig({
+  globs: ['src/**/*.ts'],
+  exclude: ['src/**/*.spec.ts', 'src/**/*.test.ts', 'src/**/*.d.ts', 'src/index.ts'],
+  outdir: '.',
+  plugins: [
+    cssVariablesFromManifestPlugin(),
+    customElementVsCodePlugin({ outdir: '.' }),
+    customElementJetBrainsPlugin({ outdir: '.', packageJson: false }),
+  ],
+});