eslint-plugin-kerfjs 5.0.0-beta.5 → 5.0.0-beta.51

package/README.md

@@ -7,18 +7,19 @@ ESLint rules that enforce kerf's hard rules. Catches AI-shaped bugs at edit time
 
 This plugin sits alongside two other defense layers shipped by [`kerfjs`](https://brianwestphal.github.io/kerf/):
 
-| Layer | Catches | When |
-|---|---|---|
-| `tsc --noEmit` with strict typings | Hard Rules 8 (partial-set), most type errors | Build time |
-| 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** |
+| Layer                                | Catches                                                                                                                                                          | When          |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
+| `tsc --noEmit` with strict typings   | Hard Rules 8 (partial-set), most type errors                                                                                                                     | Build time    |
+| 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.
+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.
 
 ## Install
 
 ```bash
 npm install --save-dev eslint-plugin-kerfjs
+npm install @kerfjs/ui
 ```
 
 ### Supported ESLint versions
@@ -33,12 +34,12 @@ A version outside the range is not "probably fine" — it is one nobody has run.
 
 ```js
 // eslint.config.js
-import kerfjs from 'eslint-plugin-kerfjs';
-import tsParser from '@typescript-eslint/parser';
+import kerfjs from "eslint-plugin-kerfjs";
+import tsParser from "@typescript-eslint/parser";
 
 export default [
   {
-    files: ['**/*.ts', '**/*.tsx'],
+    files: ["**/*.ts", "**/*.tsx"],
     languageOptions: {
       parser: tsParser,
       parserOptions: { ecmaFeatures: { jsx: true } },
@@ -48,25 +49,64 @@ export default [
 ];
 ```
 
+Applications using the UI catalog can select one of two additive flat configs:
+
+```js
+export default [
+  // parser/files configuration as above
+  kerfjs.configs['recommended-ui'], // preferences and wiring are warnings
+  // or kerfjs.configs['strict-ui']  // all UI contracts are errors
+];
+```
+
+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:
+
+```js
+settings: {
+  kerfjs: {
+    ui: {
+      workspaceRoot: import.meta.dirname,
+      catalogPath: './vendor/component-catalog-v2.json',
+      selectionCatalogPath: './vendor/component-catalog.json',
+      profileDefaultsPath: './vendor/application-ui-profile.defaults.json',
+      profileContractPath: './vendor/application-ui-profile-sync.cjs',
+    },
+  },
+}
+```
+
+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.
+
+`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.
+
+`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
 
-The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with *"couldn't find the config to extend from"* on ESLint 8 **and** on ESLint 9's legacy mode.
+The package is ESM-only. ESLint's `.eslintrc` system loads plugins with `require()`, which cannot load an ESM package, so `extends: ["plugin:kerfjs/legacy-recommended"]` fails with _"couldn't find the config to extend from"_ on ESLint 8 **and** on ESLint 9's legacy mode.
 
 Use flat config (`eslint.config.js`), shown above. The `legacy-recommended` export still exists in the package but is unreachable through any config system — treat it as deprecated.
 
-
 ## 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` |
+| 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`                 |
 
 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.
 

package/docs/rules/ai-assistant-configs.md

@@ -10,10 +10,10 @@ Maps to design doc [`docs/12-ai-assistant-configs.md`](https://github.com/brianw
 
 The rule resolves `kerfjs/ai/manifest.json` from the consumer's installed `kerfjs` (silently no-ops if `kerfjs` isn't a dep). For each bundled file, it picks a trigger heuristic — "is this project using the tool this file is for?" — and only nudges the consumer when the trigger says yes:
 
-| Bundled file | Triggers when | Installed to |
-|---|---|---|
-| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root | `.claude/skills/kerf-app/SKILL.md` |
-| `ai/cursorrules` (Cursor) | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules` |
+| Bundled file                | Triggers when                                      | Installed to                       |
+| --------------------------- | -------------------------------------------------- | ---------------------------------- |
+| `ai/skill.md` (Claude Code) | `.claude/` directory exists at the project root    | `.claude/skills/kerf-app/SKILL.md` |
+| `ai/cursorrules` (Cursor)   | `.cursorrules` file or `.cursor/` directory exists | `.cursorrules`                     |
 
 A triggered file is then classified into one of three reported states (a fourth, "up-to-date," is silent):
 
@@ -78,4 +78,4 @@ Both `claude` and `cursor` default to `true`. Setting either to `false` makes th
 - It does not install the configs at `npm install` time — there are no postinstall scripts. The first lint pass after `npm install kerfjs` surfaces the recommendation.
 - It does not write to disk under plain `eslint` (no `--fix`). The warning is emitted; nothing changes on disk.
 - It does not push Claude Code or Cursor on consumers who haven't signalled they use them — no `.claude/` or `.cursor*` ⇒ silent.
-- It does not validate the *content* of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).
+- It does not validate the _content_ of the canonical files in the bundle. That's the kerf maintainer's responsibility (and the `check:ai-bundle-in-sync` gate in the kerf repo).

package/docs/rules/no-inline-jsx-event-handlers.md

@@ -40,8 +40,8 @@ delegate(rootEl, 'submit', ACTIONS.submit.selector,  submit);
 String literals still work for ad-hoc fixed selectors:
 
 ```tsx
-<button data-action="save">Save</button>
-delegate(rootEl, 'click', '[data-action="save"]', save);
+<button data-action="save">Save</button>;
+delegate(rootEl, "click", '[data-action="save"]', save);
 ```
 
 ## Why this rule is AST-only

package/docs/rules/no-nested-mount.md

@@ -24,7 +24,12 @@ mount(bodyRoot, () => <Body />);
 
 // Composition via plain functions:
 const Header = () => <h1>{title.value}</h1>;
-const Body = () => <main><Header /><div>{count.value}</div></main>;
+const Body = () => (
+  <main>
+    <Header />
+    <div>{count.value}</div>
+  </main>
+);
 mount(root, () => <Body />);
 ```
 

package/docs/rules/no-raw-with-dynamic-arg.md

@@ -9,21 +9,21 @@ Warn when `raw()` is called with a dynamic argument (any expression that is not
 ## ❌ Incorrect
 
 ```ts
-raw(userInput)                     // variable reference
-raw(fetchedHtml())                 // function call
-raw(`<b>${title}</b>`)             // template literal with expressions
-raw(isAdmin ? adminHtml : guestHtml)  // conditional expression
+raw(userInput); // variable reference
+raw(fetchedHtml()); // function call
+raw(`<b>${title}</b>`); // template literal with expressions
+raw(isAdmin ? adminHtml : guestHtml); // conditional expression
 ```
 
 ## ✅ Correct
 
 ```ts
-raw('<p>Static markup</p>')        // string literal — no warning
-raw(`<p>Static template</p>`)      // expression-free template literal — no warning
+raw("<p>Static markup</p>"); // string literal — no warning
+raw(`<p>Static template</p>`); // expression-free template literal — no warning
 
 // Dynamic but audited — suppress with eslint-disable
 // eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg
-raw(DOMPurify.sanitize(marked(userMarkdown)))
+raw(DOMPurify.sanitize(marked(userMarkdown)));
 ```
 
 ## Why `warn` and not `error`

package/docs/rules/prefer-attr-selector.md

@@ -7,8 +7,8 @@ Prefer `attr('name', 'value').selector` over a literal `[name="value"]` selector
 ## ❌ Discouraged
 
 ```tsx
-<button data-action="toggle">Toggle</button>
-delegate(root, 'click', '[data-action="toggle"]', handler);
+<button data-action="toggle">Toggle</button>;
+delegate(root, "click", '[data-action="toggle"]', handler);
 ```
 
 The JSX attribute and the selector string are two independent literals; renaming the action key in JSX leaves the delegate selector unchanged, and the handler silently stops firing.
@@ -16,14 +16,14 @@ The JSX attribute and the selector string are two independent literals; renaming
 ## ✅ Recommended
 
 ```tsx
-import { attr, delegate, type AttrSpec } from 'kerfjs';
+import { attr, delegate, type AttrSpec } from "kerfjs";
 
 const ACTIONS = {
-  toggle: attr('data-action', 'toggle'),
-} as const satisfies Record<string, AttrSpec<'data-action'>>;
+  toggle: attr("data-action", "toggle"),
+} as const satisfies Record<string, AttrSpec<"data-action">>;
 
-<button {...ACTIONS.toggle.attrs}>Toggle</button>
-delegate(root, 'click', ACTIONS.toggle.selector, handler);
+<button {...ACTIONS.toggle.attrs}>Toggle</button>;
+delegate(root, "click", ACTIONS.toggle.selector, handler);
 ```
 
 Rename `'toggle'` to `'on'` in the `ACTIONS` map and both the rendered attribute and the delegate selector update — no string-grep migration required.

package/docs/rules/prefer-module-jsx-augmentation.md

@@ -10,7 +10,7 @@ Maps to **kerf Hard Rule 11** — kerf's JSX runtime looks up custom-element typ
 declare global {
   namespace JSX {
     interface IntrinsicElements {
-      'my-tag': { foo?: string };
+      "my-tag": { foo?: string };
     }
   }
 }
@@ -19,10 +19,10 @@ declare global {
 ## ✅ Correct
 
 ```ts
-declare module 'kerfjs/jsx-runtime' {
+declare module "kerfjs/jsx-runtime" {
   namespace JSX {
     interface IntrinsicElements {
-      'my-tag': KerfCustomElement & { foo?: string };
+      "my-tag": KerfCustomElement & { foo?: string };
     }
   }
 }
@@ -31,7 +31,11 @@ declare module 'kerfjs/jsx-runtime' {
 Import the building-block types from `kerfjs/jsx-runtime`:
 
 ```ts
-import type { KerfCustomElement, KerfBaseAttrs, AttrLike } from 'kerfjs/jsx-runtime';
+import type {
+  KerfCustomElement,
+  KerfBaseAttrs,
+  AttrLike,
+} from "kerfjs/jsx-runtime";
 ```
 
 ## What this rule does NOT catch

package/docs/rules/require-data-key-in-each.md

@@ -7,24 +7,24 @@ Maps to **kerf Hard Rule 2** — the keyed reconciler matches items by `id` firs
 ## ❌ Incorrect
 
 ```tsx
-each(items, (item) => <li>{item.name}</li>)
+each(items, (item) => <li>{item.name}</li>);
 
 each(items, (item) => {
   return <li class="row">{item.name}</li>;
-})
+});
 
-each(items, (item) => <>{item.name}</>)
+each(items, (item) => <>{item.name}</>);
 ```
 
 ## ✅ Correct
 
 ```tsx
-each(items, (item) => <li data-key={item.id}>{item.name}</li>)
+each(items, (item) => <li data-key={item.id}>{item.name}</li>);
 
-each(items, (item) => <li id={item.id}>{item.name}</li>)
+each(items, (item) => <li id={item.id}>{item.name}</li>);
 
 // Spread attributes are conservatively allowed — they may include the key.
-each(items, (item) => <li {...item.attrs}>{item.name}</li>)
+each(items, (item) => <li {...item.attrs}>{item.name}</li>);
 ```
 
 ## What this rule does NOT catch

package/docs/rules/require-delegate-disposer.md

@@ -2,7 +2,7 @@
 
 Require capturing the disposer returned by `delegate()` and `delegateCapture()`.
 
-Both helpers install a single listener on the root element and return a `() => void` disposer — the *only* way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
+Both helpers install a single listener on the root element and return a `() => void` disposer — the _only_ way to remove the listener once it's attached. Discarding the return value is safe in exactly one case: the registration is genuinely page-lifetime (root is `document.body` or another never-torn-down element, attached once at startup, never re-registered). In every other case the listener closure pins `rootEl`, `handler`, and everything the handler closes over (stores, signals, app state) — so an undisposed delegate on a transient root leaks both the listener and the app graph it references, and re-mount cycles stack listeners linearly. `mount()`'s own disposer does NOT remove delegates for you.
 
 See [kerf docs §5.3 — Disposers](https://brianwestphal.github.io/kerf/docs/5-event-delegation/#53-disposers) for the full rationale.
 
@@ -49,8 +49,8 @@ Or collect into a disposer array:
 ```ts
 const disposers: Array<() => void> = [];
 disposers.push(mount(host, render));
-disposers.push(delegate(host, 'click', '[data-action]', onAction));
-disposers.push(delegate(host, 'keydown', '[data-edit]', onEdit));
+disposers.push(delegate(host, "click", "[data-action]", onAction));
+disposers.push(delegate(host, "keydown", "[data-edit]", onEdit));
 
 function teardown() {
   for (const off of disposers) off();
@@ -64,13 +64,18 @@ If the registration is attached once at module load and the root never tears dow
 
 ```ts
 // 1. The `void` operator as an explicit-discard sigil.
-void delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+void delegate(
+  document.body,
+  "click",
+  ACTIONS.inc.selector,
+  () => count.value++,
+);
 ```
 
 ```ts
 // 2. Standard eslint-disable for one-off cases.
 // eslint-disable-next-line kerfjs/require-delegate-disposer
-delegate(document.body, 'click', ACTIONS.inc.selector, () => count.value++);
+delegate(document.body, "click", ACTIONS.inc.selector, () => count.value++);
 ```
 
 `void` is the lower-friction option when the file has many page-lifetime registrations clustered together; eslint-disable carries the rule name with it, which makes it easier to grep for.

package/docs/rules/ui-composition.md

@@ -0,0 +1,5 @@
+# `ui-composition`
+
+Enforces composition facts published by the versioned UI catalog. `KUI-L201` reports a catalog component under a known, disallowed direct parent. `KUI-L202` reports a statically visible zone child—including an intrinsic or unknown JSX element—that is not one of the zone's cataloged `accepts` entries. `KUI-L203` reports a statically provable zone cardinality violation. A zone participates only when it declares an explicit `jsx.prop` binding, including `children`; the rule never guesses that a zone id is a JSX prop. Toolbar, Pane, TabBar, AppTab, feedback, search, and layout validation is therefore catalog-driven rather than duplicated in rule-local component cases.
+
+The parent check is intentionally conservative: it reports only when both child and direct parent resolve to cataloged imports. Bound zone checks understand aliases, namespace imports, fragments, arrays, and conditional/logical branches, but expressions whose content cannot be resolved statically remain runtime and accessibility work. Accepted concepts that do not identify a catalog entry remain machine-readable guidance while the rule enforces their statically provable cardinality only. No autofix is offered because wrapping or moving UI changes structure and behavior.

package/docs/rules/ui-css-values.md

@@ -0,0 +1,24 @@
+# `ui-css-values`
+
+Checks literal JSX and direct component-function calls against each component's
+cataloged `cssValueProps` contracts. The catalog keeps length, size, flex,
+color, declaration-list, media-query, and numeric-pixel grammars distinct and
+names their accepted helpers, finite shorthands, and raw-value policy.
+
+Stable diagnostics are `KUI-L013` (raw or unknown shorthand), `KUI-L014`
+(wrong property helper), `KUI-L015` (non-standalone expression), `KUI-L016`
+(forbidden declaration list), and review-oriented `KUI-L017` (exceptional
+spacing shorthand). Messages name the preferred shorthand or helper. Dynamic
+values are left to TypeScript rather than guessed.
+
+Only component exports carry an entry's contracts. A catalog entry's
+`publicExports` also lists the helpers its props consume (`Select` ships
+`uiColor`, `List` ships `px`, `rem`, and `flex`); a helper call such as
+`flex({ gap: '12px' })` is not a `List` call and is never checked as one. A
+component export is one whose name starts with an uppercase letter, the rule
+JSX itself uses to tell a component tag from an intrinsic element; a default
+import keeps its subpath's entry. `@kerfjs/ui`'s catalog check enforces the
+convention for the package, and `kerf-ui-analyze` applies the same rule.
+
+Third-party component suites can provide the same contracts in a composition
+catalog through `settings.kerfjs.ui.catalog` and its matching selection catalog.

package/docs/rules/ui-preferences.md

@@ -0,0 +1,5 @@
+# `ui-preferences`
+
+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`.
+
+`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

@@ -0,0 +1,7 @@
+# `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.
+
+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.
+
+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.

package/docs/rules/ui-wiring.md

@@ -0,0 +1,5 @@
+# `ui-wiring`
+
+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.

package/index.js

@@ -6,9 +6,14 @@ 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 uiComposition from './lib/rules/ui-composition.js';
+import uiCssValues from './lib/rules/ui-css-values.js';
+import uiPreferences from './lib/rules/ui-preferences.js';
+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.5' },
+  meta: { name: 'eslint-plugin-kerfjs', version: '5.0.0-beta.51' },
   rules: {
     'no-inline-jsx-event-handlers': noInlineJsxEventHandlers,
     'no-raw-with-dynamic-arg': noRawWithDynamicArg,
@@ -18,6 +23,11 @@ const plugin = {
     'prefer-module-jsx-augmentation': preferModuleJsxAugmentation,
     'prefer-attr-selector': preferAttrSelector,
     'ai-assistant-configs': aiAssistantConfigs,
+    'ui-composition': uiComposition,
+    'ui-css-values': uiCssValues,
+    'ui-preferences': uiPreferences,
+    'ui-public-boundaries': uiPublicBoundaries,
+    'ui-wiring': uiWiring,
   },
   configs: {},
 };
@@ -50,6 +60,26 @@ plugin.configs.recommended = {
   plugins: { kerfjs: plugin },
   rules: recommendedRules,
 };
+const recommendedUiRules = {
+  ...recommendedRules,
+  'kerfjs/ui-public-boundaries': 'error',
+  'kerfjs/ui-composition': 'error',
+  'kerfjs/ui-css-values': 'error',
+  'kerfjs/ui-preferences': 'warn',
+  'kerfjs/ui-wiring': 'warn',
+};
+plugin.configs['recommended-ui'] = {
+  plugins: { kerfjs: plugin },
+  rules: recommendedUiRules,
+};
+plugin.configs['strict-ui'] = {
+  plugins: { kerfjs: plugin },
+  rules: {
+    ...recommendedUiRules,
+    'kerfjs/ui-preferences': 'error',
+    'kerfjs/ui-wiring': 'error',
+  },
+};
 plugin.configs.all = plugin.configs.recommended;
 
 // Legacy `.eslintrc` config — consumers extend `'plugin:kerfjs/legacy-recommended'`.

package/lib/rules/ai-assistant-configs.js

@@ -106,8 +106,10 @@ export function classifyFile(file, bundleDir, cwd) {
   }
 
   const markerIdx = findMarkerIndex(consumer);
-  if (markerIdx === -1) return { state: 'forked', reason: 'no canonical-end marker' };
-  if (markerIdx === -2) return { state: 'forked', reason: 'multiple canonical-end markers' };
+  if (markerIdx === -1)
+    return { state: 'forked', reason: 'no canonical-end marker' };
+  if (markerIdx === -2)
+    return { state: 'forked', reason: 'multiple canonical-end markers' };
 
   const canonicalEnd = canonicalEndOffset(consumer);
   const consumerCanonical = consumer.slice(0, canonicalEnd);
@@ -134,7 +136,10 @@ export function classifyFile(file, bundleDir, cwd) {
       };
     }
     if (consumerCanonicalHash !== historicalHash) {
-      return { state: 'forked', reason: 'content above marker has been edited' };
+      return {
+        state: 'forked',
+        reason: 'content above marker has been edited',
+      };
     }
     return {
       state: 'stale',
@@ -164,7 +169,9 @@ function loadBundle(cwd) {
 function isTriggered(name, cwd) {
   if (name === 'skill') return existsSync(join(cwd, '.claude'));
   if (name === 'cursorrules') {
-    return existsSync(join(cwd, '.cursorrules')) || existsSync(join(cwd, '.cursor'));
+    return (
+      existsSync(join(cwd, '.cursorrules')) || existsSync(join(cwd, '.cursor'))
+    );
   }
   return false;
 }
@@ -220,7 +227,7 @@ const meta = {
     stale:
       '{{tool}} drop-in at `{{dest}}` is stale (have {{consumerVersion}}, latest is {{bundledVersion}}). Run `eslint --fix` to update the canonical section above the `KERF-APP-CANONICAL-END` marker; your customizations below the marker are preserved.',
     forked:
-      '{{tool}} drop-in at `{{dest}}` is forked: {{reason}}. Restore the canonical layout (one `KERF-APP-CANONICAL-END` marker, no edits above it) or disable this rule with `\'kerfjs/ai-assistant-configs\': \'off\'`.',
+      "{{tool}} drop-in at `{{dest}}` is forked: {{reason}}. Restore the canonical layout (one `KERF-APP-CANONICAL-END` marker, no edits above it) or disable this rule with `'kerfjs/ai-assistant-configs': 'off'`.",
   },
   // Mark as fixable so the CLI exposes this rule under `--fix`. The callback
   // writes to a separate file and returns null, so ESLint applies no edit to
@@ -247,7 +254,10 @@ function create(context) {
         if (file.name === 'cursorrules' && !cursorEnabled) continue;
         if (result.state === 'ok') continue;
 
-        const tool = file.name === 'skill' ? 'Claude Code kerf-app skill' : 'Cursor kerf rules';
+        const tool =
+          file.name === 'skill'
+            ? 'Claude Code kerf-app skill'
+            : 'Cursor kerf rules';
         const bundle = file.bundle; // e.g. 'ai/skill.md'
         const data = { tool, dest: file.dest, bundle };
 
@@ -291,9 +301,9 @@ function create(context) {
 
 function contextCwd(context) {
   return (
-    (typeof context.cwd === 'string' && context.cwd)
-    || (typeof context.getCwd === 'function' && context.getCwd())
-    || process.cwd()
+    (typeof context.cwd === 'string' && context.cwd) ||
+    (typeof context.getCwd === 'function' && context.getCwd()) ||
+    process.cwd()
   );
 }
 

package/lib/rules/no-inline-jsx-event-handlers.js

@@ -7,7 +7,7 @@ const meta = {
   type: 'problem',
   docs: {
     description:
-      "Disallow inline `onClick`-style JSX event handler attributes; use `data-action` + `delegate()` instead.",
+      'Disallow inline `onClick`-style JSX event handler attributes; use `data-action` + `delegate()` instead.',
     url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-inline-jsx-event-handlers.md',
   },
   schema: [],

package/lib/rules/no-nested-mount.js

@@ -34,7 +34,8 @@ function create(context) {
       let p = node.parent;
       while (p) {
         if (
-          (p.type === 'ArrowFunctionExpression' || p.type === 'FunctionExpression') &&
+          (p.type === 'ArrowFunctionExpression' ||
+            p.type === 'FunctionExpression') &&
           isMountCall(p.parent) &&
           p.parent.arguments.includes(p)
         ) {

package/lib/rules/no-raw-with-dynamic-arg.js

@@ -22,13 +22,13 @@ const meta = {
   type: 'problem',
   docs: {
     description:
-      "Disallow `raw()` with dynamic arguments; `raw()` bypasses HTML escaping and passing dynamic values is an XSS vector.",
+      'Disallow `raw()` with dynamic arguments; `raw()` bypasses HTML escaping and passing dynamic values is an XSS vector.',
     url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/no-raw-with-dynamic-arg.md',
   },
   schema: [],
   messages: {
     dynamic:
-      "`raw()` bypasses HTML auto-escaping. Passing a dynamic value is an XSS risk unless the input has been sanitized. Sanitize first (`DOMPurify.sanitize(...)`) then pass to `raw()`, or add `// eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg` to mark a call as intentionally safe.",
+      '`raw()` bypasses HTML auto-escaping. Passing a dynamic value is an XSS risk unless the input has been sanitized. Sanitize first (`DOMPurify.sanitize(...)`) then pass to `raw()`, or add `// eslint-disable-next-line kerfjs/no-raw-with-dynamic-arg` to mark a call as intentionally safe.',
   },
 };
 
@@ -47,10 +47,11 @@ function create(context) {
       const callee = node.callee;
       if (!callee) return;
       // Match bare `raw(...)` and `kerfjs.raw(...)` / `kerf.raw(...)` shapes.
-      const isRaw = (callee.type === 'Identifier' && callee.name === 'raw')
-        || (callee.type === 'MemberExpression'
-            && callee.property.type === 'Identifier'
-            && callee.property.name === 'raw');
+      const isRaw =
+        (callee.type === 'Identifier' && callee.name === 'raw') ||
+        (callee.type === 'MemberExpression' &&
+          callee.property.type === 'Identifier' &&
+          callee.property.name === 'raw');
       if (!isRaw) return;
       if (node.arguments.length === 0) return;
       const arg = node.arguments[0];

package/lib/rules/prefer-module-jsx-augmentation.js

@@ -10,7 +10,8 @@ function findGlobalJSXIntrinsics(moduleBlock) {
   for (const m of moduleBlock.body) {
     if (m.type !== 'TSModuleDeclaration') continue;
     const idNode = m.id;
-    if (!idNode || idNode.type !== 'Identifier' || idNode.name !== 'JSX') continue;
+    if (!idNode || idNode.type !== 'Identifier' || idNode.name !== 'JSX')
+      continue;
     const inner = m.body;
     if (!inner || inner.type !== 'TSModuleBlock') continue;
     for (const member of inner.body) {
@@ -31,7 +32,7 @@ const meta = {
   type: 'problem',
   docs: {
     description:
-      "Declaration-merge `JSX.IntrinsicElements` into `kerfjs/jsx-runtime`, not the global namespace.",
+      'Declaration-merge `JSX.IntrinsicElements` into `kerfjs/jsx-runtime`, not the global namespace.',
     url: 'https://github.com/brianwestphal/kerf/blob/main/eslint-plugin/docs/rules/prefer-module-jsx-augmentation.md',
   },
   schema: [],

package/lib/rules/require-data-key-in-each.js

@@ -38,10 +38,15 @@ const meta = {
 function create(context) {
   return {
     CallExpression(node) {
-      if (node.callee.type !== 'Identifier' || node.callee.name !== 'each') return;
+      if (node.callee.type !== 'Identifier' || node.callee.name !== 'each')
+        return;
       const cb = node.arguments[1];
       if (!cb) return;
-      if (cb.type !== 'ArrowFunctionExpression' && cb.type !== 'FunctionExpression') return;
+      if (
+        cb.type !== 'ArrowFunctionExpression' &&
+        cb.type !== 'FunctionExpression'
+      )
+        return;
       const root = findRootJSXFromBody(cb.body);
       if (!root) return;
       if (root.type === 'JSXFragment') {

package/lib/rules/require-delegate-disposer.js

@@ -52,7 +52,8 @@ function create(context) {
       // the disposer is being routed somewhere reachable — accept.
       const parent = node.parent;
       if (!parent) return;
-      if (parent.type === 'UnaryExpression' && parent.operator === 'void') return;
+      if (parent.type === 'UnaryExpression' && parent.operator === 'void')
+        return;
       if (parent.type !== 'ExpressionStatement') return;
 
       context.report({