@anchrd/intel 0.59.0

package/ui/src/app/sidebar-preferences/sidebar-preferences.types.ts

@@ -0,0 +1,15 @@
+export interface SidebarPreferences {
+  open: boolean;
+  width: number;
+}
+
+export interface SidebarPreferenceStore {
+  read(): SidebarPreferences;
+  write(preferences: SidebarPreferences): void;
+}
+
+export interface SidebarPreferenceDeps {
+  // A `null` storage disables persistence. `undefined` means "use the browser's", which is not the
+  // same thing: a test passes null, a browser without localStorage produces null on its own.
+  storage?: Pick<Storage, "getItem" | "setItem"> | null;
+}

package/ui/src/app/sidebar-resize-handle/sidebar-resize-handle.tsx

@@ -0,0 +1,86 @@
+import { useRef } from "react";
+import {
+  clampSidebarWidth,
+  MaxSidebarWidth,
+  MinSidebarWidth,
+} from "@/app/sidebar-preferences/sidebar-preferences.ts";
+import { cn } from "@/lib/utils";
+
+const KeyboardStep = 16;
+
+// The registry has no resizable sidebar, so this is the one piece of the shell that is not a
+// primitive. It is an ARIA window splitter rather than a bare div: a drag-only handle exists for
+// nobody on a keyboard, and the tree behind it is the entire navigation.
+export function SidebarResizeHandle({
+  width,
+  label,
+  onWidthChange,
+}: {
+  width: number;
+  label: string;
+  onWidthChange(width: number): void;
+}) {
+  const drag = useRef<{ pointerId: number; startX: number; startWidth: number } | null>(null);
+
+  return (
+    // The WAI-ARIA window-splitter pattern is a focusable separator carrying a value. The rule's
+    // suggested `<hr>` cannot take focus, which would remove the keyboard operation this handle
+    // exists to provide.
+    // biome-ignore lint/a11y/useSemanticElements: a focusable window splitter cannot be an <hr>
+    <button
+      type="button"
+      role="separator"
+      aria-orientation="vertical"
+      aria-label={label}
+      aria-valuenow={width}
+      aria-valuemin={MinSidebarWidth}
+      aria-valuemax={MaxSidebarWidth}
+      className={cn(
+        "absolute inset-y-0 -right-1 z-20 hidden w-2 cursor-col-resize outline-none md:block",
+        "after:absolute after:inset-y-0 after:left-1/2 after:w-px after:-translate-x-1/2",
+        "hover:after:bg-sidebar-ring focus-visible:after:bg-sidebar-ring",
+        "focus-visible:ring-2 focus-visible:ring-sidebar-ring",
+        // Collapsed there is no sidebar left to drag. The shell already unmounts the whole panel
+        // then; this keeps the handle from reappearing should it ever be mounted collapsed.
+        "group-data-[state=collapsed]:hidden",
+      )}
+      onPointerDown={(event) => {
+        drag.current = {
+          pointerId: event.pointerId,
+          startX: event.clientX,
+          startWidth: width,
+        };
+        event.currentTarget.setPointerCapture(event.pointerId);
+      }}
+      onPointerMove={(event) => {
+        const active = drag.current;
+        if (!active || active.pointerId !== event.pointerId) return;
+        // Measured against the width the drag started from, never against the live value: reading
+        // back the clamped width would make the handle drift away from the cursor at the limits.
+        onWidthChange(clampSidebarWidth(active.startWidth + (event.clientX - active.startX)));
+      }}
+      onPointerUp={(event) => {
+        drag.current = null;
+        event.currentTarget.releasePointerCapture(event.pointerId);
+      }}
+      onPointerCancel={() => {
+        drag.current = null;
+      }}
+      onKeyDown={(event) => {
+        const next =
+          event.key === "ArrowLeft"
+            ? width - KeyboardStep
+            : event.key === "ArrowRight"
+              ? width + KeyboardStep
+              : event.key === "Home"
+                ? MinSidebarWidth
+                : event.key === "End"
+                  ? MaxSidebarWidth
+                  : null;
+        if (next === null) return;
+        event.preventDefault();
+        onWidthChange(clampSidebarWidth(next));
+      }}
+    />
+  );
+}

package/ui/src/app/tree-expansion/tree-expansion.ts

@@ -0,0 +1,107 @@
+import type {
+  ExpandedLevel,
+  TreeExpansionDeps,
+  TreeExpansionState,
+  TreeExpansionStore,
+} from "./tree-expansion.types.ts";
+
+const storageKey = "intel.tree";
+
+/**
+ * How many open levels travel across a reload.
+ *
+ * ⚠️ NOT a guess about how many folders somebody opens: the written list is already trimmed to what
+ * the tree still draws, so it cannot grow on its own. The cap is against a stored value nobody
+ * wrote — a hand-edited or corrupted entry would otherwise become that many level queries at the
+ * next start, because every remembered level is one query (#11).
+ */
+const MaxRememberedLevels = 200;
+
+function browserStorage(): Pick<Storage, "getItem" | "setItem"> | null {
+  // Reading `localStorage` throws outright in a few privacy modes, so the guard is a try, not a
+  // typeof check. Losing which folders were open is acceptable; losing the tree is not.
+  try {
+    return typeof window === "undefined" ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+const empty: TreeExpansionState = { levels: [], revealed: null };
+
+function levelFrom(value: unknown): ExpandedLevel | null {
+  if (typeof value !== "object" || value === null) return null;
+  const { id, type } = value as Partial<ExpandedLevel>;
+  if (typeof id !== "string" || id.length === 0) return null;
+  return type === "folder" || type === "flow" ? { id, type } : null;
+}
+
+/**
+ * Which levels of the tree stand open, written through so the answer survives what the component
+ * does not.
+ *
+ * ⚠️ A reload is the obvious half and the smaller one. The shell UNMOUNTS the sidebar's content
+ * when the panel collapses, so plain component state here dies at the first click on the sidebar
+ * trigger — the tree came back closed from a gesture that says nothing about folders (#805).
+ *
+ * ⚠️ What is stored is a CLAIM about a gesture, not a fact about the tree: a folder that has since
+ * been archived, moved away or unshared is still in here. Judging that is the tree's job and it
+ * already does it — a level whose row it cannot draw is never loaded (#521), and the next gesture
+ * writes the trimmed list back. Trimming here as well would need this file to know what the tree
+ * shows, which is the one thing a storage adapter must not.
+ */
+export function createTreeExpansion(deps: TreeExpansionDeps = {}): TreeExpansionStore {
+  const storage = deps.storage === undefined ? browserStorage() : deps.storage;
+
+  return {
+    read() {
+      let raw: string | null = null;
+      try {
+        raw = storage?.getItem(storageKey) ?? null;
+      } catch {
+        return empty;
+      }
+      if (raw === null) return empty;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch {
+        return empty;
+      }
+      // ⚠️ A bare list is the shape #805 wrote, and a tab that was open across the two releases has
+      // one. It is read as levels without a revealed selection, which is exactly what it means.
+      const stored: unknown = Array.isArray(parsed) ? { levels: parsed, revealed: null } : parsed;
+      if (typeof stored !== "object" || stored === null) return empty;
+      const { levels: rawLevels, revealed } = stored as Partial<TreeExpansionState>;
+      if (!Array.isArray(rawLevels)) return empty;
+      const levels: ExpandedLevel[] = [];
+      for (const entry of rawLevels.slice(0, MaxRememberedLevels)) {
+        const level = levelFrom(entry);
+        if (level === null) continue;
+        // ⚠️ A bad entry is skipped rather than emptying the answer: one unreadable line says
+        // nothing about the others, and a tree that closes completely because of it is the very
+        // failure this file exists to remove. Duplicates go the same way — two identical entries
+        // would be two queries for one level.
+        if (levels.some((seen) => seen.id === level.id && seen.type === level.type)) continue;
+        levels.push(level);
+      }
+      return {
+        levels,
+        revealed: typeof revealed === "string" && revealed.length > 0 ? revealed : null,
+      };
+    },
+    write(state) {
+      try {
+        storage?.setItem(
+          storageKey,
+          JSON.stringify({
+            levels: state.levels
+              .slice(0, MaxRememberedLevels)
+              .map((level) => ({ id: level.id, type: level.type })),
+            revealed: state.revealed,
+          }),
+        );
+      } catch {}
+    },
+  };
+}

package/ui/src/app/tree-expansion/tree-expansion.types.ts

@@ -0,0 +1,31 @@
+// One remembered level of the tree. The root is deliberately NOT one of these: it has no row to
+// open, it is always shown, and an entry for it could only ever be a value nothing reads.
+export interface ExpandedLevel {
+  id: string;
+  type: "folder" | "flow";
+}
+
+/**
+ * What the tree knows about itself between two lives of the component.
+ *
+ * ⚠️ `revealed` travels WITH the levels rather than beside them, and that is the whole reason this
+ * is an object rather than a list (#809). It names the selection the tree has already opened itself
+ * onto. Kept only in memory it dies with the panel — and the panel dies every time the sidebar is
+ * collapsed — so a folder the reader closed by hand would be opened again by a reveal that has
+ * forgotten it already happened.
+ */
+export interface TreeExpansionState {
+  levels: readonly ExpandedLevel[];
+  revealed: string | null;
+}
+
+export interface TreeExpansionStore {
+  read(): TreeExpansionState;
+  write(state: TreeExpansionState): void;
+}
+
+export interface TreeExpansionDeps {
+  // A `null` storage disables persistence. `undefined` means "use the browser's", which is not the
+  // same thing: a test passes null, a browser without localStorage produces null on its own.
+  storage?: Pick<Storage, "getItem" | "setItem"> | null;
+}

package/ui/src/app/tree-move/tree-move.tsx

@@ -0,0 +1,427 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { ChevronLeft, Folder } from "lucide-react";
+import type * as React from "react";
+import { useState } from "react";
+import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { Modal } from "@/modal/modal.tsx";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+// Where a row would land. `null` is the root of the shared tree; the title is carried along because
+// the dialog names the destination and the row that supplied it is not always still on screen.
+export type MoveDestination = { id: string | null; title: string };
+
+export type MoveVerdict = "ok" | "self" | "descendant" | "same-place";
+
+// The parent a row is filed under. Nodes and Flows keep their own record (ADR-0004), so the
+// answer is read from whichever one this row is, never from a merged shape.
+//
+// ⚠️ This is the parent the RECORD names, which since #429 is not always the level the row is shown
+// in: a shared document is filed inside the sharer's folder and reaches the root only through the
+// share. Everything about a move — which level loses the row, which one keeps it, and whether the
+// root is "same place" — is a question about the level on screen, so the level travels with the
+// move instead of being read back out of the record here (#446).
+export function parentOf(entry: TreeEntry): string | null {
+  return entry.type === "node" ? entry.node.parentId : entry.flow.parentId;
+}
+
+// One level of the shared tree, as a query key. The move writes into two of them and the picker
+// reads a third, so the shape is stated once rather than spelled out at each of those places.
+export function treeLevelKey(parentId: string | null): readonly unknown[] {
+  return ["tree", parentId];
+}
+
+/**
+ * Every level of the tree at once — what a write that changed what is IN a folder makes stale.
+ *
+ * ⚠️ Not the level that was written into: that is the obvious half, and it was the whole of #519.
+ * A folder ROW carries `openable` — since #59 the arrow only stands where there is something to
+ * open — and that is a statement about the folder's CONTENTS living one level ABOVE it. Refresh
+ * only the level below and the row keeps yesterday's answer: the first thing filed into an EMPTY
+ * folder has no arrow to appear under, `reveal` opens a level `renderRow` then never renders, and
+ * reloading the page was the only thing that read the row again. The other direction is the same
+ * bug from the other side — the last child moved or archived out leaves an arrow promising a level
+ * that is empty.
+ *
+ * ⚠️ A prefix rather than "the level, plus the level its folder row sits in", because that second
+ * level is not always the one the record names: since #429 a shared row also stands at the root
+ * (`levelsToClear`).
+ *
+ * ⚠️ What it costs is one request per level the reader has OPEN — bounded by the screen, not by how
+ * long the tab has been sitting there. `app-tree.tsx` loads a level only while the row it hangs on
+ * still stands in the level above it, so a folder that was opened and has since left the tree —
+ * archived, moved away, its share revoked — takes its query with it rather than being re-read by
+ * every write for the rest of the session.
+ *
+ * The same prefix is what `archive.tsx` has always used for the same reason: a row can come back
+ * anywhere, and the screen writing it does not know where.
+ */
+export const allTreeLevelsKey: readonly unknown[] = ["tree"];
+
+/**
+ * Which cached levels a move has to take the row out of.
+ *
+ * ⚠️ Normally one, and the caller names it. When it does not — the title line has no tree level to
+ * name — the answer is not a guess but the full set of places the row can be standing in, and that
+ * set has exactly two members.
+ *
+ * It is two rather than "all of them" because of how a level is read (`db.ts`): every level except
+ * the root is strictly `parent_id IS ?`, so there the level and the record always agree. Only the
+ * root also collects the top of every readable region — a shared row whose own record names the
+ * sharer's folder (#429). So a row is either in the level its record names, or in the root.
+ *
+ * Cleaning up one level too many costs a re-read of a list the reader is looking at anyway.
+ * Cleaning up one too few is #446: the row stays where it no longer is.
+ */
+export function levelsToClear(
+  entry: TreeEntry,
+  level: string | null | undefined,
+): (string | null)[] {
+  if (level !== undefined) return [level];
+  const recorded = parentOf(entry);
+  return recorded === null ? [null] : [recorded, null];
+}
+
+// The optimistic row, filed where it is about to land. Its own parent has to travel with it, or the
+// plus on the moved row would still file into the folder it just left.
+function withParent(entry: TreeEntry, parentId: string | null): TreeEntry {
+  return entry.type === "node"
+    ? { ...entry, node: { ...entry.node, parentId } }
+    : { ...entry, flow: { ...entry.flow, parentId } };
+}
+
+/**
+ * ⚠️ The trap this ticket is built around: a node must not travel into its own descendants. The
+ * service refuses it (`move_cycle`, `nodes.ts:421`), but a refusal that only arrives once the
+ * mouse button is already up is the one answer worse than no dragging at all — the drop has to be
+ * offered or withheld while the pointer is still moving.
+ *
+ * It costs no request. The tree already carries the ancestor path of every rendered row for its own
+ * cycle guard (`app-tree.tsx`), and "is this target inside the row I am dragging" is exactly the
+ * question that path answers: the dragged id appears above the target, or it does not.
+ */
+export function moveVerdict(input: {
+  draggedId: string;
+  // ⚠️ Two answers to "where is this row", and since #429 they can differ — which is why both are
+  // asked (#446). `draggedParentId` is what the record says and what a move would overwrite;
+  // `draggedLevel` is the level the row is shown in.
+  //
+  // "Same place" has to be true for either, and for different reasons:
+  //
+  // - The record: dropping a row on the folder its own record already names writes the value that
+  //   is already there. Nothing happens, and offering it says something will.
+  // - The level: a shared row reaches the root only through the share, and its record names the
+  //   sharer's folder. Dropping it on the root looks like a no-op to the reader — but it would
+  //   write `parentId = null` and lift the document OUT of the folder it was shared from. That is
+  //   the opposite of nothing, done by somebody who was told nothing would happen.
+  //
+  // `draggedLevel` is optional because a surface without a tree has no level to name — the resource
+  // menu opens the same dialog from a title line. There the record is the only answer there is.
+  draggedParentId: string | null;
+  draggedLevel?: string | null | undefined;
+  targetId: string | null;
+  targetAncestors: ReadonlySet<string>;
+}): MoveVerdict {
+  if (input.targetId === input.draggedId) return "self";
+  if (input.targetId !== null && input.targetAncestors.has(input.draggedId)) return "descendant";
+  if (input.targetId === input.draggedParentId) return "same-place";
+  if (input.draggedLevel !== undefined && input.targetId === input.draggedLevel) {
+    return "same-place";
+  }
+  return "ok";
+}
+
+// ⚠️ Five refusals, five sentences. The service tells them apart by `code`
+// (`nodes.ts:331/335/338/361`, `flows.ts:205–217/752`), and so does this: one message for all
+// of them would leave the reader guessing which of "you may not write there", "that is not a
+// folder", "that would be a loop", "that destination is archived" and "somebody else was faster"
+// they have just hit.
+//
+// ⚠️ `parent_archived` reaches this since #679: before that the service raised it for tasks only,
+// which never travel through the tree's move. The board is not a drop target for an archived node,
+// so a person meets it rarely — but a move over MCP or HTTP hits it, and the tree reloads from the
+// same error.
+export function moveErrorKey(error: unknown): string {
+  const code =
+    typeof error === "object" && error !== null && "code" in error
+      ? String((error as { code: unknown }).code)
+      : null;
+  switch (code) {
+    case "node_forbidden":
+    case "flow_edit_forbidden":
+      return "tree.move.failed.forbidden";
+    case "parent_not_folder":
+      return "tree.move.failed.notFolder";
+    case "parent_archived":
+      return "tree.move.failed.archived";
+    case "move_cycle":
+      return "tree.move.failed.cycle";
+    case "update_conflict":
+    case "flow_update_conflict":
+      return "tree.move.failed.conflict";
+    case "flow_parent_not_found":
+      return "tree.move.failed.gone";
+    default:
+      return "tree.move.failed.other";
+  }
+}
+
+/**
+ * The move, named before it happens.
+ *
+ * ⚠️ Since #16 a share hangs on the folder and reaches everything beneath it (`db-grants.ts`,
+ * `nodeVerbQuery`), so moving a document is a change of who may read it — without the word "share"
+ * appearing anywhere. That is why every move is confirmed rather than performed on drop.
+ *
+ * What this deliberately does not do is name the people. `listGrants` answers with the
+ * grants sitting on that one folder, needs `share` on it (`nodes.ts:459`), and says nothing
+ * about the grants above it that reach down. A list built from that would be short of exactly the
+ * entries that matter and would read as complete — "nobody is on this folder" while an ancestor
+ * opens it to the whole organization. Naming the mechanism truthfully beats enumerating it wrongly;
+ * an effective-audience answer is the server's to give, and no endpoint offers one today.
+ */
+export function MoveDialog({
+  entry,
+  level,
+  close,
+  submit,
+}: {
+  entry: TreeEntry;
+  // `undefined` where no tree level was rendered — the verdict then rests on the record alone.
+  level: string | null | undefined;
+  close(): void;
+  submit(destination: MoveDestination): void;
+}) {
+  const { data } = useIntelRouterContext();
+  const i18n = useI18n();
+  // The browsed path, root first. It is also the descendant guard for the keyboard route: the row
+  // being moved is never offered, so its subtree can never be entered in the first place.
+  const [path, setPath] = useState<MoveDestination[]>([]);
+  const here: MoveDestination = path.at(-1) ?? { id: null, title: i18n.t("tree.move.root") };
+  const children = useQuery({
+    queryKey: ["tree", here.id],
+    queryFn: async () => await data.listTreeChildren(here.id),
+  });
+  const folders = (children.data ?? []).filter(
+    (child) => child.kind === "folder" && child.id !== entry.id,
+  );
+  const verdict = moveVerdict({
+    draggedId: entry.id,
+    draggedParentId: parentOf(entry),
+    // Handed down by the caller, because the dialog is opened from two places and only one of them
+    // has a tree level to name (#446).
+    draggedLevel: level,
+    targetId: here.id,
+    targetAncestors: new Set(path.map((step) => step.id).filter((id) => id !== null)),
+  });
+
+  return (
+    <Modal title={i18n.t("tree.move.title", { title: entry.title })} close={close}>
+      {
+        <div className="space-y-3">
+          <p className="text-sm text-muted-foreground">{i18n.t("tree.move.pick")}</p>
+          <div className="flex items-center gap-2">
+            <button
+              type="button"
+              disabled={path.length === 0}
+              onClick={() => setPath((current) => current.slice(0, -1))}
+              aria-label={i18n.t("tree.move.up")}
+              className="rounded-md border p-1 outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+            >
+              <ChevronLeft aria-hidden="true" className="size-4" />
+            </button>
+            <p className="min-w-0 flex-1 truncate text-sm font-medium">{here.title}</p>
+          </div>
+          <ul className="max-h-56 space-y-1 overflow-y-auto">
+            {children.isPending ? (
+              <li className="px-2 py-1.5 text-sm text-muted-foreground">
+                {i18n.t("common.loading")}
+              </li>
+            ) : folders.length === 0 ? (
+              <li className="px-2 py-1.5 text-sm text-muted-foreground">
+                {i18n.t("tree.move.noFolders")}
+              </li>
+            ) : (
+              folders.map((folder) => (
+                <li key={folder.id}>
+                  <button
+                    type="button"
+                    onClick={() => setPath((current) => [...current, folder])}
+                    aria-label={i18n.t("tree.move.open", { title: folder.title })}
+                    className="flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    <Folder aria-hidden="true" className="size-4 shrink-0" />
+                    <span className="truncate">{folder.title}</span>
+                  </button>
+                </li>
+              ))
+            )}
+          </ul>
+          {/* ⚠️ This IS the move, not a choice that opens a confirmation. Until #776 it set a
+              destination and a second screen asked again, carrying a sentence about inherited
+              sharing; Jack removed both on 2026-08-24 — inheritance is what a person expects of a
+              folder tree, and a warning that says the same self-evident thing on every move is one
+              nobody reads by the third time. The refusals are untouched: `moveErrorKey` still words
+              all six, and a silent failure would be worse than the dialog ever was. */}
+          <button
+            type="button"
+            disabled={verdict !== "ok"}
+            onClick={() => submit(here)}
+            className="w-full rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            {i18n.t("tree.move.here", { title: here.title })}
+          </button>
+          {verdict === "same-place" ? (
+            <p className="text-sm text-muted-foreground">{i18n.t("tree.move.alreadyThere")}</p>
+          ) : null}
+        </div>
+      }
+    </Modal>
+  );
+}
+
+/**
+ * Moving a row, wherever it is asked for.
+ *
+ * ⚠️ It is asked for from two places now (#58): a drop on a folder in the tree, and the menu in the
+ * title line — the keyboard route, which since #58 is the only one the menu still has anywhere. Both
+ * are the same move, so both take it from here rather than each carrying its own mutation. Two
+ * copies of an optimistic update that rewrites two cached levels is how a rejected move ends up
+ * leaving a row standing twice.
+ *
+ * ⚠️ Optimistic, never authoritative. The row is lifted out of one level and dropped into the other
+ * before the server answers, and every refusal — 403, `parent_not_folder`, `move_cycle`,
+ * `update_conflict` — puts both levels back exactly as they were and then re-reads them.
+ *
+ * The caller renders `dialog` where it likes and words `error` itself with `moveErrorKey`: the tree
+ * says it in the sidebar, the menu over the screen, and neither position belongs to the move.
+ */
+export function useTreeMove({
+  onMoved,
+}: {
+  // What the caller wants to do with the destination once the move is through — the tree opens that
+  // folder so the row is where the eye follows it. Nobody else has a tree to open.
+  onMoved?: ((destination: MoveDestination) => void) | undefined;
+} = {}): {
+  // `level` is the one the row is standing in, and the caller says it or says `undefined` — the tree
+  // knows it from the level it rendered into, the title line has no tree at all. Guessing it here
+  // with `parentOf` is what filed a moved row into a cache level that does not exist (#446).
+  //
+  // ⚠️ `undefined` is not "root". It means the level is unknown, and it is handled by cleaning up
+  // BOTH levels such a row can stand in — see `levelsToClear`.
+  start(
+    entry: TreeEntry,
+    level: string | null | undefined,
+    destination: MoveDestination | null,
+  ): void;
+  error: unknown;
+  dialog: React.ReactNode;
+} {
+  const { data } = useIntelRouterContext();
+  const queryClient = useQueryClient();
+  const [moving, setMoving] = useState<{
+    entry: TreeEntry;
+    level: string | null | undefined;
+    initial: MoveDestination | null;
+  } | null>(null);
+
+  const move = useMutation({
+    mutationFn: async ({
+      entry,
+      destination,
+    }: {
+      entry: TreeEntry;
+      level: string | null | undefined;
+      destination: MoveDestination;
+    }) => {
+      // `baseUpdatedAt` travels with the move: it is what turns a concurrent edit into a 409 the
+      // view can act on instead of an overwrite nobody notices.
+      if (entry.type === "flow") {
+        await data.updateFlow({
+          flowId: entry.id,
+          baseUpdatedAt: entry.flow.updatedAt,
+          parentId: destination.id,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      } else {
+        await data.updateNode({
+          nodeId: entry.id,
+          baseUpdatedAt: entry.node.updatedAt,
+          parentId: destination.id,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      }
+    },
+    onMutate: async ({ entry, level, destination }) => {
+      const fromKeys = levelsToClear(entry, level).map(treeLevelKey);
+      const toKey = treeLevelKey(destination.id);
+      await Promise.all(
+        [...fromKeys, toKey].map(async (queryKey) => await queryClient.cancelQueries({ queryKey })),
+      );
+      const snapshot = [
+        ...fromKeys.map((key) => [key, queryClient.getQueryData<TreeEntry[]>(key)] as const),
+        [toKey, queryClient.getQueryData<TreeEntry[]>(toKey)] as const,
+      ];
+      for (const key of fromKeys) {
+        queryClient.setQueryData<TreeEntry[]>(key, (current) =>
+          current?.filter((row) => row.id !== entry.id),
+        );
+      }
+      // A level nobody has opened stays unloaded: writing one here would show a folder's contents
+      // that were never read.
+      queryClient.setQueryData<TreeEntry[]>(toKey, (current) =>
+        current === undefined
+          ? current
+          : [...current.filter((row) => row.id !== entry.id), withParent(entry, destination.id)],
+      );
+      return { snapshot };
+    },
+    onError: (_error, _variables, context) => {
+      for (const [key, value] of context?.snapshot ?? []) queryClient.setQueryData(key, value);
+    },
+    onSuccess: (_result, { destination }) => onMoved?.(destination),
+    onSettled: async (_result, _error, { entry }) => {
+      await Promise.all([
+        // Both ends of the move and the rows they hang under: a folder that just received its first
+        // row needs its arrow, and one that lost its last has to give it back (#519).
+        queryClient.invalidateQueries({ queryKey: allTreeLevelsKey }),
+        queryClient.invalidateQueries({
+          queryKey: [entry.type === "flow" ? "flows" : "node-graph"],
+        }),
+        queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
+      ]);
+    },
+  });
+
+  return {
+    /**
+     * ⚠️ A destination that is already known writes straight away — a drop names its folder, and
+     * asking again about the folder the pointer just landed on is a question with one answer
+     * (#776). Only the route that has NO destination opens the picker: the menu, which is the
+     * keyboard path.
+     *
+     * The optimistic update in `onMutate` is what makes this safe to do without a screen in
+     * between: the row moves at once and every refusal puts both levels back.
+     */
+    start(entry, level, destination) {
+      move.reset();
+      if (destination !== null) {
+        move.mutate({ entry, level, destination });
+        return;
+      }
+      setMoving({ entry, level, initial: null });
+    },
+    error: move.isError ? move.error : null,
+    dialog: moving ? (
+      <MoveDialog
+        entry={moving.entry}
+        level={moving.level}
+        close={() => setMoving(null)}
+        submit={(destination) => {
+          setMoving(null);
+          move.mutate({ entry: moving.entry, level: moving.level, destination });
+        }}
+      />
+    ) : null,
+  };
+}