cursedbelt 3.0.2 → 4.0.0

package/src/react/file-tree/FileTree.tsx

@@ -26,7 +26,8 @@
  * graduation. They are here now and each says so where it lives:
  *
  *   1. **Reveal** — the selected row is scrolled into view, and a shut folder holding it is
- *      marked and scrolled to instead of being forced open (see the effect below).
+ *      marked and scrolled to rather than forced open unless `expandOnReveal` says otherwise
+ *      (see the effect below, and the section on it).
  *   2. **The path is marked** — `data-ancestor` on the folders between the root and the
  *      selection, `data-holds-open` on the shut one holding it (`openPath`).
  *   3. **Escape cancels a drag** (`beginDrag`), which `pointercancel` never did.
@@ -45,6 +46,100 @@
  * needs and a design system should not have is an argument for a prop, not for a copy: the
  * three claimants collapse into one `selectedId`, and a kind-specific glyph is `renderIcon`.
  *
+ * ── 🔴 Multi-select, 2026-09-15 — and why `selectedId` did not move ─────────────────────
+ * Owner, `ideas/file-tree.md` item 2: shift-click a range, ⌘-click to add one, drag the whole
+ * selection to another folder or to the root, ⌘⌫ the lot, and ⌘X/⌘C/⌘V to move or copy them.
+ * Three apps were waiting on it and none of them forked the component to get it.
+ *
+ * Every one of those is a change to this SHARED contract, and the trap in it is that
+ * `selectedId: string | null` is load-bearing in all three: it is the row the main pane is
+ * showing in `apps/collections`, and the folder the library is filtered by in `apps/music`.
+ * So it did not move. {@link FileTreeProps.selectedIds} sits BESIDE it, the selection is
+ * `[selectedId]` for a consumer that passes neither, and every plural callback is its own
+ * optional prop — `onMoveMany`, `onDeleteMany`, `onCopy` — with one rule holding it together:
+ * **N > 1 goes through the plural verb, and without it the gesture acts on the one row it
+ * started on**. A tree that silently became multi-select would have broken "what am I looking
+ * at" in two shipped apps on the day it published.
+ *
+ * The arithmetic is `fileTreeSelection.ts`, DOM-free and unit-tested, for the same reason
+ * `core/file-tree/fileTreeModel.ts` is: happy-dom computes no layout, so the pointer half of
+ * a multi-drag cannot be asserted anywhere and the RULES have to be reachable without it.
+ *
+ * ── 🔴 New Folder with Selection, 2026-09-16 ────────────────────────────────────────────
+ * Owner, 2026-09-13: *"allow make dir from file where dir wraps file location and gets name
+ * of file"*. Half of it was already here — the {@link FileTreeProps.draft} row, which names a
+ * folder before anything is created — and the other half is `onMove`/`onMoveMany`, so this is
+ * one gesture out of two things that existed rather than a new mechanism: the draft grew a
+ * `wrap` list, and committing hands the name AND the ids back in a single call. Two calls is
+ * how a folder ends up made and empty when the second one fails.
+ *
+ * It is Finder's *New Folder with Selection* and VS Code's ⌃⌘N, invented no further: the
+ * folder is made where the row already is, named after it with the extension dropped, and the
+ * row moves in. A selection of twenty is the same code path with N > 1, named after the first
+ * in TREE order — see `planWrap`, which is where all of that is decided without a DOM.
+ *
+ * ── 🔴 Pinned rows, 2026-09-16 ──────────────────────────────────────────────────────────
+ * Owner, 2026-09-13: *"need ces ability to pin open files where they stay at the top of the
+ * file tree in a new section above the folders. Pinned will mean I want to keep them there
+ * until I unpin them. This makes it easier to keep track of important files and folders. They
+ * still will exist in the folder they were stored in and unpinning takes it back to normal.
+ * Pinning or unpinning one place doesn't change pinning in the other place."*
+ *
+ * Five things in that paragraph, and the last two are the ones a sort order loses:
+ *
+ *   1. **A SECTION, not an order.** A pinned row is drawn TWICE — once at the top and once
+ *      where it lives, because *"they still will exist in the folder they were stored in"*.
+ *      Lifting the row out would make pinning a move, and unpinning an undo of one.
+ *   2. **Files and folders both** — *"important files and folders"*.
+ *   3. **Sticky until unpinned.** It is not a recents list and it does not age out, which is
+ *      why the list is the consumer's to persist rather than the tree's to remember.
+ *   4. **Unpinning leaves nothing behind**: the top copy goes and the row in the folder is
+ *      the row it always was.
+ *   5. 🔴 **Per place.** *"Pinning or unpinning one place doesn't change pinning in the other
+ *      place."* That is free here and only because the state is CONTROLLED — the consumer
+ *      holds one list per tree, exactly as `media/stageResize.ts` holds one height per
+ *      consumer key (*"one shared key would make sizing either of them silently resize the
+ *      other"* — the same defect, one surface along).
+ *
+ * 🔴 **One identity, two row keys.** Every selection, drag, reveal and aria path in here is
+ * keyed on `node.id`, and drawing a row twice would break each of them if both copies claimed
+ * the same key: `openPath`/`data-holds-open` walks for the selected row and would find the
+ * pinned copy, marking the wrong ancestors. So the node's id stays its identity and the COPY
+ * is addressed separately — two ref maps (`rowRefs`, `pinnedRefs`), and `focused` says which
+ * section it is in. `apps/collections` makes the same split with `itemRowId`/`nodeRowId`.
+ *
+ * 🔴 **Its own `role='tree'`, outside the scroller.** `aria-setsize`/`aria-posinset` below are
+ * computed from the rows ON SCREEN, on the stated assumption that every sibling of a visible
+ * row is itself visible — folding pins into that row list would make the counts wrong for
+ * every row in the tree. The section is a separate widget with counts of its own, and it sits
+ * ABOVE `.cbft-scroll` rather than sticky inside it, so the reveal below, the autoscroll and
+ * the blank-space drop target all still mean exactly what they meant.
+ *
+ * The pinned copy is a SHORTCUT, not a second editing surface: it is flat (no twisty, no
+ * depth), a drop aimed at it lands in the real folder, and the rename field draws on the real
+ * row whenever the real row is on screen.
+ *
+ * ── 🔴 The reveal OPENS the folder now, if it is asked to, 2026-09-16 ───────────────────
+ * Owner, `ideas/collections-09-14.md`: *"clicking a file in media gallery content window
+ * should show that file in the file tree by like vscode does when you select a tab with a
+ * file in it."* Almost all of that was already here — `selectedId`, `openPath`,
+ * `data-ancestor`/`data-holds-open` and the scroll — and the one thing missing was the one
+ * thing this file had DECIDED against: limit 1 of the reveal, *a shut folder stays shut*.
+ *
+ * He named VS Code, whose `explorer.autoReveal` is `true` and expands, and he named the exact
+ * gesture. So the ask wins over the default, and the decision is recorded in full on the
+ * effect itself rather than here: {@link FileTreeProps.expandOnReveal} is OFF unless a
+ * consumer wires it, and what it opens goes into an overlay of this component's own
+ * (`revealOpened`) which is **never handed to `onCollapsedChange`**. The persisted collapse
+ * is read back unchanged on the next mount, which is the half of limit 1's objection that was
+ * never a matter of taste.
+ *
+ * 🔴 Silent is not the same as invisible, and {@link FileTreeProps.onRevealExpand} is the
+ * difference. A tree that FETCHES a folder's children when it opens — `apps/collections` asks
+ * the server per open folder — would otherwise draw the folder the reveal opened with nothing
+ * in it, because the consumer never learned the expansion happened. So it is told, in a
+ * callback that exists to feed a fetch plan and explicitly not to be stored.
+ *
  * ── Pointer events, not HTML5 drag-and-drop, for INTERNAL drags ─────────────────────────
  * The ghost image is a translucent screenshot nobody asked for, `dragover` fires at the
  * mercy of the browser, and touch does not have HTML5 dnd at all. The drag only *starts*
@@ -71,19 +166,29 @@ import {
   type AccessMarkCopy,
   accessMarkCopy,
   describeDrop,
-  descendantIdsOf,
   type DropOffer,
   type FileTreeDrop,
   type FileTreeNode,
   type FileTreeRow,
   filterFileTree,
+  findFileTreeNode,
   flattenFileTree,
   matchTypeahead,
-  resolveDrop,
   resolveKeyboardMove,
 } from 'cursedbelt-core/file-tree/file-tree-model';
 import { Input } from '../components/Input';
 import { Tooltip } from '../components/Tooltip';
+import {
+  draggedIdsOf,
+  nodesByIds,
+  planWrap,
+  refuseCopy,
+  refuseWrap,
+  resolveMultiDrop,
+  selectionRange,
+  toggleSelected,
+  topmostSelected,
+} from './fileTreeSelection';
 import './fileTree.css';
 
 /** How far a press travels before it stops being a click and becomes a drag. */
@@ -108,7 +213,16 @@ const SPRING_OPEN_MS = 600;
 const TYPEAHEAD_RESET_MS = 1000;
 
 interface DragState {
+  /** The row the press landed on — the chip's name, and the single-row `onMove` argument. */
   id: string;
+  /**
+   * EVERYTHING in the air, `id` included.
+   *
+   * 🔴 One id was the whole of this until 2026-09-15, and it is why a selection could not be
+   * dragged at all: the gesture had nowhere to carry the other rows. It is always at least
+   * `[id]`, so the single-row drag is the plural one with N = 1 rather than a second path.
+   */
+  ids: readonly string[];
   startX: number;
   startY: number;
   /**
@@ -127,11 +241,41 @@ interface DragState {
 
 const NO_OFFER: DropOffer = { target: null, refused: false, reason: null };
 
+/**
+ * One frozen empty list for "nothing is pinned", so a consumer that passes no `pinnedIds`
+ * hands the memos below a stable reference instead of a new `[]` every render.
+ */
+const NO_PINS: readonly string[] = [];
+
 export interface FileTreeProps {
   nodes: readonly FileTreeNode[];
   /** The row drawn as selected — usually "what the main pane is showing". */
   selectedId: string | null;
   onSelect: (node: FileTreeNode) => void;
+
+  /**
+   * The rows drawn as selected when there is more than one — shift-click and ⌘-click.
+   *
+   * 🔴 BESIDE {@link selectedId}, never instead of it, and that is the whole shape of this
+   * feature. `selectedId` is load-bearing in every consumer this tree has: in
+   * `apps/collections` it is the row the main pane is showing, in `apps/music` it is the
+   * folder the library is filtered by. Those are singular questions with singular answers,
+   * and a tree that silently became multi-select would break "what am I looking at" in two
+   * shipped apps on the day it published. So a consumer that passes neither this nor
+   * {@link onSelectionChange} gets EXACTLY today's behaviour, byte for byte.
+   *
+   * Omit it and the selection is `[selectedId]`, which is what makes ⌘-click work for a
+   * consumer that stores only the one id and grows into the array afterwards.
+   */
+  selectedIds?: readonly string[];
+  /**
+   * The selection changed by a gesture. **Wiring it is what turns multi-select on.**
+   *
+   * A plain click reports `[id]` and still calls {@link onSelect}; shift-click and ⌘-click
+   * report the new set and do NOT — in every file explorer, extending a selection is not
+   * also navigating, and in a consumer that opens on select it would be.
+   */
+  onSelectionChange?: (ids: string[]) => void;
   /**
    * Double-click, or Space on a focused row. Falls back to `onSelect` when omitted.
    *
@@ -142,12 +286,97 @@ export interface FileTreeProps {
   /** Shut folders, as a controlled value. Omit both for the tree's own memory. */
   collapsed?: readonly string[];
   onCollapsedChange?: (next: string[]) => void;
+  /**
+   * **Open the shut folders on the way to the selection**, instead of marking the shut one
+   * and stopping there — VS Code's `explorer.autoReveal`, which is on by default over there.
+   *
+   * Owner, `ideas/collections-09-14.md`: *"clicking a file in media gallery content window
+   * should show that file in the file tree by like vscode does when you select a tab with a
+   * file in it."* He named the application and he named the gesture, so this is what the
+   * reveal does when it is asked for by name — see limit 1 on the reveal effect for the
+   * argument this prop is the opt-in half of, and why it stays the default.
+   *
+   * 🔴 **It never touches {@link collapsed}.** The folders it opens are held in an overlay of
+   * the tree's own and {@link onCollapsedChange} is not called, so the collapse the consumer
+   * persisted is still the collapse it persisted — on the next mount the tree reads it back
+   * unchanged. Shutting one of them by hand drops it from the overlay and the persisted value
+   * decides again; nothing about it is ever written out. That is the whole of the objection
+   * limit 1 records, answered without giving up the behaviour he asked for.
+   *
+   * Off unless it is wired, like every other verb here: a consumer that passes nothing gets
+   * byte for byte today's reveal.
+   */
+  expandOnReveal?: boolean;
+  /**
+   * The folders {@link expandOnReveal} just opened, told to the consumer once per reveal.
+   *
+   * 🔴 **Not a request to persist them** — that is the one thing this must never be read as,
+   * and the whole reason the overlay exists. It is for a tree whose children are FETCHED when
+   * a folder opens: `apps/collections` asks the server for a folder's files only for the
+   * folders it believes are open (`ExplorerSidebar.tsx` → `nodesToFetch`), so an expansion it
+   * cannot see would draw the folder open and EMPTY, with the file the reveal was asked for
+   * still missing. A silent overlay is the right default and an unobservable one is a trap.
+   *
+   * Wire it to whatever decides the fetch plan, never to the stored collapse.
+   */
+  onRevealExpand?: (ids: readonly string[]) => void;
+
+  /**
+   * The rows kept in a section of their own ABOVE the folders — *"pin open files where they
+   * stay at the top of the file tree in a new section above the folders"*.
+   *
+   * Files and folders both, in the order they were pinned, and a pin the tree no longer holds
+   * is simply not drawn rather than drawn as a ghost. Each one appears TWICE: at the top and
+   * in the folder it lives in, which is the requirement — *"they still will exist in the
+   * folder they were stored in"*.
+   *
+   * 🔴 CONTROLLED, with no fallback to a memory of the tree's own — the one place this
+   * differs from {@link collapsed}, and deliberately. *"Pinned will mean I want to keep them
+   * there until I unpin them"*: a list this component remembered would be a list that
+   * evaporated on the next mount, which is the opposite of what the word means. Holding it
+   * outside is also the whole of *"pinning or unpinning one place doesn't change pinning in
+   * the other place"* — one list per tree, per app, wherever the consumer persists it, the
+   * same reasoning `media/stageResize.ts` records for its per-consumer height key.
+   *
+   * Omit it and there is no section, no pin control and no chord: byte for byte today's tree.
+   */
+  pinnedIds?: readonly string[];
+  /**
+   * Pin or unpin a row. **Wiring it is what puts the pin control on every row and ⌃⌘T on the
+   * keyboard**, the same rule every other verb here follows.
+   *
+   * The next list arrives whole (a new pin is appended, so the section keeps the order it was
+   * built in) and the consumer stores it. Pass {@link pinnedIds} without this to draw a
+   * read-only section and put the unpin on your own ⋯ menu.
+   */
+  onPinnedChange?: (next: string[]) => void;
+  /**
+   * What the pinned section is called — its heading, and its `aria-label`. Default `Pinned`.
+   *
+   * An app whose vocabulary differs ("Favourites", "Starred") passes its own, for the same
+   * reason {@link accessCopy} exists: the mechanism is general and the words are not.
+   */
+  pinnedLabel?: string;
 
   /**
    * Commit a drag. Omit it and the tree cannot be rearranged at all — no press starts a
    * drag, and {@link unavailableReason} says why on hover.
    */
   onMove?: (nodeId: string, drop: FileTreeDrop) => void;
+  /**
+   * Commit a move of MORE THAN ONE row — a dragged selection, or ⌘X then ⌘V.
+   *
+   * 🔴 The single rule that keeps every plural gesture from surprising an old consumer:
+   * **N > 1 always goes through this prop, and without it every gesture degrades to the one
+   * row it started on.** A tree that fell back to calling `onMove` N times would hand a
+   * consumer N separate writes against a tree that is re-derived between each of them, which
+   * is how a batch move half-lands.
+   *
+   * The ids arrive with descendants of other selected rows already removed — see
+   * `topmostSelected`. Moving a folder moves what is in it, so a selected child is the same
+   * move named twice, and acting on both flattens the child out of its own parent.
+   */
+  onMoveMany?: (nodeIds: readonly string[], drop: FileTreeDrop) => void;
   /** See `ResolveDropOptions.allowReorder`. Off unless the consumer stores an order. */
   allowReorder?: boolean;
   /** Words for refusing a drop into a node whose `acceptsDrop` is false. */
@@ -182,6 +411,34 @@ export interface FileTreeProps {
    * consumer owns the confirmation — this only reports which row the key was pressed on.
    */
   onDelete?: (node: FileTreeNode) => void;
+  /**
+   * The same keys on a SELECTION of more than one — *"hold command and click delete to
+   * delete all the selected files"*.
+   *
+   * Without it, ⌫ on a multi-selection deletes the focused row alone, which is today's
+   * behaviour and a consumer that never asked for the plural keeps it. The nodes are handed
+   * over rather than the ids, because a confirmation dialog needs their names.
+   */
+  onDeleteMany?: (nodes: readonly FileTreeNode[]) => void;
+
+  /**
+   * ⌘C then ⌘V — *"Copying should allow copying in another folder or the same folder."*
+   *
+   * Wiring it is what puts ⌘C on the keyboard at all. `drop` is where the paste landed,
+   * resolved by exactly the rules a drag obeys, so a copy can never reach a destination the
+   * pointer refuses.
+   */
+  onCopy?: (nodeIds: readonly string[], drop: FileTreeDrop) => void;
+  /**
+   * The consumer's veto on copying a row — words to refuse with, `null` to allow. The same
+   * shape as {@link canDrop}, and consulted BEFORE ⌘C takes, never after ⌘V.
+   *
+   * 🔴 Copy is the one clipboard verb that is not universal. A folder in `apps/music` is
+   * derived from the `folder` column of the tracks in it, so copying one would mean
+   * duplicating audio there is exactly one copy of — the tree must not assume every consumer
+   * can paste. See `refuseCopy`.
+   */
+  canCopy?: (node: FileTreeNode) => string | null;
 
   /**
    * A row being named that does not exist yet — the "New folder" gesture.
@@ -189,10 +446,59 @@ export interface FileTreeProps {
    * 🔴 Nothing is created until the name is committed. A folder made first and renamed
    * afterwards is a row that spent a moment called "untitled", and a row in the way if the
    * field is cancelled.
+   *
+   * `wrap` is the same draft asked to close AROUND rows that already exist — *"allow make
+   * dir from file where dir wraps file location and gets name of file"*, which is Finder's
+   * **New Folder with Selection** and VS Code's ⌃⌘N. It is the ids to re-file into the
+   * folder the moment it is made; the field opens pre-filled with the first one's name minus
+   * its extension, and {@link onWrapStart} is how the tree ASKS for one of these.
    */
-  draft?: { parentId: string | null } | null;
-  onDraftCommit?: (name: string) => void;
+  draft?: { parentId: string | null; wrap?: readonly string[] } | null;
+  /**
+   * The name was committed: make the folder.
+   *
+   * 🔴 `wrap` arrives in the SAME call, never as a second one, and that is the whole reason
+   * this prop grew an argument instead of a sibling callback being added beside it. "Create
+   * the folder, then move four things into it" is two round trips, and the failure mode of
+   * the second one is a folder that exists, is empty, is named after a file that is still
+   * sitting outside it, and that nobody asked for. One call is one transaction on the
+   * consumer's side, which is where the only transaction can be.
+   *
+   * It is absent — not empty — for an ordinary new folder, so a consumer written before this
+   * existed is called exactly as it always was. The ids are pruned of rows inside other
+   * wrapped rows and are in tree order; see `planWrap`.
+   */
+  onDraftCommit?: (name: string, wrap?: readonly string[]) => void;
   onDraftCancel?: () => void;
+  /**
+   * **⌃⌘N** on a focused row — *make a folder around this*. Wiring it is what puts the chord
+   * on the keyboard at all, and a consumer that does not is byte-for-byte unchanged.
+   *
+   * The tree does not own `draft`, so it cannot open one itself: this is the same shape
+   * {@link onRenameStart} has, and the answer to it is to set
+   * `draft = { parentId, wrap: nodes.map(n => n.id) }`. Both arguments are already worked
+   * out — the nodes in tree order with descendants of other chosen rows dropped, and the
+   * parent of the first of them, which is *where the file already is*. Wire a row menu's own
+   * "New folder with selection" to the SAME call so the two cannot drift.
+   *
+   * On a selection of more than one it is the whole selection (Finder's rule); on a row
+   * outside the selection it is that row alone, which is the rule every other plural gesture
+   * here already follows.
+   */
+  onWrapStart?: (nodes: readonly FileTreeNode[], parentId: string | null) => void;
+  /**
+   * The consumer's veto on wrapping a row — words to refuse with, `null` to allow. The twin
+   * of {@link canCopy}, consulted BEFORE the draft opens.
+   *
+   * 🔴 A tree whose folders are DERIVED has nothing to wrap with. `apps/music` builds a
+   * folder out of the `folder` column of the tracks inside it, so there is no folder for this
+   * gesture to make — and offering a name field that cannot be honoured is the "control that
+   * fails on commit" this component refuses everywhere else. See `refuseWrap`.
+   *
+   * A row the consumer marked `draggable: false` is refused without asking, because wrapping
+   * it MOVES it — the same all-or-nothing rule `beginDrag` holds.
+   */
+  canWrap?: (node: FileTreeNode) => string | null;
 
   /**
    * The focused row's own menu, reached by **Shift+F10** or the **Menu** key — the keyboard's
@@ -324,10 +630,18 @@ export function FileTree({
   nodes,
   selectedId,
   onSelect,
+  selectedIds,
+  onSelectionChange,
   onOpen,
   collapsed: collapsedProp,
   onCollapsedChange,
+  expandOnReveal = false,
+  onRevealExpand,
+  pinnedIds,
+  onPinnedChange,
+  pinnedLabel = 'Pinned',
   onMove,
+  onMoveMany,
   allowReorder = false,
   lockedReason,
   canDrop,
@@ -337,9 +651,14 @@ export function FileTree({
   onRename,
   onRenameCancel,
   onDelete,
+  onDeleteMany,
+  onCopy,
+  canCopy,
   draft,
   onDraftCommit,
   onDraftCancel,
+  onWrapStart,
+  canWrap,
   onRowMenu,
   renderTools,
   renderIcon,
@@ -354,6 +673,16 @@ export function FileTree({
 }: FileTreeProps): JSX.Element {
   const scrollRef = useRef<HTMLDivElement>(null);
   const rowRefs = useRef(new Map<string, HTMLElement>());
+  /**
+   * The PINNED copies' elements, in a map of their own.
+   *
+   * 🔴 The second half of "one identity, two row keys" (see the header). A pinned row is the
+   * same node drawn a second time, so registering both copies under `node.id` would make
+   * every `rowRefs.get(id)` a coin toss — the reveal would scroll to whichever won, the drag's
+   * hit test would measure the wrong box, and focus would land in the wrong section. `node.id`
+   * stays the identity; the COPY is addressed here.
+   */
+  const pinnedRefs = useRef(new Map<string, HTMLElement>());
   const autoScroll = useRef<{ direction: number; timer: ReturnType<typeof setInterval> } | null>(
     null,
   );
@@ -372,9 +701,26 @@ export function FileTree({
    * gesture; the click is debris from it.
    */
   const draggedJustNow = useRef(false);
+  /**
+   * Where a shift-click measures FROM — the last row plain-clicked or ⌘-clicked.
+   *
+   * 🔴 A shift-click deliberately does not move it. That is what lets a second shift-click
+   * re-cover the range from the same start instead of growing it one row at a time, which is
+   * the behaviour every file explorer has and the reason the anchor is not just "the last
+   * thing selected".
+   */
+  const anchor = useRef<string | null>(null);
 
   const [ownCollapsed, setOwnCollapsed] = useState<readonly string[]>([]);
-  const collapsed = collapsedProp ?? ownCollapsed;
+  /**
+   * What the CONSUMER holds — the value it persists, and the only one ever written back.
+   *
+   * 🔴 Everything below reads `collapsed` instead, which is this list minus whatever an
+   * expanding reveal opened. The two are the same list for every consumer that does not wire
+   * {@link FileTreeProps.expandOnReveal}, and keeping them apart is what lets the reveal open
+   * a folder without the open ever reaching storage — see `revealOpened`.
+   */
+  const persistedCollapsed = collapsedProp ?? ownCollapsed;
   const setCollapsed = useCallback(
     (next: string[]) => {
       if (collapsedProp === undefined) setOwnCollapsed(next);
@@ -382,9 +728,66 @@ export function FileTree({
     },
     [collapsedProp, onCollapsedChange],
   );
+  /**
+   * The folders an expanding reveal opened — a TRANSIENT overlay, never written out.
+   *
+   * 🔴 This is the answer to the objection limit 1 of the reveal records, and it is a
+   * correctness answer rather than a taste one: `collapsed` is a CONTROLLED value the
+   * consumer persists, so a reveal that opened a folder by calling `onCollapsedChange` would
+   * write a collapse the person chose away for good — every later mount would find it open
+   * and nothing in the app would ever put it back. An overlay cannot do that. The consumer's
+   * list is untouched, the open lasts as long as this tree is mounted, and shutting the
+   * folder by hand drops the overlay entry and lets the persisted value decide again.
+   *
+   * The other half is where the writes go: every one of them below is a DELTA on
+   * `persistedCollapsed` (`shutFolders`/`openFolders`) rather than the effective list handed
+   * back whole. A write computed from the effective list would drop every other overlay id
+   * out of the consumer's value — the same corruption by a longer route.
+   */
+  const [revealOpened, setRevealOpened] = useState<readonly string[]>([]);
+  /** Which folders are shut ON SCREEN: the consumer's list, minus what a reveal opened. */
+  const collapsed = useMemo(
+    () =>
+      revealOpened.length === 0
+        ? persistedCollapsed
+        : persistedCollapsed.filter((id) => !revealOpened.includes(id)),
+    [persistedCollapsed, revealOpened],
+  );
+  /**
+   * Shut folders — added to the consumer's list, and dropped from the reveal's overlay so the
+   * two cannot disagree about a folder somebody has just shut by hand.
+   */
+  const shutFolders = useCallback(
+    (ids: readonly string[]) => {
+      setRevealOpened((prev) =>
+        prev.some((id) => ids.includes(id)) ? prev.filter((id) => !ids.includes(id)) : prev,
+      );
+      const add = ids.filter((id) => !persistedCollapsed.includes(id));
+      if (add.length > 0) setCollapsed([...persistedCollapsed, ...add]);
+    },
+    [persistedCollapsed, setCollapsed],
+  );
+  /** Open folders — the same delta in the other direction. An explicit open IS persisted. */
+  const openFolders = useCallback(
+    (ids: readonly string[]) => {
+      setRevealOpened((prev) =>
+        prev.some((id) => ids.includes(id)) ? prev.filter((id) => !ids.includes(id)) : prev,
+      );
+      if (!persistedCollapsed.some((id) => ids.includes(id))) return;
+      setCollapsed(persistedCollapsed.filter((id) => !ids.includes(id)));
+    },
+    [persistedCollapsed, setCollapsed],
+  );
 
   const [drag, setDrag] = useState<DragState | null>(null);
-  const [focusedId, setFocusedId] = useState<string | null>(null);
+  /**
+   * The row the keyboard is on, and WHICH COPY of it — the roving tabindex's answer.
+   *
+   * 🔴 The section is part of the answer, not decoration. A pinned row and its row in the
+   * folder share one `node.id`, so an id alone would make both copies claim `tabIndex={0}` and
+   * the tree would have two tab stops for one row. Two trees have two stops; one row does not.
+   */
+  const [focused, setFocused] = useState<{ id: string; pinned: boolean } | null>(null);
   /** The row an EXTERNAL drag is over, drawn with the same marker an internal one uses. */
   const [externalOverId, setExternalOverId] = useState<string | null>(null);
   /**
@@ -396,6 +799,23 @@ export function FileTree({
    * reading of "broken" this tree's whole drop design exists to avoid.
    */
   const [notice, setNotice] = useState('');
+  /**
+   * What ⌘X or ⌘C is holding, and which of the two it was.
+   *
+   * 🔴 The tree owns this, not the consumer. A clipboard is UI state with a VISIBLE
+   * consequence — the cut rows are drawn lifted (`data-cut`) until they land — and pushing it
+   * out as a prop would make the mark a thing every consumer has to remember to draw. What
+   * the consumer owns is the verb: `onMoveMany`/`onMove` for a cut, `onCopy` for a copy,
+   * reached only through the same drop rules a drag obeys.
+   *
+   * Cleared by a paste of a CUT (the rows have moved; a second paste would move them again
+   * from wherever they now are) and kept after a copy, which is what Finder does and what
+   * *"copying in another folder or the same folder"* needs.
+   */
+  const [clipboard, setClipboard] = useState<{
+    mode: 'cut' | 'copy';
+    ids: readonly string[];
+  } | null>(null);
 
   const shown = useMemo(() => (filter ? filterFileTree(nodes, filter) : nodes), [nodes, filter]);
   /*
@@ -407,6 +827,127 @@ export function FileTree({
     [shown, collapsed, filter],
   );
 
+  const pinned = pinnedIds ?? NO_PINS;
+
+  /**
+   * The pinned section's rows — the same nodes, drawn a second time and drawn FLAT.
+   *
+   * Built off `flattenFileTree(shown, [])` rather than off `rows`, because a pinned row is
+   * very often inside a folder that is shut: the whole point of pinning it is to reach it
+   * without opening anything. So the section is derived from the tree rather than from what
+   * the tree is currently showing, and a pin the tree no longer holds — deleted elsewhere,
+   * narrowed away by `filter` — simply is not drawn. A ghost row that cannot be clicked is
+   * worse than an absent one, and the pin itself is the consumer's to prune if it wants.
+   *
+   * 🔴 `depth: 0` and `expandable: false`, but the REAL `parentId` and `index`. The section is
+   * a flat list of shortcuts — indenting it would redraw a hierarchy beside the one below it,
+   * and a twisty there would open a branch inside a section that has no branches. What it
+   * keeps is where the row actually LIVES, because that is what a drop aimed at it resolves
+   * against: dropping onto the pinned copy of `Projects` files things into `Projects`.
+   */
+  const pinnedRows = useMemo<FileTreeRow[]>(() => {
+    if (pinned.length === 0) return [];
+    const all = new Map(flattenFileTree(shown, []).map((row) => [row.node.id, row]));
+    const out: FileTreeRow[] = [];
+    for (const id of pinned) {
+      const real = all.get(id);
+      if (real) out.push({ ...real, depth: 0, expandable: false, expanded: false });
+    }
+    return out;
+  }, [pinned, shown]);
+
+  /**
+   * The whole selection, singular or plural — `[selectedId]` for a consumer that never
+   * passed {@link FileTreeProps.selectedIds}, which is every consumer that existed before
+   * this and the reason nothing below has a "multi-select mode" branch.
+   */
+  const selection = useMemo<readonly string[]>(
+    () => selectedIds ?? (selectedId === null ? [] : [selectedId]),
+    [selectedIds, selectedId],
+  );
+  const selected = useMemo(() => new Set(selection), [selection]);
+  const cut = useMemo(
+    () => (clipboard?.mode === 'cut' ? new Set(clipboard.ids) : null),
+    [clipboard],
+  );
+
+  /**
+   * Which rows a gesture aimed at `node` should act on: the selection when `node` is part of
+   * one and the consumer wired the plural verb, and `node` alone otherwise.
+   *
+   * 🔴 `batched` is the whole compatibility story in one argument. Every plural callback is
+   * optional, so a consumer that wired only the singular one keeps the singular behaviour on
+   * every gesture — the tree never invents a batch nobody can receive.
+   */
+  const actOn = useCallback(
+    (node: FileTreeNode, plural: boolean): { ids: string[]; batched: boolean } => {
+      if (!plural || selection.length < 2 || !selected.has(node.id))
+        return { ids: [node.id], batched: false };
+      /*
+       * 🔴 `batched` is NOT `ids.length > 1`, and the difference is a real bug that was in
+       * here first. Select a folder AND a file inside it, then press ⌫: `topmostSelected`
+       * correctly prunes the pair to one id, and a plural test written on the COUNT then
+       * falls through to the singular callback — so a consumer that only wired
+       * `onDeleteMany` gets nothing at all and the key does nothing. The gesture is plural
+       * because it was aimed at a SELECTION, whatever pruning leaves.
+       */
+      return { ids: topmostSelected(shown, selection), batched: true };
+    },
+    [selected, selection, shown],
+  );
+
+  /** Whether the tree can be rearranged at all — either verb counts. */
+  const canRearrange = Boolean(onMove || onMoveMany);
+
+  /**
+   * Commit a move through whichever verb the consumer wired, never through both.
+   *
+   * More than one row is `onMoveMany`'s alone (see its header); one row prefers `onMove`, so
+   * a consumer that wired only the singular one sees exactly the call it always saw.
+   */
+  const commitMove = useCallback(
+    (ids: readonly string[], target: FileTreeDrop) => {
+      if (ids.length === 0) return;
+      if (ids.length > 1) {
+        onMoveMany?.(ids, target);
+        return;
+      }
+      if (onMove) onMove(ids[0] as string, target);
+      else onMoveMany?.(ids, target);
+    },
+    [onMove, onMoveMany],
+  );
+
+  // ── The draft, and the rows it may be closing around ──────────────────────────────────
+
+  /**
+   * What the open draft would wrap, re-derived from the tree it is actually drawn against.
+   *
+   * 🔴 Planned HERE rather than trusted as given, even though {@link FileTreeProps.onWrapStart}
+   * hands the consumer the same answer. A draft is open for as long as somebody is typing,
+   * and the tree underneath it is re-derived while they do — a row can be gone by the time
+   * Enter is pressed. Re-planning means the ids that reach `onDraftCommit` are ids the tree
+   * still holds, in tree order, with descendants pruned, whatever the consumer stored.
+   */
+  const wrapping = useMemo(
+    () => (draft?.wrap && draft.wrap.length > 0 ? planWrap(shown, draft.wrap) : null),
+    [draft, shown],
+  );
+
+  /**
+   * The name field committed — the folder and its contents in ONE call. See
+   * {@link FileTreeProps.onDraftCommit} for why it cannot be two.
+   */
+  const commitDraft = useCallback(
+    (name: string) => {
+      // A wrap whose rows have all gone away is a plain new folder, and is called as one:
+      // `wrap` is ABSENT rather than empty, which is the argument an old consumer never sees.
+      if (wrapping) onDraftCommit?.(name, wrapping.ids);
+      else onDraftCommit?.(name);
+    },
+    [onDraftCommit, wrapping],
+  );
+
   /**
    * The folders between the root and the selected row, and the shut one HOLDING it.
    *
@@ -453,24 +994,93 @@ export function FileTree({
     return counts;
   }, [rows]);
 
+  /*
+   * 🔴 On what the row is DRAWN as, not on what the consumer stored. A folder an expanding
+   * reveal opened is in `persistedCollapsed` and open on screen, so a toggle read off the
+   * stored list would "open" a folder somebody is looking at and the twisty would do nothing.
+   */
   const toggle = useCallback(
     (id: string) => {
-      const set = new Set(collapsed);
-      if (set.has(id)) set.delete(id);
-      else set.add(id);
-      setCollapsed([...set]);
+      if (collapsed.includes(id)) openFolders([id]);
+      else shutFolders([id]);
     },
-    [collapsed, setCollapsed],
+    [collapsed, openFolders, shutFolders],
   );
 
   const openFolder = useCallback(
     (id: string) => {
       if (!collapsed.includes(id)) return false;
-      setCollapsed(collapsed.filter((c) => c !== id));
+      openFolders([id]);
       return true;
     },
-    [collapsed, setCollapsed],
+    [collapsed, openFolders],
+  );
+
+  /**
+   * Pin a row, or take the pin off — the one verb the section has, from either copy.
+   *
+   * `toggleSelected` is reused rather than re-derived: "in if it was out, out if it was in,
+   * and the ORDER of the rest is kept" is the same rule a ⌘-click follows, and the order is
+   * load-bearing here too — a new pin joins the END of the section instead of resorting a list
+   * somebody has arranged.
+   *
+   * 🔴 It says so out loud. The pinned section may be scrolled off, or the pin may have been
+   * pressed on the top copy where the change is a row VANISHING from under the pointer — so
+   * the live region names what happened, the same way every keyboard move here does.
+   */
+  const togglePin = useCallback(
+    (node: FileTreeNode) => {
+      if (!onPinnedChange) return;
+      const next = toggleSelected(pinned, node.id);
+      onPinnedChange(next);
+      setNotice(next.includes(node.id) ? `Pinned ${node.name}` : `Unpinned ${node.name}`);
+    },
+    [onPinnedChange, pinned],
+  );
+
+  /**
+   * The shut folders between the root and the selection — what an expanding reveal opens.
+   *
+   * Empty unless {@link FileTreeProps.expandOnReveal} is wired, and empty while a `filter` is
+   * running: a filter draws everything it kept whatever `collapsed` says, so there is nothing
+   * shut to open and an overlay built there would outlive the search that caused it.
+   *
+   * 🔴 `searching` exists so that no line in this file — code OR comment, both are scanned —
+   * is a bang immediately followed by the word `filter`. Tailwind v4 reads SOURCE for
+   * candidates, `filter` is a real utility, and that pair is its important variant: written
+   * literally, `expandOnReveal && <bang>filter && …` emits an escaped `filter` rule with
+   * `!important` into every stylesheet this component's area ships, which fails the CSS budget
+   * in `src/fixtureAppCss.spec.ts` — a red hundreds of lines away from anything that looks
+   * like CSS. Measured: it cost this change a whole gate run, and then a second one when the
+   * comment explaining it quoted the token it was warning about. `LogViewer.tsx` gets away
+   * with the same pair only because the `.` of `.trim()` breaks the candidate; do not rely on
+   * that. Negate a plain boolean of your own instead — no utility is named `searching`.
+   */
+  const searching = Boolean(filter);
+  const revealShut = useMemo(
+    () =>
+      expandOnReveal && !searching && openPath.path.size > 0
+        ? [...openPath.path].filter((id) => collapsed.includes(id))
+        : [],
+    [collapsed, expandOnReveal, searching, openPath],
   );
+  /**
+   * The same list, readable from the reveal without becoming one of its triggers.
+   *
+   * 🔴 The effect below must fire on a SELECTION change and on nothing else (limits 2 and 3),
+   * and `revealShut` moves whenever the tree does — a rename, a new row, a folder opened by
+   * hand. Depending on it would scroll the list on all three. The mirror is written by an
+   * effect declared FIRST, so it is already fresh when the reveal runs in the same commit.
+   */
+  const revealTargets = useRef<readonly string[]>(revealShut);
+  /** The same, for the callback: a reveal two selections later must not call a stale one. */
+  const announceReveal = useRef(onRevealExpand);
+  useEffect(() => {
+    revealTargets.current = revealShut;
+    announceReveal.current = onRevealExpand;
+  }, [revealShut, onRevealExpand]);
+  /** The selection an expanding reveal has already fired for — see limit 1 below. */
+  const revealedFor = useRef<string | null>(null);
 
   /**
    * Bring the selected row into view — the explorer's *reveal*.
@@ -484,10 +1094,31 @@ export function FileTree({
    *
    * Three deliberate limits, each of which VS Code gets right or wrong depending on a setting:
    *
-   * 1. 🔴 **A shut folder stays shut.** Its `data-holds-open` marker is scrolled to instead.
-   *    Auto-expanding is what `explorer.autoReveal` does and it is the behaviour people turn
-   *    off, because it silently undoes a collapse they chose — and `collapsed` here is often
-   *    a CONTROLLED value the consumer persists, so expanding would write it open for good.
+   * 1. **A shut folder stays shut** — *unless* {@link FileTreeProps.expandOnReveal} is wired,
+   *    which is the opt-in half of this limit rather than an exception to it. Left unwired,
+   *    the shut folder's `data-holds-open` marker is scrolled to and nothing opens.
+   *
+   *    🔴 **The argument, and what changed about it, 2026-09-16.** This limit was written as
+   *    a flat refusal: auto-expanding is what `explorer.autoReveal` does and it is the
+   *    behaviour people turn off, because it silently undoes a collapse they chose — and
+   *    `collapsed` here is often a CONTROLLED value the consumer persists, so expanding would
+   *    write it open for good. Then the owner asked for it BY NAME — *"show that file in the
+   *    file tree by like vscode does when you select a tab with a file in it"* — and named the
+   *    application whose default is `true`. His ask wins over the default this file chose for
+   *    him, so the behaviour is here.
+   *
+   *    What survives is the half of the objection that was never taste: **the persisted value
+   *    is not rewritten.** The expansion goes into `revealOpened`, an overlay of this tree's
+   *    own, and `onCollapsedChange` is never called for it — so the consumer's collapse is
+   *    read back unchanged on the next mount, and a folder shut by hand goes back to obeying
+   *    it. The two candidate designs were that and "call `onCollapsedChange` and let the
+   *    consumer refuse to keep it"; the second makes every consumer that wires the prop
+   *    responsible for not persisting a write it did not ask for, and the one that forgets
+   *    has the bug this paragraph exists to prevent. Defaults, not diligence.
+   *
+   *    It fires once per SELECTION, not continuously: shut an expanded ancestor by hand while
+   *    the same file is open and it stays shut, which is what VS Code does and the only thing
+   *    that leaves the twisty working at all.
    * 2. **Only when the row is not already visible.** A list that jumps a few pixels every
    *    time you click a row you can already see reads as a bug.
    * 3. **Never mid-drag.** Scrolling the list under a drag moves the drop target out from
@@ -500,11 +1131,31 @@ export function FileTree({
    * `data-holds-open` is the answer precisely when the selected row has none — but it is the
    * one thing whose CHANGE should reveal. And `drag` IS read, as a guard rather than a
    * trigger: adding it would reveal the moment a drag ends, which is limit 3 above.
+   *
+   * `revealOpened` is the SECOND PASS of an expanding reveal, and nothing else: the row it was
+   * asked to scroll to does not exist in the DOM until the folders above it are open, so the
+   * expansion returns without scrolling and the re-render it causes is what lands the scroll.
+   * What it must NOT be is the trigger for expanding again — that is `revealedFor`, below.
    */
-  // biome-ignore lint/correctness/useExhaustiveDependencies: `selectedId` is the trigger and not a read; `drag` is a guard and not a trigger — see just above.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `selectedId` is the trigger and not a read; `drag` is a guard and not a trigger; `revealOpened` is the second pass — see just above.
   useEffect(() => {
     const scroller = scrollRef.current;
     if (!scroller || drag?.active) return;
+    /*
+     * Once per selection, whatever it finds — the ref moves even when there is nothing shut to
+     * open, so a later hand-shut of one of these folders cannot be undone by this effect.
+     */
+    if (revealedFor.current !== selectedId) {
+      revealedFor.current = selectedId;
+      const toOpen = revealTargets.current;
+      if (toOpen.length > 0) {
+        setRevealOpened((prev) => [...prev, ...toOpen.filter((id) => !prev.includes(id))]);
+        // 🔴 Said out loud, because a consumer that FETCHES a folder's children on open has
+        // no other way to learn of it — see {@link FileTreeProps.onRevealExpand}.
+        announceReveal.current?.(toOpen);
+        return;
+      }
+    }
     const row =
       scroller.querySelector<HTMLElement>('.cbft-row[data-selected]') ??
       scroller.querySelector<HTMLElement>('.cbft-row[data-holds-open]');
@@ -515,7 +1166,7 @@ export function FileTree({
     // `nearest` on both axes: the least movement that makes the row visible, and no sideways
     // travel in a list that does not scroll sideways.
     row.scrollIntoView({ block: 'nearest', inline: 'nearest' });
-  }, [selectedId]);
+  }, [selectedId, revealOpened]);
 
   // ── The drag ──────────────────────────────────────────────────────────────────────────
 
@@ -533,17 +1184,39 @@ export function FileTree({
 
   /** The row under a client point, and how far down it the pointer is. */
   const rowAt = useCallback(
-    (x: number, y: number): { row: FileTreeRow; ratio: number } | null => {
+    (
+      x: number,
+      y: number,
+    ): { row: FileTreeRow; ratio: number; pinned: boolean } | null => {
+      /*
+       * The PINNED copies first — they are drawn in their own box above the scroller, so a
+       * point inside one is never inside a tree row and the two loops cannot both answer.
+       *
+       * 🔴 The middle of the row, and `pinned` so the caller turns REORDERING off for it. A
+       * pinned row's edges have no "between these two" to express: the section's order is the
+       * pin order, which is not an order in the tree at all — so a `before`/`after` aimed
+       * there would draw a marker in one list and re-file the row among siblings it is not
+       * drawn beside in another. What is left is the whole requirement and nothing else: the
+       * row carries its REAL `parentId`, so "into" is the real folder, and a drop on the
+       * pinned copy of `Projects` files into `Projects`.
+       */
+      for (const row of pinnedRows) {
+        const el = pinnedRefs.current.get(row.node.id);
+        if (!el) continue;
+        const box = el.getBoundingClientRect();
+        if (y >= box.top && y <= box.bottom && x >= box.left && x <= box.right)
+          return { row, ratio: 0.5, pinned: true };
+      }
       for (const row of rows) {
         const el = rowRefs.current.get(row.node.id);
         if (!el) continue;
         const box = el.getBoundingClientRect();
         if (y >= box.top && y <= box.bottom && x >= box.left && x <= box.right)
-          return { row, ratio: box.height > 0 ? (y - box.top) / box.height : 0.5 };
+          return { row, ratio: box.height > 0 ? (y - box.top) / box.height : 0.5, pinned: false };
       }
       return null;
     },
-    [rows],
+    [pinnedRows, rows],
   );
 
   const endDrag = useCallback(
@@ -554,31 +1227,50 @@ export function FileTree({
       // click — see `draggedJustNow`. Set for a cancelled drag too: the click arrives either
       // way, and Escape landing you on a different row would be its own surprise.
       if (state?.active) draggedJustNow.current = true;
-      if (commit && state?.active && state.offer.target && onMove) {
-        onMove(state.id, state.offer.target);
+      if (commit && state?.active && state.offer.target && canRearrange) {
+        commitMove(state.ids, state.offer.target);
         sprung.current = [];
       } else if (sprung.current.length > 0) {
         // A drag that opened folders on its way and then went nowhere puts them back — the
         // tree it leaves behind must be the tree it found.
-        const shut = new Set(collapsed);
-        for (const id of sprung.current) shut.add(id);
+        const back = sprung.current;
         sprung.current = [];
-        setCollapsed([...shut]);
+        shutFolders(back);
       }
       setDrag(null);
     },
-    [collapsed, onMove, setCollapsed, stopAutoScroll, stopSpring],
+    [canRearrange, commitMove, shutFolders, stopAutoScroll, stopSpring],
   );
 
   const beginDrag = useCallback(
     (event: ReactPointerEvent<HTMLElement>, node: FileTreeNode) => {
       // A row the consumer marked undraggable never starts a gesture — see
       // `FileTreeNode.draggable`. A drag that refuses everywhere reads as a broken tree.
-      if (!onMove || event.button !== 0 || node.draggable === false) return;
+      if (!canRearrange || event.button !== 0 || node.draggable === false) return;
+
+      /*
+       * Press a row that is part of a selection and the whole selection comes with you —
+       * *"with all of those selected I want to be able to click and hold on any of them to
+       * drag and drop them to another folder"*. Press one that is not, and the selection is
+       * left where it is: Finder's rule, and the only one that lets you move a single row out
+       * of a group you have built without dismantling it first.
+       */
+      const { ids } = actOn(node, Boolean(onMoveMany));
+      /*
+       * 🔴 All or nothing. One undraggable row in the set stops the whole gesture rather than
+       * quietly leaving it behind — a drag that moved four of five rows and said nothing is
+       * the failure the plural drop rule exists to prevent (see `resolveMultiDrop`), and it
+       * would be no better for arriving at the START of the gesture instead of the end.
+       * `apps/collections` marks its albums `draggable: false`, so this is reachable there by
+       * ⌘-clicking one into a selection of folders.
+       */
+      if (ids.some((id) => findFileTreeNode(shown, id)?.draggable === false)) return;
+
       const startX = event.clientX;
       const startY = event.clientY;
       let state: DragState = {
         id: node.id,
+        ids,
         startX,
         startY,
         x: startX,
@@ -595,12 +1287,18 @@ export function FileTree({
         if (!state.active && travelled < DRAG_THRESHOLD) return;
 
         const hit = rowAt(moveEvent.clientX, moveEvent.clientY);
-        const offer = resolveDrop({
+        // One row or twenty, the same call: `resolveMultiDrop` is `resolveDrop` asked once
+        // per carried row, and the strictest answer wins. See its header for why a single
+        // refusal refuses the whole drop.
+        const offer = resolveMultiDrop({
           nodes: shown,
           row: hit?.row ?? null,
           offsetRatio: hit?.ratio ?? 0.5,
-          dragId: node.id,
-          allowReorder,
+          dragIds: ids,
+          // 🔴 Off over the pinned section, whatever the consumer stores. See `rowAt`: those
+          // rows are drawn in pin order, so there is no "between these two" for an edge to
+          // mean there — only "into this", which is the real folder.
+          allowReorder: allowReorder && !hit?.pinned,
           ...(lockedReason ? { lockedReason } : {}),
           ...(canDrop ? { canDrop } : {}),
         });
@@ -677,12 +1375,14 @@ export function FileTree({
       window.addEventListener('keydown', abort);
     },
     [
+      actOn,
       allowReorder,
       canDrop,
+      canRearrange,
       collapsed,
       endDrag,
       lockedReason,
-      onMove,
+      onMoveMany,
       openFolder,
       rowAt,
       shown,
@@ -693,9 +1393,18 @@ export function FileTree({
 
   // A drag abandoned by a re-render — the folder deleted in another tab, the list replaced
   // under the pointer — must not leave a marker behind.
+  //
+  // 🔴 The pinned section counts as "still drawn". A drag started from the top copy of a row
+  // that lives inside a SHUT folder has no row in `rows` at all — which is the ordinary case
+  // for a pin, not an edge one — so this would cancel the gesture on its first re-render.
   useEffect(() => {
-    if (drag && !rows.some((r) => r.node.id === drag.id)) setDrag(null);
-  }, [drag, rows]);
+    if (
+      drag &&
+      !rows.some((r) => r.node.id === drag.id) &&
+      !pinnedRows.some((r) => r.node.id === drag.id)
+    )
+      setDrag(null);
+  }, [drag, pinnedRows, rows]);
 
   useEffect(
     () => () => {
@@ -707,11 +1416,28 @@ export function FileTree({
 
   // ── The keyboard ──────────────────────────────────────────────────────────────────────
 
-  const focusRow = useCallback((id: string | null) => {
-    setFocusedId(id);
-    if (id) rowRefs.current.get(id)?.focus();
+  /**
+   * The element drawing `id`, preferring the section asked for and falling back to the other.
+   *
+   * 🔴 The fallback is what makes the REAL row the default answer everywhere: a row in the
+   * tree is the one that has a depth, a twisty and ancestors marked above it, so focus and the
+   * rename field belong there whenever it is drawn. The pinned copy answers only for a row the
+   * tree is not currently showing — which, for a pin, is the common case.
+   */
+  const rowEl = useCallback((id: string, pinnedCopy: boolean): HTMLElement | undefined => {
+    const first = pinnedCopy ? pinnedRefs : rowRefs;
+    const second = pinnedCopy ? rowRefs : pinnedRefs;
+    return first.current.get(id) ?? second.current.get(id);
   }, []);
 
+  const focusRow = useCallback(
+    (id: string | null, pinnedCopy = false) => {
+      setFocused(id === null ? null : { id, pinned: pinnedCopy });
+      if (id) rowEl(id, pinnedCopy)?.focus();
+    },
+    [rowEl],
+  );
+
   /*
    * ── The keyboard comes back from a rename ─────────────────────────────────────────────
    *
@@ -740,12 +1466,23 @@ export function FileTree({
   }, [renamingId, focusRow]);
 
   const onKeyDown = useCallback(
-    (event: React.KeyboardEvent<HTMLElement>, row: FileTreeRow) => {
+    (
+      event: React.KeyboardEvent<HTMLElement>,
+      row: FileTreeRow,
+      /*
+       * The rows the ARROWS walk, and which section drew this one. A pinned copy's neighbours
+       * are the other pins, not the tree rows around where it lives — ↓ from the last pin
+       * jumping into the middle of a folder would be a cursor that teleports. Every verb below
+       * still acts on `row.node`, which is the one identity both copies share.
+       */
+      list: readonly FileTreeRow[],
+      pinnedCopy: boolean,
+    ) => {
       if (renamingId) return;
-      const index = rows.findIndex((r) => r.node.id === row.node.id);
+      const index = list.findIndex((r) => r.node.id === row.node.id);
       const step = (delta: number) => {
-        const next = rows[Math.min(rows.length - 1, Math.max(0, index + delta))];
-        if (next) focusRow(next.node.id);
+        const next = list[Math.min(list.length - 1, Math.max(0, index + delta))];
+        if (next) focusRow(next.node.id, pinnedCopy);
       };
 
       /*
@@ -755,11 +1492,175 @@ export function FileTree({
        */
       if (onRowMenu && (event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10'))) {
         event.preventDefault();
-        const box = rowRefs.current.get(row.node.id)?.getBoundingClientRect();
+        // The corner of the copy the keys are actually on — a menu anchored to the row in the
+        // folder while the focus ring is on the pinned one would open somewhere else entirely.
+        const box = rowEl(row.node.id, pinnedCopy)?.getBoundingClientRect();
         onRowMenu(row.node, { x: box?.right ?? 0, y: box?.bottom ?? 0 });
         return;
       }
 
+      /*
+       * ── ⌃⌘T — pin, and unpin ────────────────────────────────────────────────────────
+       *
+       * Owner, 2026-09-13: *"need … ability to pin open files where they stay at the top of
+       * the file tree … Pinned will mean I want to keep them there until I unpin them."* One
+       * chord for both directions, because it is one state with two values and a person who
+       * can pin can already see whether this row is pinned.
+       *
+       * ⌃⌘T is Finder's own **Add to Sidebar**, so the gesture is not one anybody has to be
+       * told about — and, exactly like ⌃⌘N above, it is anchored on **Ctrl** with ⌘ optional,
+       * for the Windows and Linux hosts this same tree runs on where there is no ⌘ to hold.
+       *
+       * Only when {@link FileTreeProps.onPinnedChange} is wired: with no consumer to receive
+       * the list this is not a chord this component has, and the event falls through to the
+       * browser rather than being swallowed by a control that would do nothing.
+       */
+      if (
+        onPinnedChange &&
+        event.ctrlKey &&
+        !event.altKey &&
+        !event.shiftKey &&
+        event.key.toLowerCase() === 't'
+      ) {
+        event.preventDefault();
+        togglePin(row.node);
+        return;
+      }
+
+      /*
+       * ── ⌃⌘N — New Folder with Selection ─────────────────────────────────────────────
+       *
+       * Owner, 2026-09-13: *"allow make dir from file where dir wraps file location and gets
+       * name of file"*. Finder calls it **New Folder with Selection** and VS Code binds it to
+       * ⌃⌘N, so the shape is settled and this invents nothing: the folder is made where the
+       * row already is, it is named after the row, and the row goes into it.
+       *
+       * 🔴 Ctrl is what the chord is anchored on, ⌘ optional — ⌃⌘N on a Mac, ⌃N on the
+       * Windows and Linux hosts this same tree runs on, where there is no ⌘ to hold. Bare
+       * ⌥/⇧ are excluded so the rest of the modifier space stays the app's.
+       *
+       * Like every other verb here it exists only when the consumer wired it: no
+       * `onWrapStart` and this is not a chord this component has, and the event falls through
+       * to the browser rather than being swallowed by a control that would do nothing.
+       */
+      if (
+        onWrapStart &&
+        event.ctrlKey &&
+        !event.altKey &&
+        !event.shiftKey &&
+        event.key.toLowerCase() === 'n'
+      ) {
+        event.preventDefault();
+        const { ids } = actOn(row.node, true);
+        const plan = planWrap(shown, ids);
+        if (!plan) return;
+        /*
+         * Both vetoes BEFORE the draft opens, never after a name is typed — the consumer's
+         * words first, then the tree's own rule about a row that cannot be moved at all.
+         * Either way it is said out loud: a chord that silently did nothing is the failure
+         * `notice` exists for.
+         */
+        const refused = refuseWrap(shown, plan.ids, canWrap);
+        if (refused) {
+          setNotice(refused);
+          return;
+        }
+        const stuck = plan.ids.find((id) => findFileTreeNode(shown, id)?.draggable === false);
+        if (stuck) {
+          setNotice(`${nameOf(shown, stuck)} cannot be moved`);
+          return;
+        }
+        onWrapStart(nodesByIds(shown, plan.ids), plan.parentId);
+        return;
+      }
+
+      /*
+       * ── ⌘X / ⌘C / ⌘V — the clipboard ────────────────────────────────────────────────
+       *
+       * Owner, 2026-09-14: *"I also want to be able to cut and paste to move them with
+       * command + x and command + v, and copy them with command + c and command + v. Copying
+       * should allow copying in another folder or the same folder. These are similar to how
+       * finder works except cutting and pasting will be easy with just command + x."*
+       *
+       * 🔴 Each key exists only when its verb does. No `onMove`/`onMoveMany` and ⌘X is not a
+       * key this tree has; no `onCopy` and neither is ⌘C — the event falls through to the
+       * browser rather than being swallowed by a control that would have done nothing with
+       * it. `preventDefault` is only ever called on a chord that is about to act.
+       *
+       * ⌃ as well as ⌘, because the same tree is used on Windows and Linux, where the
+       * clipboard chord is the same three letters with the other modifier.
+       *
+       * The paste DESTINATION is the focused row, resolved by exactly the rules a pointer
+       * drag obeys (`resolveMultiDrop`): a folder row means into it, a file row means the
+       * folder that row is in, and a top-level file row means the top level. So a paste can
+       * never reach somewhere the drag refuses, which is the "one opinion about what is
+       * legal" rule the keyboard MOVE already answers to.
+       */
+      if (
+        (event.metaKey || event.ctrlKey) &&
+        !event.altKey &&
+        (event.key === 'x' || event.key === 'c' || event.key === 'v')
+      ) {
+        if (event.key === 'x' && canRearrange) {
+          event.preventDefault();
+          const { ids } = actOn(row.node, Boolean(onMoveMany));
+          setClipboard({ mode: 'cut', ids });
+          setNotice(ids.length > 1 ? `Cut ${ids.length} items` : `Cut ${row.node.name}`);
+          return;
+        }
+        if (event.key === 'c' && onCopy) {
+          event.preventDefault();
+          const { ids } = actOn(row.node, true);
+          // The consumer's veto, asked BEFORE the clipboard takes — a copy that is going to
+          // be refused must be refused while there is still something to say it about.
+          const refused = refuseCopy(shown, ids, canCopy);
+          if (refused) {
+            setNotice(refused);
+            return;
+          }
+          setClipboard({ mode: 'copy', ids });
+          setNotice(ids.length > 1 ? `Copied ${ids.length} items` : `Copied ${row.node.name}`);
+          return;
+        }
+        if (event.key === 'v' && clipboard) {
+          event.preventDefault();
+          const offer = resolveMultiDrop({
+            nodes: shown,
+            row,
+            // The middle of the row: "into this", never "between these two". Reordering is a
+            // pointer gesture — a paste has no edge to aim at.
+            offsetRatio: 0.5,
+            allowReorder: false,
+            /*
+             * 🔴 The carried ids are declared for a COPY too, so the descendant rule applies
+             * to it: a folder cannot be pasted inside itself any more than it can be dragged
+             * there. What that rule does NOT refuse is the case the owner named — *"copying
+             * in … the same folder"* — because a row's own parent is not a descendant of it.
+             */
+            dragIds: clipboard.ids,
+            ...(lockedReason ? { lockedReason } : {}),
+            ...(canDrop ? { canDrop } : {}),
+          });
+          if (!offer.target) {
+            setNotice(offer.reason ?? '');
+            return;
+          }
+          setNotice(describeDrop(shown, offer.target));
+          if (clipboard.mode === 'copy') {
+            onCopy?.(clipboard.ids, offer.target);
+            // Kept, not cleared: Finder pastes the same copy again, and *"copying in another
+            // folder or the same folder"* is two pastes of one ⌘C.
+            return;
+          }
+          commitMove(clipboard.ids, offer.target);
+          // The rows have moved. A second paste would move them again from wherever they
+          // now are, which is not what the person cut them for.
+          setClipboard(null);
+          return;
+        }
+        return;
+      }
+
       /*
        * ⌥→ and ⌥← MOVE the focused row — the keyboard's half of the drag, and the only half
        * that exists on touch (a press-and-drag there scrolls the list, so the gesture is
@@ -770,7 +1671,7 @@ export function FileTree({
        * in this handler is bare-key, which is what keeps ⇧⏎/⌘F and the rest free for the app.
        */
       if (
-        onMove &&
+        canRearrange &&
         event.altKey &&
         !event.metaKey &&
         !event.ctrlKey &&
@@ -787,7 +1688,11 @@ export function FileTree({
         });
         if (offer.target) {
           setNotice(describeDrop(shown, offer.target));
-          onMove(row.node.id, offer.target);
+          // Deliberately the focused row alone, never the selection: `resolveKeyboardMove`
+          // answers for ONE row ("the nearest folder above IT", "the folder ITS folder is
+          // in"), and there is no one answer to that question for a set spread across
+          // several levels. The plural route is the drag and the clipboard.
+          commitMove([row.node.id], offer.target);
         } else {
           setNotice(offer.reason ?? '');
         }
@@ -813,16 +1718,19 @@ export function FileTree({
         case 'ArrowLeft': {
           event.preventDefault();
           if (row.expandable && row.expanded) toggle(row.node.id);
-          else if (row.parentId) focusRow(row.parentId);
+          // Never out of the pinned section: its rows are drawn flat, so "go to my parent"
+          // would leap the focus into the tree — and often onto a row that is not drawn,
+          // because the folder a pinned row lives in is very often shut.
+          else if (!pinnedCopy && row.parentId) focusRow(row.parentId);
           return;
         }
         case 'Home':
           event.preventDefault();
-          if (rows[0]) focusRow(rows[0].node.id);
+          if (list[0]) focusRow(list[0].node.id, pinnedCopy);
           return;
         case 'End':
           event.preventDefault();
-          if (rows.at(-1)) focusRow((rows.at(-1) as FileTreeRow).node.id);
+          if (list.at(-1)) focusRow((list.at(-1) as FileTreeRow).node.id, pinnedCopy);
           return;
         /*
           ── The keys VS Code taught everybody ───────────────────────────────────────────
@@ -869,11 +1777,39 @@ export function FileTree({
         // ⌫, Delete, and ⌘⌫ — the macOS chord arrives as `Backspace` + `metaKey`, so it is
         // this branch and not a fourth one. See {@link FileTreeProps.onDelete}.
         case 'Backspace':
-        case 'Delete':
+        case 'Delete': {
+          /*
+           * 🔴 On a SELECTION it deletes all of it — *"for both of these new selection
+           * functionalities I also want to be able to hold command and click delete to delete
+           * all the selected files"*. `onDeleteMany` is what makes that reachable; without it
+           * the key still means the focused row alone, which is what it has always meant.
+           *
+           * `actOn` prunes descendants of other selected rows, so deleting a folder and a
+           * file inside it asks for one deletion, not two — the second of which would be of
+           * something the first already took.
+           */
+          const { ids, batched } = actOn(row.node, Boolean(onDeleteMany));
+          if (batched && onDeleteMany) {
+            event.preventDefault();
+            onDeleteMany(nodesByIds(shown, ids));
+            return;
+          }
           if (!onDelete) return;
           event.preventDefault();
           onDelete(row.node);
           return;
+        }
+        /*
+         * Escape puts the clipboard down. A cut that is never pasted leaves every row it
+         * holds drawn as lifted (`data-cut`), and a mark with no way to take it off is a
+         * tree that looks permanently mid-gesture.
+         */
+        case 'Escape':
+          if (!clipboard) return;
+          event.preventDefault();
+          setClipboard(null);
+          setNotice('');
+          return;
         default:
           break;
       }
@@ -885,26 +1821,38 @@ export function FileTree({
           ? event.key
           : typeahead.current.word + event.key;
       typeahead.current = { word, at: now };
-      const found = matchTypeahead(rows, word, index);
+      const found = matchTypeahead(list, word, index);
       if (found >= 0) {
         event.preventDefault();
-        focusRow((rows[found] as FileTreeRow).node.id);
+        focusRow((list[found] as FileTreeRow).node.id, pinnedCopy);
       }
     },
     [
+      actOn,
+      canCopy,
       canDrop,
+      canRearrange,
+      canWrap,
+      clipboard,
+      commitMove,
       focusRow,
       lockedReason,
+      onCopy,
       onDelete,
-      onMove,
+      onDeleteMany,
+      onMoveMany,
       onOpen,
+      onPinnedChange,
       onRenameStart,
       onRowMenu,
       onSelect,
+      onWrapStart,
       renamingId,
+      rowEl,
       rows,
       shown,
       toggle,
+      togglePin,
     ],
   );
 
@@ -946,12 +1894,11 @@ export function FileTree({
         sprung.current = [];
         return;
       }
-      const shut = new Set(collapsed);
-      for (const id of sprung.current) shut.add(id);
+      const back = sprung.current;
       sprung.current = [];
-      setCollapsed([...shut]);
+      shutFolders(back);
     },
-    [collapsed, setCollapsed, stopSpring],
+    [shutFolders, stopSpring],
   );
 
   const externalHandlers = (node: FileTreeNode | null) =>
@@ -1004,13 +1951,51 @@ export function FileTree({
 
   const dropId =
     drag?.active && drag.offer.target?.kind === 'into' ? drag.offer.target.parentId : null;
-  const dragging = drag?.active ? descendantIdsOf(shown, drag.id) : null;
+  const dragging = drag?.active ? draggedIdsOf(shown, drag.ids) : null;
+
+  /**
+   * What a click on `node` means, given its modifiers — the whole of shift-click and
+   * ⌘-click.
+   *
+   * Returns whether the click was CONSUMED by the selection: a shift- or ⌘-click extends the
+   * selection and stops there, because extending a selection is not also navigating and in a
+   * consumer that opens on select it would be. A plain click reports `[id]` and falls
+   * through to `onSelect`, so the ordinary act is unchanged.
+   */
+  const clickSelected = (
+    node: FileTreeNode,
+    event: React.MouseEvent,
+    /* The rows a SHIFT-range is measured over — the section the click landed in, for the
+       reason the arrows walk one section too: a range is what you can see yourself cover. */
+    list: readonly FileTreeRow[],
+  ): boolean => {
+    if (!onSelectionChange) return false;
+    if (event.shiftKey) {
+      // From the anchor, over the rows ON SCREEN — see `selectionRange`. `selectedId` is the
+      // fallback so the very first shift-click after a deep link still has a start.
+      onSelectionChange(selectionRange(list, anchor.current ?? selectedId, node.id));
+      return true;
+    }
+    if (event.metaKey || event.ctrlKey) {
+      anchor.current = node.id;
+      onSelectionChange(toggleSelected(selection, node.id));
+      return true;
+    }
+    anchor.current = node.id;
+    onSelectionChange([node.id]);
+    return false;
+  };
 
   /**
    * The unnamed row, at whatever depth it is being made at.
    *
    * A function rather than an element so the two placements below — nested under a parent,
    * or at the root — cannot drift into drawing two different things.
+   *
+   * 🔴 A WRAP opens pre-filled and selected, with the first row's name minus its extension:
+   * one keystroke replaces it, Enter accepts it, and the suggestion is the answer often
+   * enough that it has to be the one already in the field. A plain new folder opens empty, as
+   * it always has — there is nothing for it to be named after.
    */
   const draftRow = (depth: number) => (
     <div
@@ -1026,44 +2011,421 @@ export function FileTree({
         )}
       </span>
       {nameField(
-        '',
-        (value) => onDraftCommit?.(value),
+        wrapping?.name ?? '',
+        (value) => commitDraft(value),
         () => onDraftCancel?.(),
+        // A suggested name that comes back unchanged is the person AGREEING with it. Cancelling
+        // there would make Enter mean "no" on the one field where it obviously means "yes".
+        wrapping ? 'commit' : 'cancel',
       )}
     </div>
   );
 
-  const nameField = (initial: string, commit: (value: string) => void, cancel: () => void) => (
-    <Input
-      className='cbft-name-input'
-      defaultValue={initial}
-      autoFocus
-      aria-label='Name'
-      onFocus={(event) => event.currentTarget.select()}
-      onClick={(event) => event.stopPropagation()}
-      onPointerDown={(event) => event.stopPropagation()}
-      onBlur={(event) => {
-        const value = event.currentTarget.value.trim();
-        if (!value || value === initial) cancel();
-        else commit(value);
-      }}
-      onKeyDown={(event) => {
-        event.stopPropagation();
-        if (event.key === 'Escape') {
-          event.preventDefault();
-          cancel();
-        } else if (event.key === 'Enter') {
-          event.preventDefault();
-          const value = event.currentTarget.value.trim();
-          if (!value || value === initial) cancel();
-          else commit(value);
+  const nameField = (
+    initial: string,
+    commit: (value: string) => void,
+    cancel: () => void,
+    /**
+     * What a name that came back UNCHANGED means. A rename to the name a row already has is a
+     * no-op, so it cancels and nothing is written; a pre-filled draft is the opposite — see
+     * just above. An EMPTY field always cancels, whichever this is.
+     */
+    unchanged: 'cancel' | 'commit' = 'cancel',
+  ) => {
+    const done = (value: string) => {
+      const name = value.trim();
+      if (!name || (name === initial && unchanged === 'cancel')) cancel();
+      else commit(name);
+    };
+    return (
+      <Input
+        className='cbft-name-input'
+        defaultValue={initial}
+        autoFocus
+        aria-label='Name'
+        onFocus={(event) => event.currentTarget.select()}
+        onClick={(event) => event.stopPropagation()}
+        onPointerDown={(event) => event.stopPropagation()}
+        onBlur={(event) => done(event.currentTarget.value)}
+        onKeyDown={(event) => {
+          event.stopPropagation();
+          if (event.key === 'Escape') {
+            event.preventDefault();
+            cancel();
+          } else if (event.key === 'Enter') {
+            event.preventDefault();
+            done(event.currentTarget.value);
+          }
+        }}
+      />
+    );
+  };
+
+  /**
+   * One row — drawn in the tree, or drawn a second time in the pinned section above it.
+   *
+   * 🔴 ONE function for both, and that is the point rather than a tidiness. A pinned row is
+   * the same row: it selects the same way, drags the same way, shows the same thumbnail, the
+   * same padlock, the same count and the same tool shelf. Two copies of this markup would be
+   * two rows that drift apart on the first change to either — the lesson `ListToolbar` was
+   * extracted for one repo over. What `pinnedCopy` changes is only the five things that are
+   * genuinely different, each marked below: which ref map holds it, which list its arrows
+   * walk, which tab stop it competes for, that it is drawn FLAT, and that the rename field
+   * stays on the real row while the real row is on screen.
+   */
+  const renderRow = (row: FileTreeRow, pinnedCopy: boolean): ReactNode => {
+    const { node } = row;
+    const list = pinnedCopy ? pinnedRows : rows;
+    // One id or many, asked the same way: `selected` is `[selectedId]` for every
+    // consumer that never passed `selectedIds`, so this is the old test verbatim.
+    const isSelected = selected.has(node.id);
+    /*
+     * 🔴 Exactly ONE copy ever draws the name field, and it is the visible one.
+     *
+     * `renamingId` names a NODE, and a pinned node is two rows — so the naive test opens two
+     * `<input autoFocus>`s with one `aria-label='Name'` between them, which is both an
+     * ambiguous query for a screen reader and a race for the caret. The tree's copy wins
+     * whenever it exists, because that is the row with the depth and the ancestors marked
+     * above it; the pinned copy answers only when the row is inside a shut folder and the
+     * tree is not drawing it at all — where the alternative is a rename that opens nowhere.
+     */
+    const isRenaming =
+      renamingId === node.id &&
+      (!pinnedCopy || !rows.some((other) => other.node.id === node.id));
+    const isDragged = dragging?.has(node.id) === true;
+    const isDropTarget = dropId === node.id || externalOverId === node.id;
+    const isPinned = pinned.includes(node.id);
+    const marker =
+      drag?.active && drag.offer.target && 'siblingId' in drag.offer.target
+        ? drag.offer.target.siblingId === node.id
+          ? drag.offer.target.kind
+          : null
+        : null;
+
+    const rowBody = (
+      // biome-ignore lint/a11y/useFocusableInteractive: it IS focusable — `tabIndex`
+      // is set below by the roving-focus rule (one row at 0, the rest at -1).
+      <div
+        role='treeitem'
+        aria-selected={isSelected}
+        /* Flat in the pinned section: it is a list of shortcuts, not a second hierarchy. */
+        aria-level={pinnedCopy ? 1 : row.depth + 1}
+        /* A screen reader says "3 of 7" only if it is told the level's size. Both
+           come from `shown`, so a filtered tree counts what it drew rather than
+           what it hid.
+
+           🔴 The pinned section counts ITSELF. `setSizes` is built from the rows on screen on
+           the stated assumption that every sibling of a visible row is visible too — true of
+           the tree, false the moment a pin is folded into it, and the cost would be wrong
+           counts on every row in the tree rather than only on the pinned ones. Its own
+           `role='tree'` below is the other half of the same answer. */
+        aria-posinset={pinnedCopy ? list.indexOf(row) + 1 : row.index + 1}
+        aria-setsize={pinnedCopy ? list.length : (setSizes.get(row.parentId ?? '') ?? 1)}
+        {...(row.expandable ? { 'aria-expanded': row.expanded } : {})}
+        /* One stop per SECTION, not per row and not per node: `focused` carries which copy
+           the keyboard is on, so the two trees do not both answer for one id. */
+        tabIndex={
+          node.id ===
+          (pinnedCopy
+            ? focused?.pinned
+              ? focused.id
+              : pinnedRows[0]?.node.id
+            : focused && !focused.pinned
+              ? focused.id
+              : (selectedId ?? rows[0]?.node.id))
+            ? 0
+            : -1
         }
-      }}
-    />
-  );
+        ref={(el) => {
+          const refs = pinnedCopy ? pinnedRefs : rowRefs;
+          if (el) refs.current.set(node.id, el);
+          else refs.current.delete(node.id);
+        }}
+        key={node.id}
+        className='cbft-row'
+        data-selected={isSelected || undefined}
+        /* Held by a ⌘X that has not been pasted yet — drawn lifted, the way Finder
+           draws a cut. Escape puts it down. */
+        data-cut={cut?.has(node.id) || undefined}
+        data-dragged={isDragged || undefined}
+        data-into={isDropTarget || undefined}
+        data-marker={marker ?? undefined}
+        /* Which copy this is, and whether the node is pinned at all — the second is what lets
+           the row IN THE FOLDER say so, which is the half of *"they still will exist in the
+           folder they were stored in"* that a person has to be able to see. */
+        data-pinned={isPinned || undefined}
+        data-pinned-copy={pinnedCopy || undefined}
+        /* On the way to the selection, and — when it is shut — the one HOLDING it.
+           See `openPath`: with the selected row not drawn at all, this bar is the
+           only thing in the tree that says where you are. */
+        data-ancestor={openPath.path.has(node.id) || undefined}
+        data-holds-open={
+          (row.expandable && !row.expanded && openPath.holder === node.id) || undefined
+        }
+        data-access={node.access && node.access !== 'normal' ? node.access : undefined}
+        style={{ '--cbft-depth': row.depth } as React.CSSProperties}
+        onPointerDown={(event) => {
+          if (inTools(event.target)) return;
+          beginDrag(event, node);
+        }}
+        onClick={(event) => {
+          if (inTools(event.target)) return;
+          // The click a finished drag left behind — see `draggedJustNow`.
+          if (draggedJustNow.current) {
+            draggedJustNow.current = false;
+            return;
+          }
+          if (clickSelected(node, event, list)) return;
+          onSelect(node);
+        }}
+        onDoubleClick={(event) => {
+          if (inTools(event.target)) return;
+          (onOpen ?? onSelect)(node);
+        }}
+        onKeyDown={(event) => onKeyDown(event, row, list, pinnedCopy)}
+        onFocus={() => setFocused({ id: node.id, pinned: pinnedCopy })}
+        {...externalHandlers(node)}
+      >
+        {row.expandable ? (
+          // biome-ignore lint/a11y/noStaticElementInteractions: a disclosure twisty
+          // inside a `treeitem`, which already carries `aria-expanded` — a nested
+          // <button> would be a second focus stop announcing the same state twice.
+          <span
+            className='cbft-twisty'
+            data-open={row.expanded || undefined}
+            aria-hidden='true'
+            onPointerDown={(event) => event.stopPropagation()}
+            onClick={(event) => {
+              event.stopPropagation();
+              toggle(node.id);
+            }}
+          >
+            {/*
+              🔴 A drawn chevron, not a `▸` character (2026-09-09).
+              Owner: *"the caret is too small. Use the icon and styling from ces the
+              spreadsheet app."* A text triangle is sized by `font-size`, and the one
+              here was 10px — below anything a pointer can comfortably aim at, and it
+              rendered differently on every platform because it is a FONT glyph. This
+              is the spreadsheet's own `IconChevronRight` geometry at 12px inside a
+              16px target, which is what it has always been over there.
+            */}
+            <svg
+              viewBox='0 0 24 24'
+              width='12'
+              height='12'
+              fill='none'
+              stroke='currentColor'
+              strokeWidth='2.2'
+              strokeLinecap='round'
+              strokeLinejoin='round'
+              focusable='false'
+              // Decorative, and the state it depicts is already announced: the
+              // wrapping <span> is aria-hidden and the treeitem above carries
+              // aria-expanded. Said on the SVG itself because `noSvgWithoutTitle`
+              // inspects the element, not its ancestors — a <title> here would make
+              // a screen reader read the chevron out a second time.
+              aria-hidden='true'
+            >
+              <path d='m9 6 6 6-6 6' />
+            </svg>
+          </span>
+        ) : (
+          /*
+            🔴 The icon takes the twisty's OWN column — one glyph box per row, never
+            two — see `.cbft-slot`. A row that can be opened is marked by its arrow
+            and a row that cannot is marked by its icon, so the name always sits one
+            gap from whichever glyph the row has. Reserving a second track for the
+            icon (what this did until 2026-09-10) put a glyph's width plus a gap
+            between every folder's arrow and its name: *"the text for a dir has too
+            much space between its open/closed arrow icon and the name."*
+
+            The box is fixed and unconditional, which is the property the two-track
+            layout was protecting and this keeps: every name at a given depth starts
+            on one vertical whether the row draws an arrow, a type icon or a
+            thumbnail. Since 2026-09-11 an empty folder draws its ARROW like any
+            other folder, so this branch is a file's — or a row that opted out of the
+            twisty with `expandable: false`, which every PINNED copy does.
+          */
+          <span className='cbft-slot' aria-hidden='true'>
+            <RowGlyph node={node} open={row.expanded} {...(renderIcon ? { renderIcon } : {})} />
+          </span>
+        )}
+
+        {isRenaming && onRename ? (
+          nameField(
+            node.name,
+            (value) => onRename(node, value),
+            () => onRenameCancel?.(),
+          )
+        ) : (
+          <Tooltip content={node.name}>
+            {/* The full name, for a row whose name the ellipsis cut. `Tooltip` rather
+                than `title=`: this tree is used on a phone, where a native tooltip
+                does not exist at all and a truncated folder name would have no way
+                of being read. */}
+            <span className='cbft-name'>{node.name}</span>
+          </Tooltip>
+        )}
+
+        {/*
+          🔴 A PRIVATE row says so, with a mark — added 2026-09-11.
+
+          The owner, the same day: *"When I click a 3 dot menu on a folder and choose
+          make private nothing happens."* It did happen, three times over — his live
+          `collections` database holds three private folders and 39 private files, all
+          written by this control. What was missing was any sign of it: while UNLOCKED a
+          private folder appears in the tree and, since the row padlock went on
+          2026-09-08, looked **exactly like a public one**. The only mark was
+          `font-style: italic` on the name, which one row in thirty does not carry
+          visibly at 13px. So a write that worked, and a UI that said nothing, were
+          indistinguishable from a control that was broken.
+
+          🔴 This is not the 2026-09-08 padlock coming back, and the difference is the
+          whole argument. That was an ACTION — one of three always-lit glyphs on EVERY
+          row (*"doesn't have numbers to the right of folder names or the pencil icon or
+          lock icon"*), and its verb survived its removal: privacy is on the ⋯ menu. This
+          is STATE, it appears only on the rows that have it, it is not clickable, and
+          state has nowhere else to live. Deleting it would delete the fact.
+
+          After the name and before the tools, so it never takes the glyph column (that
+          is the twisty's, and a folder losing its arrow would lose the control that
+          opens it) and never moves with how many actions a consumer wired up.
+        */}
+        {/* The mark's words are the consumer's when it has its own privacy
+            vocabulary — see accessMarkCopy for why the defaults are collections'. */}
+        {node.access === 'private' || node.access === 'locked' ? (
+          <Tooltip content={accessMarkCopy(node.access, accessCopy)}>
+            {/* Not `aria-hidden`: this is the one thing on the row a screen reader
+                cannot work out from anything else, and the name alone would announce a
+                private folder identically to a public one. */}
+            <span className='cbft-access' role='img' aria-label='Private'>
+              🔒
+            </span>
+          </Tooltip>
+        ) : null}
+        {renderAccessory ? renderAccessory(node) : null}
+        {node.count !== undefined ? <span className='cbft-count'>{node.count}</span> : null}
+
+        {/*
+          🔴 The PIN, and it is a control rather than a mark — unlike the padlock above.
+
+          The padlock is state with its verb somewhere else (the ⋯ menu); this is a state whose
+          verb has nowhere else to be. *"Pinning or unpinning one place doesn't change pinning
+          in the other place"* describes a thing a person does, on a phone as well as with
+          ⌃⌘T, and a tree that only offered the chord would be a feature with no pointer route
+          at all. It lives in the `.cbft-tools` shelf so it inherits the shelf's whole contract
+          in one line — quiet at 40%, solid on hover, focus or selection, and solid with a 44px
+          box on a coarse pointer — and so `inTools` already stops it selecting the row.
+
+          Drawn only when {@link FileTreeProps.onPinnedChange} is wired, like every other verb
+          here: a consumer that cannot receive the list sees no control that fails on press.
+        */}
+        {onPinnedChange ? (
+          <span className='cbft-tools cbft-pin-shelf'>
+            <Tooltip content={isPinned ? 'Unpin from the top' : 'Pin to the top'}>
+              <button
+                // guardrails-ignore no-raw-action-button: a 16px glyph inside a 22px tree row,
+                // sized by `--cbft-glyph` exactly as the twisty beside it is. cursedbelt's
+                // Button/IconButton carry the shared 36px control height and Tailwind classes
+                // this stylesheet deliberately does not rely on (see fileTree.css's header for
+                // why the tree ships plain CSS), so a control-class primitive here would make
+                // one row taller than every other — the geometry `file-tree-geometry.json`
+                // pins. The native element is used precisely so Enter/Space, focus and
+                // disabled semantics stay the browser's.
+                type='button'
+                className='cbft-pin'
+                aria-pressed={isPinned}
+                aria-label={isPinned ? `Unpin ${node.name}` : `Pin ${node.name}`}
+                onPointerDown={(event) => event.stopPropagation()}
+                onClick={(event) => {
+                  event.stopPropagation();
+                  togglePin(node);
+                }}
+              >
+                {/* Lucide's `pin`, drawn rather than imported for the reason the chevron is:
+                    the stylesheet sizes the box and the glyph, and a font or an icon package
+                    would put a third party between the two. Decorative — the button's own
+                    `aria-label` already says what it does and `aria-pressed` says its state. */}
+                <svg
+                  viewBox='0 0 24 24'
+                  width='12'
+                  height='12'
+                  fill='none'
+                  stroke='currentColor'
+                  strokeWidth='2'
+                  strokeLinecap='round'
+                  strokeLinejoin='round'
+                  focusable='false'
+                  aria-hidden='true'
+                >
+                  <path d='M12 17v5' />
+                  <path d='M9 10.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24V16a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z' />
+                </svg>
+              </button>
+            </Tooltip>
+          </span>
+        ) : null}
+
+        {renderTools ? <span className='cbft-tools'>{renderTools(node)}</span> : null}
+      </div>
+    );
+
+    // The "why not" only exists while the tree genuinely cannot be rearranged;
+    // wrapping every row in a tooltip otherwise would put a hint on a working
+    // control saying nothing.
+    const body =
+      unavailableReason && !canRearrange ? (
+        <Tooltip key={node.id} content={unavailableReason}>
+          {rowBody}
+        </Tooltip>
+      ) : (
+        rowBody
+      );
+
+    // The draft belongs INSIDE the folder it is being made in, one level deeper —
+    // see the note above the parentless case. Never under a PINNED copy: the draft is
+    // being made in a place, and the place is where the folder actually lives.
+    return !pinnedCopy && draft && draft.parentId === node.id ? (
+      <Fragment key={node.id}>
+        {body}
+        {draftRow(row.depth + 1)}
+      </Fragment>
+    ) : (
+      body
+    );
+  };
 
   return (
     <div className={`cbft${className ? ` ${className}` : ''}`}>
+      {/*
+       * ── The pinned section — above the folders, and outside the scroller ─────────────
+       *
+       * Owner, 2026-09-13: *"pin open files where they stay at the top of the file tree in a
+       * new section above the folders."* **Stay** is why it is a sibling of `.cbft-scroll`
+       * rather than a `position: sticky` block inside it: a row that scrolls away has not
+       * stayed anywhere, and sticky would have cost a raw z-index over the rows it overlaps
+       * plus a hit-test that has to know which of two overlapping boxes wins. Outside the
+       * scroller there is nothing to overlap — and the reveal, the autoscroll edges and the
+       * blank-space drop target below all still mean exactly what they meant, because none of
+       * them can see this box.
+       *
+       * 🔴 Its own `role='tree'`, not a slice of the one below. See `aria-setsize` in
+       * `renderRow`.
+       */}
+      {pinnedRows.length > 0 ? (
+        <div className='cbft-pinned'>
+          <div className='cbft-pinned-head'>{pinnedLabel}</div>
+          <div
+            role='tree'
+            aria-label={pinnedLabel}
+            {...(onSelectionChange ? { 'aria-multiselectable': true } : {})}
+            className={`cbft-pinned-list${drag?.active ? ' cbft-list-dragging' : ''}`}
+          >
+            {pinnedRows.map((row) => renderRow(row, true))}
+          </div>
+        </div>
+      ) : null}
+
       {/* biome-ignore lint/a11y/noStaticElementInteractions: the blank area under the tree is
           a DROP TARGET, not a control — "get this out of here" is the one gesture with no
           row to aim at. Every move it can express is also on a row's own menu. */}
@@ -1079,6 +2441,10 @@ export function FileTree({
         <div
           role='tree'
           aria-label={ariaLabel}
+          /* Only when the consumer can actually receive a second selected row. A tree that
+             announced itself multi-selectable and then replaced the selection on every click
+             would be telling a screen reader something the pointer disproves. */
+          {...(onSelectionChange ? { 'aria-multiselectable': true } : {})}
           className={`cbft-list${drag?.active ? ' cbft-list-dragging' : ''}`}
         >
           {rows.length === 0 && !draft ? <div className='cbft-empty'>{empty}</div> : null}
@@ -1093,227 +2459,7 @@ export function FileTree({
            */}
           {draft && draft.parentId === null ? draftRow(0) : null}
 
-          {rows.map((row) => {
-            const { node } = row;
-            const isSelected = node.id === selectedId;
-            const isRenaming = renamingId === node.id;
-            const isDragged = dragging?.has(node.id) === true;
-            const isDropTarget = dropId === node.id || externalOverId === node.id;
-            const marker =
-              drag?.active && drag.offer.target && 'siblingId' in drag.offer.target
-                ? drag.offer.target.siblingId === node.id
-                  ? drag.offer.target.kind
-                  : null
-                : null;
-
-            const rowBody = (
-              // biome-ignore lint/a11y/useFocusableInteractive: it IS focusable — `tabIndex`
-              // is set below by the roving-focus rule (one row at 0, the rest at -1).
-              <div
-                role='treeitem'
-                aria-selected={isSelected}
-                aria-level={row.depth + 1}
-                /* A screen reader says "3 of 7" only if it is told the level's size. Both
-                   come from `shown`, so a filtered tree counts what it drew rather than
-                   what it hid. */
-                aria-posinset={row.index + 1}
-                aria-setsize={setSizes.get(row.parentId ?? '') ?? 1}
-                {...(row.expandable ? { 'aria-expanded': row.expanded } : {})}
-                tabIndex={
-                  node.id === (focusedId ?? selectedId ?? rows[0]?.node.id) ? 0 : -1
-                }
-                ref={(el) => {
-                  if (el) rowRefs.current.set(node.id, el);
-                  else rowRefs.current.delete(node.id);
-                }}
-                key={node.id}
-                className='cbft-row'
-                data-selected={isSelected || undefined}
-                data-dragged={isDragged || undefined}
-                data-into={isDropTarget || undefined}
-                data-marker={marker ?? undefined}
-                /* On the way to the selection, and — when it is shut — the one HOLDING it.
-                   See `openPath`: with the selected row not drawn at all, this bar is the
-                   only thing in the tree that says where you are. */
-                data-ancestor={openPath.path.has(node.id) || undefined}
-                data-holds-open={
-                  (row.expandable && !row.expanded && openPath.holder === node.id) || undefined
-                }
-                data-access={node.access && node.access !== 'normal' ? node.access : undefined}
-                style={{ '--cbft-depth': row.depth } as React.CSSProperties}
-                onPointerDown={(event) => {
-                  if (inTools(event.target)) return;
-                  beginDrag(event, node);
-                }}
-                onClick={(event) => {
-                  if (inTools(event.target)) return;
-                  // The click a finished drag left behind — see `draggedJustNow`.
-                  if (draggedJustNow.current) {
-                    draggedJustNow.current = false;
-                    return;
-                  }
-                  onSelect(node);
-                }}
-                onDoubleClick={(event) => {
-                  if (inTools(event.target)) return;
-                  (onOpen ?? onSelect)(node);
-                }}
-                onKeyDown={(event) => onKeyDown(event, row)}
-                onFocus={() => setFocusedId(node.id)}
-                {...externalHandlers(node)}
-              >
-                {row.expandable ? (
-                  // biome-ignore lint/a11y/noStaticElementInteractions: a disclosure twisty
-                  // inside a `treeitem`, which already carries `aria-expanded` — a nested
-                  // <button> would be a second focus stop announcing the same state twice.
-                  <span
-                    className='cbft-twisty'
-                    data-open={row.expanded || undefined}
-                    aria-hidden='true'
-                    onPointerDown={(event) => event.stopPropagation()}
-                    onClick={(event) => {
-                      event.stopPropagation();
-                      toggle(node.id);
-                    }}
-                  >
-                    {/*
-                      🔴 A drawn chevron, not a `▸` character (2026-09-09).
-                      Owner: *"the caret is too small. Use the icon and styling from ces the
-                      spreadsheet app."* A text triangle is sized by `font-size`, and the one
-                      here was 10px — below anything a pointer can comfortably aim at, and it
-                      rendered differently on every platform because it is a FONT glyph. This
-                      is the spreadsheet's own `IconChevronRight` geometry at 12px inside a
-                      16px target, which is what it has always been over there.
-                    */}
-                    <svg
-                      viewBox='0 0 24 24'
-                      width='12'
-                      height='12'
-                      fill='none'
-                      stroke='currentColor'
-                      strokeWidth='2.2'
-                      strokeLinecap='round'
-                      strokeLinejoin='round'
-                      focusable='false'
-                      // Decorative, and the state it depicts is already announced: the
-                      // wrapping <span> is aria-hidden and the treeitem above carries
-                      // aria-expanded. Said on the SVG itself because `noSvgWithoutTitle`
-                      // inspects the element, not its ancestors — a <title> here would make
-                      // a screen reader read the chevron out a second time.
-                      aria-hidden='true'
-                    >
-                      <path d='m9 6 6 6-6 6' />
-                    </svg>
-                  </span>
-                ) : (
-                  /*
-                    🔴 The icon takes the twisty's OWN column — one glyph box per row, never
-                    two — see `.cbft-slot`. A row that can be opened is marked by its arrow
-                    and a row that cannot is marked by its icon, so the name always sits one
-                    gap from whichever glyph the row has. Reserving a second track for the
-                    icon (what this did until 2026-09-10) put a glyph's width plus a gap
-                    between every folder's arrow and its name: *"the text for a dir has too
-                    much space between its open/closed arrow icon and the name."*
-
-                    The box is fixed and unconditional, which is the property the two-track
-                    layout was protecting and this keeps: every name at a given depth starts
-                    on one vertical whether the row draws an arrow, a type icon or a
-                    thumbnail. Since 2026-09-11 an empty folder draws its ARROW like any
-                    other folder, so this branch is a file's — or a row that opted out of the
-                    twisty with `expandable: false`.
-                  */
-                  <span className='cbft-slot' aria-hidden='true'>
-                    <RowGlyph
-                      node={node}
-                      open={row.expanded}
-                      {...(renderIcon ? { renderIcon } : {})}
-                    />
-                  </span>
-                )}
-
-                {isRenaming && onRename ? (
-                  nameField(
-                    node.name,
-                    (value) => onRename(node, value),
-                    () => onRenameCancel?.(),
-                  )
-                ) : (
-                  <Tooltip content={node.name}>
-                    {/* The full name, for a row whose name the ellipsis cut. `Tooltip` rather
-                        than `title=`: this tree is used on a phone, where a native tooltip
-                        does not exist at all and a truncated folder name would have no way
-                        of being read. */}
-                    <span className='cbft-name'>{node.name}</span>
-                  </Tooltip>
-                )}
-
-                {/*
-                  🔴 A PRIVATE row says so, with a mark — added 2026-09-11.
-
-                  The owner, the same day: *"When I click a 3 dot menu on a folder and choose
-                  make private nothing happens."* It did happen, three times over — his live
-                  `collections` database holds three private folders and 39 private files, all
-                  written by this control. What was missing was any sign of it: while UNLOCKED a
-                  private folder appears in the tree and, since the row padlock went on
-                  2026-09-08, looked **exactly like a public one**. The only mark was
-                  `font-style: italic` on the name, which one row in thirty does not carry
-                  visibly at 13px. So a write that worked, and a UI that said nothing, were
-                  indistinguishable from a control that was broken.
-
-                  🔴 This is not the 2026-09-08 padlock coming back, and the difference is the
-                  whole argument. That was an ACTION — one of three always-lit glyphs on EVERY
-                  row (*"doesn't have numbers to the right of folder names or the pencil icon or
-                  lock icon"*), and its verb survived its removal: privacy is on the ⋯ menu. This
-                  is STATE, it appears only on the rows that have it, it is not clickable, and
-                  state has nowhere else to live. Deleting it would delete the fact.
-
-                  After the name and before the tools, so it never takes the glyph column (that
-                  is the twisty's, and a folder losing its arrow would lose the control that
-                  opens it) and never moves with how many actions a consumer wired up.
-                */}
-                {/* The mark's words are the consumer's when it has its own privacy
-                    vocabulary — see accessMarkCopy for why the defaults are collections'. */}
-                {node.access === 'private' || node.access === 'locked' ? (
-                  <Tooltip content={accessMarkCopy(node.access, accessCopy)}>
-                    {/* Not `aria-hidden`: this is the one thing on the row a screen reader
-                        cannot work out from anything else, and the name alone would announce a
-                        private folder identically to a public one. */}
-                    <span className='cbft-access' role='img' aria-label='Private'>
-                      🔒
-                    </span>
-                  </Tooltip>
-                ) : null}
-                {renderAccessory ? renderAccessory(node) : null}
-                {node.count !== undefined ? (
-                  <span className='cbft-count'>{node.count}</span>
-                ) : null}
-                {renderTools ? <span className='cbft-tools'>{renderTools(node)}</span> : null}
-              </div>
-            );
-
-            // The "why not" only exists while the tree genuinely cannot be rearranged;
-            // wrapping every row in a tooltip otherwise would put a hint on a working
-            // control saying nothing.
-            const body =
-              unavailableReason && !onMove ? (
-                <Tooltip key={node.id} content={unavailableReason}>
-                  {rowBody}
-                </Tooltip>
-              ) : (
-                rowBody
-              );
-
-            // The draft belongs INSIDE the folder it is being made in, one level deeper —
-            // see the note above the parentless case.
-            return draft && draft.parentId === node.id ? (
-              <Fragment key={node.id}>
-                {body}
-                {draftRow(row.depth + 1)}
-              </Fragment>
-            ) : (
-              body
-            );
-          })}
+          {rows.map((row) => renderRow(row, false))}
 
           {/*
            * The parent went away underneath an open draft — a filter narrowed, or the tree
@@ -1343,7 +2489,11 @@ export function FileTree({
           style={{ left: `${drag.x}px`, top: `${drag.y}px` }}
           aria-hidden='true'
         >
-          <span className='cbft-chip-name'>{nameOf(shown, drag.id)}</span>
+          {/* One row says its name; a selection says how many, because twenty names is not
+              something a chip under a moving cursor can be read as. */}
+          <span className='cbft-chip-name'>
+            {drag.ids.length > 1 ? `${drag.ids.length} items` : nameOf(shown, drag.id)}
+          </span>
           {/* The refusal wins the slot: while something cannot land, "why not" outranks
               "where to", and there is never both to say. */}
           <span className='cbft-chip-where'>