@kerfjs/ui 5.0.0-beta.11 → 5.0.0-beta.110

package/docs/design-philosophy.md

@@ -18,26 +18,50 @@ A reference image defines hierarchy, relationships, and intended feel. It does n
 
 ### Continuity is correctness
 
-Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the *ephemeral mechanics* around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireTokenSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
+Unrelated updates must not close controls, move focus, reset a draft, replace a selection, or jump scroll. Give every durable and transient state an explicit owner. The default owner is the application: domain data and persisted layout preferences — a navigation stack, a selection, a tab order, a pane size, a `collapsed`/`expanded` disclosure flag — are the app's signals, which it reads to render. A `wire…` helper owns only the _ephemeral mechanics_ around that state (a push/pop animation, overflow autoscroll, a live resize preview) and reports committed changes through callbacks. A helper takes over a piece of transient state itself only when hand-rolling that behavior is substantial and error-prone enough to cause real, inconsistent variation across apps — `wireSearchFields`'s collapsible reveal/focus/Escape/blur-collapse is the bar; a one-line boolean toggle is not. Preserve DOM identity when meaning has not changed. Distinguish blocking foreground work from background synchronization.
 
 ### Hierarchy precedes decoration
 
-Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction.
+Establish one reading order and one dominant action per decision point. Group first with alignment, spacing, typography, and shared surfaces. A border, fill, badge, or nested card must communicate a real distinction. A divider is chrome too: a line between a pane's own header and its list, or under a toolbar whose content already spaces itself, marks nothing and is dropped (`dividerSides=""`), never padded around. Put a control near where its effect appears — a collapsed drawer's restore beside the drawer, not in a distant top toolbar.
 
 ### Reach for the primitive, not for CSS
 
-The package is designed to look right *unstyled*. A screen built from the
+The package is designed to look right _unstyled_. A screen built from the
 primitives, their props, and the semantic tokens should already read well, so
-custom CSS is the exception. Before adding any `padding`, `margin`, `width`,
+applications do not carry a component-customization stylesheet. Prefer a Kerf
+UI component, then a native HTML element, using each for what it is good at.
+Kerf UI needs no Web Awesome; an application that adopts the optional
+integration still never renders a `Discouraged` element, which a Kerf
+component replaces (`Button`, `TextField`, `Select`, `PopupMenu`, …). Before adding any `padding`, `margin`, `width`,
 `height`, `border`, `background`, wrapper card, or decoration, check whether the
 component, the pane, or the content-item already owns it — it almost always does,
 and adding more usually **double-insets** or fights the component (the most common
 mistake). Trust component defaults: render a control at its natural size and color
 and fix the surrounding layout rather than overriding the control. Legitimate
-custom CSS is limited to genuinely new structure, and even then may only join a
-component's documented `publicClasses` or override documented `--kui-*` tokens at a
-real composition boundary — never size, space, or re-skin a primitive by hand, and
-never build a heading, toolbar, card, or pane geometry that a primitive provides.
+CSS for genuinely new structure belongs to the application-owned component that
+renders that structure. It must not select a nested Kerf or Web Awesome component;
+configure those children through props and documented tokens instead. Never size,
+space, or re-skin a primitive by hand, and never build a heading, toolbar, card,
+or pane geometry that a primitive provides.
+
+### Components own their styles; configure, never override
+
+Every component styles only itself. How it looks and sits is configuration —
+typed props and data attributes such as size, density, inset, presentation,
+tone, `dividerSides`, `ToolbarConfig`, and `PaneConfig` — never a stylesheet
+somewhere else reaching into it. When a component must adapt inside another
+(a `PopupMenu` inside a compact `ToolbarControlGroup`, an `TabBarItem` in a
+segmented `TabBar`), the **child** styles itself in that context, in its own
+stylesheet; the parent keys only its own elements on a child's state
+(`:has(> .kui-select[open])`) and names kerf children by class, not by `wa-*`
+tag. Values a parent provides to its children are custom properties named after
+the parent. A component never writes another component's private variables and
+never puts a hook class on a child's root to restyle it.
+
+The same holds for applications and component packages built on Kerf UI: expose
+configuration on your own components, configure kerf components through their
+props, and treat a missing prop as a component gap to report, not a reason to
+override. `npm run check:css-ownership` enforces this inside the package.
 
 ### Panes share one child-owned geometry
 
@@ -45,21 +69,23 @@ Sidebars, main areas, inspectors, and dialogs use the same unpadded pane. Their
 children own margin, border, background, padding, and radius, so a transparent
 surface occupies exactly the same geometry as a visible one. Major content
 groups use 24px vertical separation; the inside of an item and the gap between
-toolbar groups use 8px. Rows and actions keep 44px targets.
+toolbar groups use 8px. Rows and actions keep 44px targets. Align text to text
+and icons to icons: a title, a row label, and bare prose share one text column,
+and a border is decoration, never the alignment anchor — a bordered surface
+extends to the pane gutter rather than being indented so its border lines up
+with a heading's text.
 
 Use the package composition so the geometry has one owner:
 
 ```tsx
-<aside class="kui-pane">
-  <nav class="kui-pane__content kui-content">
+<Pane element="aside" contentElement="nav" label="Workspace" contentLabel="Workspace pages">
     <section>
-    <ListHeader label="Workspace" />
-    <ListItem action="open" label="Inbox" icon={inboxIcon} />
-    <ListItem action="open" label="Drafts" />
+      <ListHeader label="Workspace" />
+      <ListItem action="open" label="Inbox" icon={inboxIcon} />
+      <ListItem action="open" label="Drafts" />
     </section>
-    <div class="kui-content-item">Panel contents</div>
-  </nav>
-</aside>
+    <ContentItem>Panel contents</ContentItem>
+</Pane>
 ```
 
 Do not pad the pane and then pad every wrapper. That duplicates the geometry
@@ -85,13 +111,23 @@ Use the shortest understandable, recoverable interaction. Avoid modes, dialogs,
 
 Reuse a component when surfaces share its purpose, anatomy, state model, and interaction behavior—not merely its appearance. Components expose semantic actions and explicit variants. Product-specific copy, transport, persistence, and domain states stay in application adapters.
 
+### Words follow one capitalization rule
+
+Inconsistent capitalization reads as unfinished. Kerf follows Apple's
+per-element convention: anything that names a command, control, view, or
+field is title style ("Save Draft", "Workspace Settings"), and anything that
+describes, explains, or reports is sentence style ("Saved just now"). Apply it
+the same way on every screen; see [Writing interface copy](./writing.md).
+
 ### Use a finite vocabulary
 
 Color, type, spacing, radius, elevation, and motion express semantic roles. Prefer package tokens over raw values in consuming code. State is never communicated by color alone.
 
 The default vocabulary is opinionated rather than empty: neutral, brand/info,
-success, warning, and danger provide quiet/normal/loud fills, borders, and
-foregrounds compatible with Hot Sheet 2 and Web Awesome. Consumers may replace
+pop, success, warning, and danger provide quiet/normal/loud fills, borders, and
+foregrounds compatible with Hot Sheet 2 and Web Awesome. Pop is vibrant,
+non-status emphasis for featured, novel, or celebratory content; never use it as
+a success, warning, or danger substitute. Consumers may replace
 the global palette, one semantic role, or one component instance through
 documented custom properties without rewriting component CSS.
 
@@ -102,13 +138,22 @@ separation, very minor air, standard within a group, between homogeneous groups,
 and major between heterogeneous groups. Off-scale values (12px, 32px) are
 deliberate exceptions. See [`layout.md`](layout.md) "Spacing scale".
 
+Empty space also has a job. Keep related controls and content close, leave more
+room between distinct decisions, and let a short form or sparse state occupy
+only the width it needs. Align neighboring content edges before adjusting gaps.
+Do not fill an open area with a card, divider, label, or evenly stretched row
+merely to use the space. Give the pane, surface, and child layout one owner each;
+avoid a negative margin or spacer that only cancels an inset another component
+already provides. Recheck that rhythm with side rails open and at narrow and
+intermediate widths.
+
 ### Responsive design reprioritizes
 
 Protect primary content, readable type, recognizable icons, and usable targets. Relocate secondary information before compressing it below a usable scale. Keep one clear scroll owner per region and test narrow, wide, zoomed, and intermediate layouts.
 
 ### Production behavior is proof
 
-The catalog uses the same exports and CSS consumers receive. Its category-grouped master/detail layout keeps one component under review at a time, and its decorative shell consumes the same semantic palette as the component stage. Every public visual primitive has a focused route; composition demos declare their direct dependencies so reviewers can navigate both `Uses` and `Used by` relationships. Every enabled control works. Demonstrations cover meaningful variants and adverse states with realistic enough content to expose wrapping, clipping, density, and state-transition defects.
+The catalog uses the same exports and CSS consumers receive. Its category-grouped master/detail layout keeps one component under review at a time, and its decorative shell consumes the same semantic palette as the component stage. Every public visual primitive has a focused route; composition demos declare their direct dependencies so reviewers can navigate both `Uses` and `Used By` relationships. Every enabled control works. Demonstrations cover meaningful variants and adverse states with realistic enough content to expose wrapping, clipping, density, and state-transition defects.
 
 ### Be platform-fluent, not platform-costumed
 

package/docs/device-class.md

@@ -7,7 +7,7 @@ the foundation the app/dialog layouts build on (see
 [`../../docs/23-app-layouts.md`](../../docs/23-app-layouts.md)).
 
 ```ts
-import { deviceClass } from '@kerfjs/ui/device-class';
+import { deviceClass } from "@kerfjs/ui/device-class";
 
 const device = deviceClass(); // ReadonlySignal<DeviceClass>
 
@@ -19,14 +19,14 @@ effect(() => {
 
 ## `DeviceClass`
 
-| Field | Meaning |
-| --- | --- |
-| `size` | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop` |
-| `orientation` | `portrait` \| `landscape` |
+| Field                           | Meaning                                                                    |
+| ------------------------------- | -------------------------------------------------------------------------- |
+| `size`                          | `xs-mobile` \| `mobile` \| `tablet` \| `desktop` \| `xl-desktop`           |
+| `orientation`                   | `portrait` \| `landscape`                                                  |
 | `segments` / `verticalSegments` | viewport segment counts (foldables / dual-screen); `1` on ordinary devices |
-| `handset` | `xs-mobile` or `mobile` |
-| `compact` | "one pane at a time" — a handset or a portrait tablet |
-| `atLeast(size)` | true when the current size is `size` or larger |
+| `handset`                       | `xs-mobile` or `mobile`                                                    |
+| `compact`                       | "one pane at a time" — a handset or a portrait tablet                      |
+| `atLeast(size)`                 | true when the current size is `size` or larger                             |
 
 Reading `device.value` inside an `effect`/`computed` re-runs when the viewport
 crosses a breakpoint, rotates, or changes its segment count. One shared viewport
@@ -50,5 +50,6 @@ pure, DOM-free bucketing core.
 ## Server rendering
 
 Without a DOM, `deviceClass()` resolves to an SSR default (1024×768, landscape,
-one segment) and hydrates to the real class on the client. Override the assumed
+one segment). That signal is a fixed snapshot — there is no hydration step; a
+`deviceClass()` called in the browser reads the real viewport. Override the assumed
 viewport with `deviceClass({ ssr: { width, height } })`.

package/docs/disclosure.md

@@ -0,0 +1,97 @@
+# Disclosure
+
+`@kerfjs/ui/disclosure` shows and hides content under a summary row. It is a
+native `<details>` with a `<summary>` that carries a `DisclosureArrow`, the
+title, and an optional quiet detail, on the shared content-item geometry.
+
+```tsx
+import { Disclosure } from "@kerfjs/ui/disclosure";
+
+<Disclosure title="Advanced Settings" detail="3 options">
+  <Text>Proxy, request timeout, and retry limits.</Text>
+</Disclosure>;
+```
+
+## Geometry
+
+The root takes the content-item geometry: an 8px inline margin, a 1px border
+(transparent unless framed), and the rounded radius. The summary row has the
+8px inset and a 42px minimum height. The content area is offset by the arrow
+column only, so Kerf block content, which brings the shared 1px + 8px inset
+(`Text`, a `List`, a `ValueTable`), lands on the title's text column. Wrap
+prose in `Text` rather than passing a bare string.
+
+- `appearance="plain"` (default) sits on the surrounding surface.
+- `appearance="framed"` draws the standard neutral border. Frame one only when
+  it marks a real distinction.
+- `appearance="sunken"` draws the border on the lowered, textured work surface,
+  for something like a log.
+- `appearance="embedded"` is for a Disclosure inside chrome that already owns
+  the content-item geometry, such as a `ContentItem`. See below.
+
+## Embedded in a content item
+
+A compact details panel inside a `ContentItem` (a note card's AI feedback)
+would be framed twice by the default geometry: the item's 8px margin, border,
+and padding, then the Disclosure's own. `appearance="embedded"` drops the
+Disclosure's margin, border, and padding, so the summary row starts on the
+item's content inset and the arrow lines up with the item's other icons. The
+summary is a compact row with a 24px minimum height, and it has no hover
+fill, because a fill would touch the arrow and text at the item's content
+edge. Its focus ring sits just outside the row.
+
+The content starts on the title's text column, 8px below the summary. Inside
+an item, content brings no inset of its own: use a `flush` `Text` or other
+inline content rather than a block `Text`. `kerf-ui-doctor` (through
+`eslint-plugin-kerfjs`'s `ui-composition` rule) reports a block `Text`, or any
+other child that brings its own content-item inset, directly inside an
+embedded Disclosure as `KUI-L204`.
+
+```tsx
+<ContentItem frame="framed">
+  <List gap="xs">
+    <Text flush>Move the export button into the toolbar.</Text>
+    <Disclosure title="AI Feedback" detail="2 suggestions" appearance="embedded">
+      <Text flush tone="quiet">Group Export and Share in one control group.</Text>
+    </Disclosure>
+  </List>
+</ContentItem>;
+```
+
+Use `embedded` only inside owner chrome. On a pane or a list, the default
+geometry is what puts the Disclosure on the shared content column.
+
+## Open state
+
+The open state belongs to the native `<details>` once it is on the page. A
+person toggles it with a press, Enter, or Space; `open` renders it open, and a
+re-render that passes `open` opens it. A re-render never closes it, because
+kerf's morph leaves a `<details>` element's live `open` alone. To close it
+from code, set `element.open = false`. The arrow follows the live state.
+
+To react to a toggle, give it a `toggleAction` (a `data-action` on the root)
+and listen for the native `toggle` event. It does not bubble, so listen in
+the capture phase, for example with `delegateCapture`, and read
+`event.newState` (`open` or `closed`).
+
+## Accordions
+
+Disclosures that share a `name` form an exclusive group: opening one closes
+the others. This is the native `<details name>` attribute.
+
+```tsx
+{faqs.map((faq) => (
+  <Disclosure title={faq.title} name="faq" appearance="framed">
+    <Text>{faq.answer}</Text>
+  </Disclosure>
+))}
+```
+
+## Accessibility
+
+The summary is the platform's disclosure button: Enter and Space toggle it,
+and it reports its expanded state. The arrow is decorative. Keep the title a
+short, meaningful name for what it hides.
+
+Use this instead of `wa-details`, `wa-accordion`, and `wa-accordion-item`,
+which are Discouraged.

package/docs/document-baseline.md

@@ -0,0 +1,93 @@
+# Document baseline
+
+Import `@kerfjs/ui/document.css` when an application wants Kerf UI to own its
+document-level defaults:
+
+```ts
+import "@kerfjs/ui/document.css";
+```
+
+```html
+<body>
+  <div id="app" class="kui-app-root"></div>
+</body>
+```
+
+The opt-in stylesheet applies `border-box` sizing to every element and
+pseudo-element, removes the body margin, and gives the body the foundation
+font, foreground, lowered surface, and `1.45` line height. Plain links use the
+semantic `--kui-color-text-link` token with zero selector specificity.
+Native table cells (`th`, `td`) and form controls (`button`, `input`, `select`,
+`textarea`) inherit the surrounding font family, size, and line height through
+zero-specificity selectors. Table headers keep their native bold weight and
+alignment, and application styles can override the baseline.
+
+Native controls also get semantic cursors, again at zero specificity so a
+component's or application's own cursor wins:
+
+- `pointer` on enabled `button`, `a[href]`, `[role="button"]` (unless
+  `aria-disabled="true"`), `summary`, `select`, checkbox / radio / color /
+  file / button / reset / submit inputs, and a `label` wrapping an enabled
+  checkbox or radio;
+- `not-allowed` on disabled `button`, `input`, `select`, and `textarea`, on
+  `[role="button"][aria-disabled="true"]`, and on a disabled `wa-button`'s
+  `base` part (Web Awesome leaves a pointer there);
+- `text` on enabled `textarea` and text-like inputs (`text`, `search`,
+  `email`, `url`, `tel`, `password`, `number`, and untyped).
+
+Applications no longer need their own global cursor policy for native
+controls.
+
+`html`, `body`, and `.kui-app-root` form a definite `height: 100%` chain. Add
+`.kui-app-root` to the one direct mount container of a full-height application
+whose child is a `Workbench`, `SplitView`, `NavStack`, or another percentage-
+height shell. Ordinary document-flow pages can import the baseline without the
+class. Do not put `.kui-app-root` on several sibling containers: each requests
+the full available document height.
+The class sets `height: 100%`, not a viewport minimum; the direct child shell
+must also fill its parent (for example with its `fill` prop). If the host page
+already supplies a definite height, use that host geometry instead.
+
+### Viewport-locked application shell
+
+A shell that fills the whole window (a `Workbench` app such as Hot Sheet) can
+also lock the document to the viewport:
+
+```html
+<body>
+  <div id="app" class="kui-app-root" data-viewport="locked"></div>
+</body>
+```
+
+With `data-viewport="locked"` on a `.kui-app-root` that is a direct child of
+`body`, `html`, `body`, and the root take `height: 100dvh` and
+`overflow: clip`:
+
+- The **dynamic** viewport height tracks the visible area as mobile browser
+  toolbars show and hide (iOS Safari, WKWebView), so the root is never taller
+  than what the person can see.
+- `overflow: clip` (rather than `hidden`) leaves the document with no scroll
+  container at all. Neither the person, nor `scrollIntoView()`, nor focus can
+  leave the page scrolled: only the shell's `Pane`s scroll.
+
+**On-screen keyboard.** `100dvh` does not shrink for the on-screen keyboard.
+When a field near the bottom takes focus, iOS pans the _visual_ viewport to
+reveal it and pans back when the keyboard closes; because the document itself
+cannot scroll, there is no leftover document offset to restore. A field
+inside a scrolling `Pane` is revealed by that Pane's own scroll. If the
+layout should instead shrink above the keyboard, add
+`interactive-widget=resizes-content` to the viewport meta tag on engines
+that support it. Do not add scroll-restoration handlers for the document:
+the locked document has no scroll position.
+
+Leave the attribute off for document-flow pages and embedded shells; the
+default `height: 100%` chain keeps those scrolling normally.
+
+`kui-app-root` is the public class of the component catalog's
+`document-baseline` entry, so `kerf-ui-doctor` and the
+`kerfjs/ui-public-boundaries` ESLint rule accept it (no KUI-L101 finding).
+
+The stylesheet is intentionally absent from `@kerfjs/ui/styles.css` and every
+component browser import because its global selectors would otherwise change
+consumer documents implicitly. Import it once and load application overrides
+after it.

package/docs/examples/application-ui-profile.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "../../ai/application-ui-profile.schema.json",
+  "schemaVersion": 1,
+  "scope": "workspace",
+  "catalogs": [
+    {
+      "package": "@kerfjs/ui",
+      "selection": {
+        "path": "../../ai/component-catalog.json",
+        "schemaVersion": 1
+      },
+      "composition": {
+        "path": "../../ai/component-composition.json",
+        "schemaVersion": 1
+      }
+    },
+    {
+      "package": "@acme/ui",
+      "composition": {
+        "path": "./component-composition-extension.json",
+        "schemaVersion": 1
+      }
+    }
+  ],
+  "preferences": {
+    "application-shell": {
+      "preferred": "@kerfjs/ui:recipe-app-shell",
+      "rationale": "The workspace uses the standard resizable three-region shell."
+    },
+    "record-inspector": {
+      "preferred": "@acme/ui:inspector",
+      "rationale": "The application-owned inspector maps record policy onto Kerf panel primitives."
+    }
+  },
+  "theme": {
+    "colorScheme": "light",
+    "allowedColorSchemes": ["light", "dark"],
+    "density": "standard",
+    "allowedDensities": ["standard"]
+  },
+  "tokens": {
+    "--kui-color-brand-fill-normal": "oklch(0.62 0.16 255)"
+  },
+  "layout": {
+    "shell": "@kerfjs/ui:recipe-app-shell",
+    "pane": "@kerfjs/ui:pane",
+    "responsiveStrategy": "device-class",
+    "compactNavigation": "nav-stack",
+    "scrollOwnership": "one-per-pane",
+    "spacingScale": "kerf-five-step"
+  },
+  "exceptions": [
+    {
+      "id": "legacy-list-header",
+      "rules": ["KUI-C103"],
+      "target": "src/features/legacy-report/report-list-header.tsx",
+      "rationale": "The legacy report adapter owns disclosure content and its expanded state."
+    }
+  ]
+}

package/docs/examples/command-palette-adapter.tsx

@@ -1,5 +1,7 @@
 import '@kerfjs/ui/layout.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
+import { Text } from '@kerfjs/ui/text';
 import { delegate, mount, signal } from 'kerfjs';
 import { delegateActions } from 'kerfjs/actions';
 
@@ -26,17 +28,57 @@ export function mountCommandPaletteAdapter(
   const query = signal('');
   const render = () => {
     const needle = query.value.trim().toLocaleLowerCase();
-    const matches = commands.filter((command) => !needle ||
-      [command.label, ...(command.keywords ?? [])].some((value) => value.toLocaleLowerCase().includes(needle)));
-    return <section class="app-command-palette kui-content" aria-label="Command palette">
-      <div class="kui-content-item"><label for="app-command-query">Search commands</label><input id="app-command-query" type="search" value={query.value} autocomplete="off" data-command-query /></div>
-      <p class="kui-content-item" aria-live="polite">{matches.length} matching commands</p>
-      <ul class="kui-content-item" aria-label="Matching commands">{matches.map((command) => <li><button type="button" data-action="run-command" data-command-id={command.id}>{command.label}</button></li>)}</ul>
-      <footer class="kui-control-cluster kui-content-item" aria-label="Command palette actions">
-        <button type="button" data-action="clear-query">Clear search</button>
-        <button type="button" data-action="close-palette">Close</button>
-      </footer>
-    </section>;
+    const matches = commands.filter(
+      (command) =>
+        !needle ||
+        [command.label, ...(command.keywords ?? [])].some((value) =>
+          value.toLocaleLowerCase().includes(needle),
+        ),
+    );
+    return (
+      <section
+        class="app-command-palette kui-content"
+        aria-label="Command Palette"
+      >
+        <ContentItem>
+          <label for="app-command-query">Search commands</label>
+          <input
+            id="app-command-query"
+            type="search"
+            value={query.value}
+            autocomplete="off"
+            data-command-query
+          />
+        </ContentItem>
+        <Text class="kui-content-item" aria-live="polite">
+          {matches.length} matching commands
+        </Text>
+        <ul class="kui-content-item" aria-label="Matching commands">
+          {matches.map((command) => (
+            <li>
+              <button
+                type="button"
+                data-action="run-command"
+                data-command-id={command.id}
+              >
+                {command.label}
+              </button>
+            </li>
+          ))}
+        </ul>
+        <footer
+          class="kui-control-cluster kui-content-item"
+          aria-label="Command Palette Actions"
+        >
+          <button type="button" data-action="clear-query">
+            Clear Search
+          </button>
+          <button type="button" data-action="close-palette">
+            Close
+          </button>
+        </footer>
+      </section>
+    );
   };
 
   const stopMount = mount(root, render);
@@ -52,12 +94,22 @@ export function mountCommandPaletteAdapter(
     },
     'close-palette': onClose,
   });
-  const stopInput = delegate<HTMLInputElement>(root, 'input', '[data-command-query]', (_event, input) => {
-    query.value = input.value;
-  });
-  const stopEscape = delegate(root, 'keydown', '[data-command-query]', (event) => {
-    if ((event as KeyboardEvent).key === 'Escape') onClose();
-  });
+  const stopInput = delegate<HTMLInputElement>(
+    root,
+    'input',
+    '[data-command-query]',
+    (_event, input) => {
+      query.value = input.value;
+    },
+  );
+  const stopEscape = delegate(
+    root,
+    'keydown',
+    '[data-command-query]',
+    (event) => {
+      if ((event as KeyboardEvent).key === 'Escape') onClose();
+    },
+  );
   let disposed = false;
   return () => {
     if (disposed) return;

package/docs/examples/component-catalog-extension.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "../../ai/component-catalog-extension.schema.json",
+  "schemaVersion": 1,
+  "package": "@acme/ui",
+  "description": "Application-owned components composed with Kerf UI.",
+  "entries": [
+    {
+      "id": "acme-filter-chip",
+      "name": "FilterChip",
+      "kind": "component",
+      "purpose": "A removable application filter displayed inside a search-field workflow.",
+      "useWhen": [
+        "A saved application filter needs a compact visible label and remove action."
+      ],
+      "avoidWhen": [
+        "The value belongs to SearchField's own controlled token collection."
+      ],
+      "publicClasses": ["acme-filter-chip"],
+      "publicTokens": ["--acme-filter-chip-accent"],
+      "uses": ["chip"],
+      "source": "src/filter-chip.tsx",
+      "styleSources": ["src/filter-chip.css"],
+      "demoSource": "ux-demo/demos/filter-chip.tsx",
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "documentation": "docs/filter-chip.md"
+    },
+    {
+      "id": "acme-inspector",
+      "name": "Inspector",
+      "kind": "composition",
+      "purpose": "An application inspector composed from Kerf panel, content, and value primitives.",
+      "useWhen": ["A selected record needs a titled fact-and-action region."],
+      "avoidWhen": ["A ValueTable alone expresses the complete interaction."],
+      "uses": ["acme-filter-chip", "toolbar", "value-table"],
+      "source": "src/inspector.tsx",
+      "demoSource": "ux-demo/demos/inspector.tsx",
+      "geometry": {
+        "margin": "parent",
+        "border": "child",
+        "padding": "child",
+        "notes": [
+          "The embedding pane positions the inspector; Toolbar, ValueTable, and action groups retain their own geometry."
+        ]
+      },
+      "documentation": "docs/inspector.md"
+    }
+  ]
+}