cursedbelt 1.0.0 → 2.3.0

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

@@ -14,6 +14,37 @@
  * {@link FileTreeProps.allowReorder}, and everything that made it good — the gesture, the
  * spring-open, the typeahead, the in-place rename — is here unchanged.
  *
+ * ── 🔴 The graduation verdict, 2026-09-13: this one stays, and it grew ──────────────────
+ * `cursedesk` has a `FileTree.tsx` of its own — the same ancestor, kept in step by hand ever
+ * since. The pair was compared to decide which should be the shared one, and this is: it is
+ * the app's tree with the workbook/sheet/note/merge vocabulary generalised away, and it has
+ * external drags, `canDrop`, `acceptsDrop`, reordering, filtering, access marks, counts and
+ * the three render slots, none of which the app's has.
+ *
+ * But the app's carried SIX behaviours this did not, every one of them general, and adopting
+ * this tree without them would have been a regression on a 200-row library rather than a
+ * 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).
+ *   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.
+ *   4. **⌥→ / ⌥← move the focused row** (`resolveKeyboardMove`) — the keyboard's half of the
+ *      drag, and the only half touch has.
+ *   5. **The drag chip says where it is going**, not only what is held (`describeDrop`).
+ *   6. **The click a finished drag leaves behind is swallowed** (`draggedJustNow`), and the
+ *      keyboard comes back from a rename instead of being dropped on `<body>`.
+ *
+ * Two more joined them because they were the same gap wearing a different hat: `onRowMenu`
+ * (Shift+F10 / the Menu key, since the tool shelf is deliberately not a tab stop) and
+ * `aria-posinset`/`aria-setsize`.
+ *
+ * What did NOT come across is the app's vocabulary — workbooks, merge-into-a-tab, notes,
+ * derived extensions, `activeNoteId`/`activeMediaId` as separate props. A feature the app
+ * 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`.
+ *
  * ── 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*
@@ -37,6 +68,7 @@ import type {
 } from 'react';
 import { Fragment, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
+  describeDrop,
   descendantIdsOf,
   type DropOffer,
   type FileTreeDrop,
@@ -46,6 +78,7 @@ import {
   flattenFileTree,
   matchTypeahead,
   resolveDrop,
+  resolveKeyboardMove,
 } from '../../core/file-tree/fileTreeModel';
 import { Input } from '../components/Input';
 import { Tooltip } from '../components/Tooltip';
@@ -159,6 +192,22 @@ export interface FileTreeProps {
   onDraftCommit?: (name: string) => void;
   onDraftCancel?: () => void;
 
+  /**
+   * The focused row's own menu, reached by **Shift+F10** or the **Menu** key — the keyboard's
+   * route to whatever {@link renderTools} draws.
+   *
+   * 🔴 The shelf is deliberately NOT a tab stop of its own (that would be one extra stop per
+   * row, which is what the roving-tabindex rule above exists to prevent), so without this the
+   * ⋯ menu on every row is unreachable without a pointer. Shift+F10 and the Menu key are what
+   * every desktop application answers a context menu on, so it is not a shortcut anybody has
+   * to be told about.
+   *
+   * The point is handed in viewport coordinates — the focused row's bottom-right corner —
+   * which is what a popover anchors to. Wire it to the SAME call the shelf's own button
+   * makes, so the two cannot drift into meaning different things.
+   */
+  onRowMenu?: (node: FileTreeNode, at: { x: number; y: number }) => void;
+
   /** Trailing controls for a row — the tool shelf. Quiet at rest, never invisible. */
   renderTools?: (node: FileTreeNode) => ReactNode;
   /** Leading glyph. Defaults to a folder/file mark. */
@@ -276,6 +325,7 @@ export function FileTree({
   draft,
   onDraftCommit,
   onDraftCancel,
+  onRowMenu,
   renderTools,
   renderIcon,
   renderAccessory,
@@ -295,6 +345,17 @@ export function FileTree({
   /** Folders this drag opened by hovering, to shut again if it never drops. */
   const sprung = useRef<string[]>([]);
   const typeahead = useRef({ word: '', at: 0 });
+  /**
+   * Swallow the `click` a finished drag leaves behind.
+   *
+   * 🔴 A pointerdown and a pointerup on the same row still produce a click even when the
+   * pointer travelled the length of the list in between — and with `setPointerCapture` the
+   * click is delivered to the row the gesture STARTED on whatever it ended over. So without
+   * this, dropping a row into a folder also selects the row that was dropped, which in a
+   * consumer that navigates on select means the drag takes you somewhere. The drag is the
+   * gesture; the click is debris from it.
+   */
+  const draggedJustNow = useRef(false);
 
   const [ownCollapsed, setOwnCollapsed] = useState<readonly string[]>([]);
   const collapsed = collapsedProp ?? ownCollapsed;
@@ -310,6 +371,15 @@ export function FileTree({
   const [focusedId, setFocusedId] = useState<string | 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);
+  /**
+   * The last thing a KEYBOARD move said, for the live region.
+   *
+   * A pointer drag states its refusal on the chip while the row is still in the air; ⌥← on a
+   * top-level row has no chip and nowhere else to say "it is already at the top level", so a
+   * keyboard route with no voice would be a control that silently does nothing — the exact
+   * reading of "broken" this tree's whole drop design exists to avoid.
+   */
+  const [notice, setNotice] = useState('');
 
   const shown = useMemo(() => (filter ? filterFileTree(nodes, filter) : nodes), [nodes, filter]);
   /*
@@ -321,6 +391,52 @@ export function FileTree({
     [shown, collapsed, filter],
   );
 
+  /**
+   * The folders between the root and the selected row, and the shut one HOLDING it.
+   *
+   * A tree with most of its folders shut says nothing about where you are, and the one state
+   * where that matters most is the state where the selected row is not drawn at all. So the
+   * path is marked (`data-ancestor`) and the folder actually holding the selection is marked
+   * more strongly (`data-holds-open`) — which is also the thing the reveal below scrolls to
+   * when the row itself does not exist on screen.
+   *
+   * Computed over the whole tree rather than over `rows`, because a shut folder's children
+   * are not in `rows` — which is exactly the case this is for.
+   */
+  const openPath = useMemo(() => {
+    const path = new Set<string>();
+    let holder: string | null = null;
+    if (selectedId === null) return { path, holder };
+    const walk = (list: readonly FileTreeNode[], ancestors: string[]): boolean => {
+      for (const node of list) {
+        if (node.id === selectedId) {
+          for (const id of ancestors) path.add(id);
+          holder = ancestors.at(-1) ?? null;
+          return true;
+        }
+        if (node.children && walk(node.children, [...ancestors, node.id])) return true;
+      }
+      return false;
+    };
+    walk(shown, []);
+    return { path, holder };
+  }, [shown, selectedId]);
+
+  /**
+   * How many siblings a row has, by parent — `aria-setsize`, without an O(n²) scan per row.
+   *
+   * Every sibling of a visible row is itself visible (a shut folder hides its children, never
+   * its peers), so counting the rows on screen is counting the level.
+   */
+  const setSizes = useMemo(() => {
+    const counts = new Map<string, number>();
+    for (const row of rows) {
+      const key = row.parentId ?? '';
+      counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+  }, [rows]);
+
   const toggle = useCallback(
     (id: string) => {
       const set = new Set(collapsed);
@@ -340,6 +456,51 @@ export function FileTree({
     [collapsed, setCollapsed],
   );
 
+  /**
+   * Bring the selected row into view — the explorer's *reveal*.
+   *
+   * 🔴 Every other cue for "where am I" is worth nothing in the one case that matters most:
+   * a long list where the selected row is eight hundred pixels above the fold. A consumer
+   * changes `selectedId` from a command palette, a tab, a Back button, a deep link or a
+   * recents list — all of them **without the pointer ever going near the tree** — so nothing
+   * was scrolling it. `cursedesk`'s tree has had this since it was written and this one did
+   * not, which would have made adopting it a regression on a 200-row library.
+   *
+   * 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.
+   * 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
+   *    under the pointer.
+   */
+  /*
+   * 🔴 The dependency list is deliberately neither what this reads nor a superset of it.
+   *
+   * `selectedId` is not read in the body at all — the row is found through the DOM, because
+   * `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.
+   */
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `selectedId` is the trigger and not a read; `drag` is a guard and not a trigger — see just above.
+  useEffect(() => {
+    const scroller = scrollRef.current;
+    if (!scroller || drag?.active) return;
+    const row =
+      scroller.querySelector<HTMLElement>('.cbft-row[data-selected]') ??
+      scroller.querySelector<HTMLElement>('.cbft-row[data-holds-open]');
+    if (!row?.scrollIntoView) return;
+    const box = row.getBoundingClientRect();
+    const frame = scroller.getBoundingClientRect();
+    if (box.top >= frame.top && box.bottom <= frame.bottom) return;
+    // `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]);
+
   // ── The drag ──────────────────────────────────────────────────────────────────────────
 
   const stopAutoScroll = useCallback(() => {
@@ -373,6 +534,10 @@ export function FileTree({
     (commit: boolean, state: DragState | null) => {
       stopAutoScroll();
       stopSpring();
+      // Whatever happens next, a gesture that actually travelled owes the row a swallowed
+      // 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);
         sprung.current = [];
@@ -468,13 +633,32 @@ export function FileTree({
         target.removeEventListener('pointermove', move);
         target.removeEventListener('pointerup', up);
         target.removeEventListener('pointercancel', cancel);
+        window.removeEventListener('keydown', abort);
         endDrag(commit, state);
       };
       const up = finish(true);
       const cancel = finish(false);
+      /*
+       * 🔴 Escape puts the row back — the way out of a gesture you did not mean to start.
+       *
+       * Every drag surface has it and this one did not: the only way to abandon a drag here
+       * was to find somewhere the tree refuses and release there, which is a thing you have
+       * to already understand the rules to do. `pointercancel` fires when the SYSTEM takes
+       * the pointer away, never when a person changes their mind.
+       *
+       * On `window` rather than the row, because a pointer capture is in force and the
+       * keyboard's focus is wherever it was before the press — quite possibly not this tree.
+       * It is removed by `finish` on every exit path, including this one.
+       */
+      const abort = (keyEvent: KeyboardEvent) => {
+        if (keyEvent.key !== 'Escape') return;
+        keyEvent.preventDefault();
+        cancel();
+      };
       target.addEventListener('pointermove', move);
       target.addEventListener('pointerup', up);
       target.addEventListener('pointercancel', cancel);
+      window.addEventListener('keydown', abort);
     },
     [
       allowReorder,
@@ -512,6 +696,33 @@ export function FileTree({
     if (id) rowRefs.current.get(id)?.focus();
   }, []);
 
+  /*
+   * ── The keyboard comes back from a rename ─────────────────────────────────────────────
+   *
+   * Owner, of the tree this one was ported from: *"I clicked a file, pressed enter, changed
+   * the title, pressed enter, and it saved. Then I pressed enter and it should have started
+   * renaming again but didn't. I think the focus gets lost on saving a rename."*
+   *
+   * The word "lost" is literal: committing unmounts the `<input>` that had focus, and a
+   * browser hands focus to `<body>` when that happens. `<body>` is not in the tree, so the
+   * next Enter goes to the application — which has no answer for it — rather than to the row
+   * that was just renamed. Every key this tree defines is gone until something is clicked.
+   *
+   * 🔴 **Only when focus was actually lost.** Blur commits too, so the ordinary way to end a
+   * rename is to click something else, and stealing focus back would undo that click.
+   * `document.body` (or nothing at all) is the signature of the unmount; anything else means
+   * a person is already somewhere on purpose.
+   */
+  const wasRenaming = useRef<string | null>(null);
+  useEffect(() => {
+    const previous = wasRenaming.current;
+    wasRenaming.current = renamingId ?? null;
+    if (!previous || renamingId) return;
+    const active = document.activeElement;
+    if (active && active !== document.body) return;
+    focusRow(previous);
+  }, [renamingId, focusRow]);
+
   const onKeyDown = useCallback(
     (event: React.KeyboardEvent<HTMLElement>, row: FileTreeRow) => {
       if (renamingId) return;
@@ -520,6 +731,53 @@ export function FileTree({
         const next = rows[Math.min(rows.length - 1, Math.max(0, index + delta))];
         if (next) focusRow(next.node.id);
       };
+
+      /*
+       * The keyboard's route to the row's own menu — see {@link FileTreeProps.onRowMenu}.
+       * Before the switch, because `ContextMenu` and Shift+F10 are not arrow keys and the
+       * shelf is deliberately not a tab stop that could answer them itself.
+       */
+      if (onRowMenu && (event.key === 'ContextMenu' || (event.shiftKey && event.key === 'F10'))) {
+        event.preventDefault();
+        const box = rowRefs.current.get(row.node.id)?.getBoundingClientRect();
+        onRowMenu(row.node, { x: box?.right ?? 0, y: box?.bottom ?? 0 });
+        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
+       * deliberately not offered). See `resolveKeyboardMove` for what the two directions mean
+       * and why there is no ⌥↑/⌥↓.
+       *
+       * 🔴 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 &&
+        event.altKey &&
+        !event.metaKey &&
+        !event.ctrlKey &&
+        (event.key === 'ArrowLeft' || event.key === 'ArrowRight')
+      ) {
+        event.preventDefault();
+        const offer = resolveKeyboardMove({
+          nodes: shown,
+          rows,
+          row,
+          direction: event.key === 'ArrowRight' ? 'in' : 'out',
+          ...(lockedReason ? { lockedReason } : {}),
+          ...(canDrop ? { canDrop } : {}),
+        });
+        if (offer.target) {
+          setNotice(describeDrop(shown, offer.target));
+          onMove(row.node.id, offer.target);
+        } else {
+          setNotice(offer.reason ?? '');
+        }
+        return;
+      }
+
       switch (event.key) {
         case 'ArrowDown':
           event.preventDefault();
@@ -617,7 +875,21 @@ export function FileTree({
         focusRow((rows[found] as FileTreeRow).node.id);
       }
     },
-    [focusRow, onDelete, onOpen, onRenameStart, onSelect, renamingId, rows, toggle],
+    [
+      canDrop,
+      focusRow,
+      lockedReason,
+      onDelete,
+      onMove,
+      onOpen,
+      onRenameStart,
+      onRowMenu,
+      onSelect,
+      renamingId,
+      rows,
+      shown,
+      toggle,
+    ],
   );
 
   // ── External drags (Finder files, gallery tiles) ──────────────────────────────────────
@@ -825,6 +1097,11 @@ export function FileTree({
                 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
@@ -839,6 +1116,13 @@ export function FileTree({
                 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) => {
@@ -847,6 +1131,11 @@ export function FileTree({
                 }}
                 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) => {
@@ -1033,6 +1322,11 @@ export function FileTree({
        * The chip that follows the cursor. There is no browser drag image with pointer
        * events, so this is the only thing saying the gesture is working — and it is also
        * where a refusal is stated, in words, while the row is still in the air.
+       *
+       * 🔴 It says WHERE IT IS GOING, not only what is held (2026-09-13). "Into Projects" or
+       * "To the top level" is the answer to the question a drag actually asks, and it is the
+       * difference between a cue that is decoration and one that stops a wrong drop before
+       * the pointer is lifted. The name alone tells you the gesture started, which you knew.
        */}
       {drag?.active ? (
         <div
@@ -1041,12 +1335,18 @@ export function FileTree({
           style={{ left: `${drag.x}px`, top: `${drag.y}px` }}
           aria-hidden='true'
         >
-          {drag.offer.reason ?? nameOf(shown, drag.id)}
+          <span className='cbft-chip-name'>{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'>
+            {drag.offer.reason ?? describeDrop(shown, drag.offer.target)}
+          </span>
         </div>
       ) : null}
-      {/* The same words, for a screen reader, which cannot see the chip. */}
+      {/* The same words, for a screen reader, which cannot see the chip — and, between drags,
+          whatever the last keyboard move said. See `notice`. */}
       <span className='cbft-sr' role='status' aria-live='polite'>
-        {drag?.active ? (drag.offer.reason ?? '') : ''}
+        {drag?.active ? (drag.offer.reason ?? describeDrop(shown, drag.offer.target)) : notice}
       </span>
     </div>
   );

package/src/react/file-tree/fileTree.css

@@ -333,6 +333,39 @@
 	outline-offset: -2px;
 }
 
+/*
+ * ── 🔴 Where you are, when the row you are on is not drawn ──────────────────────────────
+ *
+ * A tree with most of its folders shut says nothing about where you are, and the state where
+ * that matters most is the one where the selected row is not on screen at all. So the folders
+ * BETWEEN the root and the selection are weighted a step, and the shut folder actually
+ * holding it takes a mark of its own.
+ *
+ * Weight rather than colour for the ancestors: they are context, and three tinted rows down a
+ * sidebar would compete with the one neutral fill that says *this is where you are*. 550 is
+ * `file-tree-geometry`'s `maxWeight` — the ceiling the "use thinner fonts" note put on this
+ * tree, and the reason this is not 600.
+ */
+.cbft-row[data-ancestor] .cbft-name {
+	font-weight: 550;
+}
+
+/*
+ * The shut folder holding the selection. A 2px bar on the inside edge — the same language the
+ * activity rail uses for the view you are in, so a person learns it once — and deliberately
+ * NOT the selected row's fill: this folder is not what is selected, it is what the selection
+ * is inside. The reveal scrolls to this element when the selected row does not exist.
+ */
+.cbft-row[data-holds-open]::before {
+	content: '';
+	position: absolute;
+	inset-block: 2px;
+	inset-inline-start: 0;
+	inline-size: 2px;
+	border-radius: 999px;
+	background: var(--accent-solid, var(--accent));
+}
+
 /* The row that is in the air — still drawn, so the tree does not jump, but clearly lifted. */
 .cbft-row[data-dragged] {
 	opacity: 0.4;
@@ -615,6 +648,25 @@
 
 /* ── The drag chip ───────────────────────────────────────────────────────────────────── */
 
+/*
+ * Two parts, not one string: what is held, and where it is going. The destination is drawn a
+ * step quieter because the name is what identifies the chip and the destination is what you
+ * are checking — and because a refusal takes the same slot, where the colour below is what
+ * carries the "no".
+ */
+.cbft-chip-name {
+	font-weight: 500;
+}
+
+.cbft-chip-where {
+	margin-inline-start: 0.375rem;
+	color: var(--muted-foreground);
+}
+
+.cbft-chip[data-refused] .cbft-chip-where {
+	color: inherit;
+}
+
 .cbft-chip {
 	position: fixed;
 	/* Offset off the cursor so it never covers the row being aimed at. */

package/src/react/file-tree/fileTreeGeometry.fixture.json

@@ -0,0 +1,151 @@
+{
+  "$comment": [
+    "THE SIDEBAR FILE TREE, AS NUMBERS — the design this tree implements, committed HERE.",
+    "",
+    "🔴 WHY IT IS A FILE IN THIS REPO AND NOT A LOOKUP. Until 2026-09-13 the spec beside this",
+    "file read these numbers out of a checkout in the owner's home directory, and skipped its",
+    "cross-repo assertions whenever that directory was missing. cursedbelt is PUBLISHED: a",
+    "package whose suite reaches into one person's private tree passes for them and is silently",
+    "half-skipped for everybody else. A test that quietly does nothing is worse than no test.",
+    "",
+    "So the design is vendored. Every assertion in `fileTreeGeometry.spec.ts` now runs",
+    "unconditionally, on any machine, with no fleet beside the checkout.",
+    "",
+    "🔴 The numbers are asserted against THIS tree's implementation, never against themselves.",
+    "A test that read `true` out of this file and then asserted `true` would pass on a tree that",
+    "does neither thing. Change a value here and the stylesheet reds until it follows.",
+    "",
+    "The same design is implemented a second time in cursed-embeddable-spreadsheet, which is a",
+    "separate published package and cannot depend on this one. Keeping the two in step is a",
+    "human step at the point the design changes: edit this file, then both stylesheets."
+  ],
+  "geometry": {
+    "$comment": "Pixels. Same meaning either side; the prefixes differ (--cbft-* / --cs-tree-*).",
+    "row": 22,
+    "pad": 3,
+    "inset": 8,
+    "glyph": 16,
+    "indent": 8,
+    "gap": 6,
+    "guideOffset": 4
+  },
+  "scrollbar": {
+    "$comment": [
+      "🔴 THE TREE'S OWN SCROLLBAR, added 2026-09-11. Owner: \"The scrollbar should be very thin",
+      "in the file tree and against the right edge. Currently it has space between the scrolling",
+      "marker and the edge. File tree changes need to be done in ces too.\"",
+      "",
+      "Two separate defects, one per repo, and neither is visible from the other side:",
+      "",
+      "  - ces had a GLOBAL rule, `.cs-root ::-webkit-scrollbar { width: 11px }` with the thumb",
+      "    carrying `border: 3px solid var(--cs-bg)`. That border IS the space he is describing:",
+      "    a 3px ring of page background on each side leaves a 5px marker floating in an 11px",
+      "    gutter. Correct for a document scroller, far too loud down a 22px-row tree.",
+      "  - cursedbelt's `.cbft-scroll` declared nothing at all, so it drew the platform default",
+      "    — ~15px on macOS with the thumb inset by the engine.",
+      "",
+      "And in cursedbelt there was a third, which is the 'against the right edge' half: the tree",
+      "sat inside `FilterRail`'s `px-2` body, so the scroller's own edge was 8px short of the",
+      "rail's. A filling section now bleeds that padding back out (`-mx-2`) and the tree supplies",
+      "its own `inset` for the ROWS — which is why `inset` above is unchanged and the row text",
+      "still lines up under the section heading.",
+      "",
+      "🔴 `thumbInset: 0` is the assertion that matters and the one most likely to be undone by",
+      "somebody 'tidying' the thumb with a border or a margin to round it off. The marker touches",
+      "the edge; that is the whole request."
+    ],
+    "width": 6,
+    "thumbInset": 0
+  },
+  "invariants": {
+    "$comment": [
+      "The relationships, which are what actually break. A number can be changed on purpose;",
+      "these cannot be broken on purpose, and each one has a symptom nothing else reports."
+    ],
+    "indent === 8": "VS Code's own tree step, and a MEASUREMENT the owner made on screen rather than a value derived from anything here — so nothing may recompute it. It was briefly `glyph` (16) on a reading of \"the subdir and file icons should start at the right edge of the parent folder's arrow icon … bumped over by 1 icon space\", which is literally true only at one-glyph-per-step. He saw that and said: \"I want vscode 8px style so it matches how theirs looks.\" In VS Code a child's glyph box starts at the MIDDLE of its parent's, not past its edge.",
+    "indent is INDEPENDENT of glyph": "They were coupled for one day and must not be recoupled. What makes 8px read as VS Code is the single glyph column, not the step: the old four-track layout spent 44px of chrome before every name, so 8px of step was invisible beside it; at 22px of chrome the step is the thing you see.",
+    "no density or pointer block overrides indent": "cb had 12px under `@media (pointer: coarse)` and ces 12px under `[data-density=comfortable]`. A step that is 8 on a desktop and 12 on a phone is not one look. Row height and padding DO vary — those are about how much room a row is given; the step is about reading the hierarchy and reads the same everywhere.",
+    "guideOffset === indent / 2": "The indentation guide is painted down the MIDDLE of each indent step. Break it and every guide line sits in the gutter between two levels instead of under the chevron it connects to.",
+    "gap === 6": "One character at 13px, and VS Code's own figure — owner: \"a gap about the size of a single character\", and \"the gap is the same for files from their icons and dirs from their arrows.\" The second clause is why the tree has ONE glyph column rather than a chevron track plus an icon track.",
+    "row === glyph + pad * 2": "The row's height is its line box plus its padding, and the line box is set to the glyph. Break it and the row's height becomes a function of the host app's inherited line-height — the same component drawing a different height in each app.",
+    "scrollbar.width is declared by the TREE, not inherited": "Both repos draw a scrollbar somewhere up the tree — ces globally on `.cs-root`, cursedbelt by platform default — and both were wrong here for opposite reasons. A tree whose gutter is inherited is a tree whose gutter changes when somebody restyles a dialog.",
+    "scrollbar.thumbInset === 0": "The marker touches the right edge. A `border` or a `margin` on the thumb is how the space comes back: ces's global thumb carries `border: 3px solid var(--cs-bg)` on purpose for document scrollers, and the tree must override it rather than inherit it. Owner: \"against the right edge … Currently it has space between the scrolling marker and the edge.\"",
+    "nothing may pad the SCROLLER horizontally": "The scrollbar is painted at the scroll container's border-box edge, so any ancestor padding moves it inward — which is what `FilterRail`'s `px-2` was doing. Indentation is the ROW's job (`inset`), never the scroller's."
+  },
+  "typography": {
+    "$comment": [
+      "Owner, 2026-09-10: \"use thinner fonts and less bright font in dark mode. It looks too",
+      "glaring.\" Both halves are needed: the colour is the brightness, and antialiasing is the",
+      "WEIGHT — on a dark ground macOS stem-darkening renders 13px type visibly heavier than",
+      "the same weight on white, so dimming alone leaves fat letterforms in a quieter grey.",
+      "",
+      "🔴 The two repos already differed on the second half, and each keeps its own answer:",
+      "ces has carried `-webkit-font-smoothing: antialiased` on `.cs-root` since the beginning,",
+      "so a tree-scoped copy there would be inert and is deliberately absent — its \"thinner\" is",
+      "the weight ladder alone. cursedbelt's framework sets no base, so its tree declares one",
+      "under `:where(.dark) .cbft`. Each repo's test asserts ITS arrangement; this field records",
+      "the intent, not a string to grep for.",
+      "",
+      "The dark foreground is expressed as a target rather than a literal because the two apps",
+      "theme from different palettes; each derives its own value near it. VS Code's dark themes",
+      "all sit close to #cccccc for this surface while keeping full white for the selected row."
+    ],
+    "restWeight": 400,
+    "maxWeight": 550,
+    "darkForegroundTarget": "#cbd5e1",
+    "darkFontSmoothing": "antialiased",
+    "selectedRowKeepsFullForeground": true
+  },
+  "behaviour": {
+    "$comment": [
+      "Not numbers — the two things a row DOES that both trees must agree on. Added",
+      "2026-09-11 from the owner's batch: \"Make them use an arrow icon next to a dr even when",
+      "the dir is empty. For meda files show a thumbnail instead of the file type icon to the",
+      "left of the name.\"",
+      "",
+      "🔴 These are asserted against the IMPLEMENTATION on each side, not compared flag to",
+      "flag. A test that read `true` here and asserted `true` would pass on a tree that does",
+      "neither. So: flip a flag below and the repo whose code still does the old thing goes",
+      "red, which is the only arrangement where this file can refuse anything."
+    ],
+    "everyFolderDrawsATwisty": {
+      "value": true,
+      "why": [
+        "The chevron says FOLDER, not OCCUPIED — VS Code's own rule, and it opens an empty",
+        "folder onto nothing rather than hiding the control.",
+        "",
+        "Both trees defaulted to `children.length > 0` and it was wrong twice. For a LAZY tree",
+        "it is a trap door: a row whose contents load only while it is open has no children",
+        "while shut, so it loses its caret and can never be reopened — measured in",
+        "apps/collections, which had to pass an explicit `expandable` to escape it. For an",
+        "EAGER tree it draws a brand-new empty folder as a leaf, so the one mark that says",
+        "'this is a place' is missing exactly while the folder is being filled.",
+        "",
+        "An explicit opt-out survives on each side (cb: `expandable: false`) for a row that is",
+        "a folder in name and can never hold anything."
+      ]
+    },
+    "mediaRowDrawsItsThumbnail": {
+      "value": true,
+      "why": [
+        "A folder of photographs is a column of identical camera glyphs: the glyph box costs",
+        "16px and says nothing. The thumbnail is the only thing that tells one row from the",
+        "next without opening it.",
+        "",
+        "🔴 THREE constraints, each of which has already cost something somewhere in the fleet:",
+        "  1. It takes the SAME glyph box, not a new track and not a taller row. `row === glyph",
+        "     + pad * 2` above is what keeps a tree scannable; a row that grows per file is not.",
+        "  2. It falls back to the type icon ONCE per URL and never retries. A derived",
+        "     thumbnail's ABSENCE is the normal 'not rendered yet' state, so a broken-image",
+        "     glyph is a lie about the archive (apps/family shipped and reverted exactly that on",
+        "     2026-08-14), and re-pointing `src` from inside `onError` is an infinite request",
+        "     loop with every row in view retrying at once.",
+        "  3. It is a THUMBNAIL, never the original. This is a 16px box; a 300-row folder",
+        "     pointed at full-size objects is 300 full downloads to draw a rail.",
+        "",
+        "A FOLDER's glyph box is its twisty and no picture may displace it — the row would lose",
+        "the only control that opens it."
+      ]
+    }
+  }
+}