cursedbelt 3.0.2 → 4.1.0

package/dist/react/file-tree/FileTree.js

@@ -1,9 +1,10 @@
 import { createElement as _createElement } from "react";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { accessMarkCopy, describeDrop, descendantIdsOf, filterFileTree, flattenFileTree, matchTypeahead, resolveDrop, resolveKeyboardMove, } from 'cursedbelt-core/file-tree/file-tree-model';
+import { accessMarkCopy, describeDrop, filterFileTree, findFileTreeNode, flattenFileTree, matchTypeahead, 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. */
 const DRAG_THRESHOLD = 4;
@@ -22,6 +23,11 @@ const SPRING_OPEN_MS = 600;
 /** How long a typeahead word survives a pause. One second is what every file explorer uses. */
 const TYPEAHEAD_RESET_MS = 1000;
 const NO_OFFER = { 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 = [];
 /**
  * The default marks — a consumer that wants kind-specific icons passes `renderIcon`.
  *
@@ -62,9 +68,19 @@ function RowGlyph({ node, open, renderIcon, }) {
         return icon;
     return (_jsx("img", { className: 'cbft-thumb', src: src, alt: '', "aria-hidden": 'true', loading: 'lazy', decoding: 'async', draggable: false, onError: () => setFailed(src) }, src));
 }
-export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: collapsedProp, onCollapsedChange, onMove, allowReorder = false, lockedReason, canDrop, unavailableReason, renamingId, onRenameStart, onRename, onRenameCancel, onDelete, draft, onDraftCommit, onDraftCancel, onRowMenu, renderTools, renderIcon, renderAccessory, onDropExternal, acceptsExternalDrag, accessCopy, filter, empty = 'Nothing here yet.', ariaLabel = 'Files', className, }) {
+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, unavailableReason, renamingId, onRenameStart, onRename, onRenameCancel, onDelete, onDeleteMany, onCopy, canCopy, draft, onDraftCommit, onDraftCancel, onWrapStart, canWrap, onRowMenu, renderTools, renderIcon, renderAccessory, onDropExternal, acceptsExternalDrag, accessCopy, filter, empty = 'Nothing here yet.', ariaLabel = 'Files', className, }) {
     const scrollRef = useRef(null);
     const rowRefs = useRef(new Map());
+    /**
+     * 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());
     const autoScroll = useRef(null);
     const spring = useRef(null);
     /** Folders this drag opened by hovering, to shut again if it never drops. */
@@ -81,15 +97,77 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
      * 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(null);
     const [ownCollapsed, setOwnCollapsed] = useState([]);
-    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) => {
         if (collapsedProp === undefined)
             setOwnCollapsed(next);
         onCollapsedChange?.(next);
     }, [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([]);
+    /** 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) => {
+        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) => {
+        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(null);
-    const [focusedId, setFocusedId] = useState(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(null);
     /** The row an EXTERNAL drag is over, drawn with the same marker an internal one uses. */
     const [externalOverId, setExternalOverId] = useState(null);
     /**
@@ -101,12 +179,127 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
      * 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(null);
     const shown = useMemo(() => (filter ? filterFileTree(nodes, filter) : nodes), [nodes, filter]);
     /*
      * A search shows everything it kept — a match hidden inside a collapsed folder is a match
      * the person cannot see, which reads as "not found".
      */
     const rows = useMemo(() => flattenFileTree(shown, filter ? [] : collapsed), [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(() => {
+        if (pinned.length === 0)
+            return [];
+        const all = new Map(flattenFileTree(shown, []).map((row) => [row.node.id, row]));
+        const out = [];
+        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(() => 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, plural) => {
+        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, target) => {
+        if (ids.length === 0)
+            return;
+        if (ids.length > 1) {
+            onMoveMany?.(ids, target);
+            return;
+        }
+        if (onMove)
+            onMove(ids[0], 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) => {
+        // 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.
      *
@@ -154,20 +347,81 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
         }
         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) => {
-        const set = new Set(collapsed);
-        if (set.has(id))
-            set.delete(id);
+        if (collapsed.includes(id))
+            openFolders([id]);
         else
-            set.add(id);
-        setCollapsed([...set]);
-    }, [collapsed, setCollapsed]);
+            shutFolders([id]);
+    }, [collapsed, openFolders, shutFolders]);
     const openFolder = useCallback((id) => {
         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) => {
+        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(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(null);
     /**
      * Bring the selected row into view — the explorer's *reveal*.
      *
@@ -180,10 +434,31 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
      *
      * 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
@@ -196,12 +471,32 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
      * `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('.cbft-row[data-selected]') ??
             scroller.querySelector('.cbft-row[data-holds-open]');
         if (!row?.scrollIntoView)
@@ -213,7 +508,7 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
         // `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 ──────────────────────────────────────────────────────────────────────────
     const stopAutoScroll = useCallback(() => {
         if (!autoScroll.current)
@@ -229,16 +524,36 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
     }, []);
     /** The row under a client point, and how far down it the pointer is. */
     const rowAt = useCallback((x, y) => {
+        /*
+         * 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((commit, state) => {
         stopAutoScroll();
         stopSpring();
@@ -247,30 +562,47 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
         // 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, node) => {
         // 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)
+        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 = {
             id: node.id,
+            ids,
             startX,
             startY,
             x: startX,
@@ -285,12 +617,18 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
             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 } : {}),
             });
@@ -366,12 +704,14 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
         target.addEventListener('pointercancel', cancel);
         window.addEventListener('keydown', abort);
     }, [
+        actOn,
         allowReorder,
         canDrop,
+        canRearrange,
         collapsed,
         endDrag,
         lockedReason,
-        onMove,
+        onMoveMany,
         openFolder,
         rowAt,
         shown,
@@ -380,20 +720,39 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
     ]);
     // 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))
+        if (drag &&
+            !rows.some((r) => r.node.id === drag.id) &&
+            !pinnedRows.some((r) => r.node.id === drag.id))
             setDrag(null);
-    }, [drag, rows]);
+    }, [drag, pinnedRows, rows]);
     useEffect(() => () => {
         stopAutoScroll();
         stopSpring();
     }, [stopAutoScroll, stopSpring]);
     // ── The keyboard ──────────────────────────────────────────────────────────────────────
-    const focusRow = useCallback((id) => {
-        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, pinnedCopy) => {
+        const first = pinnedCopy ? pinnedRefs : rowRefs;
+        const second = pinnedCopy ? rowRefs : pinnedRefs;
+        return first.current.get(id) ?? second.current.get(id);
     }, []);
+    const focusRow = useCallback((id, pinnedCopy = false) => {
+        setFocused(id === null ? null : { id, pinned: pinnedCopy });
+        if (id)
+            rowEl(id, pinnedCopy)?.focus();
+    }, [rowEl]);
     /*
      * ── The keyboard comes back from a rename ─────────────────────────────────────────────
      *
@@ -422,14 +781,21 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
             return;
         focusRow(previous);
     }, [renamingId, focusRow]);
-    const onKeyDown = useCallback((event, row) => {
+    const onKeyDown = useCallback((event, row, 
+    /*
+     * 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, pinnedCopy) => {
         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) => {
-            const next = rows[Math.min(rows.length - 1, Math.max(0, index + delta))];
+            const next = list[Math.min(list.length - 1, Math.max(0, index + delta))];
             if (next)
-                focusRow(next.node.id);
+                focusRow(next.node.id, pinnedCopy);
         };
         /*
          * The keyboard's route to the row's own menu — see {@link FileTreeProps.onRowMenu}.
@@ -438,10 +804,166 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
          */
         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
@@ -451,7 +973,7 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
          * 🔴 Before the arrow cases below, so one key never means two things. Everything else
          * in this handler is bare-key, which is what keeps ⇧⏎/⌘F and the rest free for the app.
          */
-        if (onMove &&
+        if (canRearrange &&
             event.altKey &&
             !event.metaKey &&
             !event.ctrlKey &&
@@ -467,7 +989,11 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
             });
             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 ?? '');
@@ -496,19 +1022,22 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
                 event.preventDefault();
                 if (row.expandable && row.expanded)
                     toggle(row.node.id);
-                else if (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).node.id);
+                if (list.at(-1))
+                    focusRow(list.at(-1).node.id, pinnedCopy);
                 return;
             /*
               ── The keys VS Code taught everybody ───────────────────────────────────────────
@@ -553,12 +1082,41 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
             // ⌫, 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;
         }
@@ -570,25 +1128,37 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
             ? 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].node.id);
+            focusRow(list[found].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,
     ]);
     // ── External drags (Finder files, gallery tiles) ──────────────────────────────────────
     const externalWanted = useCallback((event) => Boolean(onDropExternal) && (acceptsExternalDrag?.(event) ?? true), [acceptsExternalDrag, onDropExternal]);
@@ -623,12 +1193,10 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
             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]);
-    }, [collapsed, setCollapsed, stopSpring]);
+        shutFolders(back);
+    }, [shutFolders, stopSpring]);
     const externalHandlers = (node) => onDropExternal
         ? {
             onDragOver: (event) => {
@@ -679,91 +1247,191 @@ export function FileTree({ nodes, selectedId, onSelect, onOpen, collapsed: colla
         : {};
     // ── Drawing ───────────────────────────────────────────────────────────────────────────
     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, event, 
+    /* 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) => {
+        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) => (_jsxs("div", { className: 'cbft-row cbft-row-draft', style: { '--cbft-depth': depth }, children: [_jsx("span", { className: 'cbft-slot', "aria-hidden": 'true', children: renderIcon ? (renderIcon({ id: '', name: '', kind: 'folder' })) : (_jsx(DefaultIcon, { node: { id: '', name: '', kind: 'folder' }, open: false })) }), nameField(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')] }));
+    const nameField = (initial, commit, cancel, 
+    /**
+     * 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.
      */
-    const draftRow = (depth) => (_jsxs("div", { className: 'cbft-row cbft-row-draft', style: { '--cbft-depth': depth }, children: [_jsx("span", { className: 'cbft-slot', "aria-hidden": 'true', children: renderIcon ? (renderIcon({ id: '', name: '', kind: 'folder' })) : (_jsx(DefaultIcon, { node: { id: '', name: '', kind: 'folder' }, open: false })) }), nameField('', (value) => onDraftCommit?.(value), () => onDraftCancel?.())] }));
-    const nameField = (initial, commit, cancel) => (_jsx(Input, { className: 'cbft-name-input', defaultValue: initial, autoFocus: true, "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)
+    unchanged = 'cancel') => {
+        const done = (value) => {
+            const name = value.trim();
+            if (!name || (name === initial && unchanged === 'cancel'))
                 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)
+                commit(name);
+        };
+        return (_jsx(Input, { className: 'cbft-name-input', defaultValue: initial, autoFocus: true, "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, pinnedCopy) => {
+        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 = (_createElement("div", { role: 'treeitem', "aria-selected": isSelected, "aria-level": pinnedCopy ? 1 : row.depth + 1, "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
-                    commit(value);
-            }
-        } }));
-    return (_jsxs("div", { className: `cbft${className ? ` ${className}` : ''}`, children: [_jsx("div", { className: 'cbft-scroll', ref: scrollRef, ...externalHandlers(null), onPointerUp: () => {
+                    refs.current.delete(node.id);
+            }, key: node.id, className: 'cbft-row', "data-selected": isSelected || undefined, "data-cut": cut?.has(node.id) || undefined, "data-dragged": isDragged || undefined, "data-into": isDropTarget || undefined, "data-marker": marker ?? undefined, "data-pinned": isPinned || undefined, "data-pinned-copy": pinnedCopy || undefined, "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 }, 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 ? (_jsx("span", { className: 'cbft-twisty', "data-open": row.expanded || undefined, "aria-hidden": 'true', onPointerDown: (event) => event.stopPropagation(), onClick: (event) => {
+                    event.stopPropagation();
+                    toggle(node.id);
+                }, children: _jsx("svg", { viewBox: '0 0 24 24', width: '12', height: '12', fill: 'none', stroke: 'currentColor', strokeWidth: '2.2', strokeLinecap: 'round', strokeLinejoin: 'round', focusable: 'false', "aria-hidden": 'true', children: _jsx("path", { d: 'm9 6 6 6-6 6' }) }) })) : (_jsx("span", { className: 'cbft-slot', "aria-hidden": 'true', children: _jsx(RowGlyph, { node: node, open: row.expanded, ...(renderIcon ? { renderIcon } : {}) }) })),
+            isRenaming && onRename ? (nameField(node.name, (value) => onRename(node, value), () => onRenameCancel?.())) : (_jsx(Tooltip, { content: node.name, children: _jsx("span", { className: 'cbft-name', children: node.name }) })),
+            node.access === 'private' || node.access === 'locked' ? (_jsx(Tooltip, { content: accessMarkCopy(node.access, accessCopy), children: _jsx("span", { className: 'cbft-access', role: 'img', "aria-label": 'Private', children: "\uD83D\uDD12" }) })) : null,
+            renderAccessory ? renderAccessory(node) : null,
+            node.count !== undefined ? _jsx("span", { className: 'cbft-count', children: node.count }) : null,
+            onPinnedChange ? (_jsx("span", { className: 'cbft-tools cbft-pin-shelf', children: _jsx(Tooltip, { content: isPinned ? 'Unpin from the top' : 'Pin to the top', children: _jsx("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);
+                        }, children: _jsxs("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', children: [_jsx("path", { d: 'M12 17v5' }), _jsx("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' })] }) }) }) })) : null,
+            renderTools ? _jsx("span", { className: 'cbft-tools', children: renderTools(node) }) : null));
+        // 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 ? (_jsx(Tooltip, { content: unavailableReason, children: rowBody }, node.id)) : (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 ? (_jsxs(Fragment, { children: [body, draftRow(row.depth + 1)] }, node.id)) : (body);
+    };
+    return (_jsxs("div", { className: `cbft${className ? ` ${className}` : ''}`, children: [pinnedRows.length > 0 ? (_jsxs("div", { className: 'cbft-pinned', children: [_jsx("div", { className: 'cbft-pinned-head', children: pinnedLabel }), _jsx("div", { role: 'tree', "aria-label": pinnedLabel, ...(onSelectionChange ? { 'aria-multiselectable': true } : {}), className: `cbft-pinned-list${drag?.active ? ' cbft-list-dragging' : ''}`, children: pinnedRows.map((row) => renderRow(row, true)) })] })) : null, _jsx("div", { className: 'cbft-scroll', ref: scrollRef, ...externalHandlers(null), onPointerUp: () => {
                     // Releasing over the blank space means the top level; the pointer capture keeps
                     // the row's own listeners running, so this only has to not swallow the event.
-                }, children: _jsxs("div", { role: 'tree', "aria-label": ariaLabel, className: `cbft-list${drag?.active ? ' cbft-list-dragging' : ''}`, children: [rows.length === 0 && !draft ? _jsx("div", { className: 'cbft-empty', children: empty }) : null, 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 = (_createElement("div", { role: 'treeitem', "aria-selected": isSelected, "aria-level": row.depth + 1, "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, "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 }, 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 ? (_jsx("span", { className: 'cbft-twisty', "data-open": row.expanded || undefined, "aria-hidden": 'true', onPointerDown: (event) => event.stopPropagation(), onClick: (event) => {
-                                        event.stopPropagation();
-                                        toggle(node.id);
-                                    }, children: _jsx("svg", { viewBox: '0 0 24 24', width: '12', height: '12', fill: 'none', stroke: 'currentColor', strokeWidth: '2.2', strokeLinecap: 'round', strokeLinejoin: 'round', focusable: 'false', "aria-hidden": 'true', children: _jsx("path", { d: 'm9 6 6 6-6 6' }) }) })) : (_jsx("span", { className: 'cbft-slot', "aria-hidden": 'true', children: _jsx(RowGlyph, { node: node, open: row.expanded, ...(renderIcon ? { renderIcon } : {}) }) })),
-                                isRenaming && onRename ? (nameField(node.name, (value) => onRename(node, value), () => onRenameCancel?.())) : (_jsx(Tooltip, { content: node.name, children: _jsx("span", { className: 'cbft-name', children: node.name }) })),
-                                node.access === 'private' || node.access === 'locked' ? (_jsx(Tooltip, { content: accessMarkCopy(node.access, accessCopy), children: _jsx("span", { className: 'cbft-access', role: 'img', "aria-label": 'Private', children: "\uD83D\uDD12" }) })) : null,
-                                renderAccessory ? renderAccessory(node) : null,
-                                node.count !== undefined ? (_jsx("span", { className: 'cbft-count', children: node.count })) : null,
-                                renderTools ? _jsx("span", { className: 'cbft-tools', children: renderTools(node) }) : null));
-                            // 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 ? (_jsx(Tooltip, { content: unavailableReason, children: rowBody }, node.id)) : (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 ? (_jsxs(Fragment, { children: [body, draftRow(row.depth + 1)] }, node.id)) : (body);
-                        }), draft && draft.parentId !== null && !rows.some((r) => r.node.id === draft.parentId)
+                }, children: _jsxs("div", { role: 'tree', "aria-label": ariaLabel, ...(onSelectionChange ? { 'aria-multiselectable': true } : {}), className: `cbft-list${drag?.active ? ' cbft-list-dragging' : ''}`, children: [rows.length === 0 && !draft ? _jsx("div", { className: 'cbft-empty', children: empty }) : null, draft && draft.parentId === null ? draftRow(0) : null, rows.map((row) => renderRow(row, false)), draft && draft.parentId !== null && !rows.some((r) => r.node.id === draft.parentId)
                             ? draftRow(0)
-                            : null] }) }), drag?.active ? (_jsxs("div", { className: 'cbft-chip', "data-refused": drag.offer.refused || undefined, style: { left: `${drag.x}px`, top: `${drag.y}px` }, "aria-hidden": 'true', children: [_jsx("span", { className: 'cbft-chip-name', children: nameOf(shown, drag.id) }), _jsx("span", { className: 'cbft-chip-where', children: drag.offer.reason ?? describeDrop(shown, drag.offer.target) })] })) : null, _jsx("span", { className: 'cbft-sr', role: 'status', "aria-live": 'polite', children: drag?.active ? (drag.offer.reason ?? describeDrop(shown, drag.offer.target)) : notice })] }));
+                            : null] }) }), drag?.active ? (_jsxs("div", { className: 'cbft-chip', "data-refused": drag.offer.refused || undefined, style: { left: `${drag.x}px`, top: `${drag.y}px` }, "aria-hidden": 'true', children: [_jsx("span", { className: 'cbft-chip-name', children: drag.ids.length > 1 ? `${drag.ids.length} items` : nameOf(shown, drag.id) }), _jsx("span", { className: 'cbft-chip-where', children: drag.offer.reason ?? describeDrop(shown, drag.offer.target) })] })) : null, _jsx("span", { className: 'cbft-sr', role: 'status', "aria-live": 'polite', children: drag?.active ? (drag.offer.reason ?? describeDrop(shown, drag.offer.target)) : notice })] }));
 }
 /**
  * Whether an event landed on the consumer's own row controls.