@ngrok/mantle 0.82.0 → 0.83.0

package/dist/sidebar.d.ts

@@ -1,8 +1,9 @@
 import { n as WithAsChild } from "./as-child-D23mGo4f.js";
-import { n as IconButtonProps } from "./button-C7vAl6lS.js";
 import { t as WithDataSlot } from "./data-slot-CChfb_cv.js";
-import { n as Separator } from "./separator-B5UmkVRL.js";
-import { ComponentProps, ReactNode } from "react";
+import { n as IconButtonProps } from "./button-DJ7AAgII.js";
+import { n as Separator } from "./separator-CNDs98Dv.js";
+import { t as Tooltip } from "./tooltip-DuXGxIse.js";
+import { ComponentProps, ReactElement, ReactNode } from "react";
 //#region src/components/sidebar/sidebar.d.ts
 /**
  * The breakpoints below which `Sidebar.Nav` swaps from the inline desktop
@@ -78,13 +79,19 @@ type SidebarState = {
    * triggers.
    */
   navId: string;
+  /**
+   * Whether this root owns the `⌘B` / `Ctrl+B` shortcut. `Sidebar.Trigger`
+   * reads it to decide whether its tooltip advertises the chord, so the hint
+   * can never name a binding that is not bound.
+   */
+  keyboardShortcut: boolean;
 };
 /**
  * Read the nearest `Sidebar.Root` state. Throws when called outside a
  * `Sidebar.Root` so misuse fails loudly. Use it to build custom triggers,
  * a keyboard shortcut, or close-on-navigate behavior.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#usesidebar
  *
  * @example
  * ```tsx
@@ -100,6 +107,11 @@ type SidebarState = {
  */
 declare function useSidebar(): SidebarState;
 type SidebarRootProps = {
+  /**
+   * The sidebar's parts — a `Sidebar.Nav` and anything that reads the state,
+   * including a `Sidebar.Trigger` rendered anywhere below (an
+   * `AppLayout.Header`, for example). `Root` renders no DOM of its own.
+   */
   children?: ReactNode;
   /**
    * The initial desktop expanded state for the uncontrolled case.
@@ -132,10 +144,18 @@ type SidebarRootProps = {
   mobileBreakpoint?: SidebarMobileBreakpoint;
   /**
    * Toggle the sidebar with `⌘B` (macOS) / `Ctrl+B` (Windows/Linux). The
-   * shortcut requires exactly the platform modifier + `b` — combinations with
-   * `Shift`/`Alt` (e.g. the browser's own `⌘⇧B`) are left alone. Set `false`
-   * to opt out, e.g. when the app embeds a rich-text editor where `⌘B` means
-   * bold.
+   * shortcut requires exactly the platform modifier + `b`: `⌘` on Apple
+   * platforms and `Ctrl` everywhere else, resolved per host — the two never
+   * substitute for each other, so macOS's native `Ctrl+B` ("move the caret
+   * back one character") is left alone. Combinations with `Shift`/`Alt` (e.g.
+   * the browser's own `⌘⇧B`) pass through too.
+   *
+   * The shortcut is also ignored while focus is in a text-editing or form
+   * control — an `<input>`, `<textarea>`, `<select>`, or any `contenteditable`
+   * host — because the chord is usually already bound there (`⌘B` is "bold")
+   * and this is a `window` listener that calls `preventDefault()`. That covers
+   * embedded editors like Monaco and CodeMirror, which attach to exactly those
+   * elements. Set `false` to opt out entirely.
    *
    * The shortcut has exactly one owner per window: the first mounted root
    * with the shortcut enabled. Additional roots (nested or siblings) queue
@@ -148,7 +168,7 @@ type SidebarRootProps = {
 };
 /**
  * The state owner for a sidebar. Renders no DOM of its own (like
- * `Tooltip.Root`) — it provides the expanded/collapsed and mobile-sheet state
+ * `Tooltip.Root`) — it carries the expanded/collapsed and mobile-sheet state
  * to every part below it, so `Sidebar.Trigger` can live anywhere in the tree
  * (for example inside an `AppLayout.Header`) without coupling the app shell
  * to the sidebar.
@@ -156,13 +176,24 @@ type SidebarRootProps = {
  * Render exactly one `Sidebar.Nav` per `Sidebar.Root`. Nested roots shadow
  * the outer sidebar for everything below them.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarroot
  *
  * @example
  * ```tsx
  * <Sidebar.Root>
  *   <Sidebar.Nav aria-label="Main">
- *     <Sidebar.Header>…</Sidebar.Header>
+ *     <Sidebar.Header>
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <GlobeIcon />
+ *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+ *             <CaretDownIcon className="text-muted size-4 shrink-0" />
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Header>
  *     <Sidebar.Body>
  *       <Sidebar.Group>
  *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
@@ -178,11 +209,22 @@ type SidebarRootProps = {
  *         </Sidebar.List>
  *       </Sidebar.Group>
  *     </Sidebar.Body>
- *     <Sidebar.Footer>…</Sidebar.Footer>
+ *     <Sidebar.Footer>
+ *       <Sidebar.Separator />
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
+ *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Footer>
  *   </Sidebar.Nav>
- *   <main>
- *     <Sidebar.Trigger />
- *   </main>
+ *   <Sidebar.Trigger />
  * </Sidebar.Root>
  * ```
  */
@@ -226,19 +268,39 @@ type SidebarNavProps = ComponentProps<"div"> & WithDataSlot;
  * opens from. Override `--sidebar-width` at `:root` to move both together, or
  * set `--sidebar-row-width` on the outside surface itself.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"expanded"` \| `"collapsed"` | On the desktop panel surface. Mirrors the root's expanded state and drives the width collapse to the icon rail; descendant parts style off it with `group-data-[state=collapsed]/sidebar-nav:`. |
+ * | `data-hydrated` | present after hydration | Presence-only, desktop panel surface. The CSS-side twin of the `isHydrated` gate: descendant collapse transitions are enabled only under `group-data-hydrated/sidebar-nav:`, so an SSR state correction snaps instead of animating on page load. |
+ * | `data-mobile` | present in the mobile sheet | Presence-only. Marks the `Sheet.Content` presentation used below the root's `mobileBreakpoint`. |
+ * | `data-state` | `"open"` \| `"closed"` | In the mobile sheet only, where the panel *is* the `Sheet`'s Radix dialog content element and Radix owns the attribute — the sheet's open/close animation state, not the desktop expanded state. Consumers style against it too. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarnav
  *
  * @example
  * ```tsx
  * <Sidebar.Root>
  *   <Sidebar.Nav aria-label="Main">
- *     <Sidebar.Header>…</Sidebar.Header>
+ *     <Sidebar.Header>
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <GlobeIcon />
+ *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+ *             <CaretDownIcon className="text-muted size-4 shrink-0" />
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Header>
  *     <Sidebar.Body>
  *       <Sidebar.Group>
  *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
  *         <Sidebar.List>
  *           <Sidebar.Item>
- *             <Sidebar.ItemButton asChild>
+ *             <Sidebar.ItemButton asChild current>
  *               <a href="/endpoints">
  *                 <GraphIcon />
  *                 Endpoints
@@ -248,8 +310,22 @@ type SidebarNavProps = ComponentProps<"div"> & WithDataSlot;
  *         </Sidebar.List>
  *       </Sidebar.Group>
  *     </Sidebar.Body>
- *     <Sidebar.Footer>…</Sidebar.Footer>
+ *     <Sidebar.Footer>
+ *       <Sidebar.Separator />
+ *       <DropdownMenu.Root>
+ *         <DropdownMenu.Trigger asChild>
+ *           <Sidebar.SwitcherTrigger>
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
+ *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
+ *           </Sidebar.SwitcherTrigger>
+ *         </DropdownMenu.Trigger>
+ *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+ *       </DropdownMenu.Root>
+ *     </Sidebar.Footer>
  *   </Sidebar.Nav>
+ *   <Sidebar.Trigger />
  * </Sidebar.Root>
  * ```
  */
@@ -281,12 +357,24 @@ type SidebarTriggerProps = Omit<IconButtonProps, "appearance" | "asChild" | "chi
    */
   intent?: IconButtonProps["intent"];
   /**
-   * The accessible name for the trigger. Visually hidden but announced to
-   * assistive technology. Override it for localization.
+   * The accessible name for the trigger, and what its tooltip says. Visually
+   * hidden on the button itself but announced to assistive technology.
+   * Override it for localization.
    *
    * @default "Toggle Sidebar"
    */
   label?: string;
+  /**
+   * The keyboard chord that also toggles the sidebar, rendered after the label
+   * in the tooltip — usually `<><MetaKey /><Kbd>B</Kbd></>`.
+   *
+   * Ignored under `Sidebar.Root keyboardShortcut={false}`, so the tooltip can
+   * never name a binding that is not bound. Passed rather than built in so the
+   * sidebar does not have to reach into another component for the platform
+   * modifier glyph — `aria-keyshortcuts` is stamped either way, which is also
+   * why the chips render `aria-hidden`.
+   */
+  shortcut?: ReactNode;
 };
 /**
  * The button that toggles the sidebar: the mobile sheet below the root's
@@ -296,7 +384,28 @@ type SidebarTriggerProps = Omit<IconButtonProps, "appearance" | "asChild" | "chi
  * `AppLayout.Header`) — it must stay visible at every breakpoint where the
  * sidebar can collapse, or users have no way to reopen it.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * The button is icon-only at every breakpoint, so it always renders a tooltip
+ * showing `label` (plus the optional `shortcut` chips). **That means it requires
+ * a `TooltipProvider` ancestor, like any `Tooltip.Root`, and throws without
+ * one** — mount a single provider at your app root, decoupled from the sidebar,
+ * so the app-wide delay and hover settings stay app-wide.
+ *
+ * It also stamps `aria-keyshortcuts` for the `⌘B` / `Ctrl+B` chord the root
+ * binds, resolved after hydration: the server cannot know the host, so the
+ * first paint is the non-Apple answer. Both the attribute and the chips are
+ * omitted under `Sidebar.Root keyboardShortcut={false}`.
+ *
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"expanded"` \| `"collapsed"` | Mirrors what the trigger toggles: the mobile sheet below the root's `mobileBreakpoint`, the desktop panel otherwise. Pairs with `aria-expanded`. |
+ * | `data-slot` | `"sidebar-trigger-tooltip"` | On the tooltip surface, not the button — the styling hook for the label-and-chord popup this part renders. |
+ * | `data-appearance` | `"ghost"` \| `"outlined"` | Read, not stamped: the underlying `IconButton` reflects its `appearance`, which this part defaults to `"ghost"`. |
+ * | `data-intent` | `"accent"` \| `"danger"` \| `"neutral"` | Read, not stamped: the underlying `IconButton` reflects its `intent`, which this part defaults to `"neutral"`. |
+ * | `data-size` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Read, not stamped: the underlying `IconButton` reflects its `size` and its own `"md"` default. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartrigger
  *
  * @example
  * ```tsx
@@ -334,9 +443,10 @@ type SidebarTriggerProps = Omit<IconButtonProps, "appearance" | "asChild" | "chi
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -351,19 +461,19 @@ type SidebarTriggerProps = Omit<IconButtonProps, "appearance" | "asChild" | "chi
  * Placement within an `AppLayout` shell:
  * ```tsx
  * <Sidebar.Root>
- *   <Sidebar.Nav aria-label="Main">…</Sidebar.Nav>
- *   <AppLayout.Inset>
+ *   <AppLayout.Workspace>
+ *     <Sidebar.Nav aria-label="Main">…</Sidebar.Nav>
  *     <AppLayout.Content>
  *       <AppLayout.Header>
  *         <Sidebar.Trigger />
  *       </AppLayout.Header>
- *       …
+ *       <AppLayout.Body>…</AppLayout.Body>
  *     </AppLayout.Content>
- *   </AppLayout.Inset>
+ *   </AppLayout.Workspace>
  * </Sidebar.Root>
  * ```
  */
-declare const Trigger: ({ appearance, "data-slot": dataSlot, icon, intent, label, onClick, ...props }: SidebarTriggerProps) => import("react").JSX.Element;
+declare const Trigger: ({ appearance, "data-slot": dataSlot, icon, intent, label, onClick, shortcut, ...props }: SidebarTriggerProps) => import("react").JSX.Element;
 type SidebarHeaderProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
 /**
  * The top container of a `Sidebar.Nav`, pinned above the scrollable
@@ -382,7 +492,7 @@ type SidebarHeaderProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * | --- | --- | --- |
  * | `--sidebar-header-height` | `4.5rem` | The header row height (72px). Set it on a common ancestor of the sidebar and `AppLayout.Header`, not on `Sidebar.Nav`, so both rows read one value. |
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarheader
  *
  * @example
  * ```tsx
@@ -420,9 +530,10 @@ type SidebarHeaderProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -442,7 +553,7 @@ type SidebarBodyProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * `scroll-fade-y` mask; inside the collapsed icon rail the scrollbar and its
  * reserved gutter are hidden and the fade is the only overflow signal.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarbody
  *
  * @example
  * ```tsx
@@ -480,9 +591,10 @@ type SidebarBodyProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -498,10 +610,10 @@ type SidebarFooterProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
 /**
  * The bottom container of a `Sidebar.Nav`, pinned below the scrollable
  * `Sidebar.Body`. Typically holds cross-product items and the account/user
- * switcher row (`Sidebar.SwitcherTrigger` with `Sidebar.AccountAvatar` and
- * `Sidebar.UserAvatar`).
+ * switcher row (`Sidebar.SwitcherTrigger` with an
+ * [Avatar](https://mantle.ngrok.com/components/data-display/avatar)).
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarfooter
  *
  * @example
  * ```tsx
@@ -539,9 +651,10 @@ type SidebarFooterProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -560,7 +673,7 @@ type SidebarGroupProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  * group wires it to the list via `aria-labelledby` so assistive technology
  * announces the list with the group's name.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargroup
  *
  * @example
  * ```tsx
@@ -598,9 +711,10 @@ type SidebarGroupProps = ComponentProps<"div"> & WithAsChild & WithDataSlot;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -620,7 +734,7 @@ type SidebarGroupLabelProps = ComponentProps<"div"> & WithAsChild & WithDataSlot
  * the sibling list via `aria-labelledby`. Pass `asChild` to render a heading
  * at a level you control.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargrouplabel
  *
  * @example
  * ```tsx
@@ -658,9 +772,10 @@ type SidebarGroupLabelProps = ComponentProps<"div"> & WithAsChild & WithDataSlot
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -678,7 +793,7 @@ type SidebarListProps = ComponentProps<"ul"> & WithAsChild & WithDataSlot;
  * has a `Sidebar.GroupLabel`, the list is announced with the group's name via
  * `aria-labelledby`.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarlist
  *
  * @example
  * ```tsx
@@ -716,9 +831,10 @@ type SidebarListProps = ComponentProps<"ul"> & WithAsChild & WithDataSlot;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -736,7 +852,7 @@ type SidebarItemProps = ComponentProps<"li"> & WithAsChild & WithDataSlot;
  * element is the `Sidebar.ItemButton` child, so props, `ref`, and `className`
  * all target the list item itself.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritem
  *
  * @example
  * ```tsx
@@ -774,9 +890,10 @@ type SidebarItemProps = ComponentProps<"li"> & WithAsChild & WithDataSlot;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -793,6 +910,10 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
    * Marks this row as the current page: sets `aria-current="page"` and the
    * `data-current` styling state. Consumers control it from their router,
    * e.g. `current={pathname === "/endpoints"}`.
+   *
+   * A composed child that sets `aria-current="page"` itself — react-router's
+   * `NavLink` does — already gets the current-row treatment, so it needs no
+   * `current`. This prop is for the rows whose parent knows.
    */
   current?: boolean;
 };
@@ -802,6 +923,20 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
  * compose with a router link. `current` sets `aria-current="page"` and the
  * `data-current` visual state.
  *
+ * The current-row treatment follows either attribute, so a composed child that
+ * marks itself as the current page gets it without `current` — a react-router
+ * `NavLink` needs nothing but its `to`, since it already resolved the match the
+ * parent would otherwise re-derive:
+ *
+ * ```tsx
+ * <Sidebar.ItemButton asChild>
+ *   <NavLink to="/endpoints">
+ *     <GraphIcon />
+ *     Endpoints
+ *   </NavLink>
+ * </Sidebar.ItemButton>
+ * ```
+ *
  * The row sizes its **leading** icon to 20px and leaves trailing visuals — a
  * caret, a count, a status dot — to size themselves, so a row composed with
  * `DropdownMenu.Trigger asChild` can end in `<CaretDownIcon className="text-muted
@@ -811,7 +946,15 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
  * it keeps the expanded row's width instead of shrinking to this row's 28px
  * rail chip (see `Sidebar.SwitcherTrigger` for the whole contract).
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-current` | present when `current` | Presence-only — never `"false"`, since the `data-current:` variant matches the attribute's existence. Styles the current row. |
+ * | `aria-current` | `"page"` when `current` | Set alongside `data-current`. The current-row styling follows *either*, so a composed child that marks itself (react-router's `NavLink`) gets the treatment without the prop. |
+ * | `data-state` | `"open"` | **Read, not stamped** — supplied by a composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritembutton
  *
  * @example
  * ```tsx
@@ -849,9 +992,10 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -863,53 +1007,112 @@ type SidebarItemButtonProps = ComponentProps<"button"> & WithAsChild & WithDataS
  * ```
  */
 declare const ItemButton: ({ asChild, children, className, current, "data-slot": dataSlot, type, ...props }: SidebarItemButtonProps) => import("react").JSX.Element;
-type SidebarSwitcherTriggerProps = ComponentProps<"button"> & WithAsChild & WithDataSlot;
+type SidebarSearchTriggerProps = ComponentProps<"button"> & WithDataSlot & ({
+  /**
+   * Compose the search row's styling onto your own element. Then the
+   * row's entire content is yours — including any shortcut hint, which
+   * `shortcut` cannot add to a cloned child.
+   */
+  asChild: true;
+  shortcut?: never;
+} | {
+  /**
+   * Compose the search row's styling onto your own element. Then the
+   * row's entire content is yours — including any shortcut hint, which
+   * `shortcut` cannot add to a cloned child.
+   */
+  asChild?: false;
+  /**
+   * The keyboard hint for the chord that opens the same palette — usually
+   * `<><MetaKey /><Kbd>K</Kbd></>`.
+   *
+   * Rendered pinned to the end of the row and **revealed only on hover or
+   * keyboard focus**, so the row reads as a quiet navigation item at rest
+   * and teaches the chord at the moment a user reaches for it. It is
+   * `aria-hidden` and dropped outright in the collapsed rail: the chord is
+   * announced by the `aria-keyshortcuts` that `Command.SearchTrigger`
+   * adds, so repeating it here would announce it twice.
+   *
+   * Passed rather than built in, so the sidebar does not have to know
+   * which chord your palette binds.
+   */
+  shortcut?: ReactNode;
+});
 /**
- * The styled row for the sidebar's switchers: the app/product switcher in
- * `Sidebar.Header` and the account/user row in `Sidebar.Footer`. A styled
- * button only — it is not wired to any state; compose it with
- * `DropdownMenu.Trigger asChild` or `Dialog.Trigger asChild`, which supply
- * the open state (`data-state="open"` styling comes for free from those
- * primitives).
+ * The search row — the row that opens a search or command palette.
  *
- * Inside the collapsed icon rail, the row collapses to
- * its **first child element** — the leading visual (product icon, account
- * avatar) — and the remaining children become visually hidden while staying
- * in the accessibility tree, so the button's accessible name is unchanged.
- * Wrap loose text in an element (e.g. a `<span>`) so it participates.
+ * Put it at the top of `Sidebar.Body`, above the first `Sidebar.Group`: it
+ * needs no height change, and it lands in the same `px-3` gutter as the
+ * navigation rows, so it shares their column in both panel states.
  *
- * A menu opened from the row should be as wide as the row: `width="trigger"`
- * does that while the panel is expanded, but the row shrinks to a 36px chip in
- * the icon rail and would drag the menu down to it. Floor the menu at the
- * expanded row width with `className="min-w-(--sidebar-row-width)"` — the
- * token `mantle.css` declares at `:root` for exactly this, since the menu
- * renders in a portal and inherits nothing from the panel. The floor is a
- * no-op while the panel is expanded (the row already measures that wide), and
- * inert in the mobile sheet as long as its row is the wider of the two
- * (`--sidebar-width-mobile` minus `1.5rem` and the sheet's 1px border, vs
- * `--sidebar-width` minus `1rem`; 263px vs 240px at the defaults) — so widen
- * `--sidebar-width-mobile` whenever you widen `--sidebar-width`, or the floor
- * overhangs the sheet.
+ * `Sidebar.Header`, under the switcher, also works — the header's own `gap-2`
+ * sets the spacing — at the cost of a taller header. That height is a fixed one
+ * row so it can align with an `AppLayout.Header` toolbar, so a stack of two
+ * needs `--sidebar-header-height` raised on a **common ancestor of both rows**
+ * (`<AppLayout.Root className="[--sidebar-header-height:6rem]">`). Setting it on
+ * `Sidebar.Nav` only looks right: custom properties inherit downward, so
+ * `AppLayout.Header` would keep the `4.5rem` default and the two rows would stop
+ * being center-aligned.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * It is deliberately a navigation row and not a text field. The row is the same
+ * chrome as a `Sidebar.ItemButton` — same height, padding, radius, hover, and
+ * the same 28px chip in the collapsed icon rail — because a search entry point
+ * in a sidebar is one of the rows, not a form control wedged among them. The
+ * `shortcut` hint appears on hover or focus and is otherwise invisible, which
+ * keeps the resting panel quiet.
+ *
+ * A styled button only — it is not wired to any state. Compose it with
+ * [`Command.SearchTrigger`](https://mantle.ngrok.com/components/navigation/command#commandsearchtrigger),
+ * which supplies the dialog wiring, `aria-keyshortcuts`, and the behavior that
+ * makes typing or pasting into the row open the palette with that text already
+ * in the query. Wrap the pair in `Sidebar.Tooltip` so the row keeps a visible
+ * label once the panel collapses.
+ *
+ * Like every row, the rail clips everything after the leading icon rather than
+ * removing it, so the button keeps its accessible name as a chip.
+ *
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"open"` \| `"closed"` | **Read, not stamped** — supplied by the composing `Command.SearchTrigger` / `Dialog.Trigger`. The row stays highlighted while its palette is open. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarsearchtrigger
  *
  * @example
  * ```tsx
  * <Sidebar.Root>
  *   <Sidebar.Nav aria-label="Main">
  *     <Sidebar.Header>
- *       <DropdownMenu.Root>
- *         <DropdownMenu.Trigger asChild>
- *           <Sidebar.SwitcherTrigger>
- *             <GlobeIcon />
- *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
- *             <CaretDownIcon className="text-muted size-4 shrink-0" />
- *           </Sidebar.SwitcherTrigger>
- *         </DropdownMenu.Trigger>
- *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
- *       </DropdownMenu.Root>
+ *       <Sidebar.SwitcherTrigger>
+ *         <GlobeIcon />
+ *         <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+ *       </Sidebar.SwitcherTrigger>
  *     </Sidebar.Header>
  *     <Sidebar.Body>
+ *       <Command.DialogRoot>
+ *         <Sidebar.Tooltip label="Search">
+ *           <Command.SearchTrigger>
+ *             <Sidebar.SearchTrigger
+ *               shortcut={
+ *                 <>
+ *                   <MetaKey />
+ *                   <Kbd>K</Kbd>
+ *                 </>
+ *               }
+ *             >
+ *               <MagnifyingGlassIcon />
+ *               <span className="min-w-0 flex-1 truncate">Search</span>
+ *             </Sidebar.SearchTrigger>
+ *           </Command.SearchTrigger>
+ *         </Sidebar.Tooltip>
+ *         <Command.DialogContent>
+ *           <Command.Input placeholder="Search endpoints, agents, and settings..." />
+ *           <Command.List>
+ *             <Command.Empty>No results found.</Command.Empty>
+ *           </Command.List>
+ *         </Command.DialogContent>
+ *       </Command.DialogRoot>
  *       <Sidebar.Group>
  *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
  *         <Sidebar.List>
@@ -924,35 +1127,47 @@ type SidebarSwitcherTriggerProps = ComponentProps<"button"> & WithAsChild & With
  *         </Sidebar.List>
  *       </Sidebar.Group>
  *     </Sidebar.Body>
- *     <Sidebar.Footer>
- *       <Sidebar.Separator />
- *       <DropdownMenu.Root>
- *         <DropdownMenu.Trigger asChild>
- *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
- *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
- *           </Sidebar.SwitcherTrigger>
- *         </DropdownMenu.Trigger>
- *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
- *       </DropdownMenu.Root>
- *     </Sidebar.Footer>
  *   </Sidebar.Nav>
  *   <Sidebar.Trigger />
  * </Sidebar.Root>
  * ```
  */
-declare const SwitcherTrigger: ({ asChild, children, className, "data-slot": dataSlot, type, ...props }: SidebarSwitcherTriggerProps) => import("react").JSX.Element;
-type SidebarSeparatorProps = ComponentProps<typeof Separator>;
+declare const SearchTrigger: ({ asChild, children, className, "data-slot": dataSlot, shortcut, type, ...props }: SidebarSearchTriggerProps) => import("react").JSX.Element;
+type SidebarSwitcherTriggerProps = ComponentProps<"button"> & WithAsChild & WithDataSlot;
 /**
- * An inset hairline between sidebar regions. Composes the mantle `Separator`,
- * staying aligned with the `px-3` content padding of `Sidebar.Body` and
- * `Sidebar.Footer` (it deliberately does not run edge to edge) with `my-3`
- * breathing room above and below. When collapsed to the icon rail, it widens
- * to the same 36px chip width as `Sidebar.SwitcherTrigger`, balancing the
- * adjacent app-content gutter that sits outside the rail.
+ * The styled row for the sidebar's switchers: the app/product switcher in
+ * `Sidebar.Header` and the account/user row in `Sidebar.Footer`. A styled
+ * button only — it is not wired to any state; compose it with
+ * `DropdownMenu.Trigger asChild` or `Dialog.Trigger asChild`, which supply
+ * the open state (`data-state="open"` styling comes for free from those
+ * primitives).
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * Inside the collapsed icon rail, the row collapses to
+ * its **first child element** — the leading visual (product icon, account
+ * avatar) — and the remaining children become visually hidden while staying
+ * in the accessibility tree, so the button's accessible name is unchanged.
+ * Wrap loose text in an element (e.g. a `<span>`) so it participates.
+ *
+ * A menu opened from the row should be as wide as the row: `width="trigger"`
+ * does that while the panel is expanded, but the row shrinks to a 36px chip in
+ * the icon rail and would drag the menu down to it. Floor the menu at the
+ * expanded row width with `className="min-w-(--sidebar-row-width)"` — the
+ * token `mantle.css` declares at `:root` for exactly this, since the menu
+ * renders in a portal and inherits nothing from the panel. The floor is a
+ * no-op while the panel is expanded (the row already measures that wide), and
+ * inert in the mobile sheet as long as its row is the wider of the two
+ * (`--sidebar-width-mobile` minus `1.5rem` and the sheet's 1px border, vs
+ * `--sidebar-width` minus `1rem`; 263px vs 240px at the defaults) — so widen
+ * `--sidebar-width-mobile` whenever you widen `--sidebar-width`, or the floor
+ * overhangs the sheet.
+ *
+ * **Data attributes:**
+ *
+ * | Data Attribute | Value | Description |
+ * | --- | --- | --- |
+ * | `data-state` | `"open"` | **Read, not stamped** — supplied by the composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarswitchertrigger
  *
  * @example
  * ```tsx
@@ -990,9 +1205,10 @@ type SidebarSeparatorProps = ComponentProps<typeof Separator>;
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1003,105 +1219,138 @@ type SidebarSeparatorProps = ComponentProps<typeof Separator>;
  * </Sidebar.Root>
  * ```
  */
-declare const SidebarSeparator: ({ className, ...props }: SidebarSeparatorProps) => import("react").JSX.Element;
-type SidebarAccountAvatarProps = Omit<ComponentProps<"div">, "children"> & {
+declare const SwitcherTrigger: ({ asChild, children, className, "data-slot": dataSlot, type, ...props }: SidebarSwitcherTriggerProps) => import("react").JSX.Element;
+/**
+ * The props for `Sidebar.Tooltip`. `Tooltip.Content`'s props — so `className`,
+ * `style`, `ref`, `asChild`, and any `data-*` reach the tooltip surface — except
+ * the parts this row owns: `children` is the row being labeled (not the tooltip
+ * body, which is `label`), and `side` becomes optional with a sidebar default.
+ */
+type SidebarTooltipProps = Omit<ComponentProps<typeof Tooltip.Content>, "children" | "side"> & WithDataSlot & {
+  /**
+   * The row this labels — a `Sidebar.ItemButton` or `Sidebar.SwitcherTrigger`,
+   * optionally already wrapped in a `DropdownMenu.Trigger asChild`.
+   *
+   * A single element, required: `Tooltip.Trigger asChild` clones its child, so
+   * text renders nothing a pointer can hover and no children renders no row at
+   * all — both silently.
+   */
+  children: ReactElement;
+  /**
+   * What the tooltip says. Normally the row's own label text: the rail clips the
+   * visible one, so this is what a sighted pointer user reads.
+   */
+  label: ReactNode;
   /**
-   * The account's stable identifier. Used to deterministically select a
-   * background swatch from the design system's palette so the same account
-   * always gets the same color.
+   * The keyboard chord that reaches the same row, rendered after the label —
+   * usually `<><MetaKey /><Kbd>K</Kbd></>`. The rail hides the row's own
+   * shortcut hint along with its label, so the tooltip is where a pointer user
+   * can still learn the chord. The chips are `aria-hidden`: a tooltip is wired
+   * as its row's `aria-describedby`, and the chord is already announced by the
+   * row's `aria-keyshortcuts`.
+   *
+   * Passed rather than built in, so the sidebar does not have to know which
+   * chord the row's palette or action binds.
    */
-  accountId: string | undefined;
+  shortcut?: ReactNode;
   /**
-   * The account's display name. The first one or two letters become the
-   * avatar's initials. Falls back to `?` when the name is empty.
+   * Which side of the row the tooltip opens on. The rail sits at the inline
+   * start of the viewport, so the default points the tooltip away from it.
+   *
+   * @default "right"
    */
-  accountName: string | undefined;
+  side?: ComponentProps<typeof Tooltip.Content>["side"];
 };
 /**
- * A small rounded-square avatar that represents an account (workspace,
- * organization, etc.). The background color is derived deterministically from
- * the `accountId` so an account's swatch is stable across renders, sessions,
- * and devices.
+ * Labels a sidebar row while — and only while — the desktop panel is collapsed
+ * to the icon rail. Wrap it around a `Sidebar.ItemButton` or
+ * `Sidebar.SwitcherTrigger`.
  *
- * Accounts are rendered as squares to differentiate them visually from users,
- * which use a circular `Sidebar.UserAvatar`.
+ * The collapsed rail keeps every row's label in the accessibility tree (clipped,
+ * not removed), which serves screen-reader users but leaves a sighted pointer
+ * user with an unlabeled icon column. This restores the label for them without
+ * duplicating it for anyone else: expanded rows already read their own text, and
+ * the mobile sheet shows full labels, so the collapsed desktop rail is the only
+ * state that shows a label at all.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * It opens the way any tooltip does — the pointer entering the row, or focus
+ * reaching it — and the rail state vetoes it: the expanded panel and the mobile
+ * sheet keep the row at `data-state="closed"` with no `aria-describedby`, and
+ * toggling the rail dismisses whatever was showing, so collapsing the panel
+ * cannot pop a label under a pointer that has already moved on.
+ *
+ * **Requires a `TooltipProvider` ancestor**, like any `Tooltip.Root` — mount one
+ * at your app root. This part deliberately does not mount its own, so the
+ * app-wide tooltip delay stays app-wide rather than being overridden per row.
+ * The one provider setting it does override is hoverable content: a rail label
+ * holds nothing to hover into, so the pointer leaving the row closes it.
+ *
+ * It composes with a menu trigger: nest `DropdownMenu.Root >
+ * Sidebar.Tooltip > DropdownMenu.Trigger asChild > Sidebar.ItemButton` for a
+ * row that opens a menu *and* labels itself in the rail. `DropdownMenu.Root` must
+ * stay **outside** the tooltip — it is renderless, and `Tooltip.Trigger asChild`
+ * needs a real element to clone.
+ *
+ * `children` is the row; `label` is what the tooltip says. Every other prop is
+ * `Tooltip.Content`'s and lands on the tooltip surface — `className`, `style`,
+ * `ref`, `data-*`, positioning props such as `align` and `sideOffset`, and
+ * `asChild`, which Radix's `Tooltip.Content` implements itself. `side` defaults
+ * to `"right"` so the tooltip opens away from the rail.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartooltip
  *
  * @example
  * ```tsx
- * <Sidebar.Root>
- *   <Sidebar.Nav aria-label="Main">
- *     <Sidebar.Header>
- *       <DropdownMenu.Root>
- *         <DropdownMenu.Trigger asChild>
- *           <Sidebar.SwitcherTrigger>
- *             <GlobeIcon />
- *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
- *             <CaretDownIcon className="text-muted size-4 shrink-0" />
- *           </Sidebar.SwitcherTrigger>
- *         </DropdownMenu.Trigger>
- *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
- *       </DropdownMenu.Root>
- *     </Sidebar.Header>
- *     <Sidebar.Body>
- *       <Sidebar.Group>
- *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
- *         <Sidebar.List>
- *           <Sidebar.Item>
- *             <Sidebar.ItemButton asChild current>
- *               <a href="/endpoints">
- *                 <GraphIcon />
- *                 Endpoints
- *               </a>
- *             </Sidebar.ItemButton>
- *           </Sidebar.Item>
- *         </Sidebar.List>
- *       </Sidebar.Group>
- *     </Sidebar.Body>
- *     <Sidebar.Footer>
- *       <Sidebar.Separator />
- *       <DropdownMenu.Root>
- *         <DropdownMenu.Trigger asChild>
- *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
- *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
- *           </Sidebar.SwitcherTrigger>
- *         </DropdownMenu.Trigger>
- *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
- *       </DropdownMenu.Root>
- *     </Sidebar.Footer>
- *   </Sidebar.Nav>
- *   <Sidebar.Trigger />
- * </Sidebar.Root>
+ * <TooltipProvider>
+ *   <Sidebar.Root>
+ *     <Sidebar.Nav aria-label="Main">
+ *       <Sidebar.Body>
+ *         <Sidebar.Group>
+ *           <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
+ *           <Sidebar.List>
+ *             <Sidebar.Item>
+ *               <Sidebar.Tooltip label="Endpoints">
+ *                 <Sidebar.ItemButton asChild current>
+ *                   <a href="/endpoints">
+ *                     <GraphIcon />
+ *                     Endpoints
+ *                   </a>
+ *                 </Sidebar.ItemButton>
+ *               </Sidebar.Tooltip>
+ *             </Sidebar.Item>
+ *           </Sidebar.List>
+ *         </Sidebar.Group>
+ *       </Sidebar.Body>
+ *       <Sidebar.Footer>
+ *         <DropdownMenu.Root>
+ *           <Sidebar.Tooltip label="Help">
+ *             <DropdownMenu.Trigger asChild>
+ *               <Sidebar.ItemButton>
+ *                 <QuestionIcon />
+ *                 Help
+ *               </Sidebar.ItemButton>
+ *             </DropdownMenu.Trigger>
+ *           </Sidebar.Tooltip>
+ *           <DropdownMenu.Content>…</DropdownMenu.Content>
+ *         </DropdownMenu.Root>
+ *       </Sidebar.Footer>
+ *     </Sidebar.Nav>
+ *     <Sidebar.Trigger />
+ *   </Sidebar.Root>
+ * </TooltipProvider>
  * ```
  */
-declare const AccountAvatar: ({ accountId, accountName, className, ...props }: SidebarAccountAvatarProps) => import("react").JSX.Element;
-type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & {
-  /**
-   * Optional URL of the user's profile picture. When provided, the image is
-   * rendered to fill the avatar with `object-cover`. When omitted (or while
-   * loading), a neutral person silhouette is shown.
-   */
-  src?: string;
-  /**
-   * Accessible label for the avatar. Used as the image's `alt` text and as
-   * the container's `aria-label` when no image is rendered.
-   *
-   * @default "Your account"
-   */
-  alt?: string;
-};
+declare const SidebarTooltip: ({ children, "data-slot": dataSlot, label, shortcut, side, ...props }: SidebarTooltipProps) => import("react").JSX.Element;
+type SidebarSeparatorProps = ComponentProps<typeof Separator> & WithDataSlot;
 /**
- * A circular avatar that represents the currently signed-in user. Renders the
- * user's profile picture when `src` is provided, otherwise falls back to a
- * neutral, theme-aware person silhouette.
- *
- * Users are rendered as circles to differentiate them visually from accounts,
- * which use a square `Sidebar.AccountAvatar`.
+ * An inset hairline between sidebar regions. Composes the mantle `Separator`,
+ * staying aligned with the `px-3` content padding of `Sidebar.Body` and
+ * `Sidebar.Footer` (it deliberately does not run edge to edge) with `my-3`
+ * breathing room above and below. When collapsed to the icon rail, it widens
+ * to the same 36px chip width as `Sidebar.SwitcherTrigger`, balancing the
+ * adjacent app-content gutter that sits outside the rail.
  *
- * @see https://mantle.ngrok.com/components/navigation/sidebar
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarseparator
  *
  * @example
  * ```tsx
@@ -1139,9 +1388,10 @@ type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & {
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1152,7 +1402,7 @@ type SidebarUserAvatarProps = Omit<ComponentProps<"div">, "children"> & {
  * </Sidebar.Root>
  * ```
  */
-declare const UserAvatar: ({ alt, className, src, ...props }: SidebarUserAvatarProps) => import("react").JSX.Element;
+declare const SidebarSeparator: ({ className, "data-slot": dataSlot, ...props }: SidebarSeparatorProps) => import("react").JSX.Element;
 /**
  * A composable, collapsible app-navigation sidebar. `Sidebar.Root` owns the
  * state (no DOM); `Sidebar.Nav` renders the panel — inline on desktop,
@@ -1176,16 +1426,17 @@ declare const UserAvatar: ({ alt, className, src, ...props }: SidebarUserAvatarP
  * │   ├── Sidebar.Header
  * │   │   └── Sidebar.SwitcherTrigger
  * │   ├── Sidebar.Body
+ * │   │   ├── Sidebar.SearchTrigger
  * │   │   └── Sidebar.Group
  * │   │       ├── Sidebar.GroupLabel
  * │   │       └── Sidebar.List
  * │   │           └── Sidebar.Item
- * │   │               └── Sidebar.ItemButton
+ * │   │               └── Sidebar.Tooltip
+ * │   │                   └── Sidebar.ItemButton
  * │   └── Sidebar.Footer
+ * │       ├── Sidebar.ItemButton
  * │       ├── Sidebar.Separator
  * │       └── Sidebar.SwitcherTrigger
- * │           ├── Sidebar.AccountAvatar
- * │           └── Sidebar.UserAvatar
  * └── Sidebar.Trigger
  * ```
  *
@@ -1225,9 +1476,10 @@ declare const UserAvatar: ({ alt, className, src, ...props }: SidebarUserAvatarP
  *       <DropdownMenu.Root>
  *         <DropdownMenu.Trigger asChild>
  *           <Sidebar.SwitcherTrigger>
- *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+ *             <Avatar.Root appearance="square" colorSeed="acc_123">
+ *               <Avatar.Fallback name="Acme Corp" />
+ *             </Avatar.Root>
  *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
- *             <Sidebar.UserAvatar alt="Jane Doe" />
  *           </Sidebar.SwitcherTrigger>
  *         </DropdownMenu.Trigger>
  *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1240,11 +1492,11 @@ declare const UserAvatar: ({ alt, className, src, ...props }: SidebarUserAvatarP
  */
 declare const Sidebar: {
   /**
-   * The state owner for a sidebar. Renders no DOM — provides expanded /
+   * The state owner for a sidebar. Renders no DOM — carries expanded /
    * mobile-sheet state to every part below it so the trigger can live in the
    * app shell without coupling it to the sidebar.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarroot
    *
    * @example
    * ```tsx
@@ -1282,9 +1534,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1302,7 +1555,16 @@ declare const Sidebar: {
    * `--sidebar-width` / `--sidebar-width-mobile` via its `className` or
    * `style`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"expanded"` \| `"collapsed"` | On the desktop panel surface. Mirrors the root's expanded state and drives the width collapse to the icon rail; descendant parts style off it with `group-data-[state=collapsed]/sidebar-nav:`. |
+   * | `data-hydrated` | present after hydration | Presence-only, desktop panel surface. The CSS-side twin of the `isHydrated` gate: descendant collapse transitions are enabled only under `group-data-hydrated/sidebar-nav:`, so an SSR state correction snaps instead of animating on page load. |
+   * | `data-mobile` | present in the mobile sheet | Presence-only. Marks the `Sheet.Content` presentation used below the root's `mobileBreakpoint`. |
+   * | `data-state` | `"open"` \| `"closed"` | In the mobile sheet only, where the panel *is* the `Sheet`'s Radix dialog content element and Radix owns the attribute — the sheet's open/close animation state, not the desktop expanded state. Consumers style against it too. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarnav
    *
    * @example
    * ```tsx
@@ -1340,9 +1602,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1358,7 +1621,16 @@ declare const Sidebar: {
    * The `IconButton` that toggles the sidebar. Place it in the app shell's
    * header; it stays functional at every breakpoint.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"expanded"` \| `"collapsed"` | Mirrors what the trigger toggles: the mobile sheet below the root's `mobileBreakpoint`, the desktop panel otherwise. Pairs with `aria-expanded`. |
+   * | `data-appearance` | `"ghost"` \| `"outlined"` | Read, not stamped: the underlying `IconButton` reflects its `appearance`, which this part defaults to `"ghost"`. |
+   * | `data-intent` | `"accent"` \| `"danger"` \| `"neutral"` | Read, not stamped: the underlying `IconButton` reflects its `intent`, which this part defaults to `"neutral"`. |
+   * | `data-size` | `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | Read, not stamped: the underlying `IconButton` reflects its `size` and its own `"md"` default. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartrigger
    *
    * @example
    * ```tsx
@@ -1396,9 +1668,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1415,7 +1688,7 @@ declare const Sidebar: {
    * switcher (`Sidebar.SwitcherTrigger` + `DropdownMenu`/`Dialog`). Its
    * height vertically aligns the switcher with an `AppLayout.Header`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarheader
    *
    * @example
    * ```tsx
@@ -1453,9 +1726,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1470,7 +1744,7 @@ declare const Sidebar: {
   /**
    * The scrollable middle region holding the navigation groups.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarbody
    *
    * @example
    * ```tsx
@@ -1508,9 +1782,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1526,7 +1801,7 @@ declare const Sidebar: {
    * The pinned bottom container, typically holding cross-product items and
    * the account/user switcher row.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarfooter
    *
    * @example
    * ```tsx
@@ -1564,9 +1839,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1582,7 +1858,7 @@ declare const Sidebar: {
    * A grouping container pairing a `GroupLabel` with a `List`; wires the
    * label to the list via `aria-labelledby`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargroup
    *
    * @example
    * ```tsx
@@ -1620,9 +1896,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1638,7 +1915,7 @@ declare const Sidebar: {
    * The muted label of a group. Renders a `<div>`; pass `asChild` to render
    * a heading at a level you control.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebargrouplabel
    *
    * @example
    * ```tsx
@@ -1676,9 +1953,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1693,7 +1971,7 @@ declare const Sidebar: {
   /**
    * The `<ul>` of navigation rows in a group.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarlist
    *
    * @example
    * ```tsx
@@ -1731,9 +2009,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1748,7 +2027,7 @@ declare const Sidebar: {
   /**
    * A single `<li>` row wrapper.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritem
    *
    * @example
    * ```tsx
@@ -1786,9 +2065,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1804,7 +2084,15 @@ declare const Sidebar: {
    * The interactive navigation row (icon + truncating label). `asChild` for
    * router links; `current` for the active page.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-current` | present when `current` | Presence-only — never `"false"`, since the `data-current:` variant matches the attribute's existence. Styles the current row. |
+   * | `aria-current` | `"page"` when `current` | Set alongside `data-current`. The current-row styling follows *either*, so a composed child that marks itself (react-router's `NavLink`) gets the treatment without the prop. |
+   * | `data-state` | `"open"` | **Read, not stamped** — supplied by a composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebaritembutton
    *
    * @example
    * ```tsx
@@ -1842,9 +2130,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1857,28 +2146,53 @@ declare const Sidebar: {
    */
   readonly ItemButton: typeof ItemButton;
   /**
-   * The styled switcher row for the header/footer. Not state-wired — compose
-   * with `DropdownMenu.Trigger asChild` or `Dialog.Trigger asChild`.
+   * The search row for `Sidebar.Body`: an item-shaped row whose `shortcut` hint
+   * appears on hover or focus, and the same chip as any other row in the
+   * collapsed icon rail. Not state-wired — compose with
+   * `Command.SearchTrigger`.
+   *
+   * **Data attributes:**
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"open"` \| `"closed"` | **Read, not stamped** — supplied by the composing `Command.SearchTrigger` / `Dialog.Trigger`. Style the row while its palette is open with `data-state-open:`. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarsearchtrigger
    *
    * @example
    * ```tsx
    * <Sidebar.Root>
    *   <Sidebar.Nav aria-label="Main">
    *     <Sidebar.Header>
-   *       <DropdownMenu.Root>
-   *         <DropdownMenu.Trigger asChild>
-   *           <Sidebar.SwitcherTrigger>
-   *             <GlobeIcon />
-   *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
-   *             <CaretDownIcon className="text-muted size-4 shrink-0" />
-   *           </Sidebar.SwitcherTrigger>
-   *         </DropdownMenu.Trigger>
-   *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
-   *       </DropdownMenu.Root>
+   *       <Sidebar.SwitcherTrigger>
+   *         <GlobeIcon />
+   *         <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+   *       </Sidebar.SwitcherTrigger>
    *     </Sidebar.Header>
    *     <Sidebar.Body>
+   *       <Command.DialogRoot>
+   *         <Sidebar.Tooltip label="Search">
+   *           <Command.SearchTrigger>
+   *             <Sidebar.SearchTrigger
+   *               shortcut={
+   *                 <>
+   *                   <MetaKey />
+   *                   <Kbd>K</Kbd>
+   *                 </>
+   *               }
+   *             >
+   *               <MagnifyingGlassIcon />
+   *               <span className="min-w-0 flex-1 truncate">Search</span>
+   *             </Sidebar.SearchTrigger>
+   *           </Command.SearchTrigger>
+   *         </Sidebar.Tooltip>
+   *         <Command.DialogContent>
+   *           <Command.Input placeholder="Search endpoints, agents, and settings..." />
+   *           <Command.List>
+   *             <Command.Empty>No results found.</Command.Empty>
+   *           </Command.List>
+   *         </Command.DialogContent>
+   *       </Command.DialogRoot>
    *       <Sidebar.Group>
    *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
    *         <Sidebar.List>
@@ -1893,30 +2207,23 @@ declare const Sidebar: {
    *         </Sidebar.List>
    *       </Sidebar.Group>
    *     </Sidebar.Body>
-   *     <Sidebar.Footer>
-   *       <Sidebar.Separator />
-   *       <DropdownMenu.Root>
-   *         <DropdownMenu.Trigger asChild>
-   *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
-   *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
-   *           </Sidebar.SwitcherTrigger>
-   *         </DropdownMenu.Trigger>
-   *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
-   *       </DropdownMenu.Root>
-   *     </Sidebar.Footer>
    *   </Sidebar.Nav>
    *   <Sidebar.Trigger />
    * </Sidebar.Root>
    * ```
    */
-  readonly SwitcherTrigger: typeof SwitcherTrigger;
+  readonly SearchTrigger: typeof SearchTrigger;
   /**
-   * An inset hairline between sidebar regions, aligned with the content
-   * padding.
+   * The styled switcher row for the header/footer. Not state-wired — compose
+   * with `DropdownMenu.Trigger asChild` or `Dialog.Trigger asChild`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * **Data attributes:**
+   *
+   * | Data Attribute | Value | Description |
+   * | --- | --- | --- |
+   * | `data-state` | `"open"` | **Read, not stamped** — supplied by the composing `DropdownMenu.Trigger` / `Dialog.Trigger`. The row styles against it so it stays highlighted while its menu is open. |
+   *
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarswitchertrigger
    *
    * @example
    * ```tsx
@@ -1954,9 +2261,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -1967,67 +2275,77 @@ declare const Sidebar: {
    * </Sidebar.Root>
    * ```
    */
-  readonly Separator: typeof SidebarSeparator;
+  readonly SwitcherTrigger: typeof SwitcherTrigger;
   /**
-   * A rounded-square account avatar with deterministic, WCAG-compliant
-   * swatch colors derived from the account id.
+   * Labels a row while the panel is collapsed to the icon rail — wrap it
+   * around a `Sidebar.ItemButton` or `Sidebar.SwitcherTrigger`. Requires a
+   * `TooltipProvider` ancestor. Takes `Tooltip.Content`'s props (including
+   * `asChild`) on the tooltip surface; `side` defaults to `"right"`.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebartooltip
    *
    * @example
    * ```tsx
-   * <Sidebar.Root>
-   *   <Sidebar.Nav aria-label="Main">
-   *     <Sidebar.Header>
-   *       <DropdownMenu.Root>
-   *         <DropdownMenu.Trigger asChild>
-   *           <Sidebar.SwitcherTrigger>
-   *             <GlobeIcon />
-   *             <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
-   *             <CaretDownIcon className="text-muted size-4 shrink-0" />
-   *           </Sidebar.SwitcherTrigger>
-   *         </DropdownMenu.Trigger>
-   *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
-   *       </DropdownMenu.Root>
-   *     </Sidebar.Header>
-   *     <Sidebar.Body>
-   *       <Sidebar.Group>
-   *         <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
-   *         <Sidebar.List>
-   *           <Sidebar.Item>
-   *             <Sidebar.ItemButton asChild current>
-   *               <a href="/endpoints">
-   *                 <GraphIcon />
-   *                 Endpoints
-   *               </a>
-   *             </Sidebar.ItemButton>
-   *           </Sidebar.Item>
-   *         </Sidebar.List>
-   *       </Sidebar.Group>
-   *     </Sidebar.Body>
-   *     <Sidebar.Footer>
-   *       <Sidebar.Separator />
-   *       <DropdownMenu.Root>
-   *         <DropdownMenu.Trigger asChild>
-   *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
-   *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
-   *           </Sidebar.SwitcherTrigger>
-   *         </DropdownMenu.Trigger>
-   *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
-   *       </DropdownMenu.Root>
-   *     </Sidebar.Footer>
-   *   </Sidebar.Nav>
-   *   <Sidebar.Trigger />
-   * </Sidebar.Root>
+   * <TooltipProvider>
+   *   <Sidebar.Root>
+   *     <Sidebar.Nav aria-label="Main">
+   *       <Sidebar.Header>
+   *         <DropdownMenu.Root>
+   *           <DropdownMenu.Trigger asChild>
+   *             <Sidebar.SwitcherTrigger>
+   *               <GlobeIcon />
+   *               <span className="text-strong min-w-0 flex-1 truncate text-base">Universal Gateway</span>
+   *               <CaretDownIcon className="text-muted size-4 shrink-0" />
+   *             </Sidebar.SwitcherTrigger>
+   *           </DropdownMenu.Trigger>
+   *           <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+   *         </DropdownMenu.Root>
+   *       </Sidebar.Header>
+   *       <Sidebar.Body>
+   *         <Sidebar.Group>
+   *           <Sidebar.GroupLabel>Traffic</Sidebar.GroupLabel>
+   *           <Sidebar.List>
+   *             <Sidebar.Item>
+   *               <Sidebar.Tooltip label="Endpoints">
+   *                 <Sidebar.ItemButton asChild current>
+   *                   <a href="/endpoints">
+   *                     <GraphIcon />
+   *                     Endpoints
+   *                   </a>
+   *                 </Sidebar.ItemButton>
+   *               </Sidebar.Tooltip>
+   *             </Sidebar.Item>
+   *           </Sidebar.List>
+   *         </Sidebar.Group>
+   *       </Sidebar.Body>
+   *       <Sidebar.Footer>
+   *         <Sidebar.Separator />
+   *         <DropdownMenu.Root>
+   *           <Sidebar.Tooltip label="Acme Corp">
+   *             <DropdownMenu.Trigger asChild>
+   *               <Sidebar.SwitcherTrigger>
+   *                 <Avatar.Root appearance="square" colorSeed="acc_123">
+   *                   <Avatar.Fallback name="Acme Corp" />
+   *                 </Avatar.Root>
+   *                 <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
+   *               </Sidebar.SwitcherTrigger>
+   *             </DropdownMenu.Trigger>
+   *           </Sidebar.Tooltip>
+   *           <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
+   *         </DropdownMenu.Root>
+   *       </Sidebar.Footer>
+   *     </Sidebar.Nav>
+   *     <Sidebar.Trigger />
+   *   </Sidebar.Root>
+   * </TooltipProvider>
    * ```
    */
-  readonly AccountAvatar: typeof AccountAvatar;
+  readonly Tooltip: typeof SidebarTooltip;
   /**
-   * A circular user avatar with a silhouette fallback.
+   * An inset hairline between sidebar regions, aligned with the content
+   * padding.
    *
-   * @see https://mantle.ngrok.com/components/navigation/sidebar
+   * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebarseparator
    *
    * @example
    * ```tsx
@@ -2065,9 +2383,10 @@ declare const Sidebar: {
    *       <DropdownMenu.Root>
    *         <DropdownMenu.Trigger asChild>
    *           <Sidebar.SwitcherTrigger>
-   *             <Sidebar.AccountAvatar accountId="acc_123" accountName="Acme Corp" />
+   *             <Avatar.Root appearance="square" colorSeed="acc_123">
+   *               <Avatar.Fallback name="Acme Corp" />
+   *             </Avatar.Root>
    *             <span className="text-strong min-w-0 flex-1 truncate text-sm font-medium">Acme Corp</span>
-   *             <Sidebar.UserAvatar alt="Jane Doe" />
    *           </Sidebar.SwitcherTrigger>
    *         </DropdownMenu.Trigger>
    *         <DropdownMenu.Content width="trigger" className="min-w-(--sidebar-row-width)">…</DropdownMenu.Content>
@@ -2078,7 +2397,143 @@ declare const Sidebar: {
    * </Sidebar.Root>
    * ```
    */
-  readonly UserAvatar: typeof UserAvatar;
+  readonly Separator: typeof SidebarSeparator;
+};
+//#endregion
+//#region src/components/sidebar/sidebar-state-cookie.d.ts
+/**
+ * The cookie name {@link extractSidebarStateCookie} reads and
+ * {@link serializeSidebarStateCookie} writes.
+ *
+ * Exported so an app can clear the cookie on sign-out, or read it with its own
+ * cookie library, without hard-coding the name.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#sidebar_state_cookie_name
+ *
+ * @example
+ * ```ts
+ * // clear the persisted rail state on sign-out
+ * headers.append("Set-Cookie", `${SIDEBAR_STATE_COOKIE_NAME}=; Max-Age=0; Path=/`);
+ * ```
+ */
+declare const SIDEBAR_STATE_COOKIE_NAME = "mantle-sidebar-state";
+/**
+ * Parse the sidebar's expanded state out of a raw `Cookie` header.
+ *
+ * This is the server half of cookie-backed persistence: unlike storage-backed
+ * persistence, a cookie is available *before* the server renders, so the
+ * server-rendered HTML already carries the right `data-state` and there is no
+ * first-frame correction to hide. Pass the result straight to `defaultOpen` —
+ * controlled `open` is not required.
+ *
+ * Returns `undefined` — not `false` — when the cookie is absent or holds a
+ * value this helper does not recognize, so a first-time visitor is
+ * distinguishable from one who deliberately collapsed the sidebar. Collapse the
+ * state into your own default at the call site with `?? true`.
+ *
+ * Never throws: a header is client-controlled, and a value with a malformed
+ * percent-escape (`mantle-sidebar-state=%E0%A4%A`) is unparseable rather than
+ * fatal, so one hostile or corrupt cookie cannot fail the server render on
+ * every page load.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#persisting-the-collapsed-state
+ *
+ * @example
+ * ```ts
+ * // app/root.tsx loader
+ * export const loader = ({ request }: Route.LoaderArgs) => ({
+ *   sidebarOpen: extractSidebarStateCookie(request.headers.get("Cookie")) ?? true,
+ * });
+ * ```
+ *
+ * @param cookieHeader - The raw `Cookie` header string from the request, or null/undefined.
+ * @returns `true` when expanded, `false` when collapsed, `undefined` when unset, undecodable, or unparseable.
+ */
+declare function extractSidebarStateCookie(cookieHeader: string | null | undefined): boolean | undefined;
+/**
+ * Attributes for {@link serializeSidebarStateCookie}. Deliberately omits
+ * `HttpOnly`: the browser writes this cookie from `onOpenChange`, so a
+ * server-only cookie could never be updated when the user toggles the rail.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#serializesidebarstatecookie
+ *
+ * @example
+ * ```ts
+ * serializeSidebarStateCookie(open, { maxAge: 60 * 60 * 24 * 365, sameSite: "Lax" });
+ * ```
+ */
+type SerializeSidebarStateCookieOptions = {
+  /**
+   * How long the preference survives, in seconds.
+   *
+   * @default 31_536_000 // one year
+   */
+  maxAge?: number;
+  /**
+   * The path the cookie applies to. Keep the default unless the sidebar only
+   * exists under one route subtree.
+   *
+   * @default "/"
+   */
+  path?: string;
+  /**
+   * The domain the cookie applies to. Omitted by default, which scopes it to
+   * the exact current host. Set it (e.g. `".example.com"`) to share the
+   * preference across subdomains.
+   */
+  domain?: string;
+  /**
+   * `SameSite` policy. `"Lax"` is right for a UI preference — it survives
+   * top-level navigations back to your app without riding along on
+   * cross-site subrequests.
+   *
+   * @default "Lax"
+   */
+  sameSite?: "Lax" | "Strict" | "None";
+  /**
+   * Whether to add the `Secure` attribute. Omitted by default so the same call
+   * works on `http://localhost` — a `Secure` cookie is silently rejected over
+   * http, which would make the preference appear not to persist in local
+   * development. Set it to `true` in production if your CSP or policy requires
+   * it; this cookie holds no secret, only whether a rail is open.
+   *
+   * @default false
+   */
+  secure?: boolean;
 };
+/**
+ * Serialize the sidebar's expanded state as a cookie string.
+ *
+ * Framework-agnostic by design: the returned string is valid for both
+ * `document.cookie` on the client and a `Set-Cookie` response header on the
+ * server, so the same helper covers whichever side of your app owns the write.
+ *
+ * @see https://mantle.ngrok.com/components/navigation/sidebar#persisting-the-collapsed-state
+ *
+ * @example
+ * ```tsx
+ * // client: persist as the user toggles, and render from the loader value
+ * const { sidebarOpen } = useLoaderData<typeof loader>();
+ * <Sidebar.Root
+ *   defaultOpen={sidebarOpen}
+ *   onOpenChange={(open) => {
+ *     document.cookie = serializeSidebarStateCookie(open);
+ *   }}
+ * >
+ * ```
+ *
+ * @example
+ * ```ts
+ * // server: set it from an action instead
+ * return new Response(null, {
+ *   headers: { "Set-Cookie": serializeSidebarStateCookie(false, { secure: true }) },
+ * });
+ * ```
+ *
+ * @param open - Whether the sidebar is expanded.
+ * @param options - Cookie attributes; see {@link SerializeSidebarStateCookieOptions}.
+ * @returns A cookie string such as `mantle-sidebar-state=collapsed; Max-Age=31536000; Path=/; SameSite=Lax`.
+ */
+declare function serializeSidebarStateCookie(open: boolean, options?: SerializeSidebarStateCookieOptions): string;
 //#endregion
-export { Sidebar, type SidebarMobileBreakpoint, type SidebarState, useSidebar };
+export { SIDEBAR_STATE_COOKIE_NAME, type SerializeSidebarStateCookieOptions, Sidebar, type SidebarMobileBreakpoint, type SidebarState, extractSidebarStateCookie, serializeSidebarStateCookie, useSidebar };