@kerfjs/ui 5.0.0-beta.82 → 5.0.0-beta.83

package/README.md

@@ -218,6 +218,7 @@ interchangeable. `ListItem` and `ListActionRow` deliberately expose no raw
 | `DialogSurface`, `PopupSurface`                                     | `@kerfjs/ui/surface-scaffold`           | `@kerfjs/ui/surface-scaffold.css`      |
 | `FloatingToolbar`                                                   | `@kerfjs/ui/floating-toolbar`           | `@kerfjs/ui/floating-toolbar.css`      |
 | `PopupMenu` (register with `@kerfjs/ui/popup-menu/register`)        | `@kerfjs/ui/popup-menu`                 | `@kerfjs/ui/popup-menu.css`            |
+| `openAnchoredSurface`, `openAnchoredSurfaceAt`                      | `@kerfjs/ui/anchored-surface`           | `@kerfjs/ui/anchored-surface.css`      |
 | `ToolbarText`                                                       | `@kerfjs/ui/toolbar-text`               | `@kerfjs/ui/toolbar-text.css`          |
 | `Text`, `FieldLabel`                                                | `@kerfjs/ui/text`                       | `@kerfjs/ui/text.css`                  |
 | `List`                                                              | `@kerfjs/ui/list`                       | `@kerfjs/ui/list.css`                  |

package/ai/catalog-authoring.json

@@ -14,7 +14,6 @@
     "CatalogExample",
     "CatalogExampleStack",
     "wireCatalog",
-    "wireCatalogGeometryOverlay",
     "revealCatalogEntry"
   ],
   "taxonomy": {
@@ -30,7 +29,6 @@
   },
   "metadata": {
     "slot": "rootAttributes",
-    "demo": "data-demo",
-    "geometryOverlaySkip": "data-catalog-geometry-overlay-skip"
+    "demo": "data-demo"
   }
 }

package/ai/catalog-authoring.schema.json

@@ -38,11 +38,10 @@
           "CatalogExample",
           "CatalogExampleStack",
           "wireCatalog",
-          "wireCatalogGeometryOverlay",
           "revealCatalogEntry"
         ]
       },
-      "minItems": 6,
+      "minItems": 5,
       "uniqueItems": true
     },
     "taxonomy": {
@@ -94,13 +93,10 @@
     },
     "metadata": {
       "type": "object",
-      "required": ["slot", "demo", "geometryOverlaySkip"],
+      "required": ["slot", "demo"],
       "properties": {
         "slot": { "const": "rootAttributes" },
-        "demo": { "const": "data-demo" },
-        "geometryOverlaySkip": {
-          "const": "data-catalog-geometry-overlay-skip"
-        }
+        "demo": { "const": "data-demo" }
       },
       "additionalProperties": false
     }

package/ai/component-catalog.json

@@ -1059,6 +1059,7 @@
         "routing and persistence",
         "responsive replacement on larger device classes",
         "whether the bar divider follows the scroll, always shows, or never shows (chromeDividers)",
+        "whether the bar's top separator follows a sunken active surface or stays hidden (separator)",
         "optional active-scene focus (tabIndex) and persistent outline (outlined)"
       ],
       "variants": [
@@ -1067,7 +1068,8 @@
         "badged tabs (count or text-free dot)",
         "one NavStack per tab",
         "bar divider only while the active scene continues below it (wired by wireScrollDividers)",
-        "permanent or no bar divider (chromeDividers always or none)"
+        "permanent or no bar divider (chromeDividers always or none)",
+        "sunken active-scene separator (separator auto or hidden)"
       ],
       "accessibility": [
         "Give the tablist an accessible label and keep exactly the active tab in the sequential focus order.",
@@ -1081,7 +1083,7 @@
         "padding": "self",
         "notes": [
           "The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
-          "The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border."
+          "The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it."
         ]
       },
       "delivery": {
@@ -2568,6 +2570,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -2744,6 +2747,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"m\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -3087,6 +3091,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={rem(0.25)}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -4657,6 +4662,72 @@
         "recipe": "docs/component-selection.md#web-awesome-overlap-policy"
       }
     },
+    {
+      "id": "anchored-surface",
+      "name": "AnchoredSurface",
+      "category": "Feedback",
+      "kind": "component",
+      "source": "kerf",
+      "description": "A styled non-modal surface for app-owned interactive help or popup content, anchored to an element or pointer.",
+      "uses": [],
+      "purpose": "Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.",
+      "publicExports": [
+        "openAnchoredSurface",
+        "openAnchoredSurfaceAt"
+      ],
+      "useWhen": [
+        "Show interactive help or other arbitrary content near a control or pointer, including inside a modal dialog."
+      ],
+      "avoidWhen": [
+        "Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page."
+      ],
+      "alternatives": [
+        { "id": "popup-menu", "relationship": "nearest" },
+        { "id": "wa-popup", "relationship": "prefer-over" }
+      ],
+      "appOwns": [
+        "content and action policy",
+        "opening trigger and programmatic close after an action",
+        "accessible name"
+      ],
+      "variants": [
+        "element anchor",
+        "pointer anchor",
+        "top or bottom placement",
+        "modal-dialog host"
+      ],
+      "usageExamples": [
+        {
+          "title": "Interactive help",
+          "description": "The trigger owns when to open; the returned handle closes when an action completes.",
+          "code": "const handle = openAnchoredSurface(button, () => <HelpPanel />, { label: 'Field help' });\n// Close from the app's action handler: handle.close();"
+        }
+      ],
+      "accessibility": [
+        "The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default."
+      ],
+      "geometry": {
+        "margin": "none",
+        "border": "self",
+        "padding": "self"
+      },
+      "delivery": {
+        "browserImport": "@kerfjs/ui/anchored-surface",
+        "manualCssImport": "@kerfjs/ui/anchored-surface.css",
+        "sideEffects": ["browser-condition-css"]
+      },
+      "wiring": [],
+      "publicClasses": [],
+      "publicTokens": [
+        "--kui-anchored-surface-inset",
+        "--kui-anchored-surface-radius"
+      ],
+      "links": {
+        "catalogRoute": "?component=anchored-surface",
+        "documentation": "docs/anchored-surface.md",
+        "recipe": "docs/anchored-surface.md"
+      }
+    },
     {
       "id": "popup-menu",
       "name": "PopupMenu",

package/ai/component-composition.json

@@ -1013,6 +1013,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "whether the bar's top separator follows a sunken active surface or stays hidden (separator)",
+          "owner": "application",
+          "required": false
+        },
         {
           "id": "optional active-scene focus (tabIndex) and persistent outline (outlined)",
           "owner": "application",
@@ -1047,7 +1052,7 @@
           "padding": "self",
           "notes": [
             "The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.",
-            "The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border."
+            "The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it."
           ]
         }
       },
@@ -2289,6 +2294,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -2392,6 +2398,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"m\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={space(\"m\")}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -2591,6 +2598,7 @@
           "rawPolicy": "forbid",
           "examples": [
             "gap=\"xs\"",
+            "gap={{ column: \"none\", row: \"m\" }}",
             "gap={rem(0.25)}",
             "gap={calc(plus(rem(0.25), pct(10)))}"
           ]
@@ -3797,6 +3805,61 @@
         "composition": "README.md#web-awesome-theme"
       }
     },
+    {
+      "key": "@kerfjs/ui:anchored-surface",
+      "package": "@kerfjs/ui",
+      "id": "anchored-surface",
+      "name": "AnchoredSurface",
+      "kind": "component",
+      "source": "kerf",
+      "parents": { "mode": "any", "entries": [] },
+      "contexts": ["application-ui"],
+      "zones": [],
+      "children": { "mode": "any", "concepts": [], "requiredConcepts": [] },
+      "state": [
+        {
+          "id": "content and action policy",
+          "owner": "application",
+          "required": false
+        },
+        {
+          "id": "opening trigger and programmatic close after an action",
+          "owner": "application",
+          "required": false
+        },
+        { "id": "accessible name", "owner": "application", "required": false }
+      ],
+      "wiring": {
+        "required": false,
+        "helpers": [],
+        "obligations": [],
+        "stateAttributes": []
+      },
+      "responsive": { "owner": "not-applicable", "behaviors": [] },
+      "layout": {
+        "roles": ["feedback"],
+        "geometry": { "margin": "none", "border": "self", "padding": "self" }
+      },
+      "accessibility": {
+        "obligations": [
+          "The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default."
+        ]
+      },
+      "cssValueProps": [],
+      "boundaries": {
+        "rootClass": null,
+        "publicClasses": [],
+        "publicTokens": [
+          "--kui-anchored-surface-inset",
+          "--kui-anchored-surface-radius"
+        ]
+      },
+      "diagnostics": [],
+      "provenance": {
+        "selection": "ai/component-catalog.json",
+        "composition": "generated-permissive-default"
+      }
+    },
     {
       "key": "@kerfjs/ui:popup-menu",
       "package": "@kerfjs/ui",

package/ai/components/README.md

@@ -60,6 +60,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 
 ## Kerf UI — Feedback
 
+- [AnchoredSurface](./anchored-surface.md) — Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
 - [Feedback](./feedback.md) — Banners, empty states, and labeled progress.
 - [StateBanner](./state-banner.md) — Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
 - [EmptyState](./empty-state.md) — Actionable empty and busy content states.

package/ai/components/anchored-surface.md

@@ -0,0 +1,86 @@
+# AnchoredSurface
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:anchored-surface` · Kerf UI · component · Feedback
+
+A styled non-modal surface for app-owned interactive help or popup content, anchored to an element or pointer.
+
+## When to use
+
+Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
+
+- Show interactive help or other arbitrary content near a control or pointer, including inside a modal dialog.
+
+**Not when:**
+
+- Use PopupMenu for a typed action menu, Select for a choice, and a modal dialog for a task that must block the page.
+
+**Alternatives:**
+
+- [PopupMenu](./popup-menu.md) (nearest)
+- [Popup](./wa-popup.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/anchored-surface` — exports `openAnchoredSurface`, `openAnchoredSurfaceAt`.
+- CSS: the browser build of `@kerfjs/ui/anchored-surface` pulls its CSS automatically; import `@kerfjs/ui/anchored-surface.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/anchored-surface`](../public-api-signatures-v1.md#kerfjsuianchored-surface) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- element anchor
+- pointer anchor
+- top or bottom placement
+- modal-dialog host
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** content and action policy; opening trigger and programmatic close after an action; accessible name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The non-modal surface has role dialog and the required label. Focus moves to the first focusable descendant by default and returns to the opener on close; initialFocus: false leaves focus on the trigger. Escape and outside press dismiss by default.
+
+## Usage examples
+
+### Interactive help
+
+The trigger owns when to open; the returned handle closes when an action completes.
+
+```tsx
+const handle = openAnchoredSurface(button, () => <HelpPanel />, {
+  label: 'Field help',
+});
+// Close from the app's action handler: handle.close();
+```
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public tokens it reads: `--kui-anchored-surface-inset`, `--kui-anchored-surface-radius`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [PopupMenu](./popup-menu.md), [Popup](./wa-popup.md).
+- Docs: [`docs/anchored-surface.md`](../../docs/anchored-surface.md).
+- UX catalog route: `?component=anchored-surface`.

package/ai/components/tab-navigator.md

@@ -43,6 +43,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 - one NavStack per tab
 - bar divider only while the active scene continues below it (wired by wireScrollDividers)
 - permanent or no bar divider (chromeDividers always or none)
+- sunken active-scene separator (separator auto or hidden)
 
 ## Composition
 
@@ -53,7 +54,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 
 ## State and wiring
 
-**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); optional active-scene focus (tabIndex) and persistent outline (outlined).
+**The app owns:** controlled active tab id; tab labels, icons, and content; tab badge counts or dots and their localized badgeLabel phrases; routing and persistence; responsive replacement on larger device classes; whether the bar divider follows the scroll, always shows, or never shows (chromeDividers); whether the bar's top separator follows a sunken active surface or stays hidden (separator); optional active-scene focus (tabIndex) and persistent outline (outlined).
 
 **Wiring:** `wireTabNavigator`, `wireScrollDividers` is required.
 
@@ -69,7 +70,7 @@ Exact prop names and types: [`@kerfjs/ui/tab-navigator`](../public-api-signature
 Margin: none · border: conditional · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
 
 - The navigator owns the full-height scene region and safe-area-aware bottom bar; scene content owns its internal geometry.
-- The bar's top line is scroll state (wireScrollDividers): it shows only while the active scene's content continues below the bar, by coloring the bar's always-present 1px top border.
+- The bar's reserved 1px top edge separates a sunken active scene or nested Pane by default; on flat surfaces it follows scroll state (wireScrollDividers). separator=hidden suppresses it.
 
 ## Accessibility
 

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.82` and `kerfjs@5.0.0-beta.82`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.83` and `kerfjs@5.0.0-beta.83`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -66,6 +66,13 @@ type UiColorName = (typeof uiColorNames)[number];
 type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | 'text' | 'text-quiet' | 'text-link'>;
 /** Kerf UI's complete spacing-token vocabulary. `s` and `xl` are exceptions. */
 type UiSpaceName = 'none' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
+/** A token or complete typed length for one gap axis. */
+type UiGapValue = UiSpaceName | CssLength;
+/** A shared gap or independent column and row gaps. */
+type UiGap = UiGapValue | Readonly<{
+    column: UiGapValue;
+    row: UiGapValue;
+}>;
 /** Create a complete pixel length. */
 declare function px(value: number): CssLength;
 /** Create a complete root-font-relative length. */
@@ -116,7 +123,7 @@ declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroun
  */
 declare function foregroundColor(value: string): CssForegroundColor;
 
-export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiGap, type UiGapValue, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
 ```
 
 ## `@kerfjs/ui/disclosure-arrow`
@@ -651,7 +658,8 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
+export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
 
 type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -670,8 +678,8 @@ interface ListProps {
     selectionMode?: 'multiple';
     /** Accessible name for the multi-select grid. */
     ariaLabel?: string;
-    /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */
-    gap?: boolean | UiSpaceName | CssLength;
+    /** Standard gap (`true`), one spacing value, or separate column and row values. Defaults to no gap. */
+    gap?: boolean | UiGap;
     /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
     /**
@@ -708,7 +716,7 @@ type ListConfig = Pick<ListProps, 'gap' | 'hAlign' | 'vAlign' | 'dividerSides' |
 /** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
 declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
+export { CssFlex, CssFlexKeyword, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiGap };
 ```
 
 ## `@kerfjs/ui/list-action-row`
@@ -2200,14 +2208,21 @@ interface TabNavigatorProps<Id extends string = string> {
     tabs: readonly TabNavigatorTab<Id>[];
     /** The controlled active tab id (the app owns selection). */
     active: NoInfer<Id>;
+    /**
+     * The bar's top separator. `auto` (default) draws it against a sunken active
+     * work surface and otherwise follows `chromeDividers`; `hidden` suppresses
+     * the line, including a scroll divider.
+     */
+    separator?: 'auto' | 'hidden';
     /**
      * The line over the tab bar, where it meets the active scene. `scroll`
      * (default) shows it only while more of the scene's content lies below —
      * never at the scroll end or when the content fits — once
      * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
      * the scaffold; unwired, it does not show. `always` shows it without the
-     * wiring; `none` never, even when wired. The line is the bar's own 1px top
-     * border, so no state moves the bar or a tab.
+     * wiring; `none` suppresses that scroll divider. A sunken active work
+     * surface still draws the separator unless `separator="hidden"`. The line
+     * is the bar's own 1px top border, so no state moves the bar or a tab.
      */
     chromeDividers?: 'scroll' | 'always' | 'none';
     className?: string;
@@ -2222,7 +2237,7 @@ interface TabNavigatorProps<Id extends string = string> {
  * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
  * a bottom bar. See `docs/23-app-layouts.md` §3.4.
  */
-declare function TabNavigator<Id extends string>({ id, label, tabs, active, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
 
 export { TabNavigator, type TabNavigatorProps, type TabNavigatorTab };
 ```
@@ -2393,8 +2408,8 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```ts
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-C9BubXfz.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-C9BubXfz.js';
+import { a as CatalogProps } from './types-CXrh9Wyx.js';
+export { b as CatalogBackgroundStyle, c as CatalogBrand, d as CatalogEntry, e as CatalogRelated, C as CatalogResource, f as CatalogSecondaryGroup, g as CatalogSection, h as CatalogStageRootAttributes } from './types-CXrh9Wyx.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './toolbar.js';
 import './sides-BPSWde0A.js';
@@ -2417,7 +2432,7 @@ import './resizable-region.js';
  * standard toggle moves into the entry toolbar while it is collapsed, and on
  * a small screen the sidebar overlays the stage like any Workbench rail.
  */
-declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, backgroundStyle, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'text-trigger' | 'none';
@@ -2488,7 +2503,7 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-C9BubXfz.js';
+import { C as CatalogResource } from './types-CXrh9Wyx.js';
 import './toolbar.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
@@ -2603,14 +2618,6 @@ interface CatalogRevealOptions {
  * moving focus. Returns a cancellation function for rapid selection changes.
  */
 declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
-/**
- * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
- * Specimens receive computed border highlights (or a dashed bound when they
- * have no border and are transparent), while positive computed margins use
- * devtools-style orange bands. CSS/stylesheet-only changes are observed too.
- * Returns a disposer.
- */
-declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
 /**
  * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
  * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
@@ -2622,7 +2629,7 @@ declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
  */
 declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, sidebarSize, sidebarStorageKey, id: catalogId, }: WireCatalogOptions): () => void;
 
-export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog };
 ```
 
 ## `@kerfjs/ui/segmented-control`
@@ -3420,7 +3427,8 @@ import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
+export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
 
 type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3438,8 +3446,8 @@ interface RowProps {
     hAlign?: HorizontalAlignment;
     /** Vertical alignment and wrapped-line distribution. Defaults to full. */
     vAlign?: VerticalAlignment;
-    /** A named UI spacing token or typed CSS length. Defaults to xs. */
-    gap?: UiSpaceName | CssLength;
+    /** One spacing value or separate column and row values. Defaults to xs. */
+    gap?: UiGap;
     /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
     /**
@@ -3463,7 +3471,7 @@ interface RowProps {
 /** A horizontal flex row with explicit physical-axis alignment and spacing. */
 declare function Row({ children, hAlign, vAlign, gap, flex, fill, wrap, textInsets, controlInsets, className, rootAttributes, slot, }: RowProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, Sides, UiSpaceName, VerticalAlignment };
+export { CssFlex, CssFlexKeyword, HorizontalAlignment, Row, type RowProps, Sides, UiGap, VerticalAlignment };
 ```
 
 ## `@kerfjs/ui/grid`
@@ -3472,7 +3480,8 @@ export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowP
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex, CssLength } from './css-values.js';
+export { UiGapValue, UiSpaceName } from './css-values.js';
 
 type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3490,8 +3499,8 @@ interface GridCommonProps {
     selectionMode?: 'multiple';
     /** Accessible name for the multi-select grid. */
     ariaLabel?: string;
-    /** A named UI spacing token or typed CSS length. Defaults to xs. */
-    gap?: UiSpaceName | CssLength;
+    /** One spacing value or separate column and row values. Defaults to xs. */
+    gap?: UiGap;
     /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
     /**
@@ -3525,7 +3534,7 @@ type GridProps = GridCommonProps & ({
 /** Render equal tracks with a fixed count or a responsive minimum width. */
 declare function Grid({ children, selectionMode, ariaLabel, columns, minColumnWidth, autoFill, gap, flex, fill, textInsets, controlInsets, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiSpaceName };
+export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiGap };
 ```
 
 ## `@kerfjs/ui/spacer`
@@ -3558,3 +3567,38 @@ export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchRe
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```
+
+## `@kerfjs/ui/anchored-surface`
+
+```ts
+import { PopoverOptions, OverlayContent, OverlayHandle } from 'kerfjs/overlay';
+
+/** App-facing options for a non-modal, arbitrary-content help surface. */
+interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore'> {
+    /** Accessible name for the non-modal dialog. */
+    label: string;
+}
+/** A viewport pointer location; `context` is the element under the pointer. */
+interface AnchoredSurfacePoint {
+    x: number;
+    y: number;
+    /** Pass the event target when opening from inside a modal dialog. */
+    context?: Element;
+}
+/**
+ * Open app-owned content beside an element. The surface owns its Kerf UI chrome;
+ * kerfjs/overlay owns positioning, top-layer/modal hosting, focus, and dismissal.
+ * The caller owns content, action policy, and calling `close()` when an action
+ * completes. `initialFocus` defaults to the first focusable descendant; set it
+ * to `false` for read-only help that should leave focus on its trigger.
+ */
+declare function openAnchoredSurface(anchor: Element, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+/**
+ * Open the same surface at pointer coordinates. The temporary anchor has no
+ * layout or hit target. `context` keeps a surface opened inside a modal dialog
+ * in that dialog's interactive host slot; it is removed on close or failure.
+ */
+declare function openAnchoredSurfaceAt(point: AnchoredSurfacePoint, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+
+export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, openAnchoredSurface, openAnchoredSurfaceAt };
+```