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

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).
@@ -47,7 +47,7 @@ instead of hand-rolled example markup, so labels, notes, and left-edge alignment
 stay consistent:
 
 ```tsx
-import { CatalogExample, CatalogExampleStack } from '@kerfjs/ui/catalog';
+import { CatalogExample, CatalogExampleStack } from "@kerfjs/ui/catalog";
 
 const buttonPreview = (
   <CatalogExampleStack label="Button variants">
@@ -72,26 +72,99 @@ content-item/composition that already owns its geometry. The inset is published
 the `--kui-catalog-example-align` custom property so a debug overlay can exclude it
 from a specimen's measured margin.
 
+## Geometry inspection
+
+Pass `geometryOverlay` to `Catalog` when individual component previews should
+show otherwise-invisible geometry. The controlled boolean draws a dashed outer
+bound around specimens with transparent backgrounds and devtools-style orange
+bands over positive margins. Keep the prop present while switching entries so
+`wireCatalog` can reuse one overlay layer; set it to `true` for focused component
+previews and `false` for full compositions whose child geometry should remain
+unmarked.
+
+```tsx
+<Catalog
+  {...props}
+  geometryOverlay={activeEntry.kind === "component"}
+  content={renderers[active.value]()}
+/>
+```
+
+Call `wireCatalogGeometryOverlay(root)` after the first render to synchronize the
+opt-in layer across rerenders, theme changes, resizes, and scrolling, and retain
+its disposer alongside `wireCatalog`'s. `CatalogExample` labels and notes are
+excluded; its `align` inset is also subtracted so alignment scaffolding is not
+reported as intrinsic component margin. Put
+`data-catalog-geometry-overlay-skip` on a preview subtree that is intentionally
+explanatory chrome rather than a specimen.
+
+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.
+
+## 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 } from "kerfjs";
+import { Catalog, 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[] = [
   {
-    category: 'Controls',
+    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",
+        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" }],
+      },
+    ],
+  },
+  {
+    category: "Feedback",
+    entries: [
+      { id: "toast", name: "Toast", description: "A transient message." },
     ],
   },
-  { category: 'Feedback', entries: [{ id: 'toast', name: 'Toast', description: 'A transient message.' }] },
 ];
 
 // 2. One preview render per entry id.
@@ -102,32 +175,43 @@ const renderers: Record<string, () => ReturnType<typeof Button>> = {
 };
 
 // 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 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={true}
   />
 ));
 
 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

@@ -20,6 +20,34 @@ remains authored rather than generated.
 
 ## 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.
@@ -166,14 +194,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