@exegia/corpora-ui 0.20.0 → 0.21.0

package/src/components/composed/tree/tree-node.tsx

@@ -3,6 +3,7 @@
 import { LucideChevronLeft, LucideChevronRight } from "lucide-react"
 import { AnimatePresence, motion, useReducedMotion } from "motion/react"
 import * as React from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
 import { cn } from "@/lib/utils"
 import {
@@ -18,9 +19,27 @@ import {
   TREE_MICRO_TRANSITION,
   TREE_ROW_VARIANTS,
 } from "./constants"
+import {
+  cancelTreeRenameAtom,
+  renameTreeNodeAtom,
+  selectTreeNodeAtom,
+  startTreeRenameAtom,
+  toggleTreeNodeAtom,
+  treeCanRenameAtom,
+  treeCollapsedAtom,
+  treeNodeActiveAtom,
+  treeNodeDraggingAtom,
+  treeNodeDropAtom,
+  treeNodeExpandedAtom,
+  treeNodeRenamingAtom,
+  treeSectionedAtom,
+  treeSoundAtom,
+  treeVariantAtom,
+} from "./tree-atom"
 import { useTreeContext } from "./tree-context"
 import type { TreeNode } from "./type"
 import { EASE_OUT } from "@/lib/ease.ts"
+import { Button } from "@/components/ui/button"
 
 /** How a row behaves, resolved from variant + depth + shape. */
 type RowKind =
@@ -48,71 +67,94 @@ function rowKindOf(
   return variant === "toc" ? "link" : "toggle"
 }
 
-export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
-  const { tree: ctx, renderTrailing } = useTreeContext()
+function TreeRowImpl({ node, depth }: TreeRowProps): React.ReactElement {
+  const { treeId, renderTrailing, dnd } = useTreeContext()
   const reduce = useReducedMotion()
-  const kind = rowKindOf(node, depth, ctx.variant, ctx.sectioned)
+
+  // One subscription per field, per node. A row re-renders when its own
+  // branch, selection, rename or drag state changes and sits still while a
+  // sibling's does — reading the whole controller off context instead
+  // re-rendered every row in the tree on every toggle.
+  const variant = useAtomValue(treeVariantAtom(treeId))
+  const sectioned = useAtomValue(treeSectionedAtom(treeId))
+  const collapsed = useAtomValue(treeCollapsedAtom(treeId))
+  const canRename = useAtomValue(treeCanRenameAtom(treeId))
+  const sound = useAtomValue(treeSoundAtom(treeId))
+  const open = useAtomValue(treeNodeExpandedAtom(treeId, node.id))
+  const active = useAtomValue(treeNodeActiveAtom(treeId, node.id))
+  const renaming = useAtomValue(treeNodeRenamingAtom(treeId, node.id))
+  const dragging = useAtomValue(treeNodeDraggingAtom(treeId, node.id))
+  const drop = useAtomValue(treeNodeDropAtom(treeId, node.id))
+
+  const select = useSetAtom(selectTreeNodeAtom(treeId))
+  const toggleExpanded = useSetAtom(toggleTreeNodeAtom(treeId))
+  const startRename = useSetAtom(startTreeRenameAtom(treeId))
+  const cancelRename = useSetAtom(cancelTreeRenameAtom(treeId))
+  const rename = useSetAtom(renameTreeNodeAtom(treeId))
+
+  const kind = rowKindOf(node, depth, variant, sectioned)
 
   // The sidebar rail is single-level by contract — nested children are
   // ignored rather than rendered somewhere misleading.
-  const children = ctx.variant === "sidebar" ? [] : (node.children ?? [])
+  const children = variant === "sidebar" ? [] : (node.children ?? [])
   const canExpand =
-    kind !== "link" || (ctx.variant === "toc" && children.length > 0)
-  const open = ctx.isExpanded(node.id)
-  const active = ctx.activeId === node.id
-  const renaming = ctx.renamingId === node.id
+    kind !== "link" || (variant === "toc" && children.length > 0)
 
-  const { dnd } = ctx
-  const dragging = dnd.draggedId === node.id
-  const drop = dnd.dropTarget?.id === node.id ? dnd.dropTarget.position : null
+  const files = variant === "files"
 
-  // toc rows below the route level scroll — they anchor to the heading
-  // that shares their id (an explicit href always wins).
-  const href =
-    kind === "link" && !node.disabled
-      ? (node.href ??
-        (ctx.variant === "toc" && depth > 0 ? `#${node.id}` : undefined))
+  // toc rows below the route level are in-page anchors: they scroll to the
+  // heading sharing their id (an explicit `#hash` href wins). Rows are
+  // buttons, so the anchor default is reproduced by setting location.hash
+  // after `select` — the same order the old <a> gave (handlers first, then
+  // the browser's jump), with the same :target/history semantics.
+  const anchorHash =
+    variant === "toc" && kind === "link" && !node.disabled
+      ? node.href?.startsWith("#")
+        ? node.href
+        : depth > 0 && !node.href
+          ? `#${node.id}`
+          : undefined
       : undefined
 
-  const files = ctx.variant === "files"
-  const collapsed = ctx.collapsed
-
   function handlePress(event: React.MouseEvent) {
     if (node.disabled) {
       event.preventDefault()
       return
     }
     if (kind === "link") {
-      ctx.select(node.id)
+      select(node.id)
+      if (anchorHash !== undefined && typeof window !== "undefined") {
+        window.location.hash = anchorHash
+      }
       return
     }
-    ctx.toggleExpanded(node.id)
+    toggleExpanded(node.id)
   }
 
-  function startRename(event: React.MouseEvent) {
-    if (!ctx.canRename || node.disabled) return
+  function handleStartRename(event: React.MouseEvent) {
+    if (!canRename || node.disabled) return
     event.preventDefault()
-    ctx.startRename(node.id)
+    startRename(node.id)
   }
 
   const label = renaming ? (
     <input
       autoFocus
       className={cn(
-        "h-5 min-w-0 flex-1 rounded-sm border border-input bg-background px-1",
-        "text-[length:inherit] text-foreground outline-none focus-visible:ring-1 focus-visible:ring-ring"
+        "h-5 min-w-0 flex-1 rounded-sm border-none bg-transparent px-1",
+        "text-[length:inherit] text-foreground outline-none focus-visible:ring-0"
       )}
       data-slot="tree-rename-input"
       defaultValue={node.label}
-      onBlur={(event) => ctx.rename(node.id, event.currentTarget.value)}
+      onBlur={(event) => rename(node.id, event.currentTarget.value)}
       onClick={(event) => event.stopPropagation()}
       onKeyDown={(event) => {
         event.stopPropagation()
-        if (event.key === "Enter") ctx.rename(node.id, event.currentTarget.value)
-        if (event.key === "Escape") ctx.cancelRename()
+        if (event.key === "Enter") rename(node.id, event.currentTarget.value)
+        if (event.key === "Escape") cancelRename()
       }}
     />
-  ) : ctx.variant === "sidebar" ? (
+  ) : variant === "sidebar" ? (
     // The rail label folds away with the rail instead of unmounting rows.
     <AnimatePresence initial={false} mode="wait">
       <motion.span
@@ -176,7 +218,7 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
   ) : (
     <span
       className="min-w-0 flex-1 truncate"
-      onDoubleClick={ctx.canRename ? startRename : undefined}
+      onDoubleClick={canRename ? handleStartRename : undefined}
     >
       {node.label}
     </span>
@@ -184,31 +226,31 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
 
   const chevron = canExpand ? (
     <motion.span
-      animate={{ rotate: open ? (ctx.variant === "navigation" ? -90 : 90) : 0 }}
+      animate={{ rotate: open ? (variant === "navigation" ? -90 : 90) : 0 }}
       aria-hidden
       className="flex size-4 shrink-0 items-center justify-center text-muted-foreground/70"
       transition={reduce ? { duration: 0 } : TREE_MICRO_TRANSITION}
     >
-      {ctx.variant === "sidebar" && (
+      {variant === "sidebar" && (
         <LucideChevronLeft className="size-3.5 stroke-3" />
       )}
-      {ctx.variant === "toc" && (
+      {variant === "toc" && (
         <LucideChevronRight className="size-3.5 stroke-3" />
       )}
-      {ctx.variant === "navigation" && (
+      {variant === "navigation" && (
         <LucideChevronLeft className="size-3.5 stroke-3" />
       )}
     </motion.span>
   ) : null
 
   // The trailing slot is consumer-rendered and usually holds buttons, so it
-  // cannot live inside the row — a files folder row is itself a <button>, and
-  // a leaf row an <a>; either one nesting a button is invalid HTML. It sits
-  // beside the row instead, overlaid like the toc toggle.
+  // cannot live inside the row — every row is itself a <button>, and a
+  // button nesting a button is invalid HTML. It sits beside the row
+  // instead, overlaid like the toc toggle.
   const showTrailing = files && !!renderTrailing && !renaming
 
   const rowClassName = cn(
-    "group/row relative flex w-full min-w-0 items-center gap-2 rounded-md px-2",
+    "group/row relative flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md px-2",
     "text-left text-muted-foreground transition-colors duration-150 outline-none",
     "hover:bg-accent hover:text-accent-foreground",
     "focus-visible:ring-2 focus-visible:ring-ring",
@@ -217,9 +259,9 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
     active && "bg-accent font-medium text-accent-foreground",
     dragging && "opacity-50",
     drop === "inside" && "bg-accent/60 ring-1 ring-primary/50 ring-inset",
-    ctx.variant === "sidebar" && collapsed && "justify-center px-0",
+    variant === "sidebar" && collapsed && "justify-center px-0",
     // Room for the overlay expand toggle on toc parent rows.
-    ctx.variant === "toc" && kind === "link" && children.length > 0 && "pr-7",
+    variant === "toc" && kind === "link" && children.length > 0 && "pr-7",
     // …and for the overlay trailing actions on files rows. Sized for one
     // icon button plus its inset; a wider slot clips the truncated label,
     // which is why the prop is documented as row actions, not free content.
@@ -232,7 +274,7 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
     "data-branch": canExpand ? "" : undefined,
     "data-expanded": canExpand && open ? "" : undefined,
     "data-active": active ? "" : undefined,
-    "data-cuelume-press": ctx.sound ? "" : undefined,
+    "data-cuelume-press": sound ? "" : undefined,
     draggable: dnd.enabled && !renaming ? true : undefined,
     onDragStart: dnd.enabled
       ? (event: React.DragEvent) => dnd.onRowDragStart(event, node.id)
@@ -261,12 +303,11 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
         </span>
       )}
       {label}
-      {node.badge !== undefined &&
-        !(ctx.variant === "sidebar" && collapsed) && (
-          <span className="ml-auto shrink-0 text-xs text-muted-foreground/80">
-            {node.badge}
-          </span>
-        )}
+      {node.badge !== undefined && !(variant === "sidebar" && collapsed) && (
+        <span className="ml-auto shrink-0 text-xs text-muted-foreground/80">
+          {node.badge}
+        </span>
+      )}
       {/* nav toggle chevrons trail like the sidebar block; files lead;
           toc link rows get a separate overlay toggle instead. */}
       {kind === "toggle" && !files && (
@@ -289,10 +330,10 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
         {...rowInteractionProps}
         aria-expanded={open}
         className={cn(
-          "group/row flex w-full items-center gap-1 rounded-md px-2 pt-1 pb-1",
+          "group/row flex w-full cursor-pointer items-center gap-1 rounded-md px-2 py-1",
           "text-xs font-medium tracking-wide text-muted-foreground/80 uppercase",
           "transition-colors duration-150 outline-none hover:text-foreground",
-          "focus-visible:ring-2 focus-visible:ring-ring"
+          "focus-visible:ring-0 focus-visible:ring-ring"
         )}
         onClick={handlePress}
         type="button"
@@ -301,38 +342,30 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
         {chevron}
       </button>
     )
-  } else if (href !== undefined) {
-    row = (
-      <a
-        {...rowInteractionProps}
-        aria-current={active ? "page" : undefined}
-        aria-label={
-          ctx.variant === "sidebar" && collapsed ? node.label : undefined
-        }
-        className={rowClassName}
-        href={href}
-        onClick={handlePress}
-        target={node.target}
-      >
-        {content}
-      </a>
-    )
   } else {
+    // Every non-section row is the shared Button — link rows included. An
+    // `href` no longer renders an anchor: navigation runs through
+    // `selectTreeNodeAtom` (onSelect → onNavigate), and the consumer routes
+    // from the node it receives. `sound` is forwarded so Button's own
+    // press/release cues follow the tree's setting rather than its default.
     row = (
-      <button
+      <Button
         {...rowInteractionProps}
+        variant={variant === "sidebar" && active ? "secondary" : "ghost"}
         aria-current={active ? "page" : undefined}
         aria-expanded={kind === "toggle" ? open : undefined}
-        aria-label={
-          ctx.variant === "sidebar" && collapsed ? node.label : undefined
-        }
-        className={rowClassName}
+        aria-label={variant === "sidebar" && collapsed ? node.label : undefined}
+        className={cn(
+          "transform cursor-pointer! justify-start transition-transform ease-smooth-out",
+          variant === "sidebar" && collapsed ? "h-10! rounded-xl!" : undefined,
+          rowClassName
+        )}
         disabled={node.disabled}
         onClick={handlePress}
-        type="button"
+        sound={sound}
       >
         {content}
-      </button>
+      </Button>
     )
   }
 
@@ -340,7 +373,7 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
   // Expanded, the visible label already does, so the tooltip is disabled
   // rather than unmounted: swapping the wrapper in and out with `collapsed`
   // would remount the row and cut the label's fold animation short.
-  if (ctx.variant === "sidebar") {
+  if (variant === "sidebar") {
     row = (
       <Tooltip disabled={!collapsed || node.disabled}>
         <TooltipTrigger render={row} />
@@ -352,18 +385,18 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
   // toc parents navigate on the row itself, so their chevron lives beside
   // the row as its own toggle.
   const tocToggle =
-    ctx.variant === "toc" && kind === "link" && children.length > 0 ? (
+    variant === "toc" && kind === "link" && children.length > 0 ? (
       <button
         aria-expanded={open}
         aria-label={`${open ? "Collapse" : "Expand"} ${node.label}`}
         className={cn(
-          "absolute top-1/2 right-1 flex size-5 -translate-y-1/2 items-center",
+          "absolute top-1/2 right-1 flex size-5 -translate-y-1/2 cursor-pointer items-center",
           "justify-center rounded-sm text-muted-foreground/70 outline-none",
           "hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
         )}
         onClick={(event) => {
           event.stopPropagation()
-          ctx.toggleExpanded(node.id)
+          toggleExpanded(node.id)
         }}
         type="button"
       >
@@ -436,6 +469,12 @@ export function TreeRow({ node, depth }: TreeRowProps): React.ReactElement {
   )
 }
 
+/** Rows are memoized so a re-render of the root — a rail measurement, a new
+ * `renderTrailing` — does not walk the whole tree. Each row's own state
+ * reaches it through its atoms instead. */
+export const TreeRow = React.memo(TreeRowImpl)
+TreeRow.displayName = "TreeRow"
+
 /** Insertion indicator above or below a row while a drag hovers it. */
 function TreeDropLine({ side }: { side: "top" | "bottom" }) {
   return (

package/src/components/composed/tree/tree.tsx

@@ -19,6 +19,7 @@ import {
   TREE_EASE,
 } from "./constants"
 import { useTree } from "./use-tree"
+import { useTreeDndHandlers } from "./use-tree-dnd"
 import { motion, useReducedMotion } from "motion/react"
 
 const DEFAULT_LABELS: Record<TreeController["variant"], string> = {
@@ -48,14 +49,16 @@ export function Tree(props: TreeProps): React.ReactElement {
   // Two components rather than one: hooks may not be called conditionally,
   // and the controller form has no props to build a fallback controller
   // from. Nobody switches a tree between the two forms at runtime.
-  return props.tree
-    ? <TreeView
-        ariaLabel={props.ariaLabel}
-        className={props.className}
-        renderTrailing={props.renderTrailing}
-        tree={props.tree}
-      />
-    : <UncontrolledTree {...props} />
+  return props.tree ? (
+    <TreeView
+      ariaLabel={props.ariaLabel}
+      className={props.className}
+      renderTrailing={props.renderTrailing}
+      tree={props.tree}
+    />
+  ) : (
+    <UncontrolledTree {...props} />
+  )
 }
 
 /** The props form: builds its own controller and renders through it. */
@@ -70,6 +73,7 @@ function UncontrolledTree(props: TreeDataProps): React.ReactElement {
     className,
   } = props
   const tree = useTree({
+    treeId: props.treeId,
     variant,
     items,
     activeId,
@@ -112,7 +116,7 @@ function TreeView({
   // as wide as whatever holds it, which can change on resize.
   //
   // A container with no width of its own sizes to the list — so it shrinks
-  // around the 44px rail once collapsed and follows the list mid-tween. Both
+  // around the 40px rail once collapsed and follows the list mid-tween. Both
   // would feed the list's own width back in as its target and pin it. So:
   // no observing while collapsed (the last expanded width stands), and each
   // sample is taken with the list's inline width cleared, so the classes'
@@ -210,9 +214,13 @@ function TreeView({
     }
   }
 
+  // Rows take the tree's id and the stable drag handlers, never the
+  // controller — so this value keeps its identity and a toggle re-renders only
+  // the rows whose own atoms changed.
+  const dnd = useTreeDndHandlers(tree.treeId)
   const context = React.useMemo<TreeContextValue>(
-    () => ({ tree, renderTrailing }),
-    [tree, renderTrailing]
+    () => ({ treeId: tree.treeId, renderTrailing, dnd }),
+    [tree.treeId, renderTrailing, dnd]
   )
 
   const label = ariaLabel ?? DEFAULT_LABELS[variant]
@@ -220,15 +228,15 @@ function TreeView({
     <motion.ul
       aria-label={label}
       className={cn(
-        "flex min-w-0 flex-col h-full",
+        "flex h-full min-w-0 flex-col",
         // Resting widths, and the fallback until the rail is measured. The
         // motion target below overrides these with an inline width.
-        collapsed ? "w-11 gap-y-2" : "w-full",
+        collapsed ? "w-10 gap-y-2!" : "w-full",
         variant === "files" ? "gap-px" : sectioned ? "gap-3" : "gap-0.5"
       )}
       // Both endpoints must be px: motion cannot interpolate a number
-      // against "100%", and animating 44 -> "100%" pinned the inline width
-      // at 44px, so the rail collapsed once and never reopened. The
+      // against "100%", and animating 40 -> "100%" pinned the inline width
+      // at 40px, so the rail collapsed once and never reopened. The
       // expanded target is the rail's own measured width.
       initial={false}
       animate={railTarget}
@@ -266,7 +274,7 @@ function TreeView({
       ) : (
         <nav
           aria-label={label}
-          className={cn("min-w-0 flex h-full justify-center", className)}
+          className={cn("flex h-full min-w-0 justify-center", className)}
           data-slot="tree-root"
           ref={railRef}
         >

package/src/components/composed/tree/type.ts

@@ -8,8 +8,11 @@ export interface TreeNode {
   /** Leading icon. Required in practice for `sidebar` — it is all that
    * remains of a row while the rail is collapsed. */
   icon?: React.ReactNode
-  /** Renders an anchor. Without one the row is a button; `toc` leaves
-   * default to `#{id}` so they scroll to the matching heading. */
+  /** Route metadata for the consumer's `onNavigate` — every row renders as
+   * a button, so this is never turned into an anchor element. Read it (with
+   * `target`) off the node your handler receives. One native behaviour is
+   * kept: `toc` rows below the route level jump to `#{id}` after select
+   * (a `#hash` href overrides the id; a non-hash href disables the jump). */
   href?: string
   target?: "_blank" | "_self" | "_parent" | "_top"
   disabled?: boolean
@@ -27,14 +30,31 @@ export type TreeVariant = "navigation" | "toc" | "sidebar" | "files"
 /** Where a dragged row lands relative to its drop target. */
 export type TreeDropPosition = "before" | "after" | "inside"
 
+/** Key for one tree’s state in the store. Any stable string; `useTree`
+ * generates one when you don't pass it. */
+export type TreeInstanceId = string
+
+/** Row a drag hovers, and where the drop would land. */
+export interface TreeDropTarget {
+  id: string
+  position: TreeDropPosition
+}
+
 interface TreeBaseProps {
   items: TreeNode[]
+  /** Key this tree's state under a name your app can address —
+   * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+   * anywhere under `ExegiaProvider`. Without one the tree generates a key
+   * and its state is dropped when it unmounts. */
+  treeId?: TreeInstanceId
   /** Never set on the data form — `tree` selects the controller form. */
   tree?: never
   /** `id` of the current entry — matches any depth. Its ancestors expand. */
   activeId?: string
-  /** Fires for every selection (rows and leaves alike), after the row's
-   * anchor default — wire your router's navigate here. */
+  /** Fires for every selection (rows and leaves alike), after the node's
+   * own `onSelect`. Rows are buttons, so this is the routing path — wire
+   * your router's navigate here. `toc` rows below the route level still jump
+   * to `#{id}` natively, after this fires. */
   onNavigate?: (node: TreeNode) => void
   /** Expand/collapse cues. Silent until `bindSounds()`. */
   sound?: boolean
@@ -72,12 +92,14 @@ export type TreeDataProps = TreeBaseProps &
     | ({
         /** Nested app navigation. With 3 levels of nodes the top level
          * becomes collapsible section names (styled as headings, not
-         * links); with 2 it renders plain link rows. */
+         * rows); with 2 it renders plain selectable rows. */
         variant: "navigation"
       } & TreeReadonlyProps)
     | ({
-        /** Table of contents: top-level nodes are routes, leaf nodes are
-         * in-page anchors (`#{id}` unless the node carries an `href`). */
+        /** Table of contents: top-level nodes are routes (handled in
+         * `onNavigate`); rows below jump to `#{id}` after select, like an
+         * anchor would. Parents select on the row and expand from a
+         * separate overlay chevron. */
         variant: "toc"
       } & TreeReadonlyProps)
     | ({
@@ -106,6 +128,11 @@ export type TreeDataProps = TreeBaseProps &
  * controlled when passed and hook-owned when its `default*` twin is used
  * instead. */
 export interface UseTreeOptions {
+  /** Key this tree's state under a name your app can address —
+   * `useTreeState("app-nav")` / `useTreeActions("app-nav")` reach it from
+   * anywhere under `ExegiaProvider`. Without one the hook generates a key
+   * and the state is dropped when the component unmounts. */
+  treeId?: TreeInstanceId
   /** Which shape the tree takes — gates rename/reorder (`files`) and the
    * collapsible rail (`sidebar`). */
   variant: TreeVariant
@@ -143,6 +170,8 @@ export interface UseTreeOptions {
 /** Everything the tree can do, callable from outside the component.
  * Returned by `useTree` and accepted by `<Tree tree={…} />`. */
 export interface TreeController {
+  /** The key this tree's state is stored under. */
+  treeId: TreeInstanceId
   variant: TreeVariant
   items: TreeNode[]
   /** `navigation` with 3 levels of nodes — depth 0 renders as sections. */
@@ -187,26 +216,107 @@ export interface TreeController {
   canMove: boolean
   move: (id: string, parentId: string | null, index: number) => void
 
+  /** Back to the values the tree mounted with. */
+  reset: () => void
+
   dnd: TreeDndContextValue
 }
 
 /** @internal What a row needs from the root, threaded through context so
- * the recursive rows stay prop-light. */
+ * the recursive rows stay prop-light.
+ *
+ * Deliberately free of tree state. Rows read state from per-node atoms, so
+ * this value keeps its identity for the life of the tree and expanding one
+ * branch no longer re-renders every row through context. */
 export interface TreeContextValue {
-  tree: TreeController
+  treeId: TreeInstanceId
   renderTrailing?: (node: TreeNode) => React.ReactNode
+  dnd: TreeDndHandlers
 }
 
-/** @internal Drag state shared by every row (all `null`/no-op outside
- * `files`). */
-export interface TreeDndContextValue {
+/** @internal The drag event handlers, stable for the life of the tree —
+ * they read drag state out of the store instead of closing over it, so
+ * handing them to every row costs no re-renders. */
+export interface TreeDndHandlers {
   enabled: boolean
-  draggedId: string | null
-  /** Row the pointer is over and where the drop would land. */
-  dropTarget: { id: string; position: TreeDropPosition } | null
   onRowDragStart: (event: React.DragEvent, id: string) => void
   onRowDragOver: (event: React.DragEvent, node: TreeNode) => void
   onRowDragLeave: (event: React.DragEvent) => void
   onRowDrop: (event: React.DragEvent, node: TreeNode) => void
   onRowDragEnd: () => void
 }
+
+/** @internal Handlers plus live drag state — what `TreeController.dnd`
+ * exposes (all `null`/no-op outside `files`). */
+export interface TreeDndContextValue extends TreeDndHandlers {
+  draggedId: string | null
+  /** Row the pointer is over and where the drop would land. */
+  dropTarget: TreeDropTarget | null
+}
+
+/** Everything observable about one tree, for consumers reading it by id. */
+export interface TreeState {
+  variant: TreeVariant
+  items: TreeNode[]
+  activeId?: string
+  expandedIds: ReadonlySet<string>
+  collapsed: boolean
+  renamingId: string | null
+  sectioned: boolean
+  sectionIds: string[]
+  canRename: boolean
+  canMove: boolean
+  draggedId: string | null
+  dropTarget: TreeDropTarget | null
+}
+
+/** Everything doable to one tree from outside its component. */
+export interface TreeActions {
+  expand: (id: string) => void
+  collapse: (id: string) => void
+  toggleExpanded: (id: string) => void
+  expandAll: () => void
+  collapseAll: () => void
+  reveal: (id: string) => void
+  setCollapsed: (collapsed: boolean) => void
+  toggleCollapsed: () => void
+  select: (id: string) => void
+  startRename: (id: string) => void
+  cancelRename: () => void
+  rename: (id: string, label: string) => void
+  move: (id: string, parentId: string | null, index: number) => void
+  setItems: (items: TreeNode[]) => void
+  reset: () => void
+}
+
+/** @internal Projection of `useTree`'s options — primitives only, so the
+ * store write runs once per real change instead of once per render. */
+export interface TreeConfig {
+  variant: TreeVariant
+  sound: boolean
+  controlsItems: boolean
+  controlsActiveId: boolean
+  controlsCollapsed: boolean
+  managesItems: boolean
+  hasRenameHandler: boolean
+  hasMoveHandler: boolean
+}
+
+/** @internal Latest option callbacks. Only write atoms read this, so it
+ * can be refreshed every commit without re-rendering anything. */
+export interface TreeHandlers {
+  onNavigate?: (node: TreeNode) => void
+  onItemsChange?: (items: TreeNode[]) => void
+  onExpandedChange?: (ids: string[]) => void
+  onCollapsedChange?: (collapsed: boolean) => void
+  onRename?: (id: string, label: string) => void
+  onMove?: (id: string, parentId: string | null, index: number) => void
+}
+
+/** @internal What an instance starts from, replayed by `resetTreeAtom`. */
+export interface TreeSeed {
+  items: TreeNode[]
+  activeId?: string
+  collapsed: boolean
+  expandedIds?: string[]
+}