@kerfjs/ui 5.0.0-beta.16 → 5.0.0-beta.18

package/docs/nav-stack.md

@@ -8,9 +8,9 @@ a `NavStack` with one entry**. It is one of the opt-in app layouts (see
 Import the component and its companion stylesheet:
 
 ```ts
-import { NavStack, type NavStackView } from '@kerfjs/ui/nav-stack';
-import { wireNavStack } from '@kerfjs/ui/wire-nav-stack';
-import '@kerfjs/ui/nav-stack.css';
+import { NavStack, type NavStackView } from "@kerfjs/ui/nav-stack";
+import { wireNavStack } from "@kerfjs/ui/wire-nav-stack";
+import "@kerfjs/ui/nav-stack.css";
 ```
 
 ## State lives in the app
@@ -20,16 +20,25 @@ stack as a `signal<NavStackView[]>`, `NavStack({ views })` renders it, and
 `wireNavStack` animates the transitions.
 
 ```tsx
-const views = signal<NavStackView[]>([{ key: 'inbox', title: 'Inbox', content: <InboxView /> }]);
+const views = signal<NavStackView[]>([
+  { key: "inbox", title: "Inbox", content: <InboxView /> },
+]);
 
 // render inside mount():
 <NavStack id="mail" label="Mail" views={views.value} />;
 
 // once, after first render:
-const dispose = wireNavStack(root, { onBack: () => { views.value = views.value.slice(0, -1); } });
+const dispose = wireNavStack(root, {
+  onBack: () => {
+    views.value = views.value.slice(0, -1);
+  },
+});
 
 // push / pop by editing the signal:
-views.value = [...views.value, { key: id, title: 'Message', content: <MessageView id={id} /> }];
+views.value = [
+  ...views.value,
+  { key: id, title: "Message", content: <MessageView id={id} /> },
+];
 ```
 
 `NavStack` renders every entry stacked, the last one active and the rest kept

package/docs/recipes.md

@@ -14,12 +14,12 @@ the public `onCommit` callback, retains every disposer, and returns one
 idempotent disposer:
 
 ```ts
-import { createRecipe } from './navigation-sidebar.js';
-import { mountRecipe } from './mount-recipe.js';
+import { createRecipe } from "./navigation-sidebar.js";
+import { mountRecipe } from "./mount-recipe.js";
 
-const root = document.querySelector<HTMLElement>('#navigation')!;
+const root = document.querySelector<HTMLElement>("#navigation")!;
 const stopRecipe = mountRecipe(root, createRecipe(announce));
-window.addEventListener('pagehide', stopRecipe, { once: true });
+window.addEventListener("pagehide", stopRecipe, { once: true });
 ```
 
 The adapter is delivered as reference source, not a new package runtime export.

package/docs/split-view.md

@@ -6,9 +6,9 @@ on compact ones. One of the opt-in app layouts (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
 ```ts
-import { SplitView } from '@kerfjs/ui/split-view';
-import { deviceClass } from '@kerfjs/ui/device-class';
-import '@kerfjs/ui/split-view.css';
+import { SplitView } from "@kerfjs/ui/split-view";
+import { deviceClass } from "@kerfjs/ui/device-class";
+import "@kerfjs/ui/split-view.css";
 // plus nav-stack.css when the compact path is reachable, and
 // wireResizableRegions / wireNavStack for the interactive behavior.
 ```

package/docs/tab-scaffold.md

@@ -7,9 +7,9 @@ opt-in app layouts (see [`../../docs/23-app-layouts.md`](../../docs/23-app-layou
 It is distinct from `TabBar` (document-oriented, reorderable strips).
 
 ```ts
-import { TabScaffold } from '@kerfjs/ui/tab-scaffold';
-import { wireTabScaffold } from '@kerfjs/ui/wire-tab-scaffold';
-import '@kerfjs/ui/tab-scaffold.css';
+import { TabScaffold } from "@kerfjs/ui/tab-scaffold";
+import { wireTabScaffold } from "@kerfjs/ui/wire-tab-scaffold";
+import "@kerfjs/ui/tab-scaffold.css";
 ```
 
 ## Controlled selection
@@ -19,20 +19,29 @@ The app owns the active tab (a signal); `TabScaffold` renders every tab's scene
 clicks.
 
 ```tsx
-const active = signal('home');
+const active = signal("home");
 
 <TabScaffold
   id="app"
   label="Sections"
   active={active.value}
   tabs={[
-    { id: 'home', label: 'Home', icon: <HomeIcon />, content: <HomeStack /> },
-    { id: 'search', label: 'Search', icon: <SearchIcon />, content: <SearchStack /> },
+    { id: "home", label: "Home", icon: <HomeIcon />, content: <HomeStack /> },
+    {
+      id: "search",
+      label: "Search",
+      icon: <SearchIcon />,
+      content: <SearchStack />,
+    },
   ]}
 />;
 
 // once, after first render:
-const dispose = wireTabScaffold(root, { onSelect: (id) => { active.value = id; } });
+const dispose = wireTabScaffold(root, {
+  onSelect: (id) => {
+    active.value = id;
+  },
+});
 ```
 
 Each `TabScaffoldTab` has an `id`, `label`, optional `icon`, and `content`. The

package/docs/ux-demo.md

@@ -10,9 +10,9 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - The `ListActionRow` route demonstrates sibling primary/trailing native controls, independent disabled states, controlled selection, first-line leading-icon alignment for wrapped labels, and an application-owned native popover relationship without nesting controls. The `ListItem` route demonstrates the same multiline leading-icon anchor alongside its single-control navigation contract.
 - The `AppTab` route demonstrates a runtime-filtered domain metadata slot and a decorative replacement close icon without changing TabBar selection, close, reorder, or focus ownership. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
 - Every first-party visual component and every free Web Awesome 3.12 component has its own stable `?component=<id>` URL and focused demo. Composite header, menu, feedback, and theme scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component.
-- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Demo paths resolve to `ui/ux-demo/main.tsx`, the matching `ui/ux-demo/recipes/*.tsx` file, or `ui/ux-demo/webawesome-demos.tsx` according to the canonical entry. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
+- `ai/component-catalog.json` is the canonical catalog metadata. A deterministic checked-in projection supplies the demo's unique id, category, kind (`component`, `composition`, or `recipe`), source (`kerf` or `webawesome`), name, description, recommendation, direct `uses` dependencies, existing documentation path, and demo-source path; first-party, recipe, and Web Awesome renderer maps are exhaustively typed against its generated id unions. Non-supported Web Awesome recommendations project to a visible `Discouraged` sidebar tag, with Popup as the deliberate conditional exception. Demo paths resolve to the matching `ui/ux-demo/demos/<id>.tsx` or `ui/ux-demo/recipes/*.tsx` file, or to `ui/ux-demo/webawesome-demos.tsx` for Web Awesome entries. `ui/ux-demo/main.tsx` owns only the catalog shell, shared state, routing, and interaction wiring. First-party component entries additionally derive `ui/src/<browser-subpath>.tsx` from their canonical `delivery.browserImport`.
 - Every detail footer groups compact `Demo source` and `Guidance` actions; first-party component details also expose `Component source`. Web Awesome details say `Integration guidance` to distinguish the local integration contract from the upstream component implementation. Each button retains its repository-relative path in the DOM for verification and uses a deploy-safe absolute GitHub blob URL with a contextual new-tab name; the demo does not depend on a local source server or add a package runtime export. At phone widths, the resource group and related-component selector stack as full-width rows, with any resource overflow contained locally so labels cannot overlap the selector or widen the document.
-- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
+- The master/detail shell groups first-party routes by category with production `ListHeader` and `ListItem` components. Catalog entries can supply short reusable trailing tags; the Web Awesome projection uses them to label exactly the 15 discouraged choices. The 70 ecosystem components live in a separate `Web Awesome` disclosure with seven subgroups, so they remain discoverable without being presented as first-class `@kerfjs/ui` exports. Direct Web Awesome routes open the disclosure and reveal the selected row at wide sizes; narrow layouts keep the expanded list in document flow rather than introducing a competing nested scroller.
 - The shell itself uses `@kerfjs/ui/layout.css`: sidebars, details, previews, dialogs, and resize specimens share unpadded panes plus self-contained content items. Its sidebar identity uses the Kerf logo beside a vertically centered title, with the subtitle in its own aligned row like `PanelHeader`; the current-view heading is also a toolbar. Collapsing the catalog removes the pane completely and moves its restore action to the main toolbar's leading edge instead of leaving an icon-only rail. The selected view description remains inset below the page toolbar. The checkerboard belongs to the complete scrollable preview region rather than a nested card. A lightly separated footer keeps live status above compact source, guidance, and relationship groups. The focused `ResizableRegion` specimen stretches its surface through the available stage height and reports committed width in that shared status footer; narrow layouts retain local horizontal access when the pane is resized wider than the stage, and the split remains readable at 200% root scaling. Geometry coverage checks wide, intermediate, narrow, and 200% zoom layouts.
 - The composer-form recipe demonstrates one coherent visible form surface with `PanelHeader` title/summary hierarchy, fields and actions on the shared 8px control gutter, and 24px major rhythm. Its conditional error or success `StateBanner` is the only nested semantic surface. Reset synchronizes the upgraded Web Awesome fields' live value properties with their empty controlled attributes and announces `Draft reset`; browser coverage preserves behavior and verifies wide, narrow, dark, validation, success, reset, 200% zoom, and forced-colors states.
 - The list-detail dialog recipe places its header directly on the dialog edge while preserving the header's internal inset, gives the selected project title the complete outer-plus-inner content gutter, lets the value table fill the available detail column between the shared outer margins, and keeps record actions on one outer gutter without an extra content-item inset. Browser geometry coverage protects those relationships at wide and narrow widths.

package/docs/webawesome-theme.md

@@ -4,10 +4,10 @@
 free components and the Kerf/Hot Sheet 2 design system.
 
 ```ts
-import type {} from '@kerfjs/ui/webawesome';
-import '@kerfjs/ui/webawesome.css';
-import '@awesome.me/webawesome/dist/components/button/button.js';
-import '@awesome.me/webawesome/dist/components/input/input.js';
+import type {} from "@kerfjs/ui/webawesome";
+import "@kerfjs/ui/webawesome.css";
+import "@awesome.me/webawesome/dist/components/button/button.js";
+import "@awesome.me/webawesome/dist/components/input/input.js";
 ```
 
 The type-only package import augments `kerfjs/jsx-runtime` with the 70
@@ -54,6 +54,71 @@ pointer targets. Override `--kui-wa-carousel-icon-size`,
 `--kui-wa-carousel-dot-hit-size` on a carousel or containing scope when a
 product needs different geometry.
 
+Form fields carry the same content-item inset as the Kerf primitives: a 1px
+border with 8px inside it (`--wa-form-control-border-width`,
+`--wa-form-control-padding-block`, and `--wa-form-control-padding-inline` are set
+to the `--kui-layout-item-border-width` / `--kui-layout-item-padding` values), so
+a single-line control lands at the standard ~40px height and the value sits 9px
+in from the field edge. Each field's top label is inset by that same border +
+padding (9px) so it lines up with the value inside the field, and is styled
+exactly like a `ListHeader` label — uppercase, `--kui-font-xs`, weight 650, quiet
+foreground. This applies to every free field that exposes a top label
+(`::part(form-control-label)` plus the Slider's `::part(label)`). OTP Input
+exposes `label` instead of `form-control-label`; the theme gives it the same
+uppercase 12px/650 treatment. Inline control labels (Checkbox, Switch) keep
+their natural sentence case.
+
+Known Date's field captions and bordered text-like field hints use the same 9px
+inline inset, keeping secondary text aligned with the value rather than the
+field's outer border. This covers Input, Known Date, Number Input, OTP Input,
+Select, Textarea, and Time Input hints; unbordered group hints retain their own
+natural geometry. OTP Input's label and hint both use the 9px field-text inset.
+
+Checkbox Group and Radio Group option regions receive the shared 8px inline
+outer inset through `::part(form-control-input)`. Unlike bordered fields, these
+groups have no shell of their own, so the explicit margin places their controls
+on the same content-item geometry without adding padding to each option. The
+Color Picker trigger receives the same 8px inline outer inset because it also
+has no bordered field shell. Slider's complete interactive region receives the
+shared 8px logical inline outer inset through `::part(slider)`, keeping its
+track, markers, references, and hint together without moving the label.
+
+Non-field chrome follows explicit, overridable control, surface, and container
+tiers:
+
+- `--kui-wa-control-inset` defaults to the 8px content-item padding. It applies
+  to tabs, tree-item trailing content, tags, and dropdown items. Tree selection
+  also uses Kerf's 8px inline outer margin, so its background reads as an inset
+  list item instead of an edge-to-edge stripe. Buttons already consume the same
+  `--wa-form-control-padding-inline` 8px value at every size, so no extra part
+  override is needed.
+- `--kui-wa-surface-margin` and `--kui-wa-surface-inset` default to 8px.
+  Accordion, Card, Details, Callout, and Include use the margin around their
+  complete surface and the inset within it. Accordion applies the outer margin
+  once to the group rather than separating connected items; Card's header,
+  body, and footer all receive the full inset.
+- `--kui-wa-container-inset` defaults to the 16px homogeneous-group step. Tab
+  Panel retains this roomier tier for unframed panel content.
+
+Badge remains intentionally compact at Web Awesome's intrinsic `0.375em` block /
+`0.625em` inline padding (4.5px / 7.5px at its default 12px text size): it is a
+short status or count, not a content item. Breadcrumb has no bordered or filled
+container, and Scroller delegates item chrome to its slotted children, so both
+retain their upstream geometry. Web Awesome 3.12's free catalog has
+`wa-dropdown-item`, but no `wa-menu-item`; the theme therefore styles the
+supported dropdown item rather than carrying a dead selector.
+
+Override a tier for a product scope after importing the theme:
+
+```css
+.roomy-editor {
+  --kui-wa-control-inset: 0.75rem;
+  --kui-wa-surface-margin: 0.75rem;
+  --kui-wa-surface-inset: 0.75rem;
+  --kui-wa-container-inset: 1.5rem;
+}
+```
+
 Accordion, Details, Breadcrumb, and Kerf Select share
 `--kui-disclosure-icon-scale` (default `.5`) so disclosure and traversal
 chevrons keep the same visual weight. The Accordion and Details components
@@ -73,12 +138,12 @@ subtree, or for one instance after the theme import:
 
 ```css
 :root {
-  --wa-tooltip-arrow-size: .375rem;
-  --kui-wa-popover-arrow-size: .375rem;
+  --wa-tooltip-arrow-size: 0.375rem;
+  --kui-wa-popover-arrow-size: 0.375rem;
 }
 
 .pointed-popover {
-  --arrow-size: .5rem;
+  --arrow-size: 0.5rem;
 }
 ```
 
@@ -179,7 +244,7 @@ smallest subtree that needs a different identity:
 :root {
   --wa-color-brand-fill-loud: #7540a8;
   --wa-color-focus: #7540a8;
-  --wa-form-control-border-radius: .5rem;
+  --wa-form-control-border-radius: 0.5rem;
 }
 
 .billing-workspace {

package/docs/workbench.md

@@ -8,8 +8,8 @@ sidebar. One of the opt-in app layouts (see
 desktop-class devices.
 
 ```ts
-import { Workbench } from '@kerfjs/ui/workbench';
-import '@kerfjs/ui/workbench.css';
+import { Workbench } from "@kerfjs/ui/workbench";
+import "@kerfjs/ui/workbench.css";
 ```
 
 ## State lives in the app
@@ -25,9 +25,22 @@ const navCollapsed = signal(false);
   id="studio"
   label="Studio"
   main={<Editor />}
-  leftRail={{ content: <Navigator />, label: 'Navigator', collapsed: navCollapsed.value, size: 280 }}
-  rightRail={{ content: <Inspector />, label: 'Inspector', collapsed: inspectorCollapsed.value }}
-  bottomDrawer={{ content: <Console />, label: 'Console', collapsed: consoleCollapsed.value }}
+  leftRail={{
+    content: <Navigator />,
+    label: "Navigator",
+    collapsed: navCollapsed.value,
+    size: 280,
+  }}
+  rightRail={{
+    content: <Inspector />,
+    label: "Inspector",
+    collapsed: inspectorCollapsed.value,
+  }}
+  bottomDrawer={{
+    content: <Console />,
+    label: "Console",
+    collapsed: consoleCollapsed.value,
+  }}
 />;
 ```
 

package/llms.txt

@@ -6,7 +6,7 @@
 > generate correct, good-looking kerf UI — it is not a catalog to browse.
 
 ```bash
-npm install kerfjs @kerfjs/ui   # kerfjs is a peer; Web Awesome is an optional peer
+npm install kerfjs @kerfjs/ui # kerfjs is a peer; Web Awesome is an optional peer
 ```
 
 Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
@@ -22,15 +22,18 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
    [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
    callback shapes, disposer return types).
 3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
-   relationships, side effects) load the
+   relationships, side effects, and geometry ownership) load the
    [Machine-readable component catalog](./ai/component-catalog.json) — the
-   canonical checked-in source; its schema is alongside it.
+   canonical checked-in source; its schema is alongside it. Also load the
+   consuming application's catalog extension when present; generate one from the
+   [Consumer catalog extension schema](./ai/component-catalog-extension.schema.json)
+   when app-owned components must participate in selection or alignment.
 4. **Apply the rules below and in** [skill.md](./ai/skill.md).
 
 ## Core rules (do the right thing)
 
 - **Reach for the primitive, not for CSS.** The package is built to look right
-  *unstyled*. Before adding `padding`, `margin`, `width`, `height`, `border`,
+  _unstyled_. Before adding `padding`, `margin`, `width`, `height`, `border`,
   `background`, a wrapper card, or a decoration, check whether the component, the
   pane, or the content-item already owns it — it almost always does. Prefer a
   component prop or a `--kui-*` token; write CSS only for genuinely new structure,
@@ -40,6 +43,21 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
+- **Keep Web Awesome on the shared inset tiers.** `webawesome.css` uses
+  `--kui-wa-control-inset` (8px controls/items) and
+  `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside
+  Accordion, Card, Details, Callout, and Include), while
+  `--kui-wa-container-inset` keeps Tab Panel at 16px. Override the tier at the
+  narrowest useful scope instead of restyling individual shadow parts.
+  Checkbox and Radio Group option regions also receive the shared 8px inline
+  outer inset because those groups have no bordered field shell. The Color
+  Picker trigger receives the same inset for the same unbordered geometry.
+  Slider's complete interactive region uses the shared 8px logical inline outer
+  inset without shifting its already-aligned label.
+  Known Date's Month/Day/Year captions and bordered text-like field hints align
+  with field values at the shared 9px border-plus-padding inset. OTP Input's
+  label uses the same uppercase xs/650 treatment and its label and hint share
+  that 9px alignment.
 - **Trust the defaults.** Render a control at its natural size and color (a
   `LucideIcon` is 24px); if it looks wrong, fix the surrounding layout, not the
   control. Never force a component's width/height to size it — that leaves a halo
@@ -54,7 +72,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   popup menu. A toolbar popup menu is a `single` `ToolbarControlGroup` around a
   `wa-dropdown` (its `slot="trigger"` `wa-button` is the toolbar button, kept under
   `data-morph-skip-children`).
-- **`PanelHeader` is *the* panel/dialog/page heading.** A plain toolbar with an
+- **`PanelHeader` is _the_ panel/dialog/page heading.** A plain toolbar with an
   optional bordered icon group, an extra-large `ToolbarText` title, the trailing
   controls you pass, and an optional subtitle below — do not hand-build a heading
   row or restyle a toolbar into one.
@@ -75,7 +93,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 - **App state is domain/persisted; helpers own only ephemeral mechanics.** Keep
   navigation stacks, tab selection and order, pane sizes, and `collapsed`/`expanded`
   disclosure flags in the app — they are data or persisted layout, and the app reads
-  them to render. The `wire…` helpers own the *ephemeral* parts: `wireNavStack` the
+  them to render. The `wire…` helpers own the _ephemeral_ parts: `wireNavStack` the
   push/pop animation, `wireTabBars` the overflow autoscroll and drag preview,
   `wireResizableRegions` the live drag preview; they report committed changes via
   callbacks. The one richer case is `wireTokenSearchFields`, which manages the
@@ -113,13 +131,16 @@ tree-shakeable, declarative with `wire…` helpers, each with a companion CSS im
 `NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
-+ `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
-`@kerfjs/ui/catalog` is another opt-in shell — a
-`Catalog` component + `wireCatalog` helper for building a component-gallery catalog
-(collapsible category sidebar + preview stage + resources footer) from your own
-entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
-type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
-declared side effects.
+
+- `@kerfjs/ui/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence).
+  `@kerfjs/ui/catalog` is another opt-in shell — a
+  `Catalog` component + `wireCatalog` helper for building a component-gallery catalog
+  (collapsible category sidebar + preview stage + resources footer, with an opt-in
+  transparent-bound and margin geometry overlay plus focus-preserving active-row
+  reveal for long desktop sidebars) from your own
+  entries; controlled/stateless like the layouts. `@kerfjs/ui/webawesome` is a
+  type-only boundary for `wa-*` JSX; `@kerfjs/ui/select/register` and the CSS are the
+  declared side effects.
 
 ## Reference
 
@@ -130,6 +151,6 @@ declared side effects.
 - [accessibility.md](./docs/accessibility.md): keyboard and ARIA contracts per component.
 - [recipes.md](./docs/recipes.md): production compositions (app shell, list-detail dialog, composer form, …) as copyable references.
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation.
-- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists).
-- [component-catalog.json](./ai/component-catalog.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts and exact signatures.
+- [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable facts, a reusable app-component extension contract, and exact signatures.
 - [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.16",
+  "version": "5.0.0-beta.18",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -272,8 +272,9 @@
     "dev": "npm run build && vite --config ux-demo/vite.config.ts",
     "demo:build": "npm run build && vite build --config ux-demo/vite.config.ts && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
+    "format": "prettier --write . --ignore-unknown",
     "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
-    "check:format": "prettier --check \"src/**/*.css\" \"ux-demo/**/*.css\"",
+    "check:format": "prettier --check . --ignore-unknown",
     "catalog:sync": "node scripts/sync-component-catalog.mjs",
     "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/check-component-catalog.mjs",
     "check:recipes": "node scripts/check-recipes.mjs",
@@ -285,14 +286,15 @@
     "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
     "ai:regressions:score": "node scripts/score-ai-regression.mjs",
     "check:guidance": "node scripts/check-decision-guidance.mjs",
-    "lint": "eslint src tests ux-demo docs/examples --max-warnings 0",
+    "lint:eslint": "eslint src tests ux-demo docs/examples --max-warnings 0",
+    "lint": "npm run lint:eslint && npm run check:format",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
     "test": "npm run test:unit && npm run test:bundle",
     "test:unit": "vitest run tests/unit --coverage",
     "test:bundle": "npm run build && vitest run tests/bundle",
     "test:consumer-types": "npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json",
     "test:e2e": "npm run demo:build && playwright test",
-    "check": "npm run check:format && npm run check:catalog && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
+    "check": "npm run check:catalog && npm run check:recipes && npm run check:guidance && npm run check:ai-regressions && npm run lint && npm run typecheck && npm test && npm run test:consumer-types && npm run check:ai-signatures && npm run demo:build && npm run check:design-templates && npm pack --dry-run",
     "prepublishOnly": "npm run check",
     "check:design-templates": "node scripts/check-design-templates.mjs",
     "check:design-templates:drift": "node scripts/check-design-templates-drift.mjs",