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

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

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 +76 -0
package/LICENSE +21 -0
package/README.md +417 -2
package/components.json +189 -0
package/package.json +75 -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 +302 -0
package/src/cli/commands/readme.js +111 -0
package/src/cli/commands/sync.js +48 -0
package/src/cli/kmwc.js +72 -0
package/src/cli/sync-plan.js +163 -0
package/src/config.d.ts +147 -0
package/src/config.js +257 -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 +110 -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 +209 -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 +40 -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 +26 -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/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,76 @@
+# Changelog
+## [1.0.0-rc01] - 2026-10-12 [PUBLISHED]
+First release of `@keenmate/web-components-devkit`, plus the component catalogue.
+### Added
+- **Catalogue**: `components.json` registry (ids, CSS prefixes, port blocks, links);
+  the README tables (components, libraries, showcases/tests — with each repo's
+  dev port, no versions/status that would go stale) are generated by
+  `npm run readme`. Port blocks of 100 per repo (dev = block, preview = +1,
+  examples image = +10), numbered by 100 inside a range per kind with headroom —
+  components 12100–14900, libraries 15000–15900, showcases/docs 16000–16900,
+  tests 17000–17900 — so repos run side by side without collisions and new
+  components land next to the existing ones.
+- **Vite preset** `defineComponentConfig()` (Vite 7): dev server on a strict
+  registry port, library build (es + umd + `style.css` + rolled-up d.ts), and
+  `--mode examples` multi-page static build with relative asset URLs.
+- **Examples kit**, injected into every root page: `@layer kmwc` design system
+  merged from six diverged `examples-shared.css` copies, with `--kmwc-*` tokens
+  read through the rulebook's `--base-*` taxonomy (`light-dark()` fallbacks) and
+  a light / dark / auto theme switch that drives `data-theme` on `<html>`;
+  kit-generated DOM is `kmwc-` prefixed BEM. Chapter nav (bundled Floating UI,
+  shared slug logic, last-chapter highlight at page bottom), copy-link, version
+  badge with build stamp, build-only Plausible. Helpers:
+  `attachControlsPersistence`, `renderExamplesIndex` (its footer links the
+  devkit version that built the site), `mountExamplesKit`.
+- **Playwright preset** `definePlaywrightConfig()`.
+- **CLI** `kmwc`: `sync` (Dockerfile, nginx.conf with immutable `/assets/`
+  caching, Makefile + `Makefile.local`, .dockerignore, CLAUDE.md block, scripts),
+  `doctor` (devkit checks + the BlissFramework rulebook's `*.checks.sh` suites),
+  `check-vars` (declared/consumed modes; replaces three script copies),
+  `check-release` (dist-tag ⇔ version, not yet on npm — gates `make publish*`),
+  `new` (rulebook-shaped scaffold with intake: npm availability, reserved-prefix
+  check, next free block in the component port range — a taken or misaligned
+  `--port` is refused), `readme`.
+- **Fragment pages**: a page without `<html>` gets the devkit layout (head, entry
+  script, header, container) from `<meta name="kmwc:…">` tags; `<kmwc-include>` pulls
+  shared partials (parameters, nesting, cycle detection); `<kmwc-demo>` renders live
+  markup plus a code block of exactly that markup (and `<script data-kmwc-show>`), so
+  snippets can't drift from demos. `kmwc doctor` lists pages still repeating the boilerplate.
+- **Scaffold** (`kmwc new`): Element / Logic / types / logger layers, the
+  canonical eight-file CSS set, Strategy-B dark mode, Custom Elements Manifest,
+  README + `docs/`, CHANGELOG, LICENSE, `.claude/commands/publish.md`, examples,
+  smoke + dark-mode e2e specs — example pages are fragments. `--minimal` gives an
+  empty skeleton instead of the sample toggle. A fresh scaffold passes every rulebook suite.
+- **Playground** (`playground/`): a component scaffolded with `kmwc new`, linked to
+  the devkit and registered in the catalogue (port 17300) — the e2e test bed for
+  the kit, the presets and the scaffold, in dev and in the built site.
+- **Package-contents check** in `kmwc doctor`: `npm pack --dry-run` must not ship
+  `CLAUDE.md` / `.claude/` (at any depth), tests and specs, example pages,
+  partials, build/test output or local make config (`--no-pack` skips it).
+  `kmwc new` ends `files` with `!**/CLAUDE.md` and `!**/.claude`.
+- **`/publish` command** (`.claude/commands/publish.md`) for the devkit itself, in
+  the rulebook's canonical shape (passes `publish-command.checks.sh`): gates are the
+  unit tests, the playground e2e (dev + built), the playground doctor, `sync --check`
+  and `readme:check`; "build" is an entry-point smoke test, since `src/` ships as-is.
+### Fixed
+- **Flash of unstyled page on every reload in dev** (FOUC): the kit stylesheet was
+  imported from the kit's module script, which Vite dev applies only after the script
+  runs. The plugin now loads it render-blocking: a `<link>` in `<head>` in dev, a CSS
+  import (extracted to a `<head>` `<link>`) in builds. `auto.js` no longer imports
+  it. An e2e spec loads a page with JavaScript off and checks it is styled.
+- **Fragment detection** (`checkIsFragment`): a page is a full document only when it
+  *starts* with `<!DOCTYPE` / `<html>` (after a BOM, whitespace or comments). A fragment
+  whose script or code sample mentions `<html>` was passed through without the layout
+  (found migrating web-commandpalette's playground page).
+### Migrated
+- **web-commandpalette** (1.0.0-rc02) — the first component on the devkit.

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 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/README.md CHANGED Viewed

@@ -1,3 +1,418 @@
-# Temporary Holding Version
+# Keenmate Web Components
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The index of Keenmate's web components **and** the shared tooling that keeps
+them in the same shape: `@keenmate/web-components-devkit`.
+- **[Catalogue](#catalogue)**: every component, library, showcase and test
+  harness, with CSS prefixes, dev ports and links. It's
+  generated from [`components.json`](components.json).
+- **[Devkit](#the-devkit)**: one Vite preset, one examples kit, one Playwright
+  preset and the `kmwc` CLI, instead of a diverged copy of each in every repo.
+> **The rules** — component structure, naming, CSS, theming, README, Custom
+> Elements Manifest, publishing — live in the BlissFramework rulebook
+> (`BlissFramework/guidelines/web-components/`, plus the JS coding guidelines
+> in `BlissFramework/web/docs/coding-guidelines-javascript/`). The devkit
+> **generates** what the rulebook asks for (`kmwc new`) and **checks** it
+> (`kmwc doctor` runs the rulebook's `*.checks.sh` suites). Runtime code shared
+> between components (BlissElement, the input table, converters, logging,
+> positioning) lives in [`@keenmate/web-components-core`](../web-components-core).
+> Nothing here ships inside a component's bundle.
+## What's New in v1.0.0-rc01
+- **Devkit — one shared toolchain for every Keenmate web component** — Each `web-*` repo used to carry its own copy of the example helpers, the shared stylesheet, the Vite/Playwright configs and the deploy files, and every session "fixed" its own copy until they drifted apart. `@keenmate/web-components-devkit` owns all of it now: a component describes itself once in `package.json#kmwc` (title, prefix, ports, accent colours, analytics, image) and `defineComponentConfig()`, `definePlaywrightConfig()` and the `kmwc` CLI read it from there. A shared concern is fixed once in the devkit and every component picks it up on the next install.
+- **Vite preset — dev, library and examples-site builds from one config** — `defineComponentConfig()` (Vite 7) runs the dev server on the repo's registry port with `strictPort`, builds the library (`es` + `umd`, `style.css` kept under its historical name, rolled-up `.d.ts`) and, with `--mode examples`, builds every root `*.html` into a static multi-page site in `dist-examples/` with relative asset URLs. The examples plugin injects the kit into each page and loads its stylesheet render-blocking, so pages don't flash unstyled on reload.
+- **Examples kit — one design system and set of page helpers instead of six forks** — The `@layer kmwc` stylesheet merges six diverged `examples-shared.css` copies; its `--kmwc-*` tokens read the rulebook's `--base-*` taxonomy with `light-dark()` fallbacks, so a theme-designer theme restyles the demo page together with the component. Every page gets a light / dark / auto theme switch (it sets `data-theme` on `<html>`, the signal components react to), a chapter nav and copy-link buttons that share one slug algorithm, a version badge with the build stamp, and build-only Plausible. `attachControlsPersistence()` and `renderExamplesIndex()` replace the per-repo controls store and the 150-line inline index page.
+- **Fragment pages — no more copied page boilerplate** — A page without `<html>` is a fragment: `<meta name="kmwc:title">` and friends drive the shared layout (head, entry script, header with back link, container), `<kmwc-include>` pulls parameterised partials (nesting, cycle detection), and `<kmwc-demo>` renders live markup plus a code block of exactly that markup, so a snippet can no longer drift from its demo. Full documents pass through untouched, so pages migrate one at a time.
+- **`kmwc` CLI — generate, check and gate instead of hand-edit** — `kmwc sync` writes the Dockerfile, nginx.conf, Makefile (repo targets in `Makefile.local`), .dockerignore and a managed CLAUDE.md block from templates. `kmwc doctor` runs the devkit checks, an `npm pack` contents check (no CLAUDE.md, tests or example pages in the package) and every BlissFramework rulebook `*.checks.sh` suite. `kmwc check-vars` replaces three diverged manifest scripts (declared or consumed mode), and `kmwc check-release` gates `make publish*` on the dist-tag ⇔ version rule.
+- **`kmwc new` — a rulebook-shaped component on the first commit** — The scaffold runs the rulebook intake (npm name free, CSS prefix 2–4 letters and not reserved, next free port block) and generates the Element / Logic / types / logger layers, the canonical eight-file CSS set with Strategy-B dark mode, a Custom Elements Manifest, README + `docs/`, CHANGELOG, `/publish`, fragment example pages and smoke + dark-mode e2e specs. It passes every rulebook suite as generated; `--minimal` gives an empty skeleton instead of the sample toggle.
+- **Catalogue and port registry — every component listed, no port collisions** — `components.json` registers every Keenmate repo with its CSS prefix and a 100-port block (dev = block, preview = +1, image = +10), numbered inside a range per kind (components 12100–14900, libraries 15000–, showcases 16000–, tests 17000–), so any number of repos run side by side. The README catalogue is generated from it, with a ✅ for each repo on the devkit; web-commandpalette is the first.
+## Catalogue
+<!-- kmwc:catalogue:start — generated by `npm run readme`, do not edit inside -->
+### Components
+| Component | Package | Prefix | Dev port | Links | Devkit | About |
+|---|---|---|---:|---|:---:|---|
+| **web-multiselect** | `@keenmate/web-multiselect` | `ms` | 12100 | [repo](https://github.com/keenmate/web-multiselect) · [examples](https://examples.web-multiselect.keenmate.dev) · [docs](https://web-multiselect.keenmate.dev) · `web-multiselect-showcase` · `web-multiselect-docs` | — | Lightweight multiselect web component with typeahead search, rich content support, and excellent keyboard… |
+| **web-daterangepicker** | `@keenmate/web-daterangepicker` | `drp` | 12200 | [repo](https://github.com/keenmate/web-daterangepicker) · [docs](https://web-daterangepicker.keenmate.dev) · `web-daterangepicker-showcase` | — | Lightweight date picker web component with excellent keyboard navigation and range selection |
+| **web-treeview** | `@keenmate/web-treeview` | `wtv` | 12300 | [repo](https://github.com/keenmate/web-treeview) · `web-treeview-showcase` | — | Lightweight treeview web component with hierarchical data display, search, expand/collapse, drag-drop, and… |
+| **web-commandpalette** | `@keenmate/web-commandpalette` | `cp` | 12400 | [repo](https://github.com/keenmate/web-commandpalette) · [examples](https://examples.web-commandpalette.keenmate.dev) | ✅ | Framework-agnostic command-palette web component — modes, multi-step commands, scoped + global search,… |
+| **web-dropzone** | `@keenmate/web-dropzone` | `dz` | 12500 | [repo](https://github.com/keenmate/web-dropzone) | — | Lightweight file dropzone web component with drag-drop, previews, validation, and multiple display modes. |
+| **web-grid** | `@keenmate/web-grid` | `wg` | 12600 | [repo](https://github.com/keenmate/web-grid) · [docs](https://web-grid.keenmate.com) · [showcase](https://web-grid.keenmate.com) | — | Framework-agnostic data grid web component with sorting, filtering, inline editing, and keyboard navigation |
+| **web-editor** | `@keenmate/web-editor` | — | 12700 | [examples](https://examples.web-editor.keenmate.dev) | — | KeenMate Web Editor monorepo — a framework-agnostic WYSIWYG / Markdown editor built on ProseMirror. |
+| **web-switch** | `@keenmate/web-switch` | — | 12800 | [repo](https://github.com/keenmate/web-switch) | — | Framework-agnostic web component wrapper for @keenmate/svelte-switch. Works with React, Vue, Angular, or… |
+| **web-timepicker** | — | — | 12900 | — | — | Vanilla-JS prototypes (spiral / slider time pickers); no package yet. |
+| **web-wysiwyg** | — | — | 13000 | — | — | ProseMirror exploration; superseded by web-editor. |
+### Shared libraries
+| Library | Package | Dev port | About |
+|---|---|---:|---|
+| **web-components-core** | `@keenmate/web-components-core` | 15000 | Runtime foundation: BlissElement, reactive input table, converters, logging, positioning, CEM preset. |
+| **web-components** | `@keenmate/web-components-devkit` | 15100 | This repo — dev/demo/build tooling (Vite preset, examples kit, kmwc CLI). |
+### Showcases, docs & test harnesses
+| Repo | Kind | For | Dev port | About |
+|---|---|---|---:|---|
+| web-multiselect-showcase | showcase | web-multiselect | 16000 |  |
+| web-daterangepicker-showcase | showcase | web-daterangepicker | 16100 |  |
+| web-treeview-showcase | showcase | web-treeview | 16200 |  |
+| web-grid-showcase | showcase | web-grid | 16300 | [https://web-grid.keenmate.com](https://web-grid.keenmate.com) |
+| web-multiselect-docs | docs | web-multiselect | 16400 | Content-only docs (keendocs). |
+| web-component-framework-test | test | — | 17000 | Smoke + contrast tests inside CSS host frameworks (plain / Bootstrap / …). |
+| web-multiselect-test | test | web-multiselect | 17100 | npm-install vs direct-file consumption checks before publishing. |
+| web-multiselect-positioning-demo | test | web-multiselect | 17200 | Single-page positioning repro. |
+| web-playground | test | web-components | 17300 | Devkit e2e test bed — a component scaffolded with `kmwc new`, linked to this repo. |
+**Ports** — a block of 100 per repo: dev server = **Dev port**, preview = +1, examples image = +10. Each kind numbers its blocks by 100 inside its own range (component 12100–14900 · library 15000–15900 · showcase & docs 16000–16900 · test 17000–17900), so any number of repos run side by side without collisions and a new component lands next to the others. `kmwc doctor` checks a repo against its block; `kmwc new` takes the next free one.
+<!-- kmwc:catalogue:end -->
+To add or change a row, edit [`components.json`](components.json) and run
+`npm run readme`. Descriptions and the Devkit ✅ are read from the
+sibling checkouts next to this repo. `npm run readme:check` fails when the
+table is stale. Prefixes mirror the reserved-prefix table in the rulebook's
+`base-variables.md`, which stays the authority.
+---
+## The devkit
+### Why
+Before the devkit, every component repo carried its own copy of
+`examples-shared.css` (six copies, six different versions),
+`examples-chapter-nav.js` (three versions), `examples-copy-link.js`,
+`examples-controls-store.js`, `plausible-snippet.html`,
+`check-variable-manifest.mjs`, a `vite.config.ts`, a `Dockerfile`, an
+`nginx.conf` and a `Makefile`. A fix made in one repo never reached the others.
+web-treeview forked the whole 980-line stylesheet just to change purple to
+green. Two components shared a dev port and three shared an image port.
+The devkit owns all of that. A component states what's specific to it **once**,
+in `package.json#kmwc`, and gets the rest.
+### What a component gets
+| Piece | Import / command | Replaces |
+|---|---|---|
+| Vite preset | `@keenmate/web-components-devkit/vite` → `defineComponentConfig()` | per-repo `vite.config.ts`, `vite.examples.config.ts` |
+| Examples kit (auto-injected) | shared styles, chapter nav, copy-link buttons, theme switch, version badge, analytics | `examples-shared.css`, `examples-chapter-nav.js`, `examples-copy-link.js`, `plausible-snippet.html`, Dockerfile `sed` |
+| Fragment pages | `<meta name="kmwc:title">` pages + `<kmwc-include>` partials + `<kmwc-demo>` (live markup = snippet) | the head / header / container boilerplate copied into every page, hand-copied `.code-block` snippets |
+| Examples helpers | `@keenmate/web-components-devkit/examples` → `attachControlsPersistence`, `renderExamplesIndex`, `mountExamplesKit` | `examples-controls-store.js`, 150 lines of inline index-page CSS |
+| Playwright preset | `@keenmate/web-components-devkit/playwright` → `definePlaywrightConfig()` | per-repo `playwright.config.ts` |
+| Generated files | `kmwc sync` | hand-edited `Dockerfile`, `nginx.conf`, `Makefile`, `.dockerignore` |
+| Standard check | `kmwc doctor` (devkit checks + the rulebook's `*.checks.sh`) | — |
+| Manifest check | `kmwc check-vars` | 3 diverged `check-variable-manifest.mjs` |
+| Release gate | `kmwc check-release` (used by `make publish` / `publish-rc`) | — |
+| Scaffolder | `kmwc new web-<name> --prefix <p>` | copy-pasting the last repo |
+### Install
+```
+npm i -D @keenmate/web-components-devkit vite@^7
+```
+To develop against a local checkout of this repo, keep the semver range in
+`package.json` (Docker builds install from the registry) and link it:
+```
+cd ../web-components && npm link
+cd ../web-<component> && npm link @keenmate/web-components-devkit
+```
+Peer dependencies (`vite`, `@playwright/test`) are always resolved from the
+**component's** `node_modules`, so a linked devkit doesn't load a second copy.
+### `package.json#kmwc`
+Every field is optional. Defaults are derived from the package.
+```jsonc
+"kmwc": {
+  "title": "Web MultiSelect",                    // examples index header
+  "tagline": "Feature-rich multiselect …",       // default: package.json description
+  "tag": "web-multiselect",
+  "prefix": "ms",                                // reserved CSS prefix (rulebook base-variables.md)
+  "library": {
+    "entry": "src/index.ts",                     // default
+    "globalName": "MultiSelect",                 // UMD global
+    "fileName": "multiselect",                   // → dist/multiselect.js + .umd.js
+    "cssFileName": "style",                      // default; keeps dist/style.css on Vite 7
+    "shouldEmitTypes": true,                     // rolled-up .d.ts (typesPluginConfig to tune)
+    "shouldEmitSourcemap": false,
+    "external": []
+  },
+  "ports": { "dev": 12100, "image": 12110 },     // the repo's components.json port block (+10 = image)
+  "theme": { "accentColor": "#667eea", "accentEndColor": "#764ba2" },
+  "examples": {
+    "canonicalOrigin": "https://examples.web-multiselect.keenmate.dev",
+    "staticPaths": ["examples-data", "docs"],    // copied verbatim into the built site
+    "excludedPages": [],                         // root *.html that aren't example pages
+    "outDir": "dist-examples"
+  },
+  "analytics": { "plausibleSiteId": "pa-5vUESDVyztHMyzN5gs5A4" },
+  "image": {
+    "name": "registry.km8.es/web-multiselect-examples:prod",
+    "runner": "podman",
+    "packageJsonPaths": ["package.json"]         // monorepos: list workspace package.jsons too
+  },
+  "cssVariables": {
+    "sources": ["src/css"],                      // dirs (stylesheets) or explicit files (any type)
+    "internalVariables": ["ms-input-current-width"], // runtime internals, not theming knobs
+    "checkMode": "declared"                      // or "consumed" (var() reads)
+  },
+  "rulebook": {
+    "path": "../../BlissFramework/guidelines/web-components", // default; env KMWC_RULEBOOK_PATH wins
+    "skippedChecks": []                          // e.g. ["responsive-overlay"]
+  },
+  "sync": { "skippedFiles": [] }                 // e.g. ["Makefile"] to opt a file out
+}
+```
+### Vite preset
+```ts
+// vite.config.ts
+import { defineComponentConfig } from '@keenmate/web-components-devkit/vite';
+export default defineComponentConfig();
+// with repo-specific bits
+export default defineComponentConfig({
+  plugins: [shadowCssPlugin()],
+  overrides: { optimizeDeps: { entries: ['index.html', 'examples-*.html'] } },
+  getOverridesCallback: (env, config) => ({ /* env-dependent bits */ }),
+});
+```
+| Command | Result |
+|---|---|
+| `vite` | dev server on `kmwc.ports.dev` (strict, never hops ports) |
+| `vite build` | library: `dist/<fileName>.js`, `.umd.js`, `style.css`, rolled-up `.d.ts` |
+| `vite build --mode examples` | static examples site → `dist-examples/` (every root `*.html` is a page) |
+| `vite preview --mode examples` | serves the built site on the preview port (`ports.dev + 1`) |
+The preset defines `__VERSION__`, `__PACKAGE_NAME__`, `__AUTHOR__`,
+`__LICENSE__`, `__REPOSITORY__` and `__HOMEPAGE__`. For a hand-assembled config
+(monorepos, showcases), use the plugin on its own: `createExamplesPlugin()`.
+### Examples kit
+The plugin injects the kit into every **root-level** `*.html` page. Pages under
+`test/` (Playwright fixtures) are left alone, and any page can opt out with
+`<html data-kmwc="off">`.
+#### Fragment pages — no copied boilerplate
+A page without `<html>` is a **fragment**: it carries only its own content,
+and the plugin wraps it in the devkit layout (head, entry script, header with
+back link / title / subtitle, container). The whole file:
+```html
+<meta name="kmwc:title" content="Tree of Options">
+<meta name="kmwc:subtitle" content="Hierarchical options via a materialized path-member…">
+<link rel="stylesheet" href="examples-local.css">   <!-- moved into <head> -->
+<kmwc-include src="partials/no-collapse-note.html" title="No collapse"></kmwc-include>
+<div class="card">                                   <!-- each h2 = a chapter -->
+    <h2>TR01 · Basic tree</h2>
+    <kmwc-demo>
+        <web-multiselect id="tree" path-member="path"></web-multiselect>
+        <script type="module" data-kmwc-show>
+            document.getElementById('tree').options = [{ value: 'fruit', label: 'Fruit', path: '1' }];
+        </script>
+    </kmwc-demo>
+</div>
+<script type="module">
+    import { attachControlsPersistence } from '@keenmate/web-components-devkit/examples';
+    attachControlsPersistence('tree');
+</script>
+```
+| Construct | Does |
+|---|---|
+| `<meta name="kmwc:title">` (required), `kmwc:subtitle`, `kmwc:body-class` | header + `<title>`, body classes |
+| `<meta name="kmwc:layout" content="bare">` | head only, no header/container (the index page) |
+| `<meta name="kmwc:entry" content="none">` | skip the component entry script (default `/<kmwc.library.entry>`, loaded in `<head>` so the element is defined before page scripts run) |
+| `<link>` / `<style>` anywhere in a fragment | moved into `<head>` |
+| `<kmwc-include src="partials/x.html" some-param="v">inner</kmwc-include>` | the partial with `{{someParam}}` and `{{content}}` filled in; nests; cycles are an error; unknown `{{…}}` stay as written |
+| `<kmwc-demo>markup</kmwc-demo>` | the markup live **and** as a code block of exactly that markup (copy button included) — a snippet can't drift from its demo. `<script data-kmwc-show>` inside runs and is shown too. Attributes: `preview-class`, `markup-hidden`, `code-hidden` |
+Tags inside HTML comments are never expanded. Partials live in the repo's
+`partials/` folder (a change reloads the dev server page); shared demo data
+belongs in `examples-data/*.js` modules imported by pages. Full documents
+(`<html>…`) pass through untouched, so pages migrate one at a time — `kmwc
+doctor` lists the ones still repeating the head/header boilerplate.
+- **Styles** live in `@layer kmwc`, so any unlayered rule beats them
+  regardless of order (and the layered reset can never clobber a component).
+  Tokens (`--kmwc-*`) read through the rulebook's `--base-*` taxonomy with
+  `light-dark()` fallbacks, so a theme-designer theme restyles the demo page
+  together with the component; colour literals live only in `tokens.css`.
+  Re-theme a site with `kmwc.theme.accentColor`. The page vocabulary is
+  unchanged from the old shared CSS — `.card`, `.example-section`, `.controls`,
+  `.demo-area`, `.demo-card`, `.code-block`, `.note(.warning|.info|.success|.error)`,
+  `.grid`/`.card-grid`, `.reference-table`, `.log-panel`, `.pill`,
+  `.status-dot`, `.control-group`, buttons (`.btn-secondary`, `.btn-outline`,
+  `.btn-danger`) — while everything the kit **generates** is prefixed BEM
+  (`kmwc-chapter-nav__item--active`, `kmwc-copy-link--copied`, …).
+- **Theme switch** (top right) cycles light → dark → auto and sets
+  `data-theme` on `<html>` — the same signal components react to via
+  `:host-context([data-theme])`, so every example page is a dark-mode smoke
+  test. The saved choice is applied before first paint.
+- **Chapter nav and copy-link** share one section/slug algorithm, so the
+  jump-list hashes and copied links always match. Floating UI is bundled (no
+  CDN). At the bottom of a short page, the last chapter gets highlighted.
+- **Version badge**: any `[data-kmwc-version]` (or legacy `#version-badge`)
+  shows `v1.2.3`, or `v1.2.3 (built …)` in a built site.
+- **Landing page**: `renderExamplesIndex({ pages })` renders the header, cards,
+  footer and cross-page nav from the registry plus `kmwc` config.
+- **Late content**: the kit mounts one task after DOM-ready. Pages that render
+  sections after a fetch call `mountExamplesKit()`.
+- **Analytics**: the Plausible snippet goes into **built** pages only, and only
+  when `kmwc.analytics.plausibleSiteId` is set.
+### Playwright preset
+```ts
+import { definePlaywrightConfig, devices } from '@keenmate/web-components-devkit/playwright';
+export default definePlaywrightConfig({
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] }, testIgnore: ['**/mobile.spec.ts'] },
+    { name: 'mobile', use: { ...devices['Pixel 7'] }, testMatch: ['**/mobile.spec.ts'] },
+  ],
+});
+```
+baseURL and the `npm run dev` web server come from `kmwc.ports.dev`.
+### CLI
+```
+kmwc sync [--check]           regenerate Dockerfile, nginx.conf, Makefile, .dockerignore, the
+                              CLAUDE.md devkit block, .gitignore entries, missing standard scripts
+kmwc doctor [--json]          devkit checks + package contents + the rulebook's *.checks.sh suites
+                              (exit 1 on errors). --verbose lists passes, --no-rulebook skips the
+                              suites, --no-pack skips the package-contents check
+kmwc check-vars [--strict]    component-variables.manifest.json ⇔ CSS
+kmwc check-release --tag t    latest ⇔ release version, rc ⇔ -rcN, version not yet on npm
+kmwc new web-<name>           scaffold a component (--prefix, --title, --tag, --dir, --port, --minimal, --register)
+kmwc readme [--check]         regenerate this README's catalogue (devkit repo only)
+```
+Generated files start with a `GENERATED by kmwc sync` header. Repo-specific
+make targets go in `Makefile.local`, which the generated Makefile includes at
+the end. Per-developer overrides (`DOCKER_RUNNER`, `IMAGE_PORT`) go in
+`.makefile.env`. `make publish` / `make publish-rc` run `kmwc check-release`
+and the e2e suite before building and publishing.
+**`kmwc doctor` and the rulebook.** Doctor runs every suite in the rulebook
+(component-structure, naming-conventions, css-structure, theme-container,
+base-variables, color-scheme, readme-structure, custom-elements-manifest,
+responsive-overlay, publish-command) with `bash`, passing `kmwc.prefix`, and
+reports each `FAIL` as an error pointing at the matching `.checks.md` entry.
+When the rulebook isn't checked out (or there's no bash) the suites are
+skipped with a warning — the rulebook stays the single source of truth; the
+devkit never copies its rules.
+**Package contents.** Doctor runs `npm pack --dry-run` and fails on anything
+dev-only that would reach a consumer's `node_modules`: `CLAUDE.md` at any
+depth and `.claude/` (AI-assistant guidance, which a directory entry such as
+`src/css` in `files` sweeps in), `test/` / `e2e/` / `*.spec.*` / `*.test.*`,
+example pages and `partials/`, build/test output, and local make config. Keep
+`"!**/CLAUDE.md"` and `"!**/.claude"` at the end of `files`; the scaffold adds them.
+### Scaffolding a component
+```
+npx kmwc new web-colorpicker --prefix cpk --title "Web Color Picker" --register
+```
+`kmwc new` runs the rulebook intake: the npm name must be free and the CSS
+prefix must be 2–4 lowercase letters not reserved in `base-variables.md` or
+`components.json` (it's derived only when unambiguous — hyphenated words, or a
+short single word — otherwise pass `--prefix`). The result passes every
+rulebook suite on its first commit:
+- `src/web-component.ts` (`ColorpickerElement`, Element layer, `ATTRIBUTE_TABLE`,
+  `change` event with `onChange` twin) · `src/colorpicker.ts` (`WebColorpicker`,
+  logic class) · `src/types.ts` · `src/logger.ts` · `src/index.ts`
+- `src/css/` — the canonical eight files, `@layer variables, component, overrides`,
+  `--cpk-*` ⇢ `--base-*` ⇢ `light-dark()` chains, Strategy-B dark mode, FOUC rule
+- Custom Elements Manifest config + package.json `customElements` / `web-types`,
+  `component-variables.manifest.json` (exported as `/manifest`)
+- README in the canonical shape, `docs/{usage,theming,examples,accessibility}.md`,
+  CHANGELOG (`## [0.1.0] - <date>`), LICENSE, `.claude/commands/publish.md`
+- a `files` allowlist (dist, docs, manifests, editor-integration JSON) ending in
+  `!**/CLAUDE.md` and `!**/.claude`, so AI-assistant guidance never ships
+- examples (index, basic, theming), fixtures + smoke and dark-mode e2e specs,
+  and the `kmwc sync` files
+By default the component is a small working sample (a toggle with `label` /
+`active` inputs and a `change` event) to rename or replace. Add `--minimal`
+for an empty skeleton instead: the same files and structure, but an empty
+`ATTRIBUTE_TABLE`, no events, a root that renders its slotted content, and
+stub feature CSS — it passes the same rulebook suites.
+Reserve the new prefix in the rulebook's `base-variables.md` afterwards — the
+command prints the reminder.
+### Migrating a component
+`kmwc doctor` lists everything that's left, so run it after each step.
+1. `npm i -D @keenmate/web-components-devkit vite@^7` (plus `@playwright/test`
+   if the repo has e2e tests).
+2. Add `package.json#kmwc`. Take the port block (`ports.dev` = block,
+   `ports.image` = block + 10) and prefix from
+   [`components.json`](components.json), the Plausible id from the old
+   `plausible-snippet.html` (`analytics.plausibleSiteId`), the image name and
+   runner from the old Makefile, the canonical origin from the old
+   `examples-copy-link.js`, and internals from the old
+   `check-variable-manifest.mjs` (`cssVariables.internalVariables`).
+3. Replace `vite.config.ts` (and any `vite.examples.config.ts`) with
+   `defineComponentConfig()`. Move genuinely specific bits to `plugins` and
+   `overrides`. Do the same for `playwright.config.ts`.
+4. Pages: delete the `<link href="examples-shared.css">` and the
+   `examples-chapter-nav.js` / `examples-copy-link.js` script tags. Change
+   `import { persistControls } from './examples-controls-store.js'` to
+   `import { attachControlsPersistence } from '@keenmate/web-components-devkit/examples'`
+   (same storage keys — saved demo state survives). Move component-only CSS into
+   `examples-local.css`.
+5. Swap `index.html` for `renderExamplesIndex({ pages })`, keeping the page
+   registry. The inline `<style>` and header markup go away.
+6. Delete the legacy files: `examples-chapter-nav.js`, `examples-copy-link.js`,
+   `examples-controls-store.js`, `examples-shared.css`,
+   `plausible-snippet.html`, `scripts/check-variable-manifest.mjs`.
+7. Set `"check:vars": "kmwc check-vars"` and run it.
+8. `npx kmwc sync`, then review the diff. Repo-specific Makefile targets move
+   to `Makefile.local`.
+9. Check it runs: `npm run dev`, `npm run build`, `npm run build:examples`,
+   `npm run preview:examples`, the e2e tests, and finally `npx kmwc doctor`
+   (devkit + rulebook — rulebook failures are real findings to fix or to
+   document under `## Known limitations`, per the rulebook).
+### Developing the devkit
+```
+npm install
+npm test                 # unit tests (config, registry, templates, sync, checks, intake, plugin, kit)
+npm run test:e2e         # playground: the kit + scaffold in a real browser, dev server AND built site
+npm run readme           # regenerate the catalogue
+```
+[`playground/`](playground) is a real component scaffolded with `kmwc new` and
+linked to this checkout. It's the reference for "what a component looks like",
+the e2e target for every kit feature, and `npx kmwc doctor` inside it must
+report every rulebook suite green. When you change the kit or a template, add
+a spec there.
+Releases are prepared with the `/publish` Claude command
+(`.claude/commands/publish.md`, the rulebook's canonical `/publish` with devkit
+steps: unit + e2e + playground doctor + catalogue check, entry-point smoke
+test, `npm pack` review). It never publishes or pushes. That's yours.