@kerfjs/ui 5.0.0-beta.49 → 5.0.0-beta.51

package/docs/ux-demo.md

@@ -12,26 +12,26 @@ of the current `src/` and `ux-demo/` inputs, so a stale `dist-demo` cannot pass
 after a route or component edit. `npm run demo:serve` remains a preview-only
 command for an already-built catalog.
 
-Seven lazy production-composition routes live under the `Recipes` category.
+Ten lazy production-composition routes live under the `Recipes` category.
 Each `?component=recipe-*` route uses public package primitives, real wiring,
 deterministic state, and semantic layout owners from the [recipe guide](./recipes.md).
 
 - It imports public component subpaths, exercising their browser-selected reachable CSS rather than a catalog-only style path.
 - 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` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes without application readouts. The separate `Application tabs composition` route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. The `ResizableRegion` route likewise replaces only the decorative handle glyph while retaining separator semantics and shared wiring.
+- The `AppTab` and `TabBar` routes are focused component specimens: AppTab shows its selected, compact, segmented, icon-only, truncation, placeholder, metadata, and close-icon axes inside the required tablist context; TabBar shows its rail, segmented, inspector, allocation, placement, and accessory-zone axes, including an adjacent action plus a separately pinned end action whose tabs overflow at narrow widths, without application readouts. The separate `Application tabs` composition route demonstrates controlled selection, matching panel content, overflow, adding, closing, keyboard/pointer reordering, and application-owned ordering. 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, and feedback scenarios remain addressable alongside their subcomponents; the root opens the first Kerf component. The former aggregate Web Awesome theme specimen is intentionally omitted because its component families are covered by those focused routes.
-- `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/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
+- `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. Functional groups follow their authored importance order; components precede compositions inside each group, equal-importance entries use alphabetical order, and the Recipes group comes last. Composition names stay concise and project a visible `Composition` sidebar tag. Non-supported Web Awesome recommendations project to a visible `Discouraged` 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/<public-subpath>.tsx` from their canonical `delivery.browserImport` or opt-in `delivery.moduleImport`.
 - 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. 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 supporting copy in its own aligned row; 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 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 supporting copy in its own aligned row; 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 preview scroll owner rather than a viewport-height stage or nested card, and one explicitly repeated SVG tile keeps the pattern continuous through below-fold content. 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 toolbar title/supporting-copy 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.
+- The list-detail dialog recipe composes `DialogSurface`, the dialog's own labeled header and close control, `SplitView`, and footer actions. Its `SplitView` sits flush in the dialog body, both panes open with a `ListHeader` on one shared line, the dialog title and header text share the 17px text edge, the value table keeps the 8px outer margin, and the trailing actions keep the 16px footer gutter. Compact devices get a full-screen sheet with a list-to-detail drill-down. Browser geometry coverage protects those relationships at wide and narrow widths.
 - Catalog-only brand marks, preview dimensions, checkerboard tiles, and the compound display-settings control retain local geometry because they are specimen chrome or intrinsic control anatomy rather than reusable application spacing roles.
 - The menu composition route demonstrates toolbar/content/footer anatomy, 24px major gaps, 8/1/8 child geometry, the full-width `ListHeader` count-or-badge/action split, logical-end 44px action targets with 18px visuals, and 44px row/header/toolbar targets. Its one chevron is a production 18px `DisclosureArrow` inside a controlled Tools header that actually reveals and hides content; ordinary Projects navigation has no false disclosure affordance. Browser assertions cover stable naming, expanded/content transitions, visual rotation, node identity, reduced motion, RTL alignment and containment, and wide, narrow, dark, and 200% layouts. The focused ListHeader route separately shows the shared neutral count pill for Attachments, Notes (including zero), and Duplicates plus a non-count legacy badge, full-width logical-end actions, and no disclosure without content.
 - The `DisclosureArrow` route renders the production 18px root-scaled default without a catalog-only size override. Its two native buttons independently control the default right-to-down chevron and a recognizable right-facing replacement arrow with left-to-up custom directions; both use shortest-path rotation and their names stay stable while `aria-expanded` communicates state. Browser coverage verifies the custom clockwise path, pointer and native keyboard activation, focus, narrow and 200%-zoom stacking with contained labels, consumer sizing, and the independent `.5` Web Awesome glyph scale retained by Kerf `Select`.
 - A detail with relationships renders one content-fitted `Components` footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. Its popup owns the standard surface inset so headings and even long component names stay clear of the menu border. Choosing either navigates to that component's demo. The relationship group is absent when both sets are empty; no duplicate summary is rendered.
-- Demo-only CSS supplies only the catalog shell and stages; component appearance stays in package CSS. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
-- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Focused demos ship no local stylesheets, inline styles, or styling-only class names. They compose Kerf components first, Web Awesome surfaces where Kerf has no equivalent, and ordinary semantic HTML for the remainder. The catalog-owned `CatalogExample.viewport` contract supplies the few specimen constraints needed to demonstrate layout behavior. Recipes follow the same rule: they ship no stylesheets, inline styles, or styling-only classes, and the catalog frames each one in the `CatalogExample` viewport its exported `presentation` declares (full-width application arrangements span the canvas measure; narrower recipes sit in the centered example column). Demo-only CSS is limited to the document-shell `style.css`, which carries no recipe rules. Decorative chrome and Web Awesome controls share the same semantic system palette instead of carrying a separate demo identity.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. Individual Web Awesome action, form, layout, navigation, feedback, media, and helper routes provide focused theme specimens without a redundant aggregate route; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; the Headers composition demonstrates direct toolbar headings with an extra-large title, optional supporting copy, and grouped icon/actions; the Select route verifies that option icons survive unrelated Kerf rerenders and selected slot content follows value changes; the Animation route exposes preset, easing, duration, playback-rate, and transport controls with live lifecycle status; observer routes provide user-driven intersection, mutation, and resize events with live results; ToolbarControlGroup exposes all eight Hot Sheet 2 variants, loads the Web Awesome registrations needed by its popup specimen, and preserves the upgraded dropdown's managed light-DOM children across Kerf rerenders; the Toolbar route composes a collapsible TokenSearchField inside a group, animates between the empty iconic and complete field states, stays open while populated, and focuses the revealed editor; SegmentedControl covers toolbar, rounded-rectangle, pill, equal-width, and disabled presentations; TokenSearchField covers editable ordered chips, pointer and keyboard removal, caret-preserving controlled deletion, editing, clearing, free text, disabled state, and fixed first-line alignment while content wraps; StateBanner exposes every built-in tone with tone-tinted badges plus a scoped override; the Application tabs composition uses a Web Awesome card with semantic header/footer slots and Kerf `Text` while demonstrating overflow, edge autoscroll, and controlled pointer/keyboard reordering.
 - The ToolbarControlGroup route also demonstrates the public compact/tight,
   mixed-content, filled-selection, nested-dropdown, and avatar/scrim contracts
   added for consumers that previously restyled group descendants. The compact
@@ -42,7 +42,7 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
   paints only the pressed selection, with contain fitting in both cases. Its
   collapsible-search specimen follows the selected group shape with a
   concentric inner radius in both collapsed and expanded states.
-- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals them as floating warning-toned notes with a folded corner, keeping instructional copy visually distinct and removable from the specimen flow.
+- Recipe ownership notes are hidden by default. A page-toolbar toggle reveals each recipe's note as its `CatalogExample` note above the framed specimen, so instructional copy never covers the composition.
 - Settings exercise light/dark, increased contrast, and reduced motion without changing component code. The theme action starts from the operating system's effective color scheme, always names the appearance it will switch to, and installs an explicit light or dark override when activated; contrast and reduced motion expose their independent preferences through `aria-pressed`.
 - The footer action log is an `aria-live` region, making interactions visible to both people and browser tests.
 - The focused Toast route calls Web Awesome's documented programmatic stack API and notes that Hot Sheet 2 still uses its own app-level toast implementation; the catalog demonstrates ecosystem support without implying current product adoption.

package/docs/webawesome-theme.md

@@ -54,12 +54,30 @@ 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.
 
+Code text uses Kerf's named monospace stack, `--kui-font-mono`
+(`ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono",
+monospace`), and the theme points `--wa-font-family-code` at it. Web Awesome's
+own `ui-monospace, monospace` renders the generic face (Courier on macOS) in
+Chromium, which does not recognize `ui-monospace`; because the generic
+`monospace` ends any stack, Kerf's token owns the stack rather than appending
+fallbacks after Web Awesome's. Override `--kui-font-mono` to change code text in
+both Kerf and Web Awesome components.
+
 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 +
+the value sits 9px in from the field edge. Default-size single-line controls
+share Kerf's 44px control height — the height of a Kerf `Select`, a toolbar
+group, and a list row — so a `wa-input` or `wa-button` sits flush beside a Kerf
+`Select`. The theme sets `--wa-form-control-height` to `2.75em` (44px at the
+16px default) on Button, Color Picker, Input, Known Date, Number Input, Radio
+Group, Select, Textarea (its minimum height), and Time Input, so `size="large"`
+scales proportionally while `size="small"` keeps Web Awesome's compact secondary
+height. The token is scoped to those controls rather than the root because Web
+Awesome also derives tag, copy-button, and toast geometry from it. Buttons
+inside a `ToolbarControlGroup` keep the group's 40px (32px compact) control
+height. 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
@@ -97,10 +115,11 @@ tiers:
   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.
-- Plain Accordion and Details remove inline padding from both their trigger and
-  content so their text aligns directly with the surrounding flow. Outlined and
-  sunken disclosure triggers use the 16px `--kui-wa-container-inset`, one 8px
-  step beyond their compact body inset.
+- Plain Details use the 8px `--kui-wa-surface-inset` on the trigger and keep the
+  body flush; plain Accordion items use that 8px inset on both trigger and body.
+  Outlined and sunken Details use the 16px `--kui-wa-container-inset` on the
+  trigger and the 8px surface inset on the body, while framed Accordion items
+  use the 16px container inset for both regions.
 - `appearance="sunken"` is a Kerf theme extension for Accordion, Card, and
   Details. It removes raised chrome, paints the lowered semantic surface, and
   uses the shared rounded-rectangle radius. Override

package/docs/workbench.md

@@ -12,6 +12,12 @@ import { Workbench } from "@kerfjs/ui/workbench";
 import "@kerfjs/ui/workbench.css";
 ```
 
+A top-level `Workbench` needs a definite containing height. Import the opt-in
+`@kerfjs/ui/document.css` baseline and add `.kui-app-root` to the direct mount
+container, or provide an equivalent definite height in application-owned
+layout. The component intentionally uses `height: 100%` rather than `100dvh` so
+it can also be embedded. See [Document baseline](document-baseline.md).
+
 ## State lives in the app
 
 `Workbench` is declarative and the collapse is **pure CSS** — no wire. The app
@@ -90,7 +96,10 @@ with state-derived props:
 ```
 
 `wireResizableRegions` marks the active region with `data-resizing` and the
-package CSS suppresses content motion during pointer resize. A collapsed,
+package CSS suppresses content motion during pointer resize. It applies the
+live size to both the track and the slide-motion content, so content fills the
+region throughout a drag, including any safe-area edge extent, and a later
+collapse slides it out at the resized width. A collapsed,
 overlay, or hidden region is not resizeable. Together these policies replace
 app CSS for separator suppression, instant-track/composited-content collapse,
 popup overflow, mobile overlay/hidden replacement, resize-transition guards,
@@ -110,6 +119,16 @@ must classify public application selectors. Prefer the component props and two
 size tokens before selecting internal anatomy, and do not target its data
 attributes or descendant tags as styling contracts.
 
+## Safe areas
+
+Each rail and the drawer grows by the unsafe inset of the screen edge it docks
+to, so its surface and separator paint through while its content keeps the
+configured size and is padded for the edges it touches. The main area pads for
+the edges it reaches, inside its scroller: an expanded inline rail or drawer
+takes that edge away, and collapsing it (or presenting it as an overlay) hands
+the edge back. A region whose only child is a `Pane` or layout lets that child
+own the insets. See [Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
 ## How the collapse animates
 
 Collapsing snaps the panel's flex track to zero in a single reflow (so the work

package/evaluator/index.mjs

@@ -336,6 +336,50 @@ async function inspectPage(page, geometryContracts) {
       return null;
     };
 
+    const hitExtent = (element, rect) => {
+      const root = element.getRootNode();
+      const probe = root.elementFromPoint ? root : document;
+      const inViewport = (x, y) =>
+        x >= 0 && y >= 0 && x < innerWidth && y < innerHeight;
+      const owns = (x, y) => {
+        const hit = probe.elementFromPoint(x, y);
+        return !!hit && (hit === element || element.contains(hit));
+      };
+      const x = rect.left + rect.width / 2;
+      const y = rect.top + rect.height / 2;
+      if (!inViewport(x, y) || !owns(x, y)) return null;
+      // Walk out in 1px steps (no further than the 44px goal needs), then
+      // refine the last step in quarter pixels; the reach is the last owned
+      // sample, so it never overstates the target. A walk stopped by
+      // the viewport edge cannot see the rest of the layer, so it is marked
+      // and mirrored from the opposite side (hit layers are symmetric insets).
+      const reach = (dx, dy) => {
+        const at = (distance) => [x + dx * distance, y + dy * distance];
+        let owned = 0;
+        while (owned < 24) {
+          const point = at(owned + 1);
+          if (!inViewport(...point)) return { distance: owned, clipped: true };
+          if (!owns(...point)) break;
+          owned += 1;
+        }
+        if (owned >= 24) return { distance: owned, clipped: false };
+        while (owns(...at(owned + 0.25))) owned += 0.25;
+        return { distance: owned, clipped: false };
+      };
+      const span = (first, second) =>
+        first.clipped && second.clipped
+          ? first.distance + second.distance
+          : first.clipped
+            ? 2 * second.distance
+            : second.clipped
+              ? 2 * first.distance
+              : first.distance + second.distance;
+      return {
+        width: span(reach(-1, 0), reach(1, 0)),
+        height: span(reach(0, -1), reach(0, 1)),
+      };
+    };
+
     for (const element of interactives) {
       const target = selector(element);
       const rect = element.getBoundingClientRect();
@@ -495,14 +539,35 @@ async function inspectPage(page, geometryContracts) {
           'button,input:not([type="hidden"]),select,textarea,[role]',
         ) &&
         (rect.width < 43.5 || rect.height < 43.5)
-      )
-        diagnostics.push({
-          code: 'KUI-B050',
-          selector: target,
-          message: `Hit target is ${rect.width.toFixed(1)}×${rect.height.toFixed(1)}px; expected at least 44×44px.`,
-          repair: repair.target,
-          evidence: { width: rect.width, height: rect.height },
-        });
+      ) {
+        // The border box understates a control whose pointer target is
+        // extended by a transparent hit layer (a positioned ::before/::after
+        // that receives pointer events). Hit-test outward from the center to
+        // measure the area the pointer can actually reach; a probe that finds
+        // no hit (off-screen, covered center) keeps the border box.
+        const hit = hitExtent(element, rect);
+        const width = Math.max(rect.width, hit?.width ?? 0);
+        const height = Math.max(rect.height, hit?.height ?? 0);
+        // Compact density is a deliberate trade-off: its rows are 36px tall,
+        // and a taller hit layer would reach into the neighboring row. Inside
+        // `[data-density="compact"]` a target still needs the full 44px width
+        // but only the 36px compact row height.
+        const compact = element.closest('[data-density="compact"]') !== null;
+        const requiredHeight = compact ? 36 : 44;
+        if (width < 43.5 || height < requiredHeight - 0.5)
+          diagnostics.push({
+            code: 'KUI-B050',
+            selector: target,
+            message: `Hit target is ${width.toFixed(1)}×${height.toFixed(1)}px; expected at least 44×${requiredHeight}px${compact ? ' (compact density)' : ''}.`,
+            repair: repair.target,
+            evidence: {
+              width,
+              height,
+              box: { width: rect.width, height: rect.height },
+              required: { width: 44, height: requiredHeight },
+            },
+          });
+      }
     }
 
     const parse = (value) => {

package/llms.txt

@@ -12,6 +12,10 @@ npm install kerfjs @kerfjs/ui # kerfjs is a peer; Web Awesome is an optional pee
 Import each component from its own subpath (`@kerfjs/ui/list-item`, `@kerfjs/ui/toolbar`,
 …); the browser build pulls that component's reachable CSS automatically, so do not
 maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
+For a public subpath containing several visual components, use a folder with one
+component per source file and one owned stylesheet per visual component. Keep its
+compatibility entrypoints implementation-free: JavaScript/TypeScript only re-exports
+the folder modules, and CSS only imports their owner stylesheets.
 
 ## How to build a screen (retrieval order)
 
@@ -30,7 +34,9 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
    when app-owned components must participate in selection or alignment.
    Load the [Composition catalog v2](./ai/component-catalog-v2.json) to
    mechanically evaluate parents, contexts, zones/cardinality, children, state,
-   wiring, responsive/layout/accessibility rules, and public boundaries. V1
+   wiring (including the wiring-owned `stateAttributes` an app must never
+   render or remove), responsive/layout/accessibility rules, and public
+   boundaries. V1
    remains compatible; v2 joins catalogs by `package:id`. Consumer v2 catalogs
    use [the v2 extension schema](./ai/component-catalog-extension-v2.schema.json).
    Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
@@ -56,9 +62,19 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
    `ListInsetText`. These are typed props, not native `<slot>` elements,
    wrapper slot components, or a generic `slots` object. Leave unresolved
    dynamic expressions unknown.
+   Stable single-root Kerf UI components separately accept the explicit native
+   `slot="name"` prop for light-DOM composition inside a custom element and
+   preserve it across rerenders. Do not infer arbitrary native-attribute
+   spreading from this narrow interop contract. `ResizableRegion` and
+   `CollapsiblePanel` remain excluded because their optional restore controls
+   make their output multi-root; `CollapsiblePanelToggle` remains slot-capable.
 4. **When authoring a component gallery**, load
    [catalog-authoring.json](./ai/catalog-authoring.json), then follow its
    authoritative [Catalog demo authoring contract](./docs/catalog.md#catalog-demo-authoring-contract).
+   Use its component/composition/recipe taxonomy and functional-group,
+   importance, alphabetical-tie, and recipes-last ordering policy. Focused
+   demos and recipes use public components plus `CatalogExample.viewport`,
+   never local stylesheets, inline styles, or styling-only classes.
 5. **Apply the rules below and in** [skill.md](./ai/skill.md).
 6. **Before calling an integration complete**, run
    [`kerf-ui-doctor`](./docs/ui-doctor.md). Its portable JSON report merges
@@ -81,16 +97,21 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 ## 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`,
-  `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,
-  and then only join a component's documented `publicClasses` (never reach in by
-  tag/id/attribute or an unlisted class).
+  without an application customization layer. Before adding `padding`, `margin`,
+  `width`, `height`, `border`, `background`, a wrapper card, or a decoration,
+  check whether the component, pane, or content-item already owns it. Prefer a
+  component prop or documented `--kui-*` token. CSS for genuinely new structure
+  belongs to the application-owned component that renders it and must not select
+  nested Kerf or Web Awesome components.
 - **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
   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.
+- **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
+  once for border-box sizing, token-backed body/link presentation, and zero body
+  margin. Put `.kui-app-root` on the one direct mount container only when a
+  percentage-height shell needs the provided `html` → `body` → app-root height
+  chain. The baseline is not part of `styles.css` or component browser imports.
 - **Use `Row` for horizontal and `List` for vertical layout.** Both expose
   physical `hAlign`/`vAlign` props and typed gaps. Row defaults to left/full,
   an `xs` gap, and no wrapping; List retains full/top and zero-gap defaults.
@@ -105,19 +126,26 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   shorthand (`gap="xs"`, `gap="m"`) or a complete `CssLength` from the CSS-free
   `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
   for List flex, typed lengths for Skeleton geometry, and
-  `uiColor()`/`colorVar()` for choice-icon colors. These brands are intentionally
+  foreground colors for choice icons: `uiColor()` with an `*-on-*`/text token
+  or `foregroundColorVar()`; fill aliases such as `uiColor('success')` do not
+  type-check. These brands are intentionally
   not interchangeable; rows use classes/tokens/props rather than raw `style`.
 - **Use `Grid` for a fixed positive count of equal-width columns.** It uses
   zero-minimum fractional tracks, so intrinsic content cannot make one column
   wider than its peers. The app owns responsive count changes; use custom CSS
   grid for asymmetric/intrinsic tracks and `ResizableRegion` for adjustable
   boundaries. `Grid.gap` and `Grid.flex` use the same typed grammars as Row.
+- **Give a layout root `fill`, not a frame `Pane`.** A Row, List, or Grid that
+  is the sole layout root of a definite-height parent takes its full height
+  with `fill` and carries safe `data-*` markers through `rootAttributes`.
+  Inside a flex layout use `flex` instead.
 - **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
-  plain Accordion/Details remove inline trigger/body padding and their
-  outlined/sunken headers use the 16px container inset,
+  plain Details keep their body flush while plain Accordion items inset both
+  trigger and body, framed Details use the 16px container inset only on the
+  trigger, and framed Accordion items use it on both regions;
   `--kui-wa-container-inset` keeps Tab Panel at 16px. Dialog body and footer use
   the surface (8px) and container (16px) tiers respectively, independent of the
   dialog's shared `--spacing`. Override the tier at the narrowest useful scope
@@ -160,22 +188,25 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   need a Web Awesome feature, chiefly the `slot="trigger"` button of a `wa-dropdown`
   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`). Compact mixed groups keep standard item padding
-  and raised selected chrome without an internal separator; the selected item
-  paints over the outer border. For an avatar control, set `content="avatar"` and
-  `avatarImage` on the group instead of inserting an `img`; a lone control paints
-  the group and a multi-button group paints only its pressed highlight.
+  `data-morph-skip-children`). Let the group size the trigger from its icon,
+  localized text, and caret; do not force a dropdown or button width. Compact
+  mixed groups keep standard item padding and raised selected chrome without an
+  internal separator; the selected item paints over the outer border. For an
+  avatar control, set `content="avatar"` and `avatarImage` on the group instead of
+  inserting an `img`; a lone control paints the group and a multi-button group
+  paints only its pressed highlight.
 - **Use one direct toolbar composition for panel/dialog/page headings.** Put an
   optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
   in the leading zone, and actions in a trailing group. Supporting copy is
   app-owned content below. Do not create a private heading wrapper or restyle the
   toolbar.
-- **Use `Text` for ordinary semantic headings and paragraphs outside toolbar
-  title zones.** Omit `variant` for the default `p`, or pass `h1`–`h6` based on
-  the document outline. Independently compose `tone="quiet|danger"`,
+- **Use `Text` for ordinary semantic headings, paragraphs, and inline secondary
+  text outside toolbar title zones.** Omit `variant` for the default `p`, pass
+  `h1`–`h6` based on the document outline, or use `variant="span"` inside a row,
+  label, or table cell without adding box geometry. Independently compose `tone="quiet|danger"`,
   `size="compact"`, and `font="monospace"` for supporting, error, compact, and
   code roles instead of global utility classes. It passes native attributes
-  through and owns the standard transparent border plus item padding; keep
+  through; block variants own the standard transparent border plus item padding, while `span` owns none. Keep
   toolbar titles on `ToolbarText` and list-aligned bare prose on `ListInsetText`.
 - **Space by the five-step scale, by relationship not by eye.** `0`
   `--kui-space-none`, `4px` `--kui-space-2xs`, `8px` `--kui-space-xs` (inside a
@@ -207,7 +238,11 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   overflow autoscroll, drag preview, and
   replacement focus after controlled automatic tab activation,
   `wireResizableRegions` the live drag preview; they report committed changes via
-  callbacks. Managed TokenSearchField clear also preserves open state and replacement
+  callbacks. For a tab-local action plus a separate far-edge action, set
+  `TabBar trailingPlacement="adjacent"`, put the local action in `trailing`, and
+  the workspace action in `end`; the component keeps both visible while its tab
+  list shrinks and scrolls, without application descendant CSS. Managed
+  TokenSearchField clear also preserves open state and replacement
   editor focus before the next input task, so shortcut-letter typing stays in search.
   Select All deletion does the same; deletion
   restoration finishes before the next keystroke rather than on a delayed frame.
@@ -244,10 +279,13 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   optional string `badge` for a terse count or status beside the title. It
   inherits the banner tone and is announced with the banner, so keep its text
   meaningful and never rely on color alone.
+- **Use `Badge` for compact non-interactive metadata.** Configure its semantic
+  tone, appearance, shape, and size instead of creating badge CSS in an app or
+  consuming component. Use a real button or link for interactive content.
 
 ## Public exports
 
-`LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ToolbarText`, `Text`,
+`Badge`, `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `ToolbarActionLink`, `FloatingToolbar`, `ToolbarText`, `Text`,
 `ListItem`, `ListActionRow`, `ListHeader`, `ListInsetControl`,
 `ListInsetText`, `SegmentedControl`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
@@ -259,7 +297,7 @@ tree-shakeable, declarative with `wire…` helpers, each with a companion CSS im
 `@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/wire-sidebar` (`wireSidebar`: toggle, focus, compact overlay, persistence; a compact overlay starts closed and opens only on a user action, and `inlineCollapsed` declares a panel's inline default).
   `@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
@@ -280,7 +318,7 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [component-contract.md](./docs/component-contract.md): what a component owns vs. what the app owns.
 - [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.
+- [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
 - [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) + [catalog-authoring.json](./ai/catalog-authoring.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 selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
 - [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.49",
+  "version": "5.0.0-beta.51",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -58,6 +58,11 @@
       "browser": "./dist/browser/disclosure-arrow.js",
       "import": "./dist/disclosure-arrow.js"
     },
+    "./badge": {
+      "types": "./dist/badge.d.ts",
+      "browser": "./dist/browser/badge.js",
+      "import": "./dist/badge.js"
+    },
     "./toolbar": {
       "types": "./dist/toolbar.d.ts",
       "browser": "./dist/browser/toolbar.js",
@@ -287,10 +292,12 @@
       "import": "./dist/index.js"
     },
     "./foundation.css": "./dist/styles/foundation.css",
+    "./document.css": "./dist/styles/document.css",
     "./layout.css": "./dist/styles/layout.css",
     "./webawesome.css": "./dist/styles/webawesome.css",
     "./styles.css": "./dist/styles/styles.css",
     "./lucide-icon.css": "./dist/styles/lucide-icon.css",
+    "./badge.css": "./dist/styles/badge.css",
     "./disclosure-arrow.css": "./dist/styles/disclosure-arrow.css",
     "./toolbar.css": "./dist/styles/toolbar.css",
     "./toolbar-control-group.css": "./dist/styles/toolbar-control-group.css",
@@ -345,7 +352,8 @@
   "scripts": {
     "build": "tsup && node ../scripts/clean-dist-output.mjs dist && node scripts/build-css.mjs && node scripts/build-browser-entries.mjs",
     "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:bundle": "npm run build && vite build --config ux-demo/vite.config.ts",
+    "demo:build": "npm run demo:bundle && node scripts/check-demo-bundle.mjs",
     "demo:serve": "vite preview --config ux-demo/vite.config.ts",
     "test:e2e:serve": "npm run check:catalog && npm run check:demo-conformance && npm run demo:build && npm run demo:serve",
     "format": "prettier --write . --ignore-unknown",
@@ -360,6 +368,7 @@
     "check:profile": "node scripts/check-application-ui-profile.mjs",
     "check:demo-conformance": "node scripts/check-catalog-demo-conformance.mjs",
     "check:recipes": "node scripts/check-recipes.mjs",
+    "check:css-ownership": "node scripts/check-css-ownership.mjs",
     "check:ai-regressions": "node scripts/check-ai-regressions.mjs && node scripts/audit-ai-regression-results.mjs && node scripts/audit-ai-regression-results-v3.mjs",
     "check:ai-signatures": "node scripts/sync-ai-public-signatures.mjs --check",
     "ai:signatures:sync": "npm run build && node scripts/sync-ai-public-signatures.mjs",
@@ -385,7 +394,7 @@
     "test:contract-types:packed": "node scripts/check-packed-type-contracts.mjs",
     "test:consumer-types": "npm run test:contract-types:source && npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json && npm run test:contract-types:packed",
     "test:e2e": "playwright test",
-    "check": "npm run check:catalog && npm run check:component-integrations && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:guidance && npm run check:ai-compatibility && 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:component-integrations && npm run check:profile && npm run check:demo-conformance && npm run check:recipes && npm run check:css-ownership && npm run check:guidance && npm run check:ai-compatibility && 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",