@kerfjs/ui 5.0.0-beta.24 → 5.0.0-beta.26

package/docs/type-contracts.md

@@ -19,11 +19,10 @@ public-signature artifact.
 | `KUI-T004` | A literal `SegmentedControl.value` belongs to its literal `choices`.                                                                                                                   |
 | `KUI-T005` | `expanded`, `expandAction`, and `expandLabel` exist only on `TokenSearchField({ collapsible: true })`.                                                                                 |
 | `KUI-T006` | `TokenSearchEditorAttributes` accepts application `data-*` metadata but rejects component-owned identity, morph, count, and placeholder attributes.                                    |
-| `KUI-T007` | `PanelHeader.summaryId` cannot exist without rendered `summary` content.                                                                                                               |
-| `KUI-T008` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                              |
-| `KUI-T009` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                       |
-| `KUI-T010` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                      |
-| `KUI-T011` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all ToolbarControlGroup presentation axes.                        |
+| `KUI-T007` | `ToolbarText.maxLines` requires `wrap: true`; it is never silently ignored in typed code.                                                                                              |
+| `KUI-T008` | A literal `TabScaffold.active` id belongs to its literal `tabs`.                                                                                                                       |
+| `KUI-T009` | Adjacent-token keyboard removal requires `onRemoveToken`; disabling removal rejects the now-meaningless callback.                                                                      |
+| `KUI-T010` | Finite public variants have named exported union types, including divider sides, tab activation, banner urgency, and all ToolbarControlGroup presentation axes.                        |
 
 Literal identity inference is intentionally additive for dynamic applications.
 When choices or ids arrive at runtime and the state signal is correctly typed as
@@ -45,7 +44,7 @@ ordinary source/type gates:
 
 - required identity or accessible-name inputs on `AppTab`, `FloatingToolbar`,
   `NavStack`, `SplitView`, `Workbench`, `TabBar`, `ResizableRegion`,
-  `SegmentedControl`, `TokenSearchField`, `PanelHeader`, and `ValueTable`;
+  `SegmentedControl`, `TokenSearchField`, and `ValueTable`;
 - finite variants exported or represented as literal props on `DisclosureArrow`,
   `FloatingToolbar`, `Pane`, `ResizableRegion`, `SegmentedControl`, `StateBanner`,
   `SunkenPanel`, `ToolbarText`, `CollapsiblePanel`, `Catalog`, and the wire helpers;
@@ -92,8 +91,7 @@ move errors into casts without making the integration safer.
   `{ keyboard: { onRemoveToken } }` or
   `{ keyboard: { removeAdjacentToken: false } }` when only caret navigation is
   wanted.
-- Remove orphaned `summaryId`, or render the matching `summary`; add
-  `wrap: true` anywhere `ToolbarText.maxLines` is used.
+- Add `wrap: true` anywhere `ToolbarText.maxLines` is used.
 - Replace `Toolbar({ divider: false })` with `dividerSides: ''`; the default
   remains a bottom divider, while canonical combinations such as `tr` and
   `trbl` select more physical edges.

package/docs/ui-analyzer.md

@@ -46,6 +46,9 @@ policy, or analysis inputs to the containing application.
 | `KUI-L007` | error  | A declared scroll owner is nested inside another scroll owner.    |
 | `KUI-L008` | review | A dynamic class expression cannot be classified soundly.          |
 | `KUI-L009` | error  | A stylesheet cannot be parsed.                                    |
+| `KUI-L010` | error  | A selector reaches a private Kerf descendant from a public root.  |
+| `KUI-L011` | error  | A `::part()` target is not cataloged as a public extension point. |
+| `KUI-L012` | error  | CSS assigns a Kerf token without a public configuration contract. |
 
 Errors are provable contract violations and make the command exit 1. Review
 findings are deliberately heuristic and do not fail by default; pass
@@ -53,6 +56,20 @@ findings are deliberately heuristic and do not fail by default; pass
 gate CI. Text, versioned JSON, and SARIF carry the same stable rule ids,
 source locations, evidence, and ownership chain.
 
+For staged adoption, pass `--adoption`. Ownership-boundary diagnostics are
+reported as review findings so a team can inventory and migrate its baseline;
+combine it with the exact file-and-rule exceptions below for intentional legacy
+integrations. Remove `--adoption` to make unsupported overrides blocking.
+
+Catalog `boundaries.publicClasses` and `boundaries.publicTokens` are explicit
+CSS extension points. A component catalog may additionally list shadow-part
+names in `boundaries.publicParts`; all other `::part()` targets are private.
+Part names are scoped to that entry's `boundaries.rootClass`, so an extension
+point on one component does not authorize the same-named part on another.
+Parent-owned placement and selectors for application-owned content remain
+allowed because the analyzer only reserves `.kui-*`, `--kui-*`, and cataloged
+shadow boundaries.
+
 The JSON report schema is exported as
 `@kerfjs/ui/analyzer/report.schema.json`.
 
@@ -82,5 +99,6 @@ validator.
 ```
 
 Review findings remain visible until explicitly suppressed. Avoid suppressing
-`KUI-L001`, `KUI-L002`, `KUI-L003`, `KUI-L007`, or `KUI-L009`: those indicate a
+`KUI-L001`, `KUI-L002`, `KUI-L003`, `KUI-L007`, `KUI-L009`, `KUI-L010`,
+`KUI-L011`, or `KUI-L012`: those indicate a
 definite boundary or parsing failure rather than an aesthetic judgment.

package/docs/ui-doctor.md

@@ -15,7 +15,7 @@ The default terminal output is short and repair-oriented. `--format json` emits
 
 The catalog stage discovers the package-default application UI profile and workspace/root-to-leaf directory layers. It validates referenced selection/composition catalogs and, when a workspace declares `package.json#kerfComponentCatalog`, invokes the installed `create-kerf-component` catalog checker to validate metadata, source exports, schema conformance, and generated-output drift. This checker reads source text; it does not import application modules.
 
-TypeScript uses the compiler API with `noEmit`. ESLint loads the installed `eslint-plugin-kerfjs` `recommended-ui` preset (`--eslint strict-ui` opts into advisory rules as errors). This is deliberately an isolated Kerf lint pass rather than the consumer's complete ESLint configuration. Inline directives for consumer-owned plugins, such as `@typescript-eslint`, therefore do not produce false "rule definition not found" diagnostics; the consumer's normal ESLint command remains authoritative for those rules. Unknown `kerfjs/*` directives still fail the doctor pass. Stable KUI identifiers come from the packaged `application-ui-diagnostic-ids-v1.json` registry; the doctor also reads installed ESLint message metadata for semantic conflict detection instead of duplicating rule definitions. The analyzer calls the public `@kerfjs/ui/analyzer` contract. None of these stages executes generated application code.
+TypeScript uses the compiler API with `noEmit`. ESLint loads the installed `eslint-plugin-kerfjs` `recommended-ui` preset (`--eslint strict-ui` opts into advisory rules as errors). This is deliberately an isolated Kerf lint pass rather than the consumer's complete ESLint configuration. For each file, the doctor projects the applicable core ESLint rules and `linterOptions` from the consumer configuration so core-rule suppression directives retain the same used/unused semantics as the application's normal lint command. Consumer plugin rules are not executed, and inline directives for plugins such as `@typescript-eslint` therefore do not produce false "rule definition not found" diagnostics; the consumer's normal ESLint command remains authoritative for those rules. Unknown `kerfjs/*` directives still fail the doctor pass. Stable KUI identifiers come from the packaged `application-ui-diagnostic-ids-v1.json` registry; the doctor also reads installed ESLint message metadata for semantic conflict detection instead of duplicating rule definitions. The analyzer calls the public `@kerfjs/ui/analyzer` contract. None of these stages executes generated application code.
 
 The browser evaluator is different: it runs the application and is disabled by default. It only runs when configuration supplies `browser.url` or the command receives `--browser-url`. Start and authorize the target application separately.
 

package/docs/ux-demo.md

@@ -13,15 +13,18 @@ deterministic state, and semantic layout owners from the [recipe guide](./recipe
 - `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`.
 - 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 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 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 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.
 - 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 grouped footer selector: `Uses` links to direct dependencies and `Used by` links to reverse dependents. 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. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; ListItem and ListHeader demonstrate typed domain metadata, protected native button/disclosure semantics, and a native popover trigger relationship without product props; PanelHeader demonstrates its plain top-toolbar identity, extra-large title, optional subtitle row, and bordered brand-filled icon group; 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; TabBar demonstrates overflow, edge autoscroll, and controlled pointer/keyboard reordering.
+- Scenarios use deterministic data and cover real variants, long content, disabled state, selection, progress, feedback, overlays, media, helpers, and stateful interactions. The Web Awesome theme route remains the broad system view, while individual action, form, layout, navigation, feedback, media, and helper routes provide focused specimens; 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; TabBar demonstrates 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.
 - 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.
 - 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.

package/docs/webawesome-theme.md

@@ -98,7 +98,10 @@ tiers:
   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.
+  Panel retains this roomier tier for unframed panel content. Dialog body uses
+  the 8px surface inset, while its footer uses the 16px container inset so
+  content stays compact and the action group has a clearer boundary. These two
+  parts do not inherit the dialog's shared `--spacing` value.
 
 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

package/docs/workbench.md

@@ -47,7 +47,54 @@ const navCollapsed = signal(false);
 Each `WorkbenchPanel` takes `content`, an optional `collapsed`, an optional
 `size` (rail width or drawer height in px, overriding the CSS default —
 `--kui-workbench-rail-width` 280px, `--kui-workbench-drawer-height` 220px), and
-an optional `label`.
+an optional `label`. Common shell behavior is configured rather than restyled:
+
+- `separator: "auto" | "hidden"` controls the owned dock-edge separator;
+- `collapseMotion: "slide" | "fade-slide" | "none"` keeps the track change
+  instant while choosing composited content motion;
+- `contentOverflow: "clip" | "auto" | "visible"` lets a drawer temporarily
+  expose an open popup without a descendant override;
+- `presentation: "inline" | "overlay" | "hidden"` supports compact overlays
+  or a responsive replacement;
+- `restoreControl` places an application-owned restore affordance in a
+  safe-area-aware viewport corner (`restorePosition` chooses the corner).
+
+The same policy props are available on `ResizableRegion` and
+`CollapsiblePanel`, so a resizable application shell does not need to reach
+into `.kui-resizable-region__content`.
+
+## Resizable application-shell migration
+
+An application such as Hot Sheet can replace its shell descendant overrides
+with state-derived props:
+
+```tsx
+<ResizableRegion
+  id="terminal-drawer"
+  label="Terminal drawer"
+  axis="vertical"
+  edge="start"
+  size={drawerSize.value}
+  min={180}
+  max={520}
+  collapsed={!drawerVisible.value}
+  separator={magnified.value ? "hidden" : "auto"}
+  collapseMotion="fade-slide"
+  contentOverflow={createMenuOpen.value ? "visible" : "clip"}
+  presentation={mobile.value ? "overlay" : "inline"}
+  restoreControl={<button data-action="show-drawer">Show terminals</button>}
+>
+  <TerminalDrawer />
+</ResizableRegion>
+```
+
+`wireResizableRegions` marks the active region with `data-resizing` and the
+package CSS suppresses content motion during pointer resize. 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,
+and safe-area restore placement. The app still owns the signals and decides
+when each policy applies.
 
 ## Public styling boundary
 
@@ -57,7 +104,7 @@ Workbench instance. The supported composition classes are `.kui-workbench`,
 `.kui-workbench__rail`, `.kui-workbench__rail--left`,
 `.kui-workbench__rail--right`, `.kui-workbench__center`,
 `.kui-workbench__main`, `.kui-workbench__drawer`, and
-`.kui-workbench__panel-content`; these exact hooks are cataloged for tools that
+`.kui-workbench__panel-content`, and `.kui-workbench__restore`; these exact hooks are cataloged for tools that
 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.

package/doctor/eslint-diagnostics.d.mts

@@ -6,3 +6,19 @@ export interface EslintDiagnosticLike {
 export function isForeignRuleDefinitionDiagnostic(
   item: EslintDiagnosticLike,
 ): boolean;
+
+export interface ConsumerEslintConfigLike {
+  rules?: Record<string, unknown>;
+  linterOptions?: Record<string, unknown>;
+}
+
+export interface ProjectedConsumerCoreConfig {
+  files: string[];
+  rules?: Record<string, unknown>;
+  linterOptions?: Record<string, unknown>;
+}
+
+export function projectConsumerCoreConfig(
+  config: ConsumerEslintConfigLike | undefined,
+  file: string,
+): ProjectedConsumerCoreConfig | undefined;

package/doctor/eslint-diagnostics.mjs

@@ -5,3 +5,20 @@ export function isForeignRuleDefinitionDiagnostic(item) {
     item.message === `Definition for rule '${item.ruleId}' was not found.`
   );
 }
+
+export function projectConsumerCoreConfig(config, file) {
+  const rules = Object.fromEntries(
+    Object.entries(config?.rules ?? {}).filter(
+      ([ruleId]) => !ruleId.includes('/'),
+    ),
+  );
+  const linterOptions = config?.linterOptions
+    ? { ...config.linterOptions }
+    : undefined;
+  if (Object.keys(rules).length === 0 && !linterOptions) return undefined;
+  return {
+    files: [file],
+    ...(Object.keys(rules).length > 0 ? { rules } : {}),
+    ...(linterOptions ? { linterOptions } : {}),
+  };
+}

package/doctor/index.mjs

@@ -23,7 +23,10 @@ import { createRequire } from 'node:module';
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
 import { analyzeUiProject, UI_ANALYSIS_RULES } from '../analyzer/index.mjs';
 import { evaluateUi, UI_EVALUATION_RULES } from '../evaluator/index.mjs';
-import { isForeignRuleDefinitionDiagnostic } from './eslint-diagnostics.mjs';
+import {
+  isForeignRuleDefinitionDiagnostic,
+  projectConsumerCoreConfig,
+} from './eslint-diagnostics.mjs';
 import {
   isUiTraversalExcluded,
   UI_TRAVERSAL_ESLINT_IGNORES,
@@ -869,6 +872,18 @@ async function runEslint({
     });
   }
   configs.push(preset);
+  const consumerEslint = new ESLint({ cwd: packageRoot });
+  if (await consumerEslint.findConfigFile()) {
+    const consumerCoreConfigs = await Promise.all(
+      inputs.map(async (file) =>
+        projectConsumerCoreConfig(
+          await consumerEslint.calculateConfigForFile(file),
+          portablePath(packageRoot, file),
+        ),
+      ),
+    );
+    configs.push(...consumerCoreConfigs.filter(Boolean));
+  }
   const eslint = new ESLint({
     cwd: packageRoot,
     overrideConfigFile: true,

package/llms.txt

@@ -86,8 +86,10 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   `--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.
+  `--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
+  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.
@@ -97,6 +99,11 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   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.
+- `Select` requires a visible `label` or an `ariaLabel` for a visually hidden
+  accessible name. The package names the internal combobox, including custom
+  selected content; consumers do not need shadow-DOM naming workarounds.
+  Use `hint` for supporting text below the control and `placeholderText` only
+  for the empty value inside it; loading placeholders retain the visible hint.
 - **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
@@ -111,10 +118,11 @@ 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
-  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.
+- **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.
 - **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
   group), `16px` `--kui-space-m`, `24px` `--kui-space-l` (between major differing
@@ -137,7 +145,9 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   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
-  editor focus for continued typing. The one richer case is `wireTokenSearchFields`, which manages the
+  editor focus for continued typing. Select All deletion does the same; deletion
+  restoration finishes before the next keystroke rather than on a delayed frame.
+  Persist both query and remaining tokens read from an edited field. The one richer case is `wireTokenSearchFields`, which manages the
   collapsible field's expand/collapse/focus by default (on, per-behavior opt-out) and
   exposes the `expanded` signal on its handle — bind it in render or hand in your own
   via `collapsible.signals`. Do not hand-roll open/collapse/focus that helper
@@ -151,7 +161,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
   boilerplate while still owning parsing and controlled token state.
 - **Placeholder loading state, don't rebuild it.** For a value or component that is
   still loading, set `placeholder` on the component (`Select`, `ListHeader`,
-  `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`,
+  `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`,
   `AppTab`, `ToolbarText`, `ListActionRow`): it renders its real chrome with value
   slots as subtle **unanimated** skeleton blocks and interactivity disabled, so a
   parent composes a faithful loading view (e.g. an inspector) without hand-rebuilding
@@ -166,7 +176,7 @@ maintain a central style list. Configure JSX with `"jsxImportSource": "kerfjs"`.
 ## Public exports
 
 `LucideIcon`, `DisclosureArrow`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ToolbarText`,
-`PanelHeader`, `ListItem`, `ListActionRow`, `ListHeader`, `ListInsetControl`,
+`ListItem`, `ListActionRow`, `ListHeader`, `ListInsetControl`,
 `ListInsetText`, `SegmentedControl`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.24",
+  "version": "5.0.0-beta.26",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -64,6 +64,11 @@
       "browser": "./dist/browser/toolbar-control-group.js",
       "import": "./dist/toolbar-control-group.js"
     },
+    "./surface-scaffold": {
+      "types": "./dist/surface-scaffold.d.ts",
+      "browser": "./dist/browser/surface-scaffold.js",
+      "import": "./dist/surface-scaffold.js"
+    },
     "./floating-toolbar": {
       "types": "./dist/floating-toolbar.d.ts",
       "browser": "./dist/browser/floating-toolbar.js",
@@ -248,11 +253,6 @@
       "browser": "./dist/browser/empty-state.js",
       "import": "./dist/empty-state.js"
     },
-    "./panel-header": {
-      "types": "./dist/panel-header.d.ts",
-      "browser": "./dist/browser/panel-header.js",
-      "import": "./dist/panel-header.js"
-    },
     "./value-table": {
       "types": "./dist/value-table.d.ts",
       "browser": "./dist/browser/value-table.js",
@@ -270,6 +270,7 @@
     "./disclosure-arrow.css": "./dist/styles/disclosure-arrow.css",
     "./toolbar.css": "./dist/styles/toolbar.css",
     "./toolbar-control-group.css": "./dist/styles/toolbar-control-group.css",
+    "./surface-scaffold.css": "./dist/styles/surface-scaffold.css",
     "./floating-toolbar.css": "./dist/styles/floating-toolbar.css",
     "./toolbar-text.css": "./dist/styles/toolbar-text.css",
     "./list.css": "./dist/styles/list.css",
@@ -296,7 +297,6 @@
     "./token-search-field.css": "./dist/styles/token-search-field.css",
     "./state-banner.css": "./dist/styles/state-banner.css",
     "./empty-state.css": "./dist/styles/empty-state.css",
-    "./panel-header.css": "./dist/styles/panel-header.css",
     "./value-table.css": "./dist/styles/value-table.css",
     "./ai/*": "./ai/*",
     "./docs/*": "./docs/*"

package/ux-demo/recipes/app-shell.tsx

@@ -4,7 +4,6 @@ import './recipes.css';
 import { ListHeader } from '@kerfjs/ui/list-header';
 import { ListItem } from '@kerfjs/ui/list-item';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
-import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { ResizableRegion } from '@kerfjs/ui/resizable-region';
 import { Toolbar } from '@kerfjs/ui/toolbar';
 import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
@@ -30,11 +29,7 @@ export const createRecipe: RecipeFactory = (announce) => {
     >
       <Toolbar
         label="Atlas workspace"
-        leading={
-          <ToolbarControlGroup appearance="borderless" single>
-            <ToolbarText text="Atlas" />
-          </ToolbarControlGroup>
-        }
+        leading={<ToolbarText text="Atlas" />}
         trailing={
           <div class="recipe-shell__toolbar-actions">
             <ToolbarControlGroup
@@ -134,21 +129,32 @@ export const createRecipe: RecipeFactory = (announce) => {
           </ResizableRegion>
         </div>
         <main id="recipe-shell-content" class="recipe-shell__main kui-pane">
-          <PanelHeader
-            title={
-              selected.value === 'inbox' ? 'Inbox triage' : 'Active projects'
+          <Toolbar
+            label="Current workspace view"
+            dividerSides=""
+            leading={
+              <ToolbarText
+                text={
+                  selected.value === 'inbox'
+                    ? 'Inbox triage'
+                    : 'Active projects'
+                }
+                size="xlarge"
+                id="recipe-shell-main-title"
+              />
             }
-            titleId="recipe-shell-main-title"
-            actions={
-              <button
-                class="kui-recipe__button"
-                data-primary="true"
-                type="button"
-                data-action="recipe-action"
-                data-recipe-command="new"
-              >
-                New task
-              </button>
+            trailing={
+              <ToolbarControlGroup appearance="borderless" single>
+                <button
+                  class="kui-recipe__button"
+                  data-primary="true"
+                  type="button"
+                  data-action="recipe-action"
+                  data-recipe-command="new"
+                >
+                  New task
+                </button>
+              </ToolbarControlGroup>
             }
           />
           <div class="recipe-shell__main-body kui-pane__content kui-content">
@@ -183,9 +189,16 @@ export const createRecipe: RecipeFactory = (announce) => {
             edge="start"
           >
             <aside class="recipe-shell__inspector kui-pane">
-              <PanelHeader
-                title="Inspector"
-                titleId="recipe-shell-inspector-title"
+              <Toolbar
+                label="Inspector"
+                dividerSides=""
+                leading={
+                  <ToolbarText
+                    text="Inspector"
+                    size="xlarge"
+                    id="recipe-shell-inspector-title"
+                  />
+                }
               />
               <div class="recipe-shell__inspector-body kui-pane__content kui-content">
                 <ValueTable label="Selected task">

package/ux-demo/recipes/collapsible-sidebar.tsx

@@ -10,7 +10,6 @@ import { deviceClass } from '@kerfjs/ui/device-class';
 import { ListHeader } from '@kerfjs/ui/list-header';
 import { ListItem } from '@kerfjs/ui/list-item';
 import { LucideIcon } from '@kerfjs/ui/lucide-icon';
-import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { Toolbar } from '@kerfjs/ui/toolbar';
 import { ToolbarControlGroup } from '@kerfjs/ui/toolbar-control-group';
 import { ToolbarText } from '@kerfjs/ui/toolbar-text';
@@ -119,17 +118,28 @@ export const createRecipe: RecipeFactory = (announce) => {
         </nav>
       </CollapsiblePanel>
       <main class="recipe-collapsible-sidebar__main kui-pane">
-        <PanelHeader
-          title={
-            selected.value === 'projects'
-              ? 'Projects'
-              : selected.value === 'shared'
-                ? 'Shared with me'
-                : 'Inbox'
+        <Toolbar
+          label="Current navigation view"
+          dividerSides=""
+          leading={
+            <>
+              <ToolbarControlGroup appearance="borderless" single>
+                {railToggle(false)}
+              </ToolbarControlGroup>
+              <ToolbarText
+                text={
+                  selected.value === 'projects'
+                    ? 'Projects'
+                    : selected.value === 'shared'
+                      ? 'Shared with me'
+                      : 'Inbox'
+                }
+                size="xlarge"
+                id="recipe-collapsible-main-title"
+              />
+            </>
           }
-          titleId="recipe-collapsible-main-title"
-          icon={railToggle(false)}
-          actions={
+          trailing={
             <ToolbarControlGroup appearance="borderless" single>
               {drawerToggle()}
             </ToolbarControlGroup>
@@ -161,11 +171,7 @@ export const createRecipe: RecipeFactory = (announce) => {
         <Toolbar
           label="Activity"
           dividerSides="b"
-          leading={
-            <ToolbarControlGroup appearance="borderless" single>
-              <ToolbarText text="Activity" size="small" />
-            </ToolbarControlGroup>
-          }
+          leading={<ToolbarText text="Activity" size="small" />}
           trailing={
             <ToolbarControlGroup appearance="borderless" single>
               {drawerToggle()}

package/ux-demo/recipes/composer-form.tsx

@@ -6,9 +6,10 @@ import '@awesome.me/webawesome/dist/components/input/input.js';
 import '@awesome.me/webawesome/dist/components/textarea/textarea.js';
 import './recipes.css';
 
-import { PanelHeader } from '@kerfjs/ui/panel-header';
 import { Select } from '@kerfjs/ui/select';
 import { StateBanner } from '@kerfjs/ui/state-banner';
+import { Toolbar } from '@kerfjs/ui/toolbar';
+import { ToolbarText } from '@kerfjs/ui/toolbar-text';
 import { signal } from 'kerfjs';
 
 import type { RecipeFactory } from './types.js';
@@ -44,12 +45,20 @@ export const createRecipe: RecipeFactory = (announce) => {
       aria-describedby="recipe-composer-summary"
       noValidate
     >
-      <PanelHeader
-        title="Publish workspace update"
-        titleId="recipe-composer-title"
-        summary="Share a concise, actionable update with collaborators."
-        summaryId="recipe-composer-summary"
+      <Toolbar
+        label="Publish workspace update"
+        dividerSides=""
+        leading={
+          <ToolbarText
+            text="Publish workspace update"
+            size="xlarge"
+            id="recipe-composer-title"
+          />
+        }
       />
+      <p class="kui-recipe__heading-summary" id="recipe-composer-summary">
+        Share a concise, actionable update with collaborators.
+      </p>
       {status.value === 'error' && (
         <StateBanner
           title="Add a title before publishing"