@exegia/corpora-ui 0.20.0 → 0.21.0

package/src/components/blocks/nav/sidebar/ai-sidebar.tsx

@@ -1,15 +1,18 @@
-"use client";
+"use client"
 
-import { AnimatePresence } from "motion/react";
-import { cn } from "@/lib/utils";
+import { useMemo } from "react"
+import { AnimatePresence } from "motion/react"
+import { cn } from "@/lib/utils"
 import type {
   AISidebarComponentProps,
+  AISidebarContextValue,
   AISidebarController,
   AISidebarProps,
   AISidebarViewProps,
   FlatResource,
 } from "./type"
 import { useAISidebar } from "./use-ai-sidebar"
+import { AISidebarContext } from "./sidebar-context"
 import { ResourceRow } from "./sidebar-row"
 
 /**
@@ -69,8 +72,47 @@ function AISidebarView({
   const { dnd, hover } = controller
   const { draggingId, dropTarget } = dnd
 
+  // Rows take the sidebar's id and the stable handlers, never the controller
+  // — so this value keeps its identity and a hover or a toggle re-renders
+  // only the rows whose own atoms changed. Deps name each function because
+  // `dnd` itself carries live drag state and changes identity with it.
+  const context = useMemo<AISidebarContextValue>(
+    () => ({
+      sidebarId: controller.sidebarId,
+      hoverLayoutId: hover.layoutId,
+      renderIcon,
+      renderMenu,
+      renderActionsTrigger,
+      setRowRef: controller.setRowRef,
+      onRowKeyDown: controller.onRowKeyDown,
+      onRowHover: hover.onRowHover,
+      closeMenu: controller.closeMenu,
+      dnd: {
+        onDrop: dnd.onDrop,
+        onRowDragStart: dnd.onRowDragStart,
+        onRowDragEnd: dnd.onRowDragEnd,
+        onRowDragOver: dnd.onRowDragOver,
+      },
+    }),
+    [
+      controller.sidebarId,
+      controller.setRowRef,
+      controller.onRowKeyDown,
+      controller.closeMenu,
+      hover.layoutId,
+      hover.onRowHover,
+      renderIcon,
+      renderMenu,
+      renderActionsTrigger,
+      dnd.onDrop,
+      dnd.onRowDragStart,
+      dnd.onRowDragEnd,
+      dnd.onRowDragOver,
+    ]
+  )
+
   return (
-    <>
+    <AISidebarContext.Provider value={context}>
       <div
         role="tree"
         aria-label={ariaLabel}
@@ -86,43 +128,7 @@ function AISidebarView({
       >
         <AnimatePresence initial={false}>
           {controller.flat.map((row: FlatResource) => (
-            <ResourceRow
-              key={row.item.id}
-              row={row}
-              active={controller.selectedId === row.item.id}
-              expanded={controller.isExpanded(row.item.id)}
-              focused={controller.focusedId === row.item.id}
-              draggingId={draggingId}
-              dropTarget={dropTarget}
-              menuOpen={controller.menuOpenId === row.item.id}
-              renaming={controller.renamingId === row.item.id}
-              hoverActive={hover.hoveredId !== null && !draggingId}
-              hoverPill={
-                hover.hoveredId === row.item.id &&
-                !draggingId &&
-                !row.item.disabled
-              }
-              hoverLayoutId={hover.layoutId}
-              onHoverChange={(hovered) => hover.onRowHover(row.item.id, hovered)}
-              onFocus={() => controller.focus(row.item.id)}
-              onSelect={() => controller.select(row.item.id)}
-              onToggle={() => controller.toggleExpanded(row.item.id)}
-              onKeyDown={(event) => controller.onRowKeyDown(event, row)}
-              onRenameStart={() => controller.startRename(row.item.id)}
-              onRenameCancel={controller.cancelRename}
-              onRenameCommit={(label) => controller.rename(row.item.id, label)}
-              onMenuOpenChange={(open) =>
-                open ? controller.openMenu(row.item.id) : controller.closeMenu()
-              }
-              onDragStart={dnd.onRowDragStart}
-              onDragEnd={dnd.onRowDragEnd}
-              onDragOver={dnd.onRowDragOver}
-              onDrop={dnd.onDrop}
-              renderIcon={renderIcon}
-              renderMenu={renderMenu}
-              renderActionsTrigger={renderActionsTrigger}
-              setRef={(node) => controller.setRowRef(row.item.id, node)}
-            />
+            <ResourceRow key={row.item.id} row={row} />
           ))}
         </AnimatePresence>
 
@@ -139,6 +145,6 @@ function AISidebarView({
       <span className="sr-only" aria-live="polite">
         {controller.announcement}
       </span>
-    </>
+    </AISidebarContext.Provider>
   )
 }

package/src/components/blocks/nav/sidebar/index.ts

@@ -3,7 +3,59 @@ import { MarqueeLabel } from "./marquee-label.tsx"
 import { ResourceRow } from "./sidebar-row.tsx"
 import { SidebarIcon } from "./sidebar-icon.tsx"
 export { useAISidebar, type UseAISidebarOptions } from "./use-ai-sidebar.ts"
+export {
+  useAISidebarActions,
+  useAISidebarState,
+} from "./use-ai-sidebar-state.ts"
 export type * from "./type.ts"
+// The public atom surface. `@internal` atoms (config, handlers, mount, the
+// projections, the owned-* loop guards) stay unexported on purpose —
+// `export *` would make every internal a breaking-change surface for
+// consumer apps.
+export {
+  aiSidebarActiveIdAtom,
+  aiSidebarAnnouncementAtom,
+  aiSidebarDraggingIdAtom,
+  aiSidebarDropTargetAtom,
+  aiSidebarExpandedIdsAtom,
+  aiSidebarFlatAtom,
+  aiSidebarFocusedIdAtom,
+  aiSidebarHoverActiveAtom,
+  aiSidebarHoveredIdAtom,
+  aiSidebarItemsAtom,
+  aiSidebarMenuOpenIdAtom,
+  aiSidebarMovePendingAtom,
+  aiSidebarRenamingIdAtom,
+  aiSidebarRowDraggingAtom,
+  aiSidebarRowDropAtom,
+  aiSidebarRowExpandedAtom,
+  aiSidebarRowFocusedAtom,
+  aiSidebarRowHoveredAtom,
+  aiSidebarRowMenuOpenAtom,
+  aiSidebarRowRenamingAtom,
+  aiSidebarRowSelectedAtom,
+  aiSidebarStateAtom,
+  cancelAISidebarRenameAtom,
+  clearAISidebarHoverAtom,
+  closeAISidebarMenuAtom,
+  collapseAISidebarRowAtom,
+  collapseAllAISidebarRowsAtom,
+  endAISidebarDragAtom,
+  expandAISidebarRowAtom,
+  expandAllAISidebarRowsAtom,
+  focusAISidebarRowAtom,
+  moveAISidebarRowAtom,
+  openAISidebarMenuAtom,
+  removeAISidebarInstance,
+  renameAISidebarRowAtom,
+  resetAISidebarAtom,
+  revealAISidebarRowAtom,
+  selectAISidebarRowAtom,
+  setAISidebarHoveredAtom,
+  setAISidebarItemsAtom,
+  startAISidebarRenameAtom,
+  toggleAISidebarRowAtom,
+} from "./ai-sidebar-atom.ts"
 
 export { AISidebar, MarqueeLabel, ResourceRow, SidebarIcon }
 
@@ -11,5 +63,5 @@ export const Sidebar = {
   Wrapper: AISidebar,
   MarqueeLabel,
   Row: ResourceRow,
-  Icon: SidebarIcon
+  Icon: SidebarIcon,
 }

package/src/components/blocks/nav/sidebar/sidebar-context.ts

@@ -0,0 +1,15 @@
+"use client";
+
+import { createContext, useContext } from "react";
+
+import type { AISidebarContextValue } from "./type.ts";
+
+export const AISidebarContext = createContext<AISidebarContextValue | null>(
+  null
+);
+
+export function useAISidebarContext(): AISidebarContextValue {
+  const context = useContext(AISidebarContext);
+  if (!context) throw new Error("Sidebar rows must render inside <AISidebar>.");
+  return context;
+}

package/src/components/blocks/nav/sidebar/sidebar-row.tsx

@@ -1,10 +1,15 @@
+"use client"
+
 import {
   cloneElement,
+  memo,
+  useCallback,
   useEffect,
   useRef,
   useState,
   type MouseEvent,
 } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 import type { ResourceRowProps } from "./type"
 import {
   AnimatePresence,
@@ -15,6 +20,25 @@ import {
 import { ChevronRight, MoreHorizontal, Pencil } from "lucide-react"
 import { SPRING_LAYOUT } from "@/lib/ease.ts"
 import { cn } from "@/lib/utils.ts"
+import {
+  aiSidebarHoverActiveAtom,
+  aiSidebarRowDraggingAtom,
+  aiSidebarRowDropAtom,
+  aiSidebarRowExpandedAtom,
+  aiSidebarRowFocusedAtom,
+  aiSidebarRowHoveredAtom,
+  aiSidebarRowMenuOpenAtom,
+  aiSidebarRowRenamingAtom,
+  aiSidebarRowSelectedAtom,
+  cancelAISidebarRenameAtom,
+  focusAISidebarRowAtom,
+  openAISidebarMenuAtom,
+  renameAISidebarRowAtom,
+  selectAISidebarRowAtom,
+  startAISidebarRenameAtom,
+  toggleAISidebarRowAtom,
+} from "./ai-sidebar-atom.ts"
+import { useAISidebarContext } from "./sidebar-context.ts"
 import { canContain } from "./utils"
 import { SidebarIcon } from "./sidebar-icon"
 import { MarqueeLabel } from "./marquee-label"
@@ -23,7 +47,7 @@ import {
   MorphPopoverContent,
   MorphPopoverTrigger,
 } from "@/components/motion/popover-morph.tsx"
-import { Button } from "@/components/ui/button";
+import { Button } from "@/components/ui/button"
 
 // Same choreography as SharedLayoutBg: the wrapper only fades/blurs out when
 // the pointer leaves the whole tree; a row-to-row move exits instantly so the
@@ -41,46 +65,74 @@ const reducedPillVariants: Variants = {
   exit: (hoverActive: boolean) => (!hoverActive ? { opacity: 0 } : {}),
 }
 
-export function ResourceRow({
-  row,
-  active,
-  expanded,
-  focused,
-  draggingId,
-  dropTarget,
-  menuOpen,
-  renaming,
-  onDragEnd,
-  onDragOver,
-  onDragStart,
-  onDrop,
-  onFocus,
-  onKeyDown,
-  onMenuOpenChange,
-  onRenameCancel,
-  onRenameCommit,
-  onRenameStart,
-  onSelect,
-  onToggle,
-  hoverActive = false,
-  hoverPill = false,
-  hoverLayoutId,
-  onHoverChange,
-  renderIcon,
-  renderMenu,
-  renderActionsTrigger,
-  setRef,
-}: ResourceRowProps) {
+function ResourceRowImpl({ row }: ResourceRowProps) {
+  const {
+    sidebarId,
+    hoverLayoutId,
+    renderIcon,
+    renderMenu,
+    renderActionsTrigger,
+    setRowRef,
+    onRowKeyDown,
+    onRowHover,
+    closeMenu,
+    dnd,
+  } = useAISidebarContext()
   const reduce = useReducedMotion() ?? false
+
+  // One subscription per field, per row. A row re-renders when its own
+  // selection, expansion, focus, rename, menu, drag or hover state changes
+  // and sits still while a sibling's does — reading the controller off
+  // context instead re-rendered every row on every change.
+  const active = useAtomValue(aiSidebarRowSelectedAtom(sidebarId, row.item.id))
+  const expanded = useAtomValue(
+    aiSidebarRowExpandedAtom(sidebarId, row.item.id)
+  )
+  const focused = useAtomValue(aiSidebarRowFocusedAtom(sidebarId, row.item.id))
+  const renaming = useAtomValue(
+    aiSidebarRowRenamingAtom(sidebarId, row.item.id)
+  )
+  const menuOpen = useAtomValue(
+    aiSidebarRowMenuOpenAtom(sidebarId, row.item.id)
+  )
+  const isDragging = useAtomValue(
+    aiSidebarRowDraggingAtom(sidebarId, row.item.id)
+  )
+  const dropPosition = useAtomValue(
+    aiSidebarRowDropAtom(sidebarId, row.item.id)
+  )
+  const hoverActive = useAtomValue(aiSidebarHoverActiveAtom(sidebarId))
+  const hoverPill =
+    useAtomValue(aiSidebarRowHoveredAtom(sidebarId, row.item.id)) &&
+    !row.item.disabled
+
+  const select = useSetAtom(selectAISidebarRowAtom(sidebarId))
+  const toggleExpanded = useSetAtom(toggleAISidebarRowAtom(sidebarId))
+  const setFocusedRow = useSetAtom(focusAISidebarRowAtom(sidebarId))
+  const startRename = useSetAtom(startAISidebarRenameAtom(sidebarId))
+  const cancelRename = useSetAtom(cancelAISidebarRenameAtom(sidebarId))
+  const rename = useSetAtom(renameAISidebarRowAtom(sidebarId))
+  const openMenu = useSetAtom(openAISidebarMenuAtom(sidebarId))
+
+  const onMenuOpenChange = useCallback(
+    (open: boolean) => {
+      if (open) openMenu(row.item.id)
+      else closeMenu()
+    },
+    [closeMenu, openMenu, row.item.id]
+  )
+
+  const setRef = useCallback(
+    (node: HTMLDivElement | null) => setRowRef(row.item.id, node),
+    [row.item.id, setRowRef]
+  )
+
   const [hovered, setHovered] = useState(false)
   const inputRef = useRef<HTMLInputElement>(null)
   const skipRenameBlurRef = useRef(false)
   const draggedRef = useRef(false)
   const [draft, setDraft] = useState(row.item.label)
   const acceptsChildren = canContain(row.item)
-  const isDragging = draggingId === row.item.id
-  const dropPosition =
-    dropTarget?.id === row.item.id ? dropTarget.position : null
 
   useEffect(() => {
     if (!renaming) return
@@ -96,14 +148,14 @@ export function ResourceRow({
     close: () => onMenuOpenChange(false),
     rename: () => {
       onMenuOpenChange(false)
-      onRenameStart()
+      startRename(row.item.id)
     },
   }) ?? (
     <button
       type="button"
       onClick={() => {
         onMenuOpenChange(false)
-        onRenameStart()
+        startRename(row.item.id)
       }}
       className="flex h-8 w-full items-center gap-2 rounded-lg px-2.5 text-left text-xs text-foreground transition-colors outline-none hover:bg-muted focus-visible:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
     >
@@ -127,8 +179,8 @@ export function ResourceRow({
       data-menu-open={menuOpen || undefined}
       data-drop={dropPosition ?? undefined}
       data-dragging={isDragging || undefined}
-      onFocus={onFocus}
-      onKeyDown={onKeyDown}
+      onFocus={() => setFocusedRow(row.item.id)}
+      onKeyDown={(event) => onRowKeyDown(event, row)}
       onClick={(event) => {
         if (
           event.defaultPrevented ||
@@ -137,34 +189,34 @@ export function ResourceRow({
           row.item.disabled
         )
           return
-        if (acceptsChildren) onToggle()
-        else onSelect()
+        if (acceptsChildren) toggleExpanded(row.item.id)
+        else select(row.item.id)
       }}
       onDoubleClick={(event) => {
         if (acceptsChildren || row.item.disabled) return
         event.preventDefault()
-        onRenameStart()
+        startRename(row.item.id)
       }}
       onMouseEnter={() => {
         setHovered(true)
-        onHoverChange?.(true)
+        onRowHover(row.item.id, true)
       }}
       onMouseLeave={() => {
         setHovered(false)
-        onHoverChange?.(false)
+        onRowHover(row.item.id, false)
       }}
       onDragStartCapture={(event) => {
         draggedRef.current = true
-        onDragStart(event, row.item.id)
+        dnd.onRowDragStart(event, row.item.id)
       }}
       onDragEndCapture={() => {
-        onDragEnd()
+        dnd.onRowDragEnd()
         requestAnimationFrame(() => {
           draggedRef.current = false
         })
       }}
-      onDragOver={(event) => onDragOver(event, row)}
-      onDrop={onDrop}
+      onDragOver={(event) => dnd.onRowDragOver(event, row)}
+      onDrop={dnd.onDrop}
       className={cn(
         "group/resource relative flex min-h-9 min-w-0 cursor-pointer items-center gap-2.5 rounded-md pr-3 text-sm outline-none",
         "text-muted-foreground transition-[color,background-color,scale] duration-150 ease-smooth-out hover:text-foreground motion-reduce:transition-none",
@@ -226,17 +278,17 @@ export function ResourceRow({
           onClick={(event) => event.stopPropagation()}
           onDoubleClick={(event) => event.stopPropagation()}
           onBlur={() => {
-            if (!skipRenameBlurRef.current) onRenameCommit(draft)
+            if (!skipRenameBlurRef.current) rename(row.item.id, draft)
           }}
           onKeyDown={(event) => {
             event.stopPropagation()
             if (event.key === "Enter") {
               skipRenameBlurRef.current = true
-              onRenameCommit(draft)
+              rename(row.item.id, draft)
             }
             if (event.key === "Escape") {
               skipRenameBlurRef.current = true
-              onRenameCancel()
+              cancelRename()
             }
           }}
           className="relative h-7 min-w-0 flex-1 text-sm text-foreground outline-none focus-visible:ring-0 focus-visible:ring-ring"
@@ -307,3 +359,20 @@ export function ResourceRow({
     </motion.div>
   )
 }
+
+/** `flat` is rebuilt whenever expansion changes, so its `FlatResource`
+ * wrappers are fresh objects even for rows nothing happened to. The
+ * comparator looks through the wrapper at what a row actually renders from —
+ * its item (stable unless the data changed), depth and parent — so a sibling
+ * opening does not walk every row. Each row's own state reaches it through
+ * its atoms instead. */
+function sameRow(prev: ResourceRowProps, next: ResourceRowProps): boolean {
+  return (
+    prev.row.item === next.row.item &&
+    prev.row.depth === next.row.depth &&
+    prev.row.parentId === next.row.parentId
+  )
+}
+
+export const ResourceRow = memo(ResourceRowImpl, sameRow)
+ResourceRow.displayName = "ResourceRow"

package/src/components/blocks/nav/sidebar/type.ts

@@ -23,10 +23,19 @@ export interface SidebarResourceMenuControls {
   rename: () => void
 }
 
+/** Key for one sidebar's state in the store. Any stable string;
+ * `useAISidebar` generates one when you don't pass it. */
+export type AISidebarInstanceId = string
+
 /** Options for `useAISidebar`. `items`, `activeId` and `expandedIds` are
  * each controlled when passed and hook-owned via their `default*` twin
  * otherwise. */
 export interface UseAISidebarOptions {
+  /** Key this sidebar's state under a name your app can address —
+   * `useAISidebarState("app-resources")` / `useAISidebarActions(...)` reach
+   * it from anywhere under `ExegiaProvider`. Without one the hook generates
+   * a key and the state is dropped when the component unmounts. */
+  sidebarId?: AISidebarInstanceId
   items?: SidebarResource[]
   defaultItems?: SidebarResource[]
   onItemsChange?: (items: SidebarResource[]) => void
@@ -46,6 +55,8 @@ export interface UseAISidebarOptions {
  * toolbar, a command palette, a route change. Returned by `useAISidebar`
  * and accepted by `<AISidebar controller={…} />`. */
 export interface AISidebarController {
+  /** The key this sidebar's state is stored under. */
+  sidebarId: AISidebarInstanceId
   items: SidebarResource[]
   /** Visible rows in order, each with its depth and parent id. */
   flat: FlatResource[]
@@ -89,19 +100,31 @@ export interface AISidebarController {
   /** Live-region text for the last move or rename outcome. */
   announcement: string
 
+  /** Back to the values the sidebar mounted with. */
+  reset: () => void
+
   /** @internal Row wiring the view threads through — drag state, the
    * hover pill and roving keyboard nav all belong to the rendering. */
   dnd: AISidebarDndState
   hover: AISidebarHoverState
-  onRowKeyDown: (event: KeyboardEvent<HTMLDivElement>, row: FlatResource) => void
+  onRowKeyDown: (
+    event: KeyboardEvent<HTMLDivElement>,
+    row: FlatResource
+  ) => void
   setRowRef: (id: string, node: HTMLDivElement | null) => void
 }
 
 /** @internal */
-export interface AISidebarDndState {
+export interface AISidebarDndState extends AISidebarRowDndHandlers {
   draggingId: string | null
   dropTarget: DropTarget | null
   onRootDragOver: (event: DragEvent<HTMLDivElement>) => void
+}
+
+/** @internal The drag handlers a row needs, stable for the life of the
+ * sidebar — they read drag state out of the store when they run instead of
+ * closing over it, so handing them to every row costs no re-renders. */
+export interface AISidebarRowDndHandlers {
   onDrop: (event: DragEvent<HTMLDivElement>) => void
   onRowDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void
   onRowDragEnd: () => void
@@ -164,36 +187,108 @@ export interface DropTarget {
   position: SidebarResourceDropPosition
 }
 
+/** A row takes its place in the tree and nothing else: selection,
+ * expansion, focus, rename, drag and hover state all arrive through its own
+ * atoms, and the rendering options through the sidebar context. */
 export interface ResourceRowProps {
   row: FlatResource
-  active: boolean
-  expanded: boolean
-  focused: boolean
-  draggingId: string | null
-  dropTarget: DropTarget | null
-  menuOpen: boolean
-  renaming: boolean
-  onDragEnd: () => void
-  onDragOver: (event: DragEvent<HTMLDivElement>, row: FlatResource) => void
-  onDragStart: (event: DragEvent<HTMLDivElement>, id: string) => void
-  onDrop: (event: DragEvent<HTMLDivElement>) => void
-  onFocus: () => void
-  onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void
-  onMenuOpenChange: (open: boolean) => void
-  onRenameCancel: () => void
-  onRenameCommit: (label: string) => void
-  onRenameStart: () => void
-  onSelect: () => void
-  onToggle: () => void
-  /** Some row in the tree is hovered — mounts the pill fade wrapper. */
-  hoverActive?: boolean
-  /** This row owns the sliding hover pill. */
-  hoverPill?: boolean
-  /** Shared motion layoutId that lets the pill travel between rows. */
-  hoverLayoutId?: string
-  onHoverChange?: (hovered: boolean) => void
-  renderIcon?: (item: SidebarResource) => ReactNode
+}
+
+/** @internal What a row needs from the block, threaded through context so
+ * the rows stay prop-light.
+ *
+ * Deliberately free of sidebar state and of the controller. Rows read state
+ * from per-row atoms, so this value keeps its identity for the life of the
+ * sidebar and hovering or expanding one row no longer re-renders every row
+ * through context. */
+export interface AISidebarContextValue {
+  sidebarId: AISidebarInstanceId
+  /** Shared motion layoutId that lets the hover pill travel between rows. */
+  hoverLayoutId: string
+  renderIcon?: AISidebarProps["renderIcon"]
   renderMenu?: AISidebarProps["renderMenu"]
   renderActionsTrigger?: AISidebarProps["renderActionsTrigger"]
-  setRef: (node: HTMLDivElement | null) => void
+  /** Registers the row's DOM node with the block, which owns the ref map —
+   * DOM nodes never go in the store. */
+  setRowRef: (id: string, node: HTMLDivElement | null) => void
+  onRowKeyDown: (
+    event: KeyboardEvent<HTMLDivElement>,
+    row: FlatResource
+  ) => void
+  onRowHover: (id: string, hovered: boolean) => void
+  /** Closing returns DOM focus to the row that owned the menu, so it goes
+   * through the block rather than the store. */
+  closeMenu: () => void
+  dnd: AISidebarRowDndHandlers
+}
+
+/** Everything observable about one sidebar, for consumers reading it by id. */
+export interface AISidebarState {
+  items: SidebarResource[]
+  /** Visible rows in order, each with its depth and parent id. */
+  flat: FlatResource[]
+  selectedId: string | null
+  expandedIds: ReadonlySet<string>
+  focusedId: string | null
+  renamingId: string | null
+  menuOpenId: string | null
+  draggingId: string | null
+  dropTarget: DropTarget | null
+  hoveredId: string | null
+  /** A move is in flight — further moves are refused until it settles. */
+  movePending: boolean
+  /** Live-region text for the last move or rename outcome. */
+  announcement: string
+}
+
+/** Everything doable to one sidebar from outside its component. */
+export interface AISidebarActions {
+  select: (id: string) => void
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggleExpanded: (id: string) => void
+  expandAll: () => void
+  collapseAll: () => void
+  reveal: (id: string) => void
+  /** Moves the roving-focus target. DOM focus follows only for callers that
+   * hold the controller — the ref map lives in the block, not the store. */
+  focus: (id: string) => void
+  startRename: (id: string) => void
+  cancelRename: () => void
+  rename: (id: string, label: string) => void
+  openMenu: (id: string) => void
+  closeMenu: () => void
+  move: (move: SidebarResourceMove) => Promise<void>
+  setItems: (items: SidebarResource[]) => void
+  reset: () => void
+}
+
+/** @internal Projection of `useAISidebar`'s options — primitives only, so
+ * the store write runs once per real change instead of once per render. */
+export interface AISidebarConfig {
+  controlsItems: boolean
+  controlsActiveId: boolean
+  controlsExpandedIds: boolean
+}
+
+/** @internal Latest option callbacks. Only write atoms read this, so it can
+ * be refreshed every commit without re-rendering anything. */
+export interface AISidebarHandlers {
+  onItemsChange?: (items: SidebarResource[]) => void
+  onMove?: (move: SidebarResourceMove) => void | Promise<void>
+  onMoveError?: (error: unknown, move: SidebarResourceMove) => void
+  onRename?: (item: SidebarResource, label: string) => void | Promise<void>
+  onActiveChange?: (id: string) => void
+  onExpandedChange?: (ids: string[]) => void
+}
+
+/** @internal What an instance starts from, replayed by
+ * `resetAISidebarAtom`. */
+export interface AISidebarSeed {
+  items: SidebarResource[]
+  /** Hook-owned selection — the `defaultActiveId`, never the controlled
+   * `activeId`. */
+  activeId: string | null
+  focusedId: string | null
+  expandedIds: string[]
 }