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

package/dist/wire-tab-scaffold.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/wire-tab-scaffold.ts"],"names":[],"mappings":";;;AAWO,SAAS,eAAA,CAAgB,MAAe,OAAA,EAA6C;AAC1F,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,CAAQ,iCAAiC,IAAI,IAAA,GAAO,IAAA,CAAK,cAAc,iCAAiC,CAAA;AAC7H,EAAA,IAAI,EAAE,OAAA,YAAmB,WAAA,CAAA,EAAc,OAAO,MAAM;AAAA,EAAC,CAAA;AACrD,EAAA,OAAO,SAAS,OAAA,EAAS,OAAA,EAAS,yBAAA,EAA2B,CAAC,QAAQ,MAAA,KAAW;AAC/E,IAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,YAAA,CAAa,uBAAuB,CAAA;AACzD,IAAA,IAAI,KAAA,EAAO,OAAA,CAAQ,QAAA,CAAS,KAAK,CAAA;AAAA,EACnC,CAAC,CAAA;AACH","file":"wire-tab-scaffold.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireTabScaffoldOptions {\n  /** Invoked with the selected tab id when a bottom-bar tab is activated. */\n  onSelect: (tabId: string) => void;\n}\n\n/**\n * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its\n * id (the app then updates its controlled `active`). Returns a disposer.\n */\nexport function wireTabScaffold(root: Element, options: WireTabScaffoldOptions): () => void {\n  const section = root.matches('[data-component=\"tab-scaffold\"]') ? root : root.querySelector('[data-component=\"tab-scaffold\"]');\n  if (!(section instanceof HTMLElement)) return () => {};\n  return delegate(section, 'click', '[data-tab-scaffold-tab]', (_event, target) => {\n    const tabId = target.getAttribute('data-tab-scaffold-tab');\n    if (tabId) options.onSelect(tabId);\n  });\n}\n"]}
+{"version":3,"sources":["../src/wire-tab-scaffold.ts"],"names":[],"mappings":";;;AAWO,SAAS,eAAA,CACd,MACA,OAAA,EACY;AACZ,EAAA,MAAM,OAAA,GAAU,KAAK,OAAA,CAAQ,iCAAiC,IAC1D,IAAA,GACA,IAAA,CAAK,cAAc,iCAAiC,CAAA;AACxD,EAAA,IAAI,EAAE,OAAA,YAAmB,WAAA,CAAA,EAAc,OAAO,MAAM;AAAA,EAAC,CAAA;AACrD,EAAA,OAAO,QAAA;AAAA,IACL,OAAA;AAAA,IACA,OAAA;AAAA,IACA,yBAAA;AAAA,IACA,CAAC,QAAQ,MAAA,KAAW;AAClB,MAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,YAAA,CAAa,uBAAuB,CAAA;AACzD,MAAA,IAAI,KAAA,EAAO,OAAA,CAAQ,QAAA,CAAS,KAAK,CAAA;AAAA,IACnC;AAAA,GACF;AACF","file":"wire-tab-scaffold.js","sourcesContent":["import { delegate } from 'kerfjs';\n\nexport interface WireTabScaffoldOptions {\n  /** Invoked with the selected tab id when a bottom-bar tab is activated. */\n  onSelect: (tabId: string) => void;\n}\n\n/**\n * Wire a `TabScaffold`'s bottom tab bar: clicking a tab calls `onSelect` with its\n * id (the app then updates its controlled `active`). Returns a disposer.\n */\nexport function wireTabScaffold(\n  root: Element,\n  options: WireTabScaffoldOptions,\n): () => void {\n  const section = root.matches('[data-component=\"tab-scaffold\"]')\n    ? root\n    : root.querySelector('[data-component=\"tab-scaffold\"]');\n  if (!(section instanceof HTMLElement)) return () => {};\n  return delegate(\n    section,\n    'click',\n    '[data-tab-scaffold-tab]',\n    (_event, target) => {\n      const tabId = target.getAttribute('data-tab-scaffold-tab');\n      if (tabId) options.onSelect(tabId);\n    },\n  );\n}\n"]}

package/dist/wire-token-search-fields.d.ts

@@ -101,6 +101,6 @@ interface TokenSearchFieldsHandle {
  * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
  * exposes the managed `expanded` state per field id.
  */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
 export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };

package/dist/wire-token-search-fields.js

@@ -1,4 +1,4 @@
-export { wireTokenSearchFields } from './chunk-LCOBDOCC.js';
+export { wireTokenSearchFields } from './chunk-ENVTNLYC.js';
 
 
 

package/dist/workbench.d.ts

@@ -28,6 +28,6 @@ interface WorkbenchProps {
  * work area relayouts once, not per frame. The app owns each `collapsed` flag;
  * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, }: WorkbenchProps): SafeHtml;
 
 export { Workbench, type WorkbenchPanel, type WorkbenchProps };

package/dist/workbench.js

@@ -1,15 +1,62 @@
 import { jsxs, jsx } from 'kerfjs/jsx-runtime';
 
 // src/workbench.tsx
-function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className = "" }) {
-  return /* @__PURE__ */ jsxs("section", { class: `kui-workbench ${className}`.trim(), id, "data-component": "workbench", "aria-label": label, children: [
-    leftRail && /* @__PURE__ */ jsx("aside", { class: "kui-workbench__rail kui-workbench__rail--left", "data-workbench-rail": "left", "data-collapsed": String(leftRail.collapsed ?? false), "aria-label": leftRail.label || void 0, style: leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : void 0, children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: leftRail.content }) }),
-    /* @__PURE__ */ jsxs("div", { class: "kui-workbench__center", children: [
-      /* @__PURE__ */ jsx("div", { class: "kui-workbench__main", "data-workbench-main": true, children: main }),
-      bottomDrawer && /* @__PURE__ */ jsx("section", { class: "kui-workbench__drawer", "data-workbench-drawer": true, "data-collapsed": String(bottomDrawer.collapsed ?? false), "aria-label": bottomDrawer.label || void 0, style: bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : void 0, children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: bottomDrawer.content }) })
-    ] }),
-    rightRail && /* @__PURE__ */ jsx("aside", { class: "kui-workbench__rail kui-workbench__rail--right", "data-workbench-rail": "right", "data-collapsed": String(rightRail.collapsed ?? false), "aria-label": rightRail.label || void 0, style: rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : void 0, children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: rightRail.content }) })
-  ] });
+function Workbench({
+  id,
+  label,
+  main,
+  leftRail,
+  rightRail,
+  bottomDrawer,
+  className = ""
+}) {
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      class: `kui-workbench ${className}`.trim(),
+      id,
+      "data-component": "workbench",
+      "aria-label": label,
+      children: [
+        leftRail && /* @__PURE__ */ jsx(
+          "aside",
+          {
+            class: "kui-workbench__rail kui-workbench__rail--left",
+            "data-workbench-rail": "left",
+            "data-collapsed": String(leftRail.collapsed ?? false),
+            "aria-label": leftRail.label || void 0,
+            style: leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : void 0,
+            children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: leftRail.content })
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { class: "kui-workbench__center", children: [
+          /* @__PURE__ */ jsx("div", { class: "kui-workbench__main", "data-workbench-main": true, children: main }),
+          bottomDrawer && /* @__PURE__ */ jsx(
+            "section",
+            {
+              class: "kui-workbench__drawer",
+              "data-workbench-drawer": true,
+              "data-collapsed": String(bottomDrawer.collapsed ?? false),
+              "aria-label": bottomDrawer.label || void 0,
+              style: bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : void 0,
+              children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: bottomDrawer.content })
+            }
+          )
+        ] }),
+        rightRail && /* @__PURE__ */ jsx(
+          "aside",
+          {
+            class: "kui-workbench__rail kui-workbench__rail--right",
+            "data-workbench-rail": "right",
+            "data-collapsed": String(rightRail.collapsed ?? false),
+            "aria-label": rightRail.label || void 0,
+            style: rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : void 0,
+            children: /* @__PURE__ */ jsx("div", { class: "kui-workbench__panel-content", children: rightRail.content })
+          }
+        )
+      ]
+    }
+  );
 }
 
 export { Workbench };

package/dist/workbench.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":";;;AAgCO,SAAS,SAAA,CAAU,EAAE,EAAA,EAAI,KAAA,EAAO,IAAA,EAAM,UAAU,SAAA,EAAW,YAAA,EAAc,SAAA,GAAY,EAAA,EAAG,EAAmB;AAChH,EAAA,uBAAO,IAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAO,CAAA,cAAA,EAAiB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK,EAAG,EAAA,EAAQ,gBAAA,EAAe,WAAA,EAAY,YAAA,EAAY,KAAA,EACxG,QAAA,EAAA;AAAA,IAAA,QAAA,oBAAY,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,+CAAA,EAAgD,qBAAA,EAAoB,MAAA,EAAO,gBAAA,EAAgB,MAAA,CAAO,QAAA,CAAS,SAAA,IAAa,KAAK,CAAA,EAAG,cAAY,QAAA,CAAS,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,QAAA,CAAS,IAAA,GAAO,CAAA,4BAAA,EAA+B,QAAA,CAAS,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAC3Q,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,QAAA,CAAS,SAAQ,CAAA,EAC9D,CAAA;AAAA,oBACA,IAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EACT,QAAA,EAAA;AAAA,sBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,qBAAA,EAAsB,qBAAA,EAAmB,MAAE,QAAA,EAAA,IAAA,EAAK,CAAA;AAAA,MAC1D,YAAA,oBAAgB,GAAA,CAAC,SAAA,EAAA,EAAQ,KAAA,EAAM,uBAAA,EAAwB,uBAAA,EAAqB,IAAA,EAAC,gBAAA,EAAgB,MAAA,CAAO,YAAA,CAAa,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,YAAA,CAAa,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,YAAA,CAAa,IAAA,GAAO,CAAA,+BAAA,EAAkC,aAAa,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EACvQ,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,YAAA,CAAa,SAAQ,CAAA,EAClE;AAAA,KAAA,EACF,CAAA;AAAA,IACC,SAAA,oBAAa,GAAA,CAAC,OAAA,EAAA,EAAM,KAAA,EAAM,gDAAA,EAAiD,qBAAA,EAAoB,OAAA,EAAQ,gBAAA,EAAgB,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,KAAK,GAAG,YAAA,EAAY,SAAA,CAAU,KAAA,IAAS,MAAA,EAAW,KAAA,EAAO,SAAA,CAAU,IAAA,GAAO,CAAA,4BAAA,EAA+B,UAAU,IAAI,CAAA,EAAA,CAAA,GAAO,MAAA,EAClR,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,QAAA,EAAA,SAAA,CAAU,SAAQ,CAAA,EAC/D;AAAA,GAAA,EACF,CAAA;AACF","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: SafeHtml;\n  /** Whether the panel is currently collapsed (the app owns this). */\n  collapsed?: boolean;\n  /** Rail width, or drawer height, in px. Overrides the CSS default. */\n  size?: number;\n  /** Accessible name for the panel region. */\n  label?: string;\n}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: SafeHtml;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  className?: string;\n}\n\n/**\n * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and\n * bottom drawer around a central work area (any absent). Collapsing snaps the\n * panel's track to zero in one reflow while its fixed-size content slides out via\n * a composited transform — the instant-width / sliding-content technique, so the\n * work area relayouts once, not per frame. The app owns each `collapsed` flag;\n * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className = '' }: WorkbenchProps) {\n  return <section class={`kui-workbench ${className}`.trim()} id={id} data-component=\"workbench\" aria-label={label}>\n    {leftRail && <aside class=\"kui-workbench__rail kui-workbench__rail--left\" data-workbench-rail=\"left\" data-collapsed={String(leftRail.collapsed ?? false)} aria-label={leftRail.label || undefined} style={leftRail.size ? `--kui-workbench-rail-width: ${leftRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n    </aside>}\n    <div class=\"kui-workbench__center\">\n      <div class=\"kui-workbench__main\" data-workbench-main>{main}</div>\n      {bottomDrawer && <section class=\"kui-workbench__drawer\" data-workbench-drawer data-collapsed={String(bottomDrawer.collapsed ?? false)} aria-label={bottomDrawer.label || undefined} style={bottomDrawer.size ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px` : undefined}>\n        <div class=\"kui-workbench__panel-content\">{bottomDrawer.content}</div>\n      </section>}\n    </div>\n    {rightRail && <aside class=\"kui-workbench__rail kui-workbench__rail--right\" data-workbench-rail=\"right\" data-collapsed={String(rightRail.collapsed ?? false)} aria-label={rightRail.label || undefined} style={rightRail.size ? `--kui-workbench-rail-width: ${rightRail.size}px` : undefined}>\n      <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n    </aside>}\n  </section>;\n}\n"]}
+{"version":3,"sources":["../src/workbench.tsx"],"names":[],"mappings":";;;AAgCO,SAAS,SAAA,CAAU;AAAA,EACxB,EAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,QAAA;AAAA,EACA,SAAA;AAAA,EACA,YAAA;AAAA,EACA,SAAA,GAAY;AACd,CAAA,EAAmB;AACjB,EAAA,uBACE,IAAA;AAAA,IAAC,SAAA;AAAA,IAAA;AAAA,MACC,KAAA,EAAO,CAAA,cAAA,EAAiB,SAAS,CAAA,CAAA,CAAG,IAAA,EAAK;AAAA,MACzC,EAAA;AAAA,MACA,gBAAA,EAAe,WAAA;AAAA,MACf,YAAA,EAAY,KAAA;AAAA,MAEX,QAAA,EAAA;AAAA,QAAA,QAAA,oBACC,GAAA;AAAA,UAAC,OAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,+CAAA;AAAA,YACN,qBAAA,EAAoB,MAAA;AAAA,YACpB,gBAAA,EAAgB,MAAA,CAAO,QAAA,CAAS,SAAA,IAAa,KAAK,CAAA;AAAA,YAClD,YAAA,EAAY,SAAS,KAAA,IAAS,MAAA;AAAA,YAC9B,OACE,QAAA,CAAS,IAAA,GACL,CAAA,4BAAA,EAA+B,QAAA,CAAS,IAAI,CAAA,EAAA,CAAA,GAC5C,MAAA;AAAA,YAGN,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,mBAAS,OAAA,EAAQ;AAAA;AAAA,SAC9D;AAAA,wBAEF,IAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,uBAAA,EACT,QAAA,EAAA;AAAA,0BAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,qBAAA,EAAsB,qBAAA,EAAmB,MACjD,QAAA,EAAA,IAAA,EACH,CAAA;AAAA,UACC,YAAA,oBACC,GAAA;AAAA,YAAC,SAAA;AAAA,YAAA;AAAA,cACC,KAAA,EAAM,uBAAA;AAAA,cACN,uBAAA,EAAqB,IAAA;AAAA,cACrB,gBAAA,EAAgB,MAAA,CAAO,YAAA,CAAa,SAAA,IAAa,KAAK,CAAA;AAAA,cACtD,YAAA,EAAY,aAAa,KAAA,IAAS,MAAA;AAAA,cAClC,OACE,YAAA,CAAa,IAAA,GACT,CAAA,+BAAA,EAAkC,YAAA,CAAa,IAAI,CAAA,EAAA,CAAA,GACnD,MAAA;AAAA,cAGN,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EACR,uBAAa,OAAA,EAChB;AAAA;AAAA;AACF,SAAA,EAEJ,CAAA;AAAA,QACC,SAAA,oBACC,GAAA;AAAA,UAAC,OAAA;AAAA,UAAA;AAAA,YACC,KAAA,EAAM,gDAAA;AAAA,YACN,qBAAA,EAAoB,OAAA;AAAA,YACpB,gBAAA,EAAgB,MAAA,CAAO,SAAA,CAAU,SAAA,IAAa,KAAK,CAAA;AAAA,YACnD,YAAA,EAAY,UAAU,KAAA,IAAS,MAAA;AAAA,YAC/B,OACE,SAAA,CAAU,IAAA,GACN,CAAA,4BAAA,EAA+B,SAAA,CAAU,IAAI,CAAA,EAAA,CAAA,GAC7C,MAAA;AAAA,YAGN,QAAA,kBAAA,GAAA,CAAC,KAAA,EAAA,EAAI,KAAA,EAAM,8BAAA,EAAgC,oBAAU,OAAA,EAAQ;AAAA;AAAA;AAC/D;AAAA;AAAA,GAEJ;AAEJ","file":"workbench.js","sourcesContent":["import type { SafeHtml } from 'kerfjs';\n\n/** A collapsible Workbench panel — a side rail or the bottom drawer. */\nexport interface WorkbenchPanel {\n  content: SafeHtml;\n  /** Whether the panel is currently collapsed (the app owns this). */\n  collapsed?: boolean;\n  /** Rail width, or drawer height, in px. Overrides the CSS default. */\n  size?: number;\n  /** Accessible name for the panel region. */\n  label?: string;\n}\n\nexport interface WorkbenchProps {\n  id: string;\n  label: string;\n  /** The central work area. */\n  main: SafeHtml;\n  leftRail?: WorkbenchPanel;\n  rightRail?: WorkbenchPanel;\n  bottomDrawer?: WorkbenchPanel;\n  className?: string;\n}\n\n/**\n * The Xcode-like multi-panel workspace: a collapsible left rail, right rail, and\n * bottom drawer around a central work area (any absent). Collapsing snaps the\n * panel's track to zero in one reflow while its fixed-size content slides out via\n * a composited transform — the instant-width / sliding-content technique, so the\n * work area relayouts once, not per frame. The app owns each `collapsed` flag;\n * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.\n */\nexport function Workbench({\n  id,\n  label,\n  main,\n  leftRail,\n  rightRail,\n  bottomDrawer,\n  className = '',\n}: WorkbenchProps) {\n  return (\n    <section\n      class={`kui-workbench ${className}`.trim()}\n      id={id}\n      data-component=\"workbench\"\n      aria-label={label}\n    >\n      {leftRail && (\n        <aside\n          class=\"kui-workbench__rail kui-workbench__rail--left\"\n          data-workbench-rail=\"left\"\n          data-collapsed={String(leftRail.collapsed ?? false)}\n          aria-label={leftRail.label || undefined}\n          style={\n            leftRail.size\n              ? `--kui-workbench-rail-width: ${leftRail.size}px`\n              : undefined\n          }\n        >\n          <div class=\"kui-workbench__panel-content\">{leftRail.content}</div>\n        </aside>\n      )}\n      <div class=\"kui-workbench__center\">\n        <div class=\"kui-workbench__main\" data-workbench-main>\n          {main}\n        </div>\n        {bottomDrawer && (\n          <section\n            class=\"kui-workbench__drawer\"\n            data-workbench-drawer\n            data-collapsed={String(bottomDrawer.collapsed ?? false)}\n            aria-label={bottomDrawer.label || undefined}\n            style={\n              bottomDrawer.size\n                ? `--kui-workbench-drawer-height: ${bottomDrawer.size}px`\n                : undefined\n            }\n          >\n            <div class=\"kui-workbench__panel-content\">\n              {bottomDrawer.content}\n            </div>\n          </section>\n        )}\n      </div>\n      {rightRail && (\n        <aside\n          class=\"kui-workbench__rail kui-workbench__rail--right\"\n          data-workbench-rail=\"right\"\n          data-collapsed={String(rightRail.collapsed ?? false)}\n          aria-label={rightRail.label || undefined}\n          style={\n            rightRail.size\n              ? `--kui-workbench-rail-width: ${rightRail.size}px`\n              : undefined\n          }\n        >\n          <div class=\"kui-workbench__panel-content\">{rightRail.content}</div>\n        </aside>\n      )}\n    </section>\n  );\n}\n"]}

package/docs/app-layouts.md

@@ -21,13 +21,13 @@ gate the roomier presentations.
 
 ## Decision matrix
 
-| Situation | Layout | Device threshold |
-| --- | --- | --- |
-| Simple app, a few flat sections | `NavStack` with one entry (single pane); add `TabScaffold` for 2–5 co-equal sections on handset | `TabScaffold` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')` |
-| Drill-down browsing (list → item → sub-item) | `NavStack`; upgrade to `SplitView` once list + detail fit together | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact` |
-| Two related panes, selecting on the left updates the right | `SplitView` | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact` |
-| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench` | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
-| Mobile app with 2–5 top-level destinations, each its own drill-down | `TabScaffold`, each tab a `NavStack` | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')` |
+| Situation                                                                    | Layout                                                                                          | Device threshold                                                                                                                   |
+| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Simple app, a few flat sections                                              | `NavStack` with one entry (single pane); add `TabScaffold` for 2–5 co-equal sections on handset | `TabScaffold` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')`                                  |
+| Drill-down browsing (list → item → sub-item)                                 | `NavStack`; upgrade to `SplitView` once list + detail fit together                              | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact`                                   |
+| Two related panes, selecting on the left updates the right                   | `SplitView`                                                                                     | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact`                                                 |
+| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench`                                                                                     | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
+| Mobile app with 2–5 top-level destinations, each its own drill-down          | `TabScaffold`, each tab a `NavStack`                                                            | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')`                                                          |
 
 ### Worked examples
 

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,19 +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?, resources?, related? }] }`. Each entry becomes a sidebar `ListItem`
-  under a `ListHeader` for its category.
+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).
@@ -46,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">
@@ -71,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.',
-        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.
@@ -101,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