@multiplatform.one/components 6.0.4 → 6.3.0

package/src/views/TreeView.tsx

@@ -1,17 +1,55 @@
 import { componentColors } from "../componentColors";
+import { EmptyState } from "../layouts/page";
 import { FlashList, type FlashListRef } from "@shopify/flash-list";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
 import {
-  CaretDownIcon,
+  MIN_PRESS_TARGET,
+  ensureKeyboardModalityTracking,
+  pressTargetHitSlop,
+  useReadableTextOn,
+  useResolvedKnobs,
+  wasKeyboardFocus,
+} from "@multiplatform.one/theme";
+import {
+  CaretLeftIcon,
   CaretRightIcon,
+  DotsSixVerticalIcon,
   FileIcon,
   FolderIcon,
   FolderOpenIcon,
 } from "@phosphor-icons/react";
+import { useDirection } from "../hooks/useDirection";
 import { useHotkey } from "@tanstack/react-hotkeys";
 import type { RegisterableHotkey } from "@tanstack/react-hotkeys";
-import React, { useCallback, useId, useMemo, useRef, useState } from "react";
-import { ListItem, Text, View, YStack, type YStackProps } from "tamagui";
+import React, {
+  useCallback,
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { useTranslation } from "react-i18next";
+import { Text, View, XStack, YStack, type YStackProps } from "tamagui";
+import { autoScrollVelocity } from "./kanbanDnd";
+import {
+  applyTreeMove,
+  describeTreeCancel,
+  describeTreeDragState,
+  flattenDndRows,
+  indicatorForTarget,
+  resolveTreeDrop,
+  subtreeIds,
+  treeDropTargetForY,
+  treeKeyboardLift,
+  treeKeyboardMove,
+  type TreeDragAnnouncement,
+  type TreeDragSession,
+  type TreeDropIndicator,
+  type TreeDropTarget,
+} from "./treeViewDnd";
+import { diffVisibleRows, flattenVisibleIds, isEmptyDiff } from "./treeViewMotion";
 
 /**
  * A node in a tree structure.
@@ -27,6 +65,10 @@ export interface TreeNode<T = unknown> {
   children?: TreeNode<T>[];
   /** Additional data */
   data?: T;
+  /** Optional leading icon (closed / leaf state) */
+  icon?: ReactNode;
+  /** Optional leading icon when the branch is expanded */
+  iconWhenExpanded?: ReactNode;
 }
 
 /**
@@ -41,16 +83,24 @@ export interface TreeViewHotkeys {
   expand?: RegisterableHotkey;
   /** Collapse focused node (default: ArrowLeft) */
   collapse?: RegisterableHotkey;
+  /** Toggle expand/collapse on focused branch (default: Space) */
+  toggle?: RegisterableHotkey;
   /** Select the focused node (default: Enter) */
   select?: RegisterableHotkey;
+  /** Move focus to first visible node (default: Home) */
+  first?: RegisterableHotkey;
+  /** Move focus to last visible node (default: End) */
+  last?: RegisterableHotkey;
 }
 
+export type TreeViewDisplay = "default" | "compressed";
+
 /**
  * Props for the generic TreeView component.
  *
  * @typeParam T - Additional data type stored on the nodes
  */
-export interface TreeViewProps<T = unknown> extends Omit<YStackProps, "children"> {
+export interface TreeViewProps<T = unknown> extends Omit<YStackProps, "children" | "display"> {
   /** Tree nodes to render */
   nodes: TreeNode<T>[];
   /** Render function for each node (defaults to rendering node.label) */
@@ -59,16 +109,34 @@ export interface TreeViewProps<T = unknown> extends Omit<YStackProps, "children"
   onNodeToggle?: (node: TreeNode<T>) => void;
   /** Called when a node is selected/clicked */
   onNodeSelect?: (node: TreeNode<T>) => void;
-  /** Estimated size of each row in pixels (default: 36) */
+  /**
+   * Called when a node is reordered by drag or keyboard. `target.index` is
+   * the insertion position among the destination parent's children with the
+   * moved node removed (0-based), so consumers can apply the move directly
+   * with `applyTreeMove(nodes, nodeId, target)`. Opt-in: without this prop no
+   * drag affordance renders and Space keeps its expand/collapse binding.
+   */
+  onNodeMove?: (nodeId: string, target: TreeDropTarget) => void;
+  /** Estimated size of each row in pixels */
   estimateSize?: number;
   /** Number of items to render outside visible area (default: 10) */
   overscan?: number;
-  /** Height of the scrollable container in pixels (default: 400) */
+  /** Height of the scrollable container in pixels */
   height?: number;
   /** Message shown when there are no nodes */
   emptyMessage?: string;
-  /** Initially expanded node IDs */
+  /** Initially expanded node IDs (wins over expandByDefault when provided) */
   defaultExpandedIds?: string[];
+  /** Expand every branch on initial load */
+  expandByDefault?: boolean;
+  /** Density — compressed uses smaller row/icon/type sizes (EUI-style) */
+  display?: TreeViewDisplay;
+  /** Show caret arrows next to branches (default: true) */
+  showExpansionArrows?: boolean;
+  /** Sticky selected node id (separate from keyboard focus) */
+  selectedId?: string;
+  /** Accessible name for the tree (also accepts aria-label via stack props) */
+  ariaLabel?: string;
   /** Configurable keyboard shortcut overrides */
   hotkeys?: TreeViewHotkeys;
 }
@@ -85,67 +153,233 @@ interface FlatNode<T> {
 }
 
 /**
- * Generic virtualized tree view component with keyboard navigation.
+ * One toggle's worth of row motion. `armed` renders rows at their previous
+ * position (FLIP invert) / hidden (enter) with the tween suppressed; one
+ * frame later `play` releases everyone to identity with
+ * `knobProps.transition` so the whole toggle tweens (Axiom 4 / LC-25).
+ */
+interface TreeMotion {
+  phase: "armed" | "play";
+  entering: Set<string>;
+  deltas: Map<string, number>;
+}
+
+/** Entering rows rise this many px into their slot (subtle, from the parent). */
+const ENTER_RISE_PX = -4;
+
+// ── Reorder interaction constants (gesture recognition, not animation
+// timing — LC-43's documented exemption; values mirror Kanban) ──────────
+
+/** Pixels of pointer travel before a press becomes a drag (clicks stay clicks below this). */
+const DRAG_THRESHOLD_PX = 4;
+/** Touch/pen hold before lift so vertical swipes still scroll the list. */
+const TOUCH_LONG_PRESS_MS = 200;
+/** Distance from a scroll edge where auto-scroll engages. */
+const AUTO_SCROLL_EDGE_PX = 48;
+/** Auto-scroll speed cap in px per frame; ramps with edge proximity. */
+const AUTO_SCROLL_MAX_SPEED = 16;
+
+// Raised drag shadow: the house $4 elevation tier (single light source,
+// blur = 2 × y-offset — Axiom 14 OPTICS). Explicit props because the lift is
+// a gesture state, not the tree's resting elevation knob; mirrors Kanban.
+const LIFT_SHADOW = {
+  shadowColor: "#000",
+  shadowOffset: { width: 0, height: 10 },
+  shadowOpacity: 0.15,
+  shadowRadius: 20,
+} as const;
+
+/** Active drag session UI state (pointer ghost or keyboard insertion point). */
+interface TreeDragUi<T> {
+  mode: "pointer" | "keyboard";
+  node: TreeNode<T>;
+  session: TreeDragSession;
+  /** Dragged node + descendants (dimmed; invalid as drop targets). */
+  subtree: Set<string>;
+  sourceDepth: number;
+  /**
+   * Container-relative x of the row box at lift (rows span edge-to-edge —
+   * SP-EDGE — so every settle destination shares this left edge).
+   */
+  homeX: number;
+  /** Ghost clone chrome size (pointer mode). */
+  width: number;
+  height: number;
+  indicator: TreeDropIndicator | null;
+  /** Ghost position in list-container coordinates (pointer mode, 1:1). */
+  ghost?: { x: number; y: number };
+}
+
+/** Overlay settle leap after a pointer drop/cancel (LC-42 FLIP settle). */
+interface TreeSettle<T> {
+  node: TreeNode<T>;
+  width: number;
+  height: number;
+  to: { x: number; y: number };
+  /** Row hidden while the overlay is its visual (committed drops only). */
+  hideId?: string;
+}
+
+function collectBranchIds<T>(items: TreeNode<T>[], into: Set<string> = new Set()): Set<string> {
+  for (const node of items) {
+    if ((node.children?.length ?? 0) > 0) {
+      into.add(node.id);
+      collectBranchIds(node.children!, into);
+    }
+  }
+  return into;
+}
+
+function defaultNodeIcon(hasChildren: boolean, isExpanded: boolean, iconSize: number): ReactNode {
+  if (hasChildren) {
+    return isExpanded ? (
+      <FolderOpenIcon size={iconSize} weight="duotone" />
+    ) : (
+      <FolderIcon size={iconSize} weight="duotone" />
+    );
+  }
+  return <FileIcon size={iconSize} weight="duotone" />;
+}
+
+/**
+ * Generic virtualized tree view (EUI-inspired flat directory chrome).
  *
  * Flattens the tree for virtualization using `@shopify/flash-list`
  * and uses `@tanstack/react-hotkeys` for keyboard navigation.
- * Each tree node renders as a Tamagui `ListItem` with indent and
- * expand/collapse disclosure.
+ * Rows are compact XStacks: optional expansion caret, node icon, label.
  *
- * @typeParam T - Additional data type stored on the nodes
+ * Motion (Axiom 4): expanding/collapsing a branch FLIPs the surviving rows
+ * from their previous offsets and fades the revealed children in, while the
+ * caret rotates — all tweened with `knobProps.transition`, transform/opacity
+ * only (native-safe). Initial mount renders settled (no wiggle) and
+ * `animation: none` / reduced motion renders every toggle instantly.
  *
- * @example
- * ```tsx
- * <TreeView
- *   nodes={treeData}
- *   renderNode={(node, depth) => <Text>{node.label}</Text>}
- *   onNodeSelect={(node) => console.log(node)}
- * />
- * ```
+ * Pressing a branch row toggles it (EUI/VS Code semantics), so the expand
+ * target is the full row — the caret itself is a non-interactive indicator.
+ *
+ * @typeParam T - Additional data type stored on the nodes
  */
 export function TreeView<T = unknown>({
   nodes,
-  renderNode = (node) => node.label,
+  renderNode,
   onNodeToggle,
   onNodeSelect,
+  onNodeMove,
   estimateSize: estimateSizeProp,
   overscan = 10,
   height: heightProp,
-  emptyMessage = "No items found",
+  emptyMessage: emptyMessageProp,
   defaultExpandedIds,
+  expandByDefault = false,
+  display = "default",
+  showExpansionArrows = true,
+  selectedId,
+  ariaLabel,
   hotkeys: hotkeyOverrides,
   ...stackProps
 }: TreeViewProps<T>) {
-  const { knobProps } = useResolvedKnobs();
+  const { t } = useTranslation();
+  const emptyMessage = emptyMessageProp ?? t("No items found");
+  const { knobProps, control } = useResolvedKnobs();
+  // UX-P02 / Axiom 15: the selected row paints `$accentBackground`; its label
+  // must sit on the accent fill with a luminance-computed foreground (the
+  // scheme `$color` ink measured 2.59:1 on the accent).
+  const onAccentLabel = useReadableTextOn("$accentBackground");
+  const transition = knobProps.transition;
+  const compressed = display === "compressed";
   const sz = knobProps.sizeToken;
-  const estimateSize = estimateSizeProp ?? (sz === "$3" ? 30 : sz === "$5" ? 44 : 36);
+
+  const estimateSize =
+    estimateSizeProp ??
+    (compressed ? (sz === "$5" ? 32 : 28) : sz === "$3" ? 30 : sz === "$5" ? 40 : 36);
   const height = heightProp ?? (sz === "$3" ? 320 : sz === "$5" ? 480 : 400);
-  const expandIconSize = sz === "$3" ? 16 : sz === "$5" ? 24 : 20;
+  const expandIconSize = compressed ? 14 : sz === "$3" ? 16 : sz === "$5" ? 20 : 18;
+  const nodeIconSize = compressed ? 14 : 18;
+  const caretSize = compressed ? 12 : 14;
+  // Collapsed caret encodes the expansion direction (inline-end), so it
+  // mirrors in RTL via glyph swap (useDirection, Axiom 15); the rotation
+  // sign flips with it so the expanded state still points down.
+  const isRTL = useDirection() === "rtl";
+  const CollapsedCaretIcon = isRTL ? CaretLeftIcon : CaretRightIcon;
+  const expandedCaretRotation = isRTL ? "-90deg" : "90deg";
+  const indentStep = compressed ? 12 : 16;
+  const labelFontSize = compressed ? 12 : 14;
+  // SP-EDGE row density (spec TreeView rows): the space knob steps the row
+  // padding — never an outer tree inset (LC-02). House space-map pattern
+  // (getTableCellPadding precedent); medium keeps the previous 6/8
+  // (4/6 compressed) geometry so default density is unchanged.
+  const rowPad =
+    (compressed
+      ? { small: { y: 3, x: 4 }, medium: { y: 4, x: 6 }, large: { y: 6, x: 10 } }
+      : { small: { y: 4, x: 6 }, medium: { y: 6, x: 8 }, large: { y: 10, x: 13 } })[
+      knobProps.space
+    ] ?? (compressed ? { y: 4, x: 6 } : { y: 6, x: 8 });
+  const rowPadY = rowPad.y;
+  const rowPadX = rowPad.x;
+
   const treeId = useId();
   const containerRef = useRef<HTMLDivElement>(null);
   const flashListRef = useRef<FlashListRef<FlatNode<T>>>(null);
   const [focusedIndex, setFocusedIndex] = useState(-1);
-  const [expandedIds, setExpandedIds] = useState<Set<string>>(
-    () => new Set(defaultExpandedIds ?? []),
+  // Axiom 12: the tree is one tab stop (aria-activedescendant pattern) — but
+  // Tab-in with no active row painted NOTHING (ring suppressed on the
+  // container, no row highlighted until an arrow was pressed). On
+  // keyboard-origin focus, light up the first row so position is visible.
+  if (typeof document !== "undefined") ensureKeyboardModalityTracking();
+  const handleContainerFocus = useCallback(() => {
+    if (!wasKeyboardFocus()) return;
+    setFocusedIndex((prev) => (prev < 0 ? 0 : prev));
+  }, []);
+  const [expandedIds, setExpandedIds] = useState<Set<string>>(() => {
+    if (defaultExpandedIds) return new Set(defaultExpandedIds);
+    if (expandByDefault) return collectBranchIds(nodes);
+    return new Set();
+  });
+
+  // ── Expand/collapse motion (FLIP + enter fade; Axiom 4) ────────────────
+  const [motion, setMotion] = useState<TreeMotion | null>(null);
+  const rowHeights = useRef(new Map<string, number>());
+  const getRowHeight = useCallback(
+    (id: string) => rowHeights.current.get(id) ?? estimateSize,
+    [estimateSize],
   );
 
   const toggleNode = useCallback(
     (node: TreeNode<T>) => {
-      setExpandedIds((prev) => {
-        const next = new Set(prev);
-        if (next.has(node.id)) {
-          next.delete(node.id);
-        } else {
-          next.add(node.id);
-        }
-        return next;
-      });
+      const next = new Set(expandedIds);
+      if (next.has(node.id)) {
+        next.delete(node.id);
+      } else {
+        next.add(node.id);
+      }
+      // Mount never animates and `animation: none` / reduced motion skips
+      // the machine entirely — the toggle then renders in one jump.
+      if (transition) {
+        const diff = diffVisibleRows(
+          flattenVisibleIds(nodes, expandedIds),
+          flattenVisibleIds(nodes, next),
+          getRowHeight,
+        );
+        setMotion(isEmptyDiff(diff) ? null : { phase: "armed", ...diff });
+      } else {
+        setMotion(null);
+      }
+      setExpandedIds(next);
       onNodeToggle?.(node);
     },
-    [onNodeToggle],
+    [expandedIds, nodes, transition, getRowHeight, onNodeToggle],
   );
 
-  // Flatten tree into a list respecting expanded state
+  // Release the FLIP one frame after the armed styles paint so the tween
+  // runs from the previous layout to the new one.
+  useLayoutEffect(() => {
+    if (motion?.phase !== "armed") return;
+    const raf = requestAnimationFrame(() => {
+      setMotion((m) => (m && m.phase === "armed" ? { ...m, phase: "play" } : m));
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [motion]);
+
   const flatNodes = useMemo(() => {
     const result: FlatNode<T>[] = [];
 
@@ -164,7 +398,6 @@ export function TreeView<T = unknown>({
     return result;
   }, [nodes, expandedIds]);
 
-  // Scroll to focused item
   const scrollToIndex = useCallback(
     (index: number) => {
       if (index >= 0 && index < flatNodes.length) {
@@ -174,7 +407,491 @@ export function TreeView<T = unknown>({
     [flatNodes.length],
   );
 
-  // Keyboard navigation via @tanstack/react-hotkeys
+  // ── Drag-reorder (LC-42 DRAG-ANATOMY / LC-43 DND-A11Y) ─────────────────
+  // Opt-in via `onNodeMove`. The ghost is an overlay clone outside the
+  // FlashList (virtualization-safe); hit-testing is pure math over the
+  // flattened rows + measured heights, so no DOM traversal of virtual cells.
+  const canReorder = Boolean(onNodeMove);
+
+  const [dragUi, setDragUi] = useState<TreeDragUi<T> | null>(null);
+  const [settle, setSettle] = useState<TreeSettle<T> | null>(null);
+  const [announcement, setAnnouncement] = useState("");
+  // Scroll offset snapshot that re-renders the drop indicator while the list
+  // scrolls mid-drag (the ref below is the always-current value).
+  const [dragScrollY, setDragScrollY] = useState(0);
+  const dragUiRef = useRef<TreeDragUi<T> | null>(null);
+  dragUiRef.current = dragUi;
+  const scrollOffsetRef = useRef(0);
+  const pointerPosRef = useRef({ x: 0, y: 0 });
+  const grabOffsetRef = useRef({ x: 0, y: 0 });
+  const suppressClickRef = useRef(false);
+  const sessionCleanupRef = useRef<(() => void) | null>(null);
+  const autoScrollRafRef = useRef<number | null>(null);
+  // A committed move's FLIP arms only once the consumer applies the move
+  // (guarded by the expected visible order — a lie is worse than a jump).
+  const pendingMoveFlipRef = useRef<{ prevIds: string[]; expectedIds: string[] } | null>(null);
+
+  useEffect(() => () => sessionCleanupRef.current?.(), []);
+
+  const dndRows = useMemo(() => flattenDndRows(nodes, expandedIds), [nodes, expandedIds]);
+
+  /** Content-coordinate top of the visible row / insertion line at a flat index. */
+  const topOfFlatIndex = useCallback(
+    (flatIndex: number): number => {
+      let top = 0;
+      for (let i = 0; i < flatIndex && i < flatNodes.length; i++) {
+        top += getRowHeight(flatNodes[i].node.id);
+      }
+      return top;
+    },
+    [flatNodes, getRowHeight],
+  );
+
+  const announce = useCallback(
+    (a: TreeDragAnnouncement) => {
+      const parent = a.parent ?? t("top level");
+      const text =
+        a.type === "lift"
+          ? t(
+              "Lifted {{node}} in {{parent}}, position {{position}} of {{count}}. Use arrow keys to move, space to drop, escape to cancel.",
+              { ...a, parent },
+            )
+          : a.type === "move"
+            ? t("Moved {{node}} to {{parent}}, position {{position}} of {{count}}.", {
+                ...a,
+                parent,
+              })
+            : a.type === "drop"
+              ? t("Dropped {{node}} in {{parent}}, position {{position}} of {{count}}.", {
+                  ...a,
+                  parent,
+                })
+              : t("Movement cancelled. {{node}} returned to {{parent}}.", { ...a, parent });
+      setAnnouncement(text);
+    },
+    [t],
+  );
+
+  /** Pointer y (client coords) → drop target + indicator, or null over the dragged subtree. */
+  const hitTest = useCallback(
+    (
+      clientY: number,
+      ui: TreeDragUi<T>,
+    ): { target: TreeDropTarget; indicator: TreeDropIndicator } | null => {
+      const rect = (containerRef.current as HTMLElement | null)?.getBoundingClientRect?.();
+      if (!rect) return null;
+      return treeDropTargetForY({
+        localY: clientY - rect.top + scrollOffsetRef.current,
+        rows: dndRows,
+        getHeight: getRowHeight,
+        session: ui.session,
+        draggedSubtree: ui.subtree,
+      });
+    },
+    [dndRows, getRowHeight],
+  );
+
+  // ── Auto-scroll near list edges (velocity ramps with proximity) ────────
+
+  const stopAutoScroll = useCallback(() => {
+    if (autoScrollRafRef.current !== null) cancelAnimationFrame(autoScrollRafRef.current);
+    autoScrollRafRef.current = null;
+  }, []);
+
+  const startAutoScroll = useCallback(() => {
+    stopAutoScroll();
+    const tick = () => {
+      const ui = dragUiRef.current;
+      if (!ui || ui.mode !== "pointer") {
+        autoScrollRafRef.current = null;
+        return;
+      }
+      const rect = (containerRef.current as HTMLElement | null)?.getBoundingClientRect?.();
+      if (rect) {
+        const vy = autoScrollVelocity({
+          pos: pointerPosRef.current.y,
+          start: rect.top,
+          end: rect.bottom,
+          edge: AUTO_SCROLL_EDGE_PX,
+          maxSpeed: AUTO_SCROLL_MAX_SPEED,
+        });
+        if (vy !== 0) {
+          const max = Math.max(0, topOfFlatIndex(flatNodes.length) - rect.height);
+          const next = Math.min(max, Math.max(0, scrollOffsetRef.current + vy));
+          if (next !== scrollOffsetRef.current) {
+            scrollOffsetRef.current = next;
+            flashListRef.current?.scrollToOffset({ offset: next, animated: false });
+            setDragScrollY(next);
+            const hit = hitTest(pointerPosRef.current.y, ui);
+            if (hit) {
+              setDragUi((prev) =>
+                prev
+                  ? {
+                      ...prev,
+                      session: { ...prev.session, target: hit.target },
+                      indicator: hit.indicator,
+                    }
+                  : prev,
+              );
+            }
+          }
+        }
+      }
+      autoScrollRafRef.current = requestAnimationFrame(tick);
+    };
+    autoScrollRafRef.current = requestAnimationFrame(tick);
+  }, [flatNodes.length, hitTest, stopAutoScroll, topOfFlatIndex]);
+
+  // ── Drop / cancel ──────────────────────────────────────────────────────
+
+  const endDrag = useCallback(
+    (commit: boolean) => {
+      const ui = dragUiRef.current;
+      if (!ui) return;
+      stopAutoScroll();
+      sessionCleanupRef.current?.();
+      sessionCleanupRef.current = null;
+
+      const resolved = resolveTreeDrop(ui.session);
+      const canCommit = commit && resolved.commit && Boolean(onNodeMove);
+
+      // Destination geometry from the post-move layout so the overlay
+      // settles exactly onto the row's final slot.
+      let dest: { x: number; y: number } | null = null;
+      let expectedIds: string[] | null = null;
+      if (canCommit) {
+        const nextNodes = applyTreeMove(nodes, ui.session.nodeId, resolved.to);
+        expectedIds = flattenVisibleIds(nextNodes, expandedIds);
+        const destFlat = expectedIds.indexOf(ui.session.nodeId);
+        const parentRow =
+          resolved.to.parentId === null
+            ? null
+            : (dndRows.find((r) => r.id === resolved.to.parentId) ?? null);
+        let top = 0;
+        if (destFlat >= 0) {
+          for (let i = 0; i < destFlat; i++) top += getRowHeight(expectedIds[i]);
+        } else if (parentRow) {
+          // Moved into a collapsed parent: the row will not be visible —
+          // settle the ghost onto the parent row instead.
+          top = topOfFlatIndex(dndRows.indexOf(parentRow));
+        }
+        dest = { x: ui.homeX, y: top - scrollOffsetRef.current };
+      } else {
+        const originFlat = flatNodes.findIndex((f) => f.node.id === ui.session.nodeId);
+        dest = {
+          x: ui.homeX,
+          y: (originFlat >= 0 ? topOfFlatIndex(originFlat) : 0) - scrollOffsetRef.current,
+        };
+      }
+
+      setDragUi(null);
+      dragUiRef.current = null;
+
+      if (ui.mode === "pointer" && dest) {
+        setSettle({
+          node: ui.node,
+          width: ui.width,
+          height: ui.height,
+          to: dest,
+          hideId: canCommit ? ui.session.nodeId : undefined,
+        });
+      }
+
+      if (canCommit && expectedIds) {
+        if (transition) {
+          pendingMoveFlipRef.current = {
+            prevIds: flattenVisibleIds(nodes, expandedIds),
+            expectedIds,
+          };
+        }
+        announce(describeTreeDragState("drop", ui.session, nodes, ui.node.label));
+        onNodeMove?.(ui.session.nodeId, resolved.to);
+      } else {
+        announce(describeTreeCancel(ui.session, nodes, ui.node.label));
+      }
+    },
+    [
+      announce,
+      dndRows,
+      expandedIds,
+      flatNodes,
+      getRowHeight,
+      nodes,
+      onNodeMove,
+      stopAutoScroll,
+      topOfFlatIndex,
+      transition,
+    ],
+  );
+
+  // Arm the move FLIP once the consumer applies the move: surviving rows
+  // tween from their pre-move offsets (transform-only, LC-42). If the
+  // consumer renders anything other than the expected order, drop the FLIP.
+  useLayoutEffect(() => {
+    const pending = pendingMoveFlipRef.current;
+    if (!pending) return;
+    const currentIds = flatNodes.map((f) => f.node.id);
+    const same = (a: readonly string[], b: readonly string[]) =>
+      a.length === b.length && a.every((v, i) => v === b[i]);
+    if (same(currentIds, pending.prevIds)) return; // move not applied yet
+    pendingMoveFlipRef.current = null;
+    if (!same(currentIds, pending.expectedIds)) return;
+    const diff = diffVisibleRows(pending.prevIds, pending.expectedIds, getRowHeight);
+    if (!isEmptyDiff(diff)) setMotion({ phase: "armed", ...diff });
+  }, [flatNodes, getRowHeight]);
+
+  // Settle completion: watch the overlay transform until it stops changing
+  // (mechanical spring-rest detection — no timing constants). With
+  // animation=none the position lands in one frame and this exits instantly.
+  useEffect(() => {
+    if (!settle) return;
+    const el = (containerRef.current as HTMLElement | null)?.querySelector?.(
+      "[data-treeview-overlay]",
+    ) as HTMLElement | null;
+    if (!el || typeof requestAnimationFrame === "undefined") {
+      setSettle(null);
+      return;
+    }
+    let last: string | null = null;
+    let stableFrames = 0;
+    let raf = 0;
+    const check = () => {
+      const current = getComputedStyle(el).transform;
+      if (current === last) stableFrames += 1;
+      else {
+        stableFrames = 0;
+        last = current;
+      }
+      if (stableFrames >= 3) {
+        setSettle(null);
+        return;
+      }
+      raf = requestAnimationFrame(check);
+    };
+    raf = requestAnimationFrame(check);
+    return () => cancelAnimationFrame(raf);
+  }, [settle]);
+
+  // ── Pointer drag session (drag handle → window listeners) ──────────────
+
+  const beginPointerDrag = useCallback(
+    (flat: FlatNode<T>, rowEl: HTMLElement, clientX: number, clientY: number): boolean => {
+      const container = containerRef.current as HTMLElement | null;
+      if (!container?.getBoundingClientRect) return false;
+      const session = treeKeyboardLift(nodes, flat.node.id);
+      if (!session) return false;
+      const rowRect = rowEl.getBoundingClientRect();
+      const containerRect = container.getBoundingClientRect();
+      grabOffsetRef.current = { x: clientX - rowRect.left, y: clientY - rowRect.top };
+      pointerPosRef.current = { x: clientX, y: clientY };
+      const ui: TreeDragUi<T> = {
+        mode: "pointer",
+        node: flat.node,
+        session,
+        subtree: subtreeIds(nodes, flat.node.id),
+        sourceDepth: flat.depth,
+        homeX: rowRect.left - containerRect.left,
+        width: rowRect.width,
+        height: rowRect.height,
+        indicator: null,
+        ghost: {
+          x: rowRect.left - containerRect.left,
+          y: rowRect.top - containerRect.top,
+        },
+      };
+      setSettle(null);
+      setDragScrollY(scrollOffsetRef.current);
+      setDragUi(ui);
+      dragUiRef.current = ui;
+      announce(describeTreeDragState("lift", session, nodes, flat.node.label));
+      startAutoScroll();
+      return true;
+    },
+    [announce, nodes, startAutoScroll],
+  );
+
+  const handleDragHandlePointerDown = useCallback(
+    (flat: FlatNode<T>, e: any) => {
+      if (!canReorder || typeof window === "undefined") return;
+      if (e.button !== undefined && e.button !== 0) return;
+      if (dragUiRef.current) return;
+      sessionCleanupRef.current?.();
+      e.stopPropagation?.();
+
+      const handleEl = e.currentTarget as HTMLElement;
+      const rowEl = (handleEl.closest?.("[data-treeview-row]") ?? handleEl) as HTMLElement;
+      const startX = e.clientX as number;
+      const startY = e.clientY as number;
+      const pointerType: string = e.pointerType ?? "mouse";
+      let lifted = false;
+      let longPressTimer: ReturnType<typeof setTimeout> | null = null;
+      let prevUserSelect = "";
+      let prevCursor = "";
+
+      const lift = (x: number, y: number) => {
+        if (lifted) return;
+        lifted = beginPointerDrag(flat, rowEl, x, y);
+        if (!lifted) return;
+        prevUserSelect = document.body.style.userSelect;
+        document.body.style.userSelect = "none";
+        prevCursor = document.documentElement.style.cursor;
+        document.documentElement.style.cursor = "grabbing";
+      };
+
+      const teardown = () => {
+        if (longPressTimer !== null) clearTimeout(longPressTimer);
+        window.removeEventListener("pointermove", onMove);
+        window.removeEventListener("pointerup", onUp);
+        window.removeEventListener("pointercancel", onCancel);
+        window.removeEventListener("keydown", onKey, true);
+        window.removeEventListener("touchmove", onTouchMove);
+        window.removeEventListener("contextmenu", onContextMenu, true);
+        sessionCleanupRef.current = null;
+        if (lifted) {
+          document.body.style.userSelect = prevUserSelect;
+          document.documentElement.style.cursor = prevCursor;
+          suppressClickRef.current = true;
+          setTimeout(() => {
+            suppressClickRef.current = false;
+          }, 0);
+        }
+      };
+
+      const onMove = (me: PointerEvent) => {
+        pointerPosRef.current = { x: me.clientX, y: me.clientY };
+        if (!lifted) {
+          const travelled = Math.hypot(me.clientX - startX, me.clientY - startY);
+          if (pointerType === "mouse") {
+            if (travelled >= DRAG_THRESHOLD_PX) lift(me.clientX, me.clientY);
+          } else if (travelled >= DRAG_THRESHOLD_PX) {
+            // Finger moved before the hold elapsed — this is a scroll, not a drag.
+            teardown();
+          }
+          if (!lifted) return;
+        }
+        const containerRect = (
+          containerRef.current as HTMLElement | null
+        )?.getBoundingClientRect?.();
+        const ghost = {
+          x: me.clientX - (containerRect?.left ?? 0) - grabOffsetRef.current.x,
+          y: me.clientY - (containerRect?.top ?? 0) - grabOffsetRef.current.y,
+        };
+        const ui = dragUiRef.current;
+        if (!ui) return;
+        const hit = hitTest(me.clientY, ui);
+        setDragUi((prev) =>
+          prev
+            ? {
+                ...prev,
+                ghost,
+                ...(hit && {
+                  session: { ...prev.session, target: hit.target },
+                  indicator: hit.indicator,
+                }),
+              }
+            : prev,
+        );
+      };
+
+      const onUp = () => {
+        const wasLifted = lifted;
+        teardown();
+        if (wasLifted) endDrag(true);
+      };
+
+      const onCancel = () => {
+        const wasLifted = lifted;
+        teardown();
+        if (wasLifted) endDrag(false);
+      };
+
+      const onKey = (ke: KeyboardEvent) => {
+        if (ke.key !== "Escape") return;
+        ke.stopPropagation();
+        const wasLifted = lifted;
+        teardown();
+        if (wasLifted) endDrag(false);
+      };
+
+      // While lifted, claim touch moves so the page/list does not scroll out
+      // from under the drag (registered non-passive on purpose).
+      const onTouchMove = (te: TouchEvent) => {
+        if (lifted) te.preventDefault();
+      };
+      const onContextMenu = (ce: Event) => {
+        if (lifted || longPressTimer !== null) ce.preventDefault();
+      };
+
+      window.addEventListener("pointermove", onMove);
+      window.addEventListener("pointerup", onUp);
+      window.addEventListener("pointercancel", onCancel);
+      window.addEventListener("keydown", onKey, true);
+      window.addEventListener("touchmove", onTouchMove, { passive: false });
+      window.addEventListener("contextmenu", onContextMenu, true);
+      sessionCleanupRef.current = () => {
+        const wasLifted = lifted;
+        teardown();
+        if (wasLifted) endDrag(false);
+      };
+
+      if (pointerType !== "mouse") {
+        longPressTimer = setTimeout(() => {
+          longPressTimer = null;
+          const p = pointerPosRef.current;
+          lift(p.x || startX, p.y || startY);
+        }, TOUCH_LONG_PRESS_MS);
+        pointerPosRef.current = { x: startX, y: startY };
+      }
+    },
+    [beginPointerDrag, canReorder, endDrag, hitTest],
+  );
+
+  // ── Keyboard drag (kanban grammar mapped onto the tree — LC-43) ────────
+
+  const liftFocusedNode = useCallback((): boolean => {
+    if (!canReorder || dragUiRef.current) return false;
+    const flat = flatNodes[focusedIndex];
+    if (!flat) return false;
+    const session = treeKeyboardLift(nodes, flat.node.id);
+    if (!session) return false;
+    const ui: TreeDragUi<T> = {
+      mode: "keyboard",
+      node: flat.node,
+      session,
+      subtree: subtreeIds(nodes, flat.node.id),
+      sourceDepth: flat.depth,
+      homeX: 0,
+      width: 0,
+      height: getRowHeight(flat.node.id),
+      indicator: indicatorForTarget(dndRows, session, session.target),
+    };
+    setSettle(null);
+    setDragScrollY(scrollOffsetRef.current);
+    setDragUi(ui);
+    dragUiRef.current = ui;
+    announce(describeTreeDragState("lift", session, nodes, flat.node.label));
+    return true;
+  }, [announce, canReorder, dndRows, flatNodes, focusedIndex, getRowHeight, nodes]);
+
+  const moveKeyboardDrag = useCallback(
+    (direction: "up" | "down" | "left" | "right"): boolean => {
+      const ui = dragUiRef.current;
+      if (!ui || ui.mode !== "keyboard") return false;
+      const next = treeKeyboardMove(ui.session, nodes, direction);
+      if (next === ui.session) return true; // boundary no-op still swallows the key
+      const indicator = indicatorForTarget(dndRows, next, next.target);
+      const updated: TreeDragUi<T> = { ...ui, session: next, indicator };
+      setDragUi(updated);
+      dragUiRef.current = updated;
+      if (indicator.kind === "line" && flatNodes.length > 0) {
+        scrollToIndex(Math.min(indicator.flatIndex, flatNodes.length - 1));
+      }
+      announce(describeTreeDragState("move", next, nodes, ui.node.label));
+      return true;
+    },
+    [announce, dndRows, flatNodes.length, nodes, scrollToIndex],
+  );
+
   const hotkeyOpts = {
     target: containerRef as React.RefObject<HTMLElement | null>,
   };
@@ -182,6 +899,7 @@ export function TreeView<T = unknown>({
   useHotkey(
     hotkeyOverrides?.next ?? "ArrowDown",
     () => {
+      if (moveKeyboardDrag("down")) return;
       setFocusedIndex((prev) => {
         const next = prev < 0 ? 0 : Math.min(prev + 1, flatNodes.length - 1);
         scrollToIndex(next);
@@ -194,6 +912,7 @@ export function TreeView<T = unknown>({
   useHotkey(
     hotkeyOverrides?.prev ?? "ArrowUp",
     () => {
+      if (moveKeyboardDrag("up")) return;
       setFocusedIndex((prev) => {
         const next = prev < 0 ? flatNodes.length - 1 : Math.max(prev - 1, 0);
         scrollToIndex(next);
@@ -206,6 +925,8 @@ export function TreeView<T = unknown>({
   useHotkey(
     hotkeyOverrides?.expand ?? "ArrowRight",
     () => {
+      // While lifted: nest into the previous sibling (kanban grammar).
+      if (moveKeyboardDrag("right")) return;
       if (focusedIndex >= 0 && focusedIndex < flatNodes.length) {
         const { node, hasChildren, isExpanded } = flatNodes[focusedIndex];
         if (hasChildren && !isExpanded) {
@@ -219,6 +940,8 @@ export function TreeView<T = unknown>({
   useHotkey(
     hotkeyOverrides?.collapse ?? "ArrowLeft",
     () => {
+      // While lifted: un-nest to after the current parent.
+      if (moveKeyboardDrag("left")) return;
       if (focusedIndex >= 0 && focusedIndex < flatNodes.length) {
         const { node, hasChildren, isExpanded } = flatNodes[focusedIndex];
         if (hasChildren && isExpanded) {
@@ -229,9 +952,36 @@ export function TreeView<T = unknown>({
     hotkeyOpts,
   );
 
+  useHotkey(
+    hotkeyOverrides?.toggle ?? "Space",
+    () => {
+      // With reorder enabled, Space follows the WAI-ARIA drag grammar
+      // (lift/drop); expand/collapse stays on ArrowRight/ArrowLeft + press.
+      if (dragUiRef.current?.mode === "keyboard") {
+        endDrag(true);
+        return;
+      }
+      if (canReorder) {
+        liftFocusedNode();
+        return;
+      }
+      if (focusedIndex >= 0 && focusedIndex < flatNodes.length) {
+        const { node, hasChildren } = flatNodes[focusedIndex];
+        if (hasChildren) {
+          toggleNode(node);
+        }
+      }
+    },
+    hotkeyOpts,
+  );
+
   useHotkey(
     hotkeyOverrides?.select ?? "Enter",
     () => {
+      if (dragUiRef.current?.mode === "keyboard") {
+        endDrag(true);
+        return;
+      }
       if (focusedIndex >= 0 && focusedIndex < flatNodes.length) {
         onNodeSelect?.(flatNodes[focusedIndex].node);
       }
@@ -239,27 +989,70 @@ export function TreeView<T = unknown>({
     hotkeyOpts,
   );
 
+  useHotkey(
+    "Escape",
+    () => {
+      if (dragUiRef.current?.mode === "keyboard") endDrag(false);
+    },
+    hotkeyOpts,
+  );
+
+  useHotkey(
+    hotkeyOverrides?.first ?? "Home",
+    () => {
+      if (flatNodes.length > 0) {
+        setFocusedIndex(0);
+        scrollToIndex(0);
+      }
+    },
+    hotkeyOpts,
+  );
+
+  useHotkey(
+    hotkeyOverrides?.last ?? "End",
+    () => {
+      if (flatNodes.length > 0) {
+        const last = flatNodes.length - 1;
+        setFocusedIndex(last);
+        scrollToIndex(last);
+      }
+    },
+    hotkeyOpts,
+  );
+
   if (nodes.length === 0) {
-    return (
-      <YStack {...knobProps.panelPadding} alignItems="center" {...stackProps}>
-        <Text color={componentColors.text.muted}>{emptyMessage}</Text>
-      </YStack>
-    );
+    return <EmptyState compact title={emptyMessage} {...stackProps} />;
   }
 
-  // Clamp focused index if flat list shrunk
   const effectiveFocused = focusedIndex >= flatNodes.length ? -1 : focusedIndex;
+  const resolvedAriaLabel =
+    ariaLabel ??
+    (typeof (stackProps as { "aria-label"?: string })["aria-label"] === "string"
+      ? (stackProps as { "aria-label"?: string })["aria-label"]
+      : undefined);
 
+  const overlayNode = dragUi?.mode === "pointer" ? dragUi.node : settle?.node;
+  const overlayHasChildren = ((overlayNode?.children?.length ?? 0) as number) > 0;
+  // Handle glyphs stay small; the hit target reaches the 44px floor via
+  // negative outset + hitSlop (DG-LAY-04 pattern shared with Chip/Button).
+  const handleOutset = Math.max(0, (MIN_PRESS_TARGET - estimateSize) / 2);
+
+  // Rows span edge-to-edge inside the frame (SP-EDGE / LC-01): the container
+  // owns only its border; rows own their inset, so hover/selection fills and
+  // hit targets reach both edges.
   return (
-    <YStack {...knobProps.borderRadius} {...stackProps}>
+    <YStack {...knobProps.borderRadius} overflow="hidden" {...stackProps}>
       <View
         ref={containerRef as any}
         role="tree"
+        aria-label={resolvedAriaLabel}
         aria-activedescendant={
           effectiveFocused >= 0 ? `${treeId}-node-${effectiveFocused}` : undefined
         }
         tabIndex={0}
         outlineWidth={0}
+        onFocus={handleContainerFocus}
+        position="relative"
         style={{
           height,
         }}
@@ -269,67 +1062,280 @@ export function TreeView<T = unknown>({
           data={flatNodes}
           drawDistance={overscan * estimateSize}
           keyExtractor={(item) => item.node.id}
-          extraData={effectiveFocused}
+          extraData={{ focused: effectiveFocused, selectedId, expandedIds, motion, dragUi, settle }}
+          {...(canReorder && {
+            onScroll: (e: any) => {
+              const y = e?.nativeEvent?.contentOffset?.y;
+              if (typeof y === "number") {
+                scrollOffsetRef.current = y;
+                if (dragUiRef.current) setDragScrollY(y);
+              }
+            },
+            scrollEventThrottle: 16,
+          })}
           renderItem={({ item, index }) => {
             const { node, depth, hasChildren, isExpanded } = item;
             const isFocused = effectiveFocused === index;
+            const isSelected = selectedId !== undefined && selectedId === node.id;
+            const leadingIcon =
+              hasChildren && isExpanded && node.iconWhenExpanded
+                ? node.iconWhenExpanded
+                : node.icon
+                  ? node.icon
+                  : defaultNodeIcon(hasChildren, isExpanded, nodeIconSize);
+
+            const labelContent = renderNode ? (
+              renderNode(node, depth)
+            ) : (
+              <Text
+                fontSize={labelFontSize}
+                color={isSelected && onAccentLabel ? onAccentLabel : "$color"}
+                numberOfLines={1}
+                flexShrink={1}
+              >
+                {node.label}
+              </Text>
+            );
+
+            // FLIP/enter styles for this toggle (identity when idle).
+            const armed = motion?.phase === "armed";
+            const entering = motion?.entering.has(node.id) ?? false;
+            const delta = motion?.deltas.get(node.id) ?? 0;
+            const rowY = armed ? (entering ? ENTER_RISE_PX : delta) : 0;
+            // Drag states: the lifted subtree dims in place (the ghost is the
+            // carried visual); the moved row hides while the overlay settles
+            // onto its final slot.
+            const inDraggedSubtree = dragUi?.subtree.has(node.id) ?? false;
+            const isSettleHidden = settle?.hideId === node.id;
+            const isDropParent =
+              dragUi?.indicator?.kind === "into" && dragUi.indicator.parentId === node.id;
+            const rowOpacity = isSettleHidden
+              ? 0
+              : armed && entering
+                ? 0
+                : inDraggedSubtree
+                  ? 0.4
+                  : 1;
+            // Armed rows apply their inverted offset instantly; everyone else
+            // keeps the knob tween (also covers hover/press fills — A-STATE).
+            const rowTransition = armed && (entering || delta !== 0) ? "none" : transition;
+
             return (
-              <ListItem
+              <XStack
+                // Remount when a recycled cell switches nodes so state fills
+                // and the caret never tween across two different rows.
+                key={node.id}
                 id={`${treeId}-node-${index}`}
+                {...{ "data-treeview-row": node.id }}
+                {...(isDropParent && { "data-treeview-drop-parent": "true" })}
                 role="treeitem"
                 aria-expanded={hasChildren ? isExpanded : undefined}
-                aria-selected={isFocused}
+                aria-selected={isSelected}
                 aria-level={depth + 1}
-                size={knobProps.sizeToken}
-                paddingLeft={`$${Math.max(depth * 4, 1) as 1}`}
-                icon={
+                alignItems="center"
+                minHeight={estimateSize}
+                paddingVertical={rowPadY}
+                paddingInlineEnd={rowPadX}
+                paddingInlineStart={rowPadX + depth * indentStep}
+                gap="$2"
+                cursor="pointer"
+                y={rowY}
+                opacity={rowOpacity}
+                transition={rowTransition as any}
+                onLayout={(e: any) => {
+                  const h = e?.nativeEvent?.layout?.height;
+                  if (typeof h === "number" && h > 0) rowHeights.current.set(node.id, h);
+                }}
+                backgroundColor={
+                  // Nest-into parent highlight wins while a drag is active
+                  // (LC-42 drop-target affordance).
+                  isDropParent
+                    ? componentColors.interactive.background
+                    : isSelected
+                      ? "$accentBackground"
+                      : isFocused
+                        ? componentColors.interactive.background
+                        : "transparent"
+                }
+                // Row hover/press come from the knob state recipes (A-STATE);
+                // selection tint stays sticky underneath them.
+                hoverStyle={{
+                  ...(control.hoverKnobProps as any),
+                  ...(isSelected && { backgroundColor: "$accentBackground" }),
+                }}
+                pressStyle={{
+                  ...(control.pressKnobProps as any),
+                  ...(isSelected && { backgroundColor: "$accentBackground" }),
+                }}
+                // Focus ring (Axiom 12): ≥2px, non-removable — also visible on
+                // selected rows; inset so the virtualized viewport can't clip it.
+                outlineWidth={isFocused ? 2 : 0}
+                outlineStyle="solid"
+                outlineColor="$outlineColor"
+                outlineOffset={-2}
+                onPress={() => {
+                  // A completed drag's terminating click is not a selection.
+                  if (suppressClickRef.current) return;
+                  setFocusedIndex(index);
+                  // Branch rows toggle on press (EUI/VS Code semantics): the
+                  // whole row is the expand target, not a sub-44px caret.
+                  if (hasChildren) toggleNode(node);
+                  onNodeSelect?.(node);
+                }}
+              >
+                {showExpansionArrows ? (
                   hasChildren ? (
-                    <View flexDirection="row" alignItems="center" gap="$1">
-                      <View
-                        onPress={() => toggleNode(node)}
-                        width={expandIconSize}
-                        height={expandIconSize}
-                        alignItems="center"
-                        justifyContent="center"
-                        cursor="pointer"
-                      >
-                        {isExpanded ? (
-                          <CaretDownIcon size={14} weight="bold" />
-                        ) : (
-                          <CaretRightIcon size={14} weight="bold" />
-                        )}
-                      </View>
-                      {isExpanded ? (
-                        <FolderOpenIcon size={18} weight="duotone" />
-                      ) : (
-                        <FolderIcon size={18} weight="duotone" />
-                      )}
+                    <View
+                      width={expandIconSize}
+                      height={expandIconSize}
+                      alignItems="center"
+                      justifyContent="center"
+                      pointerEvents="none"
+                      // Indicator only — the row is the toggle target. One
+                      // caret that rotates (transform, knob tween) instead of
+                      // an icon swap, so the state change is continuous.
+                      rotate={isExpanded ? expandedCaretRotation : "0deg"}
+                      transition={transition as any}
+                    >
+                      <CollapsedCaretIcon size={caretSize} weight="bold" />
                     </View>
                   ) : (
-                    <View flexDirection="row" alignItems="center" gap="$1">
-                      <View style={{ width: expandIconSize }} />
-                      <FileIcon size={18} weight="duotone" />
-                    </View>
+                    <View width={expandIconSize} height={expandIconSize} />
                   )
-                }
-                title={renderNode(node, depth) as any}
-                backgroundColor={
-                  isFocused
-                    ? "$accentBackground"
-                    : index % 2 === 1
-                      ? ({ backgroundColor: componentColors.surface.background }?.backgroundColor ??
-                        componentColors.surface.background)
-                      : "transparent"
-                }
-                hoverStyle={{ backgroundColor: componentColors.interactive.background }}
-                pressStyle={{ backgroundColor: componentColors.interactive.hover }}
-                {...knobProps.borderRadius}
-                cursor="pointer"
-                onPress={() => onNodeSelect?.(node)}
-              />
+                ) : null}
+
+                <View
+                  width={nodeIconSize + 2}
+                  height={nodeIconSize + 2}
+                  alignItems="center"
+                  justifyContent="center"
+                  flexShrink={0}
+                >
+                  {leadingIcon}
+                </View>
+
+                <View flex={1} minWidth={0} justifyContent="center">
+                  {labelContent}
+                </View>
+
+                {canReorder ? (
+                  <View
+                    {...{ "data-treeview-handle": node.id }}
+                    role="button"
+                    aria-label={t("Drag {{label}} to reorder", { label: node.label })}
+                    tabIndex={-1}
+                    alignItems="center"
+                    justifyContent="center"
+                    flexShrink={0}
+                    minWidth={MIN_PRESS_TARGET}
+                    minHeight={MIN_PRESS_TARGET}
+                    marginVertical={-handleOutset}
+                    hitSlop={pressTargetHitSlop(caretSize)}
+                    cursor="grab"
+                    opacity={0.45}
+                    transition={transition as any}
+                    hoverStyle={{ opacity: 1 }}
+                    onPress={(e: any) => e?.stopPropagation?.()}
+                    {...{
+                      onPointerDown: (e: any) => handleDragHandlePointerDown(item, e),
+                    }}
+                  >
+                    <DotsSixVerticalIcon size={caretSize} weight="bold" />
+                  </View>
+                ) : null}
+              </XStack>
             );
           }}
         />
+
+        {/* Drop-target line between rows, indented to the destination depth
+            (LC-42). Logical padding keeps it RTL-correct. */}
+        {dragUi?.indicator?.kind === "line" && (
+          <XStack
+            {...{ "data-treeview-drop-indicator": "line" }}
+            position="absolute"
+            top={0}
+            left={0}
+            right={0}
+            y={topOfFlatIndex(dragUi.indicator.flatIndex) - dragScrollY - 1}
+            height={2}
+            paddingInlineStart={rowPadX + dragUi.indicator.depth * indentStep}
+            paddingInlineEnd={rowPadX}
+            pointerEvents="none"
+            zIndex={999}
+            transition={dragUi.mode === "keyboard" ? (transition as any) : ("none" as any)}
+          >
+            <View flex={1} height={2} borderRadius={1} backgroundColor="$accentBackground" />
+          </XStack>
+        )}
+
+        {/* Ghost overlay: clone of the dragged row outside the virtualized
+            list. Pointer mode tracks 1:1 with no tween; the drop/cancel
+            settle leap tweens with the animation knob (LC-42). */}
+        {overlayNode !== undefined && (
+          <View
+            {...{
+              "data-treeview-overlay": "true",
+              "data-treeview-overlay-phase": dragUi ? "pointer" : "settling",
+            }}
+            position="absolute"
+            top={0}
+            left={0}
+            x={(dragUi?.mode === "pointer" ? dragUi.ghost?.x : settle?.to.x) ?? 0}
+            y={(dragUi?.mode === "pointer" ? dragUi.ghost?.y : settle?.to.y) ?? 0}
+            width={dragUi?.width ?? settle?.width}
+            height={dragUi?.height ?? settle?.height}
+            pointerEvents="none"
+            zIndex={1000}
+            transition={dragUi ? ("none" as any) : (transition as any)}
+          >
+            <XStack
+              alignItems="center"
+              height="100%"
+              paddingHorizontal={rowPadX}
+              gap="$2"
+              {...knobProps.borderRadius}
+              backgroundColor="$background"
+              borderWidth={1}
+              borderColor="$borderColor"
+              overflow="hidden"
+              transition={transition as any}
+              enterStyle={{ scale: 1 }}
+              scale={dragUi ? 1.03 : 1}
+              {...(dragUi ? LIFT_SHADOW : undefined)}
+            >
+              <View
+                width={nodeIconSize + 2}
+                height={nodeIconSize + 2}
+                alignItems="center"
+                justifyContent="center"
+                flexShrink={0}
+              >
+                {overlayNode.icon ?? defaultNodeIcon(overlayHasChildren, false, nodeIconSize)}
+              </View>
+              <Text fontSize={labelFontSize} color="$color" numberOfLines={1} flexShrink={1}>
+                {overlayNode.label}
+              </Text>
+            </XStack>
+          </View>
+        )}
+
+        {/* Screen-reader drag announcements (WAI-ARIA drag pattern, LC-43). */}
+        {canReorder && (
+          <View
+            aria-live="assertive"
+            aria-atomic
+            {...{ "data-treeview-announcer": "true" }}
+            position="absolute"
+            width={1}
+            height={1}
+            overflow="hidden"
+            opacity={0}
+            pointerEvents="none"
+          >
+            <Text>{announcement}</Text>
+          </View>
+        )}
       </View>
     </YStack>
   );