@kerfjs/ui 5.0.0-beta.17 → 5.0.0-beta.21

package/docs/catalog.md

@@ -7,7 +7,7 @@ you get the same shell without rebuilding it. Like the app layouts, it is a
 subpath-only, tree-shakeable module that adds nothing to the main barrel.
 
 ```bash
-npm install @kerfjs/ui   # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
+npm install @kerfjs/ui # kerfjs is a peer; @kerfjs/ui/select/register is needed only if entries use `related`
 ```
 
 - `Catalog(props)` returns the shell as `SafeHtml` (a `<main class="kui-catalog">`).
@@ -17,20 +17,20 @@ npm install @kerfjs/ui   # kerfjs is a peer; @kerfjs/ui/select/register is neede
 - `wireCatalog(root, options)` wires the interactions (sidebar selection, the
   related-entry popup menu, and the collapse/theme toggles) with one delegated
   listener set and returns a disposer; it can also mirror the active id into the
-  URL.
+  URL and reveal the active sidebar row after a controlled render.
 
 ## What you supply
 
 - **`sections`** — category-grouped entries: `{ category, entries: [{ id, name,
-  description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
+description?, tags?, resources?, related? }] }`. Each entry becomes a sidebar
   `ListItem` under a `ListHeader` for its category. Short `tags` render as quiet
   trailing pills for decision metadata such as `Discouraged`.
 - **`content`** — the rendered preview for the active entry. Keep a map of `id →
-  () => SafeHtml` in your app and call `renderers[active]()` in your render.
+() => SafeHtml` in your app and call `renderers[active]()` in your render.
 - **`brand`** — `{ title, subtitle?, logoUrl? }` for the sidebar header.
 - **`secondarySections`** — an optional secondary "ecosystem" group shown below the
   primary sections with a quieter treatment: `{ label, sections, collapsible?,
-  expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
+expanded? }`. When `collapsible`, the label is a disclosure toggle controlling
   `expanded` (the app owns it; wire it with `wireCatalog`'s `onToggleSecondary`).
 - Optional slots: `headerActions` (extra header controls), `sidebarFooter` (extra
   sidebar content), and `status` (a footer status line).
@@ -40,94 +40,297 @@ Per-entry `resources` render as "open in new tab" links in the footer, and
 around a `wa-dropdown` (grouped by each entry's `group`), so register its elements
 with `@kerfjs/ui/select/register` when you use it.
 
-## Preview examples
+## Catalog demo authoring contract
 
-Compose each entry's `content` from `CatalogExample` (and `CatalogExampleStack`)
-instead of hand-rolled example markup, so labels, notes, and left-edge alignment
-stay consistent:
+This section is the single authoritative contract for tools and people that
+author Catalog previews. The machine-readable discovery entry is
+[`catalog-authoring.json`](../ai/catalog-authoring.json); exact props remain in
+[`public-api-signatures-v1.md`](../ai/public-api-signatures-v1.md#kerfjsuicatalog).
+The component catalog deliberately does not duplicate these rules: it describes
+which component to choose, while this contract describes how to present the
+chosen component.
+
+### Choose the demo mode
+
+Classify every entry before rendering it:
+
+| Entry kind            | Preview purpose                                                         | Geometry overlay                                                                    |
+| --------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Focused component     | Show one public component, its meaningful variants, and adverse states. | `true`; the overlay inspects each selected specimen.                                |
+| Composition or recipe | Show several components cooperating as one product surface.             | `false`; child geometry remains unmarked so the composition can be read as a whole. |
+
+Keep `geometryOverlay` present and compute it from the active entry. Do not make
+it a permanent catalog-wide `true`, and do not give individual specimens their
+own overlay implementation.
+
+### Required structure
+
+- `Catalog` is the one shell. The app owns active-entry state and passes one
+  active preview through `content`.
+- `CatalogExampleStack` is the group for one preview's rows. Put route/test
+  metadata such as `data-demo` on its rendered root through `rootAttributes`.
+  Pass `label` when the stack needs an accessible name: the rendered `section`
+  is then exposed as a named region. An unlabeled stack remains an ordinary
+  grouping rather than adding an unnecessary landmark.
+- `CatalogExample` is one row: optional generated `ListHeader` label, optional
+  generated note, then one specimen or one intentionally coupled specimen
+  cluster. Use one row per variant/state; do not hand-author the helper's private
+  classes.
+- The specimen is an immediate child of `CatalogExample`. A focused component
+  row should place the component root there, without a decorative card or
+  spacing wrapper. A composition row may place the composition root there.
+
+Use `align="glyph"` for a bare glyph/text specimen, `align="inline-control"`
+for a control whose own inline padding contributes about 8px, and `align="none"`
+(the default) for a content item or composition that owns its geometry.
 
 ```tsx
-import { CatalogExample, CatalogExampleStack } from '@kerfjs/ui/catalog';
+import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
-  <CatalogExampleStack label="Button variants">
+  <CatalogExampleStack
+    label="Button variants"
+    rootAttributes={{ "data-demo": "button" }}
+  >
     <CatalogExample label="Icon" note="A bare glyph." align="glyph">
       <LucideIcon icon={Plus} name="plus" />
     </CatalogExample>
     <CatalogExample label="Control" align="inline-control">
       <SegmentedControl id="view" label="View" value="list" choices={choices} />
     </CatalogExample>
-    <CatalogExample label="In composition">
-      <ValueTable label="Metadata">{rows}</ValueTable>
+    <CatalogExample
+      label="Authoring note"
+      note="Explanatory chrome is not a specimen."
+      rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
+    >
+      <p>Use the public helper contract.</p>
     </CatalogExample>
   </CatalogExampleStack>
 );
 ```
 
-`label` is optional — omit it for a bare specimen with no `ListHeader`. `align`
-lines a specimen's visible left edge up with its label text: `'glyph'`
-(16px) for a bare glyph/text specimen, `'inline-control'` (8px) for a control that
-already carries ~8px of its own inline padding, and `'none'` (the default) for a
-content-item/composition that already owns its geometry. The inset is published as
-the `--kui-catalog-example-align` custom property so a debug overlay can exclude it
-from a specimen's measured margin.
+The overlay selects every immediate child of a `CatalogExample` except the
+helper-generated label and note. It does not recursively promote a nested child
+to be the specimen. Outside an example row, it selects only top-level
+`[data-component]` roots in the canvas and ignores nested component descendants.
+These rules keep a row's label/group scaffolding out of the measurement and make
+the authored nesting determine exactly what is inspected.
+
+### Metadata ownership
+
+Use `rootAttributes` on either helper for authoring metadata such as `data-demo`
+or `data-catalog-geometry-overlay-skip`; the metadata lands on that helper's
+rendered root. The slot accepts only `data-*` strings. Structural
+`data-catalog-example`, `data-catalog-example-stack`, and `data-align` semantics
+remain helper-owned and are rejected case-insensitively at runtime, including
+from structurally widened or JavaScript objects. Do not copy the helpers'
+private `kui-catalog-*` classes into preview markup.
+
+The app owns entry ids, `kind`, routing, sources, relationships, and test hooks.
+The helpers own their structural markers, label/note anatomy, alignment marker,
+and private classes. Component metadata such as margin/border/padding ownership
+lives in `component-catalog.json`; do not infer or overwrite it from overlay
+pixels.
+
+### Geometry overlay and legend
+
+Pass the conditional `geometryOverlay` boolean to `Catalog`, then call
+`wireCatalogGeometryOverlay(root)` once after the first render and retain its
+disposer alongside `wireCatalog`'s.
+
+| Overlay mark            | Meaning                                                                                              | It is not                                                                              |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Orange translucent band | A positive computed margin on the selected specimen, after subtracting the helper's alignment inset. | Padding, gap, or empty content. Zero and negative margins are not drawn.               |
+| Quiet dashed outline    | The border-box outer bound of a selected specimen whose computed background is transparent.          | A real CSS border, focus ring, padding edge, or proof that the specimen owns its size. |
+
+The overlay does not visualize padding, borders, gaps, negative/zero margins,
+scroll overflow, hit targets, nested descendants, or geometry ownership. Inspect
+computed styles and the machine-readable `geometry` metadata for those facts.
+Opaque specimens do not receive the transparent-bound outline.
+
+```tsx
+<Catalog
+  {...props}
+  geometryOverlay={activeEntry.kind === "component"}
+  content={renderers[active.value]()}
+/>
+```
+
+Put `rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}` on a
+`CatalogExample` or `CatalogExampleStack` only when that whole subtree is
+explanatory chrome rather than a specimen. The marker excludes the marked root
+and every descendant from selection; it does not merely hide one band. It is
+normally unnecessary in a composition because the active entry already sets the
+global overlay to `false`.
+
+Use the overlay together with machine-readable geometry ownership metadata; the
+overlay verifies what is rendered, while metadata tells people and AI tools
+whether the component, its parent, or its children are responsible for margin,
+border, and padding. Catalogs for downstream components should conform to the
+[`component-catalog-extension.schema.json`](../ai/component-catalog-extension.schema.json)
+contract and can start from the checked
+[`component-catalog-extension.json`](./examples/component-catalog-extension.json)
+example; provide those entries beside Kerf's shipped catalog to AI tools.
+
+### Automated conformance and reviewed exceptions
+
+Run `npm run check:demo-conformance` after changing a first-party demo, its
+catalog kind, or the shell's overlay logic. The TypeScript-AST gate verifies
+facts that source can prove without guessing at rendered intent:
+
+- focused component routes import and use `CatalogExampleStack` and
+  `CatalogExample` from the public package;
+- focused route metadata uses the helpers' `rootAttributes` slot, example rows
+  are not empty, and composition routes do not add redundant skip markers;
+- every `@kerfjs/ui` import is a published package export and relative imports
+  do not reach into `ui/src`;
+- demo JSX does not copy private `kui-catalog-*` structural classes; and
+- the shell derives both geometry-overlay enablement and documented demo mode
+  from the active entry's source and kind.
+
+The gate deliberately does not infer component ownership from arbitrary class
+names, margins, borders, or nested descendants. Runtime selection and geometry
+remain the browser suite's job.
+
+A focused route may bypass the two public layout helpers only when the route's
+stage geometry is itself the reviewed specimen. Add the narrow waiver to
+[`catalog-conformance-exceptions.json`](../ux-demo/catalog-conformance-exceptions.json)
+with the exact route, source file, stable diagnostic ids, a substantive reason,
+and the reviewing `KF-*` ticket. Only helper/metadata rules are waivable;
+private imports, private markup, empty examples, composition overlay drift, and
+shell-mode drift always fail. The gate rejects duplicate, malformed, unused,
+and stale exceptions, so delete a waiver when its route adopts the standard
+helpers.
+
+## Selection reveal
+
+Set `revealSelection: true` on `wireCatalog` for a long desktop sidebar. After
+`onSelect` updates controlled state, the helper waits one animation frame, finds
+the exact matching `data-item-id`, and scrolls it into view without changing
+focus. A newer selection or disposal cancels the pending reveal. The default
+media guard is the Catalog desktop layout (`min-width: 52.01rem`), so compact
+layouts keep their existing scroll position.
+
+Pass an options object instead of `true` to customize `block`, `inline`,
+`behavior`, or `media`; `media: false` deliberately enables the behavior at all
+sizes. For an initial deep link that did not come through `wireCatalog`, call
+`revealCatalogEntry(app, initialId, { block: "center" })` after the first mount.
 
 ## Complete example
 
 ```tsx
-import { mount, signal } from 'kerfjs';
-import { Catalog, type CatalogSection } from '@kerfjs/ui/catalog';
-import { wireCatalog } from '@kerfjs/ui/wire-catalog';
-import '@kerfjs/ui/styles.css'; // or import each primitive's CSS + @kerfjs/ui/catalog.css
+import { mount, signal, type SafeHtml } from "kerfjs";
+import {
+  Catalog,
+  CatalogExample,
+  CatalogExampleStack,
+  type CatalogSection,
+} from "@kerfjs/ui/catalog";
+import {
+  revealCatalogEntry,
+  wireCatalog,
+  wireCatalogGeometryOverlay,
+} from "@kerfjs/ui/wire-catalog";
+import "@kerfjs/ui/styles.css"; // or import each primitive's CSS + @kerfjs/ui/catalog.css
 
-// 1. Describe your components once.
-const sections: CatalogSection[] = [
+type DemoKind = "component" | "composition";
+type DemoEntry = CatalogSection["entries"][number] & { kind: DemoKind };
+
+// 1. Describe selection and overlay mode once.
+const entries: DemoEntry[] = [
   {
-    category: 'Controls',
-    entries: [
-      { id: 'button', name: 'Button', description: 'A pressable control.',
-        resources: [{ label: 'Source', href: '/src/button.tsx', detail: 'src/button.tsx' }] },
-      { id: 'field', name: 'Field', description: 'A labeled input.', tags: ['Discouraged'],
-        related: [{ id: 'button', name: 'Button', group: 'Used with' }] },
+    id: "button",
+    name: "Button",
+    kind: "component",
+    description: "A pressable control.",
+    resources: [
+      { label: "Source", href: "/src/button.tsx", detail: "src/button.tsx" },
     ],
   },
-  { category: 'Feedback', entries: [{ id: 'toast', name: 'Toast', description: 'A transient message.' }] },
+  {
+    id: "profile-form",
+    name: "Profile form",
+    kind: "composition",
+    description: "A labeled field and save action working together.",
+  },
+];
+const sections: CatalogSection[] = [
+  {
+    category: "Examples",
+    entries: entries.map(({ kind: _kind, ...entry }) => entry),
+  },
 ];
 
-// 2. One preview render per entry id.
-const renderers: Record<string, () => ReturnType<typeof Button>> = {
-  button: () => <Button label="Save" />,
-  field: () => <Field label="Name" />,
-  toast: () => <Toast>Saved</Toast>,
+// 2. Every preview uses one public group and public example rows.
+const renderers: Record<string, () => SafeHtml> = {
+  button: () => (
+    <CatalogExampleStack
+      label="Button states"
+      rootAttributes={{ "data-demo": "button" }}
+    >
+      <CatalogExample label="Default" align="inline-control">
+        <Button label="Save" />
+      </CatalogExample>
+      <CatalogExample
+        label="Authoring note"
+        note="This explanatory row is deliberately excluded from inspection."
+        rootAttributes={{ "data-catalog-geometry-overlay-skip": "" }}
+      >
+        <p>The application owns product copy and actions.</p>
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
+  "profile-form": () => (
+    <CatalogExampleStack
+      label="Profile form composition"
+      rootAttributes={{ "data-demo": "profile-form" }}
+    >
+      <CatalogExample label="Complete composition">
+        <ProfileForm />
+      </CatalogExample>
+    </CatalogExampleStack>
+  ),
 };
 
 // 3. App-owned state (domain: which entry; transient: collapsed; global: theme).
-const initial = new URLSearchParams(location.search).get('c') ?? sections[0].entries[0].id;
+const initial =
+  new URLSearchParams(location.search).get("c") ?? sections[0].entries[0].id;
 const active = signal(initial);
 const collapsed = signal(false);
-const theme = signal<'light' | 'dark'>('light');
+const theme = signal<"light" | "dark">("light");
+const activeEntry = () => entries.find(({ id }) => id === active.value) ?? entries[0];
 
-const app = document.getElementById('app')!;
+const app = document.getElementById("app")!;
 mount(app, () => (
   <Catalog
-    brand={{ title: 'Acme UI', subtitle: 'Design system' }}
+    brand={{ title: "Acme UI", subtitle: "Design system" }}
     sections={sections}
     active={active.value}
     content={renderers[active.value]?.() ?? <></>}
     collapsed={collapsed.value}
     theme={theme.value}
+    geometryOverlay={activeEntry().kind === "component"}
   />
 ));
 
 wireCatalog(app, {
-  onSelect: (id) => { active.value = id; },
-  onToggleSidebar: () => { collapsed.value = !collapsed.value; },
+  onSelect: (id) => {
+    active.value = id;
+  },
+  onToggleSidebar: () => {
+    collapsed.value = !collapsed.value;
+  },
   onToggleTheme: () => {
-    theme.value = theme.value === 'dark' ? 'light' : 'dark';
+    theme.value = theme.value === "dark" ? "light" : "dark";
     document.documentElement.dataset.theme = theme.value; // apply your theme however you like
   },
-  urlParam: 'c', // mirror the active id into ?c=<id>
+  urlParam: "c", // mirror the active id into ?c=<id>
+  revealSelection: true, // reveal long desktop sidebars without moving focus
 });
+wireCatalogGeometryOverlay(app);
+
+// Optional for an initial deep link whose row may start outside the viewport.
+revealCatalogEntry(app, initial, { block: "center" });
 ```
 
 ## Ownership boundary

package/docs/collapsible-panel.md

@@ -7,7 +7,7 @@ a full shell so you can dock one panel wherever your layout needs it. They are
 subpath-only, tree-shakeable modules that add nothing to the main barrel.
 
 ```bash
-npm install @kerfjs/ui   # kerfjs is a peer
+npm install @kerfjs/ui # kerfjs is a peer
 ```
 
 Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.css`.
@@ -46,33 +46,60 @@ Import the panel CSS (`@kerfjs/ui/collapsible-panel.css`) alongside `foundation.
 ## Example
 
 ```tsx
-import { signal, mount } from 'kerfjs';
-import { deviceClass } from '@kerfjs/ui/device-class';
-import { CollapsiblePanel, CollapsiblePanelToggle } from '@kerfjs/ui/collapsible-panel';
-import { wireSidebar } from '@kerfjs/ui/wire-sidebar';
-import '@kerfjs/ui/collapsible-panel.css';
+import { signal, mount } from "kerfjs";
+import { deviceClass } from "@kerfjs/ui/device-class";
+import {
+  CollapsiblePanel,
+  CollapsiblePanelToggle,
+} from "@kerfjs/ui/collapsible-panel";
+import { wireSidebar } from "@kerfjs/ui/wire-sidebar";
+import "@kerfjs/ui/collapsible-panel.css";
 
 const navCollapsed = signal(false);
 const device = deviceClass();
 
-const app = document.querySelector('#app')!;
+const app = document.querySelector("#app")!;
 mount(app, () => (
   <div class="layout">
-    <CollapsiblePanel id="nav" side="left" collapsed={navCollapsed.value} label="Navigator">
+    <CollapsiblePanel
+      id="nav"
+      side="left"
+      collapsed={navCollapsed.value}
+      label="Navigator"
+    >
       <header>
-        <CollapsiblePanelToggle side="left" collapsed={navCollapsed.value} action="toggle-nav" panelId="nav" />
+        <CollapsiblePanelToggle
+          side="left"
+          collapsed={navCollapsed.value}
+          action="toggle-nav"
+          panelId="nav"
+        />
       </header>
       {/* nav items */}
     </CollapsiblePanel>
     <main>
-      {navCollapsed.value && <CollapsiblePanelToggle side="left" collapsed action="toggle-nav" label="Show navigator" />}
+      {navCollapsed.value && (
+        <CollapsiblePanelToggle
+          side="left"
+          collapsed
+          action="toggle-nav"
+          label="Show navigator"
+        />
+      )}
       {/* content */}
     </main>
   </div>
 ));
 
 const stop = wireSidebar(app, {
-  panels: [{ id: 'nav', collapsed: navCollapsed, toggleAction: 'toggle-nav', storageKey: 'app.nav-collapsed' }],
+  panels: [
+    {
+      id: "nav",
+      collapsed: navCollapsed,
+      toggleAction: "toggle-nav",
+      storageKey: "app.nav-collapsed",
+    },
+  ],
   deviceClass: device,
 });
 ```

package/docs/component-contract.md

@@ -18,8 +18,124 @@ package delivery paths, Web Awesome's installed manifest, AI guidance, and
 documentation links. Nuanced prose in this contract and the selection guide
 remains authored rather than generated.
 
+### Composition catalog v2
+
+[`component-catalog-v2.json`](../ai/component-catalog-v2.json) adds a formal,
+machine-evaluable composition layer without changing the v1 selection and
+delivery contract. Every v1 entry projects once, in order, under the stable
+qualified key `package:id`. Each v2 entry explicitly covers parents/contexts,
+named zones and cardinality, child concepts, state ownership, required wiring,
+responsive ownership, layout and geometry, accessibility obligations, public
+CSS boundaries, diagnostics, and provenance.
+
+The generator starts with permissive defaults. An `any` mode records that the
+catalog has no defensible prohibition; it does not claim every composition is
+recommended. Objective rules live in
+`component-catalog-v2-overrides.json` and may carry stable `KUI-C###`
+diagnostics. A tool reports a diagnostic only after proving its exact `when`
+condition. Subjective choice, product policy, and visual taste remain prose.
+
+V1 consumers continue unchanged. V2 consumers read v1 for selection/delivery
+and v2 for composition. `npm run catalog:sync` projects every new component,
+recipe, and supported Web Awesome entry, and the completeness gate prevents
+silent omissions. Downstream catalogs use the v2 extension schema and types,
+retain their own package identity, and qualify cross-catalog references. See
+the checked
+[`component-catalog-extension-v2.json`](./examples/component-catalog-extension-v2.json)
+application-owned example.
+
+### Compile-time contract boundary
+
+The versioned
+[`compile-time-contracts-v1.json`](../ai/compile-time-contracts-v1.json)
+artifact maps stable `KUI-T###` ids to public imports, emitted symbols, and
+catalog identities. Its positive/negative fixture compiles against both source
+and a freshly packed package, so source declarations and shipped declarations
+cannot silently diverge. See [Compile-time contracts](./type-contracts.md) for
+the full audit, migration guidance, and the relationships deliberately left to
+runtime/catalog checks because TypeScript cannot prove them.
+
+### Application UI profile
+
+The component catalogs describe what packages provide; an application profile
+describes which supported choices a project has approved. A workspace may
+check in `.kerf-ui-profile.json` conforming to
+[`application-ui-profile.schema.json`](../ai/application-ui-profile.schema.json).
+Keep package-qualified catalog locations and recurring-concept preferences,
+allowed color schemes and density, public semantic-token overrides,
+layout/responsive conventions, and narrow rule exceptions there. Product
+records, copy, permissions, user preferences, and transport state do not belong
+in this policy file.
+
+Every catalog location names a v2 composition artifact. `selection` is optional
+for consumer packages whose generated metadata declares v1 selection guidance
+not applicable; `@kerfjs/ui` retains its required v1 selection artifact. This
+lets a generated `component-catalog-v2.json` participate directly without a
+fabricated compatibility file.
+
+Discovery and precedence are deterministic:
+
+1. Load `application-ui-profile.defaults.json` from `@kerfjs/ui`.
+2. Load `.kerf-ui-profile.json` at the workspace root when present.
+3. Walk from the workspace root toward the target directory and load each
+   directory-local profile in parent-to-child order.
+
+Later scalar and object-map values win. Catalogs merge by package; preferences
+and token overrides merge by key; exceptions merge by stable id. Lists such as
+allowed themes/densities replace the earlier list rather than accumulating.
+Every resolved field retains its source file. The shipped
+`application-ui-profile.mjs` API implements discovery, merge, loading, and
+validation and reports actionable originating file + JSON-path diagnostics for stale
+catalogs, unknown component/rule/token references, preference conflicts, and
+broad exceptions. Each raw layer is validated against the catalogs effective at
+that exact precedence point before merge, so a broken parent catalog, stale
+parent reference, invalid value, or unknown field cannot disappear merely
+because a child profile replaces it. The shipped
+`application-ui-profile-sync.cjs` projects the same merge and validation contract
+for synchronous hosts such as ESLint rules; it deliberately performs no async
+I/O.
+See the
+[`application-ui-profile.json`](./examples/application-ui-profile.json) example.
+
+Catalog detail footers use one standard resource vocabulary and order. Build
+them with `catalogResources()` from `@kerfjs/ui/catalog-resources`: `Demo source`
+first, optional `Component source` and `Design template`, then `Guidance`.
+Third-party entries use the typed `integrationGuidance` kind, which renders
+`Integration guidance`, and omit `Component source` when the implementation is
+not owned by the catalog's project. Prefer these semantic kinds over local labels
+such as “View source” or “Read UI guidance”; the helper makes that convention a
+compile-time choice while still returning ordinary `CatalogResource[]` values.
+
 ## Ownership boundaries
 
+### Geometry ownership metadata
+
+The canonical [`component-catalog.json`](../ai/component-catalog.json) records
+the margin, border, and padding owner for every component and composition under
+`geometry`. Read it before adding a wrapper or local spacing rule:
+
+- `self` means the entry's public visual contract supplies that geometry.
+- `parent` means the embedding layout must supply it.
+- `child` means composed descendants supply it; the entry's outer shell does not.
+- `none` means that dimension is intentionally absent from the standard contract.
+- `conditional` means a variant, part, or configuration changes ownership; the
+  accompanying `notes` explain the boundary.
+
+The values describe public ownership, including themed shadow parts, rather
+than merely asking whether a CSS declaration appears on the host element.
+Recipes are exempt because they arrange entries whose individual ownership is
+already cataloged.
+
+Downstream packages and applications should publish the same contract for their
+reusable visual components. Use
+[`component-catalog-extension.schema.json`](../ai/component-catalog-extension.schema.json)
+and copy the structure of the checked
+[`component-catalog-extension.json`](./examples/component-catalog-extension.json)
+example. Keep app and Kerf entries as package-qualified inputs, then let people
+or AI tools search their combined entries and compare `geometry` before adding
+wrappers or insets. Do not add app-owned entries to Kerf's canonical catalog or
+claim Kerf delivery paths for them.
+
 - Components own semantic markup, stable anatomy, documented variants, ARIA projection, and package CSS hooks.
 - Applications own signals/stores, product copy, domain-state mapping, persistence, routing, permissions, and transport.
 - Actions are `data-action` strings. Wire them at a stable root with `delegate()` or `delegateActions()` and retain the disposer.
@@ -27,7 +143,8 @@ remains authored rather than generated.
 - Consumers style through `--kui-*` semantic tokens and public component classes. Foundation tokens provide opinionated neutral, brand/info, success, warning, and danger fill/border/foreground roles. Stateful components expose local override variables; prefer an equivalent prop or token before writing a selector.
 
 `ListItem.rootAttributes`, `ListActionRow.rootAttributes`,
-`ListHeader.rootAttributes`, and `AppTab.rootAttributes` accept
+`ListHeader.rootAttributes`, `AppTab.rootAttributes`,
+`CatalogExample.rootAttributes`, and `CatalogExampleStack.rootAttributes` accept
 application-owned `data-*` metadata without
 adding product fields to the shared API. A `ListActionRow` trailing action uses
 `trailingActionAttributes`, and a `ListHeader` action/disclosure uses
@@ -36,7 +153,7 @@ the corresponding `aria-controls`/`aria-haspopup` relationship. These slots do
 not accept roles or component-owned action, selection, disclosure, accessible
 name, disabled, or icon fields. Extension objects are filtered at runtime,
 including case-insensitive rejection of protected `data-*` names, and the
-component writes its protected attributes after the accepted metadata. Typed,
+component or helper writes its protected attributes after the accepted metadata. Typed,
 structurally widened, and JavaScript callers therefore cannot replace its
 contract.
 
@@ -65,6 +182,11 @@ layout cannot be expressed by a prop or token. A class being public does not
 make copied component markup an invocation or transfer state and accessibility
 ownership to the application.
 
+The v2 composition catalog additionally requires `boundaries.rootClass` to be
+either one exact member of `publicClasses` or `null` when the entry has no
+rendered class root. Runtime geometry tooling uses this explicit field; array
+order never implies root ownership.
+
 Do not select a component's descendant by element name, id, attribute alone, or
 an unlisted implementation class. Selectors such as `.kui-state-banner span`,
 `.kui-list-item [data-state]`, and `.kui-list-item .local-label` depend on
@@ -103,9 +225,12 @@ separator with a compact grip that appears on hover or keyboard focus. Override
 `--kui-resizable-region-handle-active-color` on a region when its containing
 surface needs a different contrast level.
 
-`@kerfjs/ui/layout.css` defines one structural model for sidebars, main areas,
-inspectors, and dialogs. `.kui-pane` is unpadded and contains an optional
-toolbar, one scrolling `.kui-pane__content`, and an optional footer.
+`Pane` defines one structural model for sidebars, main areas, inspectors, and
+dialogs. Its `.kui-pane` root is unpadded and contains an optional vertical
+header, one scrolling vertical `.kui-pane__content`, and an optional footer.
+Logical-edge separator lines are independently opt-in and default off.
+`@kerfjs/ui/layout.css` retains the pane roles and supplies the related content
+geometry classes.
 `.kui-content` gives major children 24px vertical separation.
 `.kui-content-item` gives one child 8px inline margin, a real 1px border,
 8px padding, and 12px corners; border and background may be transparent without
@@ -166,14 +291,14 @@ render, hands in its own via `collapsible.signals`, drives it through
 UI is consistent by default without every app reinventing it.
 
 `wireTokenSearchFields` is a deliberate exception, not the rule for `wire…`
-helpers. Its collapse behavior was *rich and error-prone* — reveal, focus
+helpers. Its collapse behavior was _rich and error-prone_ — reveal, focus
 transfer, Escape, empty-blur collapse, focus return — the kind of transient chrome
 apps kept reimplementing inconsistently, so the helper owns it. Everywhere else the
 app's state is **domain or persisted, not transient chrome, and stays app-owned**: a
 `NavStack`'s view stack is navigation history, a `TabBar`/`TabScaffold`'s selection
 and tab order are data, a `ResizableRegion`'s committed size and a
 `Workbench`/`SplitView` rail's `collapsed` flag are persisted layout preferences.
-Each helper already owns only the *ephemeral mechanics* around that state —
+Each helper already owns only the _ephemeral mechanics_ around that state —
 `wireNavStack` the push/pop animation, `wireTabBars` the overflow autoscroll and
 drag preview, `wireResizableRegions` the live drag preview — and reports committed
 changes through callbacks. A `ListHeader` `toggle` disclosure's `expanded` is