eslint-plugin-kerfjs 5.0.0-beta.56 → 5.0.0-beta.58

package/README.md

@@ -13,15 +13,17 @@ This plugin sits alongside two other defense layers shipped by [`kerfjs`](https:
 | Opt-in dev-warns (`KERF_DEV_WARN_*`) | Hard Rules 4 (rebuilt listeners), 7 (untracked signals), 8 (narrow set)                                                                                          | Runtime       |
 | **This plugin**                      | Hard Rules 2, 5, 6, 10, 12 — AST-shaped antipatterns; plus rename-safety / `raw()`-audit nudges and a project-hygiene check for the bundled AI-assistant configs | **Edit time** |
 
-All but one rule are AST-only — no `@typescript-eslint/parser` _service_ dependency is required by the plugin (consumers configure their own parser). The exception, `ai-assistant-configs`, reads the filesystem instead of the AST and runs once per lint pass.
+The core syntax rules analyze the AST without TypeScript parser services. `ai-assistant-configs` reads the filesystem, and the optional UI rules also resolve catalog and profile artifacts. Consumers configure their own parser; no `@typescript-eslint/parser` _service_ is required.
 
 ## Install
 
 ```bash
 npm install --save-dev eslint-plugin-kerfjs
-npm install @kerfjs/ui
 ```
 
+Install `@kerfjs/ui` as well when using `recommended-ui` or `strict-ui`; the
+core `recommended` preset does not require it.
+
 ### Supported ESLint versions
 
 `peerDependencies` declares `^9.0.0 || ^10.0.0`, and that is a **tested** range rather than an optimistic one: the rule suite runs against the latest release of each of those majors in CI on every push. A major is added to the range only after the suite has passed on it.
@@ -59,14 +61,14 @@ export default [
 ];
 ```
 
-The UI rules resolve the installed `@kerfjs/ui` v1 selection catalog, v2 composition catalog, and application profile defaults. They then merge `.kerf-ui-profile.json` files from the workspace root toward the linted file. Package authors and monorepos can provide explicit artifacts without duplicating their facts:
+The UI rules resolve the installed `@kerfjs/ui` selection catalog (`component-catalog.json`), composition catalog (`component-composition.json`), and application profile defaults. They then merge `.kerf-ui-profile.json` files from the workspace root toward the linted file. Package authors and monorepos can provide explicit artifacts without duplicating their facts:
 
 ```js
 settings: {
   kerfjs: {
     ui: {
       workspaceRoot: import.meta.dirname,
-      catalogPath: './vendor/component-catalog-v2.json',
+      catalogPath: './vendor/component-composition.json',
       selectionCatalogPath: './vendor/component-catalog.json',
       profileDefaultsPath: './vendor/application-ui-profile.defaults.json',
       profileContractPath: './vendor/application-ui-profile-sync.cjs',
@@ -75,13 +77,20 @@ settings: {
 }
 ```
 
-For deterministic generated configs, the same settings accept parsed `catalog`, `selectionCatalog`, and `profile` objects. File-based precedence is package defaults, then workspace profile, then root-to-leaf directory profiles. The rules load `application-ui-profile-sync.cjs` from the installed `@kerfjs/ui` package by default because ESLint rule creation is synchronous; `profileContractPath` is only needed when artifacts are vendored. Every raw layer is schema- and catalog-reference-validated before merge, so a child cannot hide malformed or stale parent policy. Exceptions use exact `KUI-L*` diagnostic ids and repository-relative file or directory targets.
+For deterministic generated configs, the same settings accept parsed `catalog`, `selectionCatalog`, and `profile` objects. File-based precedence is package defaults, then workspace profile, then root-to-leaf directory profiles. The rules load `application-ui-profile-sync.cjs` from the installed `@kerfjs/ui` package by default because ESLint rule creation is synchronous; `profileContractPath` is only needed when artifacts are vendored, and then its directory must also hold `application-ui-diagnostic-ids-v1.json` and `component-class-owners.cjs` (the class-to-component rule `KUI-L103` shares with `@kerfjs/ui`'s generated component pages) from the same `@kerfjs/ui` release. Every raw layer is schema- and catalog-reference-validated before merge, so a child cannot hide malformed or stale parent policy. Exceptions use exact `KUI-L*` diagnostic ids and repository-relative file or directory targets.
 
 `ui-css-values` consumes each catalog entry's property-specific grammar and
 emits `KUI-L013`–`KUI-L017` with a preferred shorthand or helper. It covers JSX,
 direct component calls, nested catalog paths, and explicitly configured
 third-party catalogs; dynamic values remain governed by TypeScript.
 
+`ui-component-ownership` keeps code out of another package's component
+internals: `KUI-L020` reports a reference to a component's private `--_*`
+variable and `KUI-L021` an assignment to a token a typed prop sets (use the
+prop). Each message ends by routing a real need with no prop to a component-gap
+report instead of an override. `kerf-ui-analyze` reports the same ids, plus the
+stylesheet-only `KUI-L019` / `KUI-L022`, for CSS files.
+
 `KUI-L090` is reserved for catalog/profile loading and configuration failures. The supported-ESLint matrix installs real packed `eslint-plugin-kerfjs` and `@kerfjs/ui` tarballs in a downstream flat-config fixture, ensuring these defaults resolve from the consumer rather than this repository's source tree.
 
 ## Legacy `.eslintrc` configs are not supported
@@ -92,21 +101,22 @@ Use flat config (`eslint.config.js`), shown above. The `legacy-recommended` expo
 
 ## Rules
 
-| Rule                                                                             | Hard Rule                                            | Severity (recommended) |
-| -------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------- |
-| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md)     | 10 — use `data-action` + `delegate()`                | `error`                |
-| [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md)             | 2 — `data-key` per item                              | `error`                |
-| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md)           | 5 — capture `delegate()` disposers when scope < page | `warn`                 |
-| [`no-nested-mount`](docs/rules/no-nested-mount.md)                               | 6 — one `mount()` per root                           | `error`                |
-| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global        | `error`                |
-| [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md)                     | — (rename-safety nudge for `delegate()` selectors)   | `warn`                 |
-| [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md)               | — (XSS audit trail)                                  | `warn`                 |
-| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md)                     | — (project hygiene)                                  | `warn`                 |
-| [`ui-public-boundaries`](docs/rules/ui-public-boundaries.md)                     | — (cataloged CSS boundaries)                         | `error`                |
-| [`ui-composition`](docs/rules/ui-composition.md)                                 | — (cataloged parents and zones)                      | `error`                |
-| [`ui-css-values`](docs/rules/ui-css-values.md)                                   | — (cataloged property-specific value grammar)        | `error`                |
-| [`ui-preferences`](docs/rules/ui-preferences.md)                                 | — (application component choices)                    | `warn`                 |
-| [`ui-wiring`](docs/rules/ui-wiring.md)                                           | — (required setup and cleanup)                       | `warn`                 |
+| Rule                                                                             | Hard Rule                                                       | Severity (recommended) |
+| -------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------- |
+| [`no-inline-jsx-event-handlers`](docs/rules/no-inline-jsx-event-handlers.md)     | 10 — use `data-action` + `delegate()`                           | `error`                |
+| [`require-data-key-in-each`](docs/rules/require-data-key-in-each.md)             | 2 — `data-key` per item                                         | `error`                |
+| [`require-delegate-disposer`](docs/rules/require-delegate-disposer.md)           | 5 — capture `delegate()` disposers when scope < page            | `warn`                 |
+| [`no-nested-mount`](docs/rules/no-nested-mount.md)                               | 6 — one `mount()` per root                                      | `error`                |
+| [`prefer-module-jsx-augmentation`](docs/rules/prefer-module-jsx-augmentation.md) | 12 — augment `kerfjs/jsx-runtime`, not global                   | `error`                |
+| [`prefer-attr-selector`](docs/rules/prefer-attr-selector.md)                     | — (rename-safety nudge for `delegate()` selectors)              | `warn`                 |
+| [`no-raw-with-dynamic-arg`](docs/rules/no-raw-with-dynamic-arg.md)               | — (XSS audit trail)                                             | `warn`                 |
+| [`ai-assistant-configs`](docs/rules/ai-assistant-configs.md)                     | — (project hygiene)                                             | `warn`                 |
+| [`ui-public-boundaries`](docs/rules/ui-public-boundaries.md)                     | — (cataloged classes/tokens; component anatomy on app elements) | `error`                |
+| [`ui-component-ownership`](docs/rules/ui-component-ownership.md)                 | — (configure components, never override them)                   | `error`                |
+| [`ui-composition`](docs/rules/ui-composition.md)                                 | — (cataloged parents and zones)                                 | `error`                |
+| [`ui-css-values`](docs/rules/ui-css-values.md)                                   | — (cataloged property-specific value grammar)                   | `error`                |
+| [`ui-preferences`](docs/rules/ui-preferences.md)                                 | — (application component choices)                               | `warn`                 |
+| [`ui-wiring`](docs/rules/ui-wiring.md)                                           | — (required setup and cleanup)                                  | `warn`                 |
 
 The "Hard Rule" column refers to the numbered rules in [`docs/ai/usage-guide.md`](../docs/ai/usage-guide.md) on the main kerf repo. `no-raw-with-dynamic-arg` and `ai-assistant-configs` don't map to numbered Hard Rules — the former creates an audit trail for every dynamic `raw()` call site (potential XSS); the latter checks that the bundled AI-assistant configs are installed and current. See [`docs/12-ai-assistant-configs.md`](../docs/12-ai-assistant-configs.md) on the main kerf repo for the AI-configs design.
 
@@ -121,6 +131,7 @@ When a real bug ships that the existing defense stack misses AND a new lint rule
 ```bash
 npm install
 npm test
+npm run test:eslint-matrix # real packed-plugin loading on every supported ESLint major
 ```
 
 The AST rules' test suites use ESLint's `RuleTester` with `@typescript-eslint/parser`. The `ai-assistant-configs` tests are filesystem-driven — they build temp project roots with fixture `node_modules/kerfjs/ai/` bundles, drive the classifier directly, and use the real ESLint API to prove plain lint is read-only while explicit `--fix` performs the external write.

package/docs/rules/ui-component-ownership.md

@@ -0,0 +1,43 @@
+# `ui-component-ownership`
+
+Components own their styles and are configured, never overridden. This rule
+keeps application and component-package code from reaching into another
+package's component through its variables:
+
+- `KUI-L020` — a string, template, object key, or `style` value references a
+  component's private `--_<root>-*` variable (`--_kui-list-gap`), or any
+  `--_kui-*` variable. Private variables are implementation; reading or writing
+  them breaks when the component changes.
+- `KUI-L021` — code assigns a component token that a typed prop sets, in a
+  `style` string (`style="--kui-list-gap: 4px"`), a style object key
+  (`style={{ '--kui-floating-toolbar-inset': '0' }}`), or
+  `style.setProperty('--kui-disclosure-arrow-size', …)`. Set the prop instead
+  (`<List gap="xs" />`).
+
+Both messages name the owning component and end with the same guidance: if no
+configuration covers the need, report the component gap to the owning package
+(open a feature request) instead of overriding it.
+
+```tsx
+// KUI-L020 / KUI-L021
+<div style="--_kui-list-gap: 2px; --kui-list-gap: 4px">…</div>;
+
+// Configure the component instead.
+<List gap="xs">…</List>;
+```
+
+Ownership comes from the loaded composition catalogs, so third-party component
+packages declared in `.kerf-ui-profile.json` get the same protection. A file
+inside the package that owns a component (the nearest `package.json` names the
+catalog entry's `package`) may use that component's own private variables and
+tokens. Reading a public token (`var(--kui-list-divider-color)`) and setting a
+theme token with no equivalent prop remain configuration and are not reported.
+
+CSS files are outside ESLint's reach: `kerf-ui-analyze` (and `kerf-ui-doctor`)
+report the same `KUI-L020` / `KUI-L021` ids in stylesheets, plus `KUI-L019`
+(a rule whose subject is a cataloged component) and `KUI-L022` (a hook class
+on a component's root). See `@kerfjs/ui/docs/ui-analyzer.md`.
+
+Exact profile exceptions may name either id. The rule reads
+`@kerfjs/ui/ai/component-composition.json` by default; see the plugin README for
+alternate catalog settings.

package/docs/rules/ui-preferences.md

@@ -2,4 +2,15 @@
 
 Reports cataloged components listed in an application UI profile preference's `avoid` set and points to the package-qualified `preferred` component. The stable diagnostic is `KUI-L301`.
 
+A component matches whether it is rendered through an imported export (`<WaButtonGroup />`) or written directly as its custom-element tag (`<wa-dropdown>`), which resolves through the selection catalog's `customElement`. The `@kerfjs/ui` package defaults avoid every `Discouraged` Web Awesome element, so each of these reports and names the Kerf component to render instead:
+
+```tsx
+<wa-dropdown>…</wa-dropdown>        // KUI-L301: prefer @kerfjs/ui:popup-menu
+<wa-select>…</wa-select>            // KUI-L301: prefer @kerfjs/ui:select
+<wa-tab-group>…</wa-tab-group>      // KUI-L301: prefer @kerfjs/ui:tab-bar
+<wa-icon name="gear" />             // KUI-L301: prefer @kerfjs/ui:lucide-icon
+```
+
+Supported Web Awesome elements (`<wa-button>`, `<wa-dialog>`, the encouraged `<wa-popup>`) and unknown custom elements are not reported. The source file of a component declared in a profile catalog is exempt: that wrapper owns the element it renders, and the preference applies to its callers.
+
 `recommended-ui` treats the rule as a warning; `strict-ui` treats it as an error. Use a narrowly targeted `KUI-L301` profile exception when a documented application boundary cannot follow the preference. Component substitutions are not autofixed because their props and interaction contracts can differ.

package/docs/rules/ui-public-boundaries.md

@@ -1,7 +1,48 @@
 # `ui-public-boundaries`
 
-Rejects `kui-*` classes and `--kui-*` custom properties that are not listed in the versioned composition catalog. This keeps application code out of private component anatomy while allowing cataloged styling seams.
+Rejects `kui-*` classes and `--kui-*` custom properties that are not listed in the versioned composition catalog, and cataloged component classes written onto elements the application owns. This keeps application code out of private component anatomy while allowing cataloged styling seams.
 
-Diagnostics are stable: `KUI-L101` identifies a private/unknown class and `KUI-L102` an unknown token. Exact profile exceptions can name either id. The rule deliberately does not rewrite selectors or tokens because there is no generally safe replacement.
+Diagnostics are stable: `KUI-L101` identifies a private/unknown class, `KUI-L102` an unknown token, and `KUI-L103` a component's anatomy class placed on an application-owned element. Exact profile exceptions can name any of these ids. The rule deliberately does not rewrite selectors, tokens, or markup because there is no generally safe replacement.
 
-The rule reads `@kerfjs/ui/ai/component-catalog-v2.json` by default. See the plugin README for alternate catalog settings used by monorepos and package authors.
+## Component anatomy on your own element (`KUI-L103`)
+
+A public class such as `kui-toolbar` or `kui-pane__content` is the rendered anatomy of a component. Writing it onto your own element recreates the component by class: the element inherits (and invites you to restyle) the component's CSS without its props, behavior, accessibility, or future fixes. Components own their styles; render and configure them instead.
+
+```tsx
+<div class="kui-toolbar">…</div>                        // KUI-L103: render `Toolbar`
+<aside class="kui-pane"><nav class="kui-pane__content"> // KUI-L103: render `Pane`
+<wa-dropdown class="kui-popup-menu">…</wa-dropdown>     // KUI-L103: render `PopupMenu`
+<Text class="kui-toolbar-text" />                       // KUI-L103: render `ToolbarText`
+<div class="kui-content-item">…</div>                   // KUI-L103: render `ContentItem`
+```
+
+The catalog marks the classes an application may place with `boundaries.placeableClasses`; these stay allowed:
+
+```tsx
+<div id="app" class="kui-app-root" />                   // document root
+<main class="kui-content kui-scroll-owner" />           // layout utilities
+<footer class="kui-control-cluster kui-content-item" /> // item geometry on a non-div carrier
+<Toolbar className="kui-toolbar" />                     // a component's own element
+```
+
+A placeable class can still be a component's own root. When a catalog entry names the `boundaries.rootElement` its component renders around its placeable classes, a plain element of that tag carrying them is the component recreated and is reported: `<div class="kui-content-item">` is exactly what `ContentItem` renders. The class stays placeable on any other carrier — a `<ul>`, a `Text`, or a control-cluster `<footer>` that must carry the geometry itself. `@kerfjs/ui`'s own `check:guidance` derives its repository check from the same catalog fields, so the two cannot disagree.
+
+The component a diagnostic names is the export named after the class's block, tried from the whole block down to its last word (`kui-toolbar-action-link` → `ToolbarActionLink`, `kui-pane__content` → `Pane`, `acme-meter__bar` → `Meter`), else the entry's own component, else every component the entry exports. That rule ships once, as `@kerfjs/ui/ai/component-class-owners.cjs`; the rule loads it beside `application-ui-profile-sync.cjs`, and `@kerfjs/ui`'s generated `ai/components/*.md` pages render their "render X instead" lines from the same file, so the lint message and the component reference always name the same component. An `@kerfjs/ui` too old to ship it fails the contract load (`KUI-L090`) rather than guessing.
+
+## Component packages
+
+`KUI-L103` is not limited to `kui-*` classes. Every application or third-party composition catalog your `.kerf-ui-profile.json` declares under `catalogs` contributes its entries' public classes the same way: an `acme-meter` class on your own `<div>` is reported with the package's component to render (`Meter`), its `boundaries.placeableClasses` stay allowed, and its `boundaries.rootElement` reports a placeable class on a plain element of the tag the component renders. Component packages declare these fields in `kerf.components.json`; see the component-packages guide (`docs/13-component-packages.md` §13.7). The first catalog to list a class owns it, so `@kerfjs/ui`'s catalog wins over a declared one. `KUI-L101` (private/unknown class) still applies only to `kui-*` names.
+
+String class values are inspected in `class` / `className` literals and in a template literal's static, whitespace-delimited names (``class={`kui-content-item ${extra}`}``); a name an interpolation completes (`` `kui-toolbar-${size}` ``) is not known and is skipped.
+
+The no-build `kerfjs/html` tagged template writes the same markup without JSX, so its `class` attributes carry the same `KUI-L101` / `KUI-L103` contract. The rule reads the template's static parts by the runtime's own rules: a complete static value (`class="kui-pane"`, `class='…'`, or unquoted) counts, tag and attribute names are case-insensitive, and the element is the tag the markup names, so a plain `<div class="kui-content-item">` is `ContentItem` recreated there too. A hole is a whole attribute value (`class=${cls}`), so the class it supplies is unknown and skipped; comments, text, and tags or attributes whose name is a hole are not inspected. Only the `html` tag imported from `kerfjs/html` (by name, alias, or namespace) is read.
+
+```ts
+import { html } from 'kerfjs/html';
+html`<aside class="kui-pane">…</aside>`;          // KUI-L103: render `Pane`
+html`<div class="kui-content-item">…</div>`;      // KUI-L103: render `ContentItem`
+html`<ul class="kui-content-item">…</ul>`;        // allowed: placeable on a <ul>
+html`<aside class=${paneClass}>…</aside>`;        // not inspected: the value is a hole
+```
+
+The rule reads `@kerfjs/ui/ai/component-composition.json` by default. See the plugin README for alternate catalog settings used by monorepos and package authors.

package/docs/rules/ui-wiring.md

@@ -2,4 +2,4 @@
 
 Checks wiring obligations published by the versioned composition catalog. `KUI-L401` reports a used component whose required helper or side-effect registration import is absent. `KUI-L402` reports a helper call whose disposer is discarded.
 
-Assign, return, or otherwise retain a disposer when the binding has a shorter lifetime than the page. A `void` call is accepted as an explicit page-lifetime choice. The rule derives valid helper sources from each v1 entry's `publicExports` and `wiring[].import` facts, so aliases, root named imports, root namespaces, wiring-subpath named imports, and wiring-subpath namespaces resolve without a second hard-coded export table. It does not attempt flow-sensitive cleanup proof and offers no autofix.
+Assign, return, or otherwise retain a disposer when the binding has a shorter lifetime than the page. A `void` call is accepted as an explicit page-lifetime choice. The rule derives valid helper sources from each component-catalog entry's `publicExports` and `wiring[].import` facts, so aliases, root named imports, root namespaces, wiring-subpath named imports, and wiring-subpath namespaces resolve without a second hard-coded export table. It does not attempt flow-sensitive cleanup proof and offers no autofix.

package/index.js

@@ -6,6 +6,7 @@ import preferAttrSelector from './lib/rules/prefer-attr-selector.js';
 import preferModuleJsxAugmentation from './lib/rules/prefer-module-jsx-augmentation.js';
 import requireDataKeyInEach from './lib/rules/require-data-key-in-each.js';
 import requireDelegateDisposer from './lib/rules/require-delegate-disposer.js';
+import uiComponentOwnership from './lib/rules/ui-component-ownership.js';
 import uiComposition from './lib/rules/ui-composition.js';
 import uiCssValues from './lib/rules/ui-css-values.js';
 import uiPreferences from './lib/rules/ui-preferences.js';
@@ -13,7 +14,7 @@ import uiPublicBoundaries from './lib/rules/ui-public-boundaries.js';
 import uiWiring from './lib/rules/ui-wiring.js';
 
 const plugin = {
-  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.56' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.58' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
@@ -23,6 +24,7 @@ const plugin = {
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
     'prefer-attr-selector': preferAttrSelector,
     'ai-assistant-configs': aiAssistantConfigs,
+    'ui-component-ownership': uiComponentOwnership,
     'ui-composition': uiComposition,
     'ui-css-values': uiCssValues,
     'ui-preferences': uiPreferences,
@@ -63,6 +65,7 @@ plugin.configs.recommended = {
 const recommendedUiRules = {
   ...recommendedRules,
   'kerfjs/ui-public-boundaries': 'error',
+  'kerfjs/ui-component-ownership': 'error',
   'kerfjs/ui-composition': 'error',
   'kerfjs/ui-css-values': 'error',
   'kerfjs/ui-preferences': 'warn',

package/lib/html-template-classes.js

@@ -0,0 +1,104 @@
+// The `class` attributes a `kerfjs/html` tagged template writes, read from its
+// static parts. It follows the runtime's static-part rules
+// (`src/utils/parseTemplate.ts`): markup is text, open tags, and comments; a
+// `${…}` hole is a whole attribute value (`class=${x}` / `class="${x}"`), so
+// a class it supplies is unknown and skipped. A complete static value
+// (`class="kui-pane"`) counts in full; when a hole interrupts a value (which
+// the runtime rejects as a partial value) only the whitespace-delimited names
+// the static text completes count, as for a JSX template literal. Tags whose
+// name is a hole, and holes inside comments, are not markup and are skipped.
+
+const HOLE = '\0';
+
+const isSpace = (ch) => /\s/.test(ch);
+
+// `{ quasi, tag, value }` for every `class` attribute, where `quasi` is the
+// index of the static part the attribute name starts in, `tag` the lowercased
+// element name, and `value` the attribute value with each hole as `\0`.
+export function htmlTemplateClassAttributes(strings) {
+  const text = strings.join(HOLE);
+  // Offset where each static part starts in `text`.
+  const starts = [];
+  let offset = 0;
+  for (const part of strings) {
+    starts.push(offset);
+    offset += part.length + 1;
+  }
+  const quasiAt = (position) => {
+    let index = 0;
+    while (index + 1 < starts.length && starts[index + 1] <= position)
+      index += 1;
+    return index;
+  };
+  const attributes = [];
+  let i = 0;
+  while (i < text.length) {
+    if (text[i] !== '<') {
+      i += 1;
+      continue;
+    }
+    if (text.startsWith('<!--', i)) {
+      const end = text.indexOf('-->', i + 4);
+      i = end === -1 ? text.length : end + 3;
+      continue;
+    }
+    if (!/[a-zA-Z]/.test(text[i + 1] ?? '')) {
+      // A closing tag, `<!DOCTYPE`, `<?…`, or a tag-name hole: skip it whole.
+      if (/[!/?]/.test(text[i + 1] ?? '')) {
+        const end = text.indexOf('>', i + 1);
+        i = end === -1 ? text.length : end + 1;
+      } else i += 1;
+      continue;
+    }
+    let j = i + 1;
+    while (j < text.length && !/[\s/>]/.test(text[j]) && text[j] !== HOLE)
+      j += 1;
+    const tag = text.slice(i + 1, j).toLowerCase();
+    // A hole completing the tag name (`<div${x}>`) makes it unknown.
+    const knownTag = text[j] !== HOLE;
+    // Attributes until the tag closes.
+    while (j < text.length && text[j] !== '>') {
+      if (isSpace(text[j]) || text[j] === '/' || text[j] === HOLE) {
+        j += 1;
+        continue;
+      }
+      const nameStart = j;
+      while (j < text.length && !/[\s"'<>/=]/.test(text[j]) && text[j] !== HOLE)
+        j += 1;
+      if (j === nameStart) {
+        // A stray quote or `=` with no name; step past it.
+        j += 1;
+        continue;
+      }
+      const name = text.slice(nameStart, j).toLowerCase();
+      // A hole completing the name (`data-${x}=…`) makes it unknown.
+      const knownName = text[j] !== HOLE;
+      let k = j;
+      while (k < text.length && isSpace(text[k])) k += 1;
+      if (text[k] !== '=') continue;
+      k += 1;
+      while (k < text.length && isSpace(text[k])) k += 1;
+      let value;
+      if (text[k] === '"' || text[k] === "'") {
+        const end = text.indexOf(text[k], k + 1);
+        value = text.slice(k + 1, end === -1 ? text.length : end);
+        j = end === -1 ? text.length : end + 1;
+      } else {
+        let end = k;
+        while (end < text.length && !/[\s>]/.test(text[end])) end += 1;
+        value = text.slice(k, end);
+        j = end;
+      }
+      if (knownTag && knownName && name === 'class')
+        attributes.push({ quasi: quasiAt(nameStart), tag, value });
+    }
+    i = j + 1;
+  }
+  return attributes;
+}
+
+// The class names a value states outright: whitespace-delimited names no hole
+// touches.
+export function staticClassNames(value) {
+  return value.split(/\s+/).filter((name) => name && !name.includes(HOLE));
+}

package/lib/rules/ui-component-ownership.js

@@ -0,0 +1,199 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import {
+  isExcepted,
+  loadUiContract,
+  UI_CONTRACT_LOAD_CODE,
+  UI_RULE_SCHEMA,
+} from '../ui-contract.js';
+
+const PRIVATE_CODE = 'KUI-L020';
+const TYPED_CODE = 'KUI-L021';
+
+const kebab = (value) =>
+  value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+// The same catalog-derived facts `kerf-ui-analyze` uses for KUI-L020 /
+// KUI-L021 (`@kerfjs/ui/analyzer/component-ownership.mjs`): every root-like
+// public class names a component, `--_<root>-*` is that component's private
+// variable, and `--<root>-<prop>` is the token its typed `<prop>` sets.
+const factsCache = new WeakMap();
+function ownershipFacts(contract) {
+  if (factsCache.has(contract)) return factsCache.get(contract);
+  const privatePrefixes = [];
+  const typedTokens = new Map();
+  for (const entry of contract.entries.values()) {
+    const boundaries = entry.boundaries ?? {};
+    const roots = [
+      ...new Set(
+        [boundaries.rootClass, ...(boundaries.publicClasses ?? [])].filter(
+          (name) => name && !name.includes('__') && !name.includes('--'),
+        ),
+      ),
+    ];
+    const tokens = new Set(boundaries.publicTokens ?? []);
+    for (const root of roots) {
+      privatePrefixes.push({ prefix: `--_${root}`, entry });
+      for (const contractProp of entry.cssValueProps ?? []) {
+        const [head] = contractProp.path.split('[].');
+        const token = `--${root}-${kebab(head)}`;
+        if (tokens.has(token) && !typedTokens.has(token))
+          typedTokens.set(token, { entry, path: contractProp.path });
+      }
+    }
+  }
+  privatePrefixes.sort((a, b) => b.prefix.length - a.prefix.length);
+  const facts = { privatePrefixes, typedTokens };
+  factsCache.set(contract, facts);
+  return facts;
+}
+
+const packageNames = new Map();
+function ownPackage(filename) {
+  for (
+    let directory = dirname(resolve(filename));
+    ;
+    directory = dirname(directory)
+  ) {
+    if (packageNames.has(directory)) return packageNames.get(directory);
+    const manifest = resolve(directory, 'package.json');
+    if (existsSync(manifest)) {
+      let name;
+      try {
+        name = JSON.parse(readFileSync(manifest, 'utf8')).name;
+      } catch {
+        name = undefined;
+      }
+      if (typeof name === 'string') {
+        packageNames.set(directory, name);
+        return name;
+      }
+    }
+    if (dirname(directory) === directory) return undefined;
+  }
+}
+
+const gap = (entry) =>
+  `If no configuration covers this need, report the component gap to ${entry?.package ?? '@kerfjs/ui'} (open a feature request) instead of overriding it.`;
+
+export default {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        "Keep code from reaching into a Kerf UI component's private variables or overriding a token its typed prop configures.",
+      url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/ui-component-ownership.md',
+    },
+    schema: UI_RULE_SCHEMA,
+    messages: {
+      config: `${UI_CONTRACT_LOAD_CODE}: Kerf UI catalog/profile could not be loaded: {{error}}`,
+      private: `${PRIVATE_CODE}: \`{{name}}\` is {{owner}}'s private variable; components own their styles. Configure it through its typed props, variants, or public tokens. {{gap}}`,
+      typed: `${TYPED_CODE}: \`{{name}}\` is what {{component}}'s typed \`{{prop}}\` prop sets; set the prop on {{component}} instead of overriding the token. {{gap}}`,
+    },
+  },
+  create(context) {
+    const contract = loadUiContract(context);
+    const filename = context.filename ?? context.getFilename();
+    let configured = false;
+    if (contract.error)
+      return {
+        Program(node) {
+          if (configured) return;
+          configured = true;
+          context.report({
+            node,
+            messageId: 'config',
+            data: { error: contract.error },
+          });
+        },
+      };
+    const facts = ownershipFacts(contract);
+    const own = ownPackage(filename);
+    const checkPrivate = !isExcepted(contract, PRIVATE_CODE, filename);
+    const checkTyped = !isExcepted(contract, TYPED_CODE, filename);
+
+    const privateOwner = (name) => {
+      const match = facts.privatePrefixes.find(
+        ({ prefix }) => name === prefix || name.startsWith(`${prefix}-`),
+      );
+      if (match) return match.entry;
+      return name.startsWith('--_kui-') ? null : undefined;
+    };
+    const reportPrivate = (node, text) => {
+      if (!checkPrivate) return;
+      for (const [name] of text.matchAll(/--_[a-z0-9_-]+/gi)) {
+        const owner = privateOwner(name);
+        if (owner === undefined || (owner && owner.package === own)) continue;
+        context.report({
+          node,
+          messageId: 'private',
+          data: {
+            name,
+            owner: owner ? owner.name : 'a Kerf component',
+            gap: gap(owner),
+          },
+        });
+      }
+    };
+    const reportTyped = (node, token) => {
+      if (!checkTyped) return;
+      const typed = facts.typedTokens.get(token);
+      if (!typed || typed.entry.package === own) return;
+      context.report({
+        node,
+        messageId: 'typed',
+        data: {
+          name: token,
+          component: typed.entry.name,
+          prop: typed.path,
+          gap: gap(typed.entry),
+        },
+      });
+    };
+    const inspectText = (node, text) => {
+      if (typeof text !== 'string') return;
+      reportPrivate(node, text);
+      // `--token: value` inside a style string assigns the token.
+      for (const [, token] of text.matchAll(/(--[a-z0-9-]+)\s*:/gi))
+        reportTyped(node, token);
+    };
+    const keyName = (property) =>
+      property.computed
+        ? property.key.type === 'Literal'
+          ? property.key.value
+          : undefined
+        : (property.key.name ?? property.key.value);
+
+    return {
+      Literal(node) {
+        if (node.parent?.type === 'Property' && node.parent.key === node)
+          return;
+        inspectText(node, node.value);
+      },
+      TemplateElement(node) {
+        inspectText(node, node.value.raw);
+      },
+      // `style={{ '--kui-list-gap': … }}` and any object keyed by a token.
+      Property(node) {
+        const key = keyName(node);
+        if (typeof key !== 'string' || !key.startsWith('--')) return;
+        reportPrivate(node.key, key);
+        reportTyped(node.key, key);
+      },
+      // `element.style.setProperty('--kui-list-gap', …)`.
+      CallExpression(node) {
+        const callee = node.callee;
+        const [first] = node.arguments;
+        if (
+          callee.type === 'MemberExpression' &&
+          !callee.computed &&
+          callee.property.name === 'setProperty' &&
+          first?.type === 'Literal' &&
+          typeof first.value === 'string'
+        )
+          reportTyped(first, first.value);
+      },
+    };
+  },
+};

package/lib/rules/ui-preferences.js

@@ -1,4 +1,7 @@
+import { resolve } from 'node:path';
+
 import {
+  customElementKey,
   importRegistry,
   isExcepted,
   jsxKey,
@@ -39,7 +42,12 @@ export default {
       },
       JSXOpeningElement(node) {
         if (!registry || isExcepted(contract, CODE, filename)) return;
-        const actual = jsxKey(node.name, registry, contract);
+        // A declared component's own source is the wrapper that owns the
+        // element it renders; the preference governs its callers.
+        if (contract.componentSources.has(resolve(filename))) return;
+        const actual =
+          jsxKey(node.name, registry, contract) ??
+          customElementKey(node.name, contract);
         if (!actual) return;
         for (const [concept, preference] of Object.entries(
           contract.profile.preferences ?? {},

package/lib/rules/ui-public-boundaries.js

@@ -1,12 +1,37 @@
 import {
+  importRegistry,
   isExcepted,
+  jsxKey,
   loadUiContract,
   UI_CONTRACT_LOAD_CODE,
   UI_RULE_SCHEMA,
 } from '../ui-contract.js';
+import {
+  htmlTemplateClassAttributes,
+  staticClassNames,
+} from '../html-template-classes.js';
 
 const CLASS_CODE = 'KUI-L101';
 const TOKEN_CODE = 'KUI-L102';
+const PLACEMENT_CODE = 'KUI-L103';
+
+const HTML_SOURCE = 'kerfjs/html';
+
+// The `html` tag imported from `kerfjs/html`, by name or through a namespace.
+function isHtmlTag(tag, registry) {
+  if (tag.type === 'Identifier') {
+    const helper = registry.helpers.get(tag.name);
+    return helper?.imported === 'html' && helper.source === HTML_SOURCE;
+  }
+  return (
+    tag.type === 'MemberExpression' &&
+    !tag.computed &&
+    tag.object.type === 'Identifier' &&
+    tag.property.type === 'Identifier' &&
+    tag.property.name === 'html' &&
+    registry.namespaces.get(tag.object.name) === HTML_SOURCE
+  );
+}
 
 export default {
   meta: {
@@ -23,21 +48,70 @@ export default {
         'KUI-L101: `{{name}}` is private or uncataloged Kerf UI anatomy. Use a cataloged public class, prop, token, or component instead.',
       token:
         'KUI-L102: `{{name}}` is not a cataloged public Kerf UI token. Use a public semantic/component token.',
+      component:
+        "KUI-L103: `{{name}}` is {{component}}'s rendered anatomy, not a class to place on your own element. Render {{render}} and configure it through its props; components own their styles.",
+      componentRoot:
+        'KUI-L103: a plain `<{{element}}>` carrying `{{name}}` is exactly what {{component}} renders. Render {{render}} instead; the class stays placeable only on another carrier element (such as a `<ul>` or a `<footer>`).',
     },
   },
   create(context) {
     const contract = loadUiContract(context);
     const filename = context.filename ?? context.getFilename();
     let configured = false;
-    const inspect = (node, value, classContext = false) => {
+    let registry;
+    // A cataloged component's anatomy class on an element the application
+    // writes recreates the component by class instead of rendering it. The
+    // component's own element (`<Toolbar className="kui-toolbar">`) is exempt.
+    // A placeable class whose entry names a `rootElement` is reported only on
+    // a plain element of that tag (`<div class="kui-content-item">` is
+    // ContentItem); another carrier element keeps it.
+    // `element` is the JSX opening element (or `{ tag }` for markup a
+    // `kerfjs/html` template writes) that carries the class.
+    const inspectPlacement = (node, names, element) => {
+      if (isExcepted(contract, PLACEMENT_CODE, filename)) return;
+      const opening = element?.type === 'JSXOpeningElement';
+      const renderedKey =
+        registry && opening
+          ? jsxKey(element.name, registry, contract)
+          : undefined;
+      const intrinsicTag = opening
+        ? element.name.type === 'JSXIdentifier'
+          ? element.name.name
+          : undefined
+        : element?.tag;
+      for (const name of names) {
+        const owner = contract.componentClasses?.get(name);
+        if (!owner || owner.key === renderedKey) continue;
+        if (owner.element && owner.element !== intrinsicTag) continue;
+        context.report({
+          node,
+          messageId: owner.element ? 'componentRoot' : 'component',
+          data: {
+            name,
+            element: owner.element,
+            component: owner.render.join(' / '),
+            render: owner.render.map((item) => `\`${item}\``).join(' or '),
+          },
+        });
+      }
+    };
+    const inspect = (
+      node,
+      value,
+      classContext = false,
+      tokens = true,
+      element = node.parent,
+    ) => {
       if (typeof value !== 'string') return;
+      const names = classContext ? value.split(/\s+/).filter(Boolean) : [];
       if (classContext && !isExcepted(contract, CLASS_CODE, filename))
-        for (const name of value
-          .split(/\s+/)
-          .filter((item) => item.startsWith('kui-')))
-          if (!contract.publicClasses.has(name))
+        for (const name of names)
+          if (name.startsWith('kui-') && !contract.publicClasses.has(name))
             context.report({ node, messageId: 'class', data: { name } });
-      if (!isExcepted(contract, TOKEN_CODE, filename))
+      // Placement covers every cataloged class, not only `kui-*`: a declared
+      // component package's anatomy (`acme-meter`) is checked the same way.
+      if (classContext) inspectPlacement(node, names, element);
+      if (tokens && !isExcepted(contract, TOKEN_CODE, filename))
         for (const match of value.matchAll(/--kui-[a-z0-9-]+/g))
           if (!contract.publicTokens.has(match[0]))
             context.report({
@@ -56,6 +130,8 @@ export default {
             data: { error: contract.error },
           });
         }
+        if (!contract.error)
+          registry = importRegistry(node, contract, filename);
       },
       JSXAttribute(node) {
         if (contract.error || !['class', 'className'].includes(node.name?.name))
@@ -67,6 +143,43 @@ export default {
           node.value.expression.type === 'Literal'
         )
           inspect(node, node.value.expression.value, true);
+        // A template literal's static, whitespace-delimited class names
+        // (`class={`kui-content-item ${extra}`}`); a name an interpolation
+        // completes (`kui-toolbar-${size}`) is not known and is skipped.
+        if (
+          node.value?.type === 'JSXExpressionContainer' &&
+          node.value.expression.type === 'TemplateLiteral'
+        )
+          inspect(
+            node,
+            staticClassNames(
+              node.value.expression.quasis
+                .map((quasi) => quasi.value.cooked ?? quasi.value.raw)
+                .join('\0'),
+            ).join(' '),
+            true,
+            // Its tokens are inspected once, by TemplateElement below.
+            false,
+          );
+      },
+      // `kerfjs/html` tagged templates write the same markup without JSX:
+      // their static `class` attributes are inspected like JSX `class`
+      // values, on the plain element that carries them. Tokens are left to
+      // TemplateElement below.
+      TaggedTemplateExpression(node) {
+        if (contract.error || !registry || !isHtmlTag(node.tag, registry))
+          return;
+        const { quasis } = node.quasi;
+        for (const { quasi, tag, value } of htmlTemplateClassAttributes(
+          quasis.map((item) => item.value.cooked ?? item.value.raw),
+        ))
+          inspect(
+            quasis[quasi],
+            staticClassNames(value).join(' '),
+            true,
+            false,
+            { tag },
+          );
       },
       Literal(node) {
         if (!contract.error) inspect(node, node.value, false);

package/lib/ui-contract.js

@@ -125,6 +125,24 @@ function discoveredProfiles(cwd, filename, settings) {
   return layers;
 }
 
+// `@kerfjs/ui`'s class-to-component rule ships beside its profile contract.
+// An older `@kerfjs/ui` without it cannot report KUI-L103 consistently, so it
+// fails the contract load instead of guessing.
+function loadClassOwnership(profileContractPath) {
+  const path = resolve(
+    dirname(profileContractPath),
+    'component-class-owners.cjs',
+  );
+  if (!existsSync(path))
+    throw new Error(
+      `Cannot find ${path}; install an @kerfjs/ui release that matches eslint-plugin-kerfjs.`,
+    );
+  const { componentClassOwnership } = loadCommonJs(path);
+  if (typeof componentClassOwnership !== 'function')
+    throw new Error(`${path} does not export componentClassOwnership.`);
+  return componentClassOwnership;
+}
+
 export function loadUiContract(context) {
   const settings = context.settings?.kerfjs?.ui ?? {};
   const cwd = settings.workspaceRoot ?? context.cwd ?? process.cwd();
@@ -135,7 +153,7 @@ export function loadUiContract(context) {
     const catalog =
       settings.catalog ??
       readJson(
-        settings.catalogPath ?? packageAsset(cwd, 'component-catalog-v2.json'),
+        settings.catalogPath ?? packageAsset(cwd, 'component-composition.json'),
       );
     const selection =
       settings.selectionCatalog ??
@@ -190,6 +208,20 @@ export function loadUiContract(context) {
     // `<absolute source file>\0<Export>` to the entry key.
     const packageExports = new Map();
     const sourceExports = new Map();
+    // Source files of declared components: a wrapper's own source may render
+    // the element it wraps (Kerf's PopupMenu renders `wa-dropdown`).
+    const componentSources = new Set();
+    // Every cataloged entry whose public classes may be a component's rendered
+    // anatomy: the base catalog's (exports from the selection catalog) and each
+    // declared application/third-party catalog's (exports on the entry).
+    const classOwnerEntries = catalog.entries.map((entry) => ({
+      key: entry.key,
+      name: entry.name,
+      boundaries: entry.boundaries,
+      exports: (
+        selection.entries.find(({ id }) => id === entry.id)?.publicExports ?? []
+      ).map(exportName),
+    }));
     for (const { artifact, root } of profileCatalogs(
       loadedProfile,
       selection.package,
@@ -197,6 +229,12 @@ export function loadUiContract(context) {
       for (const entry of artifact.entries ?? []) {
         const key = entry.key ?? `${artifact.package}:${entry.id}`;
         entries.set(key, entry);
+        classOwnerEntries.push({
+          key,
+          name: entry.name,
+          boundaries: entry.boundaries,
+          exports: (entry.publicExports ?? []).map(exportName),
+        });
         for (const item of entry.publicExports ?? []) {
           const name = exportName(item);
           if (!name || !isComponentExport(name)) continue;
@@ -210,12 +248,17 @@ export function loadUiContract(context) {
                 : (entry.package ?? artifact.package);
             packageExports.set(`${specifier}\0${name}`, key);
           }
-          if (entry.source)
+          if (entry.source) {
             sourceExports.set(`${resolve(root, entry.source)}\0${name}`, key);
+            componentSources.add(resolve(root, entry.source));
+          }
         }
       }
     const imports = new Map();
     const exports = new Map();
+    // Custom-element tag -> entry key, for elements authored directly in JSX
+    // (`<wa-dropdown>`) rather than through an imported component.
+    const customElements = new Map();
     const helperSources = new Map();
     const addHelperSource = (name, source) => {
       const sources = helperSources.get(name) ?? new Set();
@@ -224,6 +267,7 @@ export function loadUiContract(context) {
     };
     for (const entry of selection.entries) {
       const key = `${selection.package}:${entry.id}`;
+      if (entry.customElement) customElements.set(entry.customElement, key);
       if (entry.delivery?.browserImport)
         imports.set(entry.delivery.browserImport, key);
       if (entry.delivery?.moduleImport)
@@ -242,12 +286,18 @@ export function loadUiContract(context) {
       exports,
       packageExports,
       sourceExports,
+      componentSources,
+      customElements,
       helperSources,
       profile,
       cwd,
       publicClasses: new Set(
         catalog.entries.flatMap((entry) => entry.boundaries.publicClasses),
       ),
+      componentClasses: componentClassOwners(
+        classOwnerEntries,
+        loadClassOwnership(profileContractPath),
+      ),
       publicTokens: new Set(
         catalog.entries.flatMap((entry) => entry.boundaries.publicTokens),
       ),
@@ -262,6 +312,32 @@ export function loadUiContract(context) {
   }
 }
 
+// Public classes that are a component's rendered anatomy — `@kerfjs/ui`'s
+// `kui-*` classes and any class a declared application or third-party catalog
+// lists (`acme-meter`) — mapped to the entry and the export that renders it.
+// Which classes an entry owns, and which export renders each, is
+// `@kerfjs/ui`'s shared rule (`ai/component-class-owners.cjs`), the same one
+// its generated component reference pages use. The first catalog to claim a
+// class owns it, so the base catalog wins over a declared one.
+function componentClassOwners(classOwnerEntries, componentClassOwnership) {
+  const owners = new Map();
+  for (const entry of classOwnerEntries)
+    for (const { className, render, element } of componentClassOwnership({
+      name: entry.name,
+      exports: entry.exports,
+      publicClasses: entry.boundaries?.publicClasses,
+      placeableClasses: entry.boundaries?.placeableClasses,
+      rootElement: entry.boundaries?.rootElement,
+    }))
+      if (!owners.has(className))
+        owners.set(className, {
+          key: entry.key,
+          render,
+          ...(element ? { element } : {}),
+        });
+  return owners;
+}
+
 export function importRegistry(program, contract, filename) {
   const locals = new Map();
   const namespaces = new Map();
@@ -405,6 +481,14 @@ export function jsxKey(name, registry, contract) {
   return undefined;
 }
 
+// A custom element authored directly as a lowercase JSX tag resolves to its
+// selection-catalog entry. Kept separate from `jsxKey` so composition rules
+// keep treating raw elements as application-owned markup.
+export function customElementKey(name, contract) {
+  if (name.type !== 'JSXIdentifier' || !name.name.includes('-')) return;
+  return contract.customElements?.get(name.name);
+}
+
 export function helperCall(callee, registry, contract) {
   let imported;
   let source;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-kerfjs",
-  "version": "5.0.0-beta.56",
+  "version": "5.0.0-beta.58",
   "description": "ESLint rules that enforce kerf's hard rules — catches AI-shaped bugs at edit time.",
   "type": "module",
   "license": "MIT",