@young1lin/dsh-ui-gitworkbench 0.1.14 → 0.1.16

package/src/client/SideRails.tsx

@@ -0,0 +1,106 @@
+import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from 'react'
+
+import css from './GitWorkbenchPanel.module.css'
+import { NO_RAIL, railsShown, sameMetric, type RailMetric } from './h-rail.ts'
+
+/** A column and the rail that scrolls it, as the DOM hands them over. */
+type Box = { current: HTMLElement | null }
+
+/**
+ * Measure one column and keep its rail's scroll position tied to it.
+ *
+ * The measurement runs on EVERY render rather than on a dependency list: the
+ * content width changes for reasons no list can name — a window scrolled to
+ * longer rows, syntax spans replacing plain text, the editor mounting into the
+ * right column, wrap turning on. Two integer reads is a cheap price for never
+ * being stale, and {@link sameMetric} is what keeps setting state on every
+ * render from becoming a render on every render.
+ *
+ * @param colRef - the column, which clips and scrolls its own content.
+ * @param railRef - the strip at the bottom of the pane that stands in for it.
+ * @returns the column's measured widths.
+ */
+function useRail(colRef: Box, railRef: Box): RailMetric {
+  const [metric, setMetric] = useState<RailMetric>(NO_RAIL)
+
+  const measure = (col: HTMLElement): void => {
+    const next = { view: col.clientWidth, content: col.scrollWidth }
+    setMetric(prev => sameMetric(prev, next) ? prev : next)
+  }
+
+  useLayoutEffect(() => {
+    const col = colRef.current
+    if (col !== null) measure(col)
+  })
+
+  // A pane resized without a re-render — the drawer's own edge dragged, the
+  // window resized — changes what fits without changing what is rendered.
+  useEffect(() => {
+    const col = colRef.current
+    if (col === null) return
+    const observer = new ResizeObserver(() => { measure(col) })
+    observer.observe(col)
+    return () => { observer.disconnect() }
+  }, [colRef])
+
+  // Two-way, because both ends are real scrollers: the rail is what the reader
+  // drags, and the column still scrolls on its own from a trackpad swipe or a
+  // shift-wheel over the code. Each writes only when the value differs, which
+  // is what stops the pair from echoing a scroll back and forth forever.
+  useEffect(() => {
+    const col = colRef.current
+    const rail = railRef.current
+    if (col === null || rail === null) return
+    const toRail = (): void => { if (rail.scrollLeft !== col.scrollLeft) rail.scrollLeft = col.scrollLeft }
+    const toCol = (): void => { if (col.scrollLeft !== rail.scrollLeft) col.scrollLeft = rail.scrollLeft }
+    col.addEventListener('scroll', toRail, { passive: true })
+    rail.addEventListener('scroll', toCol, { passive: true })
+    toRail()
+    return () => {
+      col.removeEventListener('scroll', toRail)
+      rail.removeEventListener('scroll', toCol)
+    }
+  }, [colRef, railRef])
+
+  return metric
+}
+
+/**
+ * The side-by-side pane's horizontal scrollbars, stuck to the bottom of the
+ * pane instead of the bottom of the file — see `h-rail.ts` for why they are
+ * here at all.
+ *
+ * Always rendered, never conditionally: the strip collapses to nothing through
+ * a class when neither column overflows, so both rails keep their elements and
+ * the effects above keep stable dependencies. A rail that mounted and
+ * unmounted with the measurement would re-attach its listeners on every file.
+ *
+ * @param leftRef - the left column.
+ * @param rightRef - the right column.
+ * @param split - the divider's position, as a fraction of the pane's width;
+ *                the rails carry the same flex sizing so each sits under the
+ *                column it scrolls.
+ * @returns the sticky rail strip.
+ */
+export function SideRails({ leftRef, rightRef, split }: {
+  leftRef: Box
+  rightRef: Box
+  split: number
+}): ReactNode {
+  const leftRailRef = useRef<HTMLDivElement>(null)
+  const rightRailRef = useRef<HTMLDivElement>(null)
+  const left = useRail(leftRef, leftRailRef)
+  const right = useRail(rightRef, rightRailRef)
+  const shown = railsShown(left, right)
+  return (
+    <div className={shown ? `${css.sideRails} ${css.sideRailsOn}` : css.sideRails} aria-hidden="true">
+      <div ref={leftRailRef} className={css.sideRail} style={{ flexBasis: `${split * 100}%` }}>
+        <div className={css.sideRailSpan} style={{ width: left.content }} />
+      </div>
+      <div className={css.sideRailGap} />
+      <div ref={rightRailRef} className={`${css.sideRail} ${css.sideRailRight}`}>
+        <div className={css.sideRailSpan} style={{ width: right.content }} />
+      </div>
+    </div>
+  )
+}

package/src/client/diff-cells.tsx

@@ -0,0 +1,147 @@
+/**
+ * The side-by-side pane's leaf cells: what one row's four boxes are called and
+ * what goes inside them.
+ *
+ * Split out of `DiffViews.tsx` because that file holds two whole views and a
+ * module the reviewer cannot hold in their head is the thing the size guard in
+ * `tests/panel-modules.test.ts` exists to prevent. Nothing here decides
+ * anything — every function takes a row and returns a class or a fragment —
+ * which is exactly the part of the view that reads better away from the state
+ * it is rendered from.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/diff-cells
+ */
+
+import type { MouseEventHandler, ReactNode } from 'react'
+
+import css from './GitWorkbenchPanel.module.css'
+import { CR_GLYPH, splitOnCr } from './cr-mark.ts'
+import { blockEdge, type SideCell, type SideRow } from './side-rows.ts'
+import type { HighlightRun } from './highlight.ts'
+
+/** Classes that paint only a block's OUTER perimeter. Internal rows carry the
+ * vertical edges but no top/bottom line, avoiding the blue ladder a large
+ * addition block used to draw. Absent side-cells return no class at all. */
+export function blockHotClass(rows: readonly SideRow[], index: number, side: 'left' | 'right', hot: boolean): string {
+  if (!hot) return ''
+  const edge = blockEdge(rows, index, side)
+  if (edge === null) return ''
+  const first = edge === 'first' || edge === 'single' ? ` ${css.sideBlockHotFirst}` : ''
+  const last = edge === 'last' || edge === 'single' ? ` ${css.sideBlockHotLast}` : ''
+  return ` ${css.sideBlockHot}${first}${last}`
+}
+
+/** Line-number cell class: a PRESENT cell of a changed row carries its side's
+ *  tint into the gutter; an absent one stays blank, the way a split diff shows
+ *  a one-sided change with an empty opposite pane rather than a tinted void. */
+export function sideNumClass(row: SideRow, side: 'left' | 'right'): string {
+  const cell = side === 'left' ? row.left : row.right
+  if (cell === null || row.kind === 'same') return css.sideNum
+  return `${css.sideNum} ${side === 'left' ? css.sideNumDel : css.sideNumAdd}`
+}
+
+/** Code cell class: deletions tint left, additions right, context stays quiet. */
+export function sideCodeClass(row: SideRow, side: 'left' | 'right'): string {
+  const cell = side === 'left' ? row.left : row.right
+  if (cell === null || row.kind === 'same') return css.sideCodeSame
+  return `${side === 'left' ? css.sideCodeDel : css.sideCodeAdd} ${css.sideCellBlock}`
+}
+
+/** One text with every carriage return drawn as the CR glyph. No CR means
+ * the text comes back untouched — the common line, on both sides, costs one
+ * `includes`. The glyph spans are aria-hidden and unselectable, so copying a
+ * line copies code, not markers. */
+export function renderWithCrMarks(text: string): ReactNode {
+  const parts = splitOnCr(text)
+  if (parts.length === 1) return text
+  const out: ReactNode[] = [parts[0]!]
+  for (let i = 1; i < parts.length; i += 1) {
+    out.push(<span key={`cr${i}`} className={css.crMark} aria-hidden="true">{CR_GLYPH}</span>)
+    out.push(parts[i]!)
+  }
+  return out
+}
+
+/** One cell's Shiki runs, or its plain text when no tokens exist; either way
+ * each carriage return in the cell is drawn, so a line whose only change is
+ * its ending shows the difference instead of two identical-looking cells. */
+export function renderSideCode(cell: SideCell | null, tokens: readonly HighlightRun[] | undefined): ReactNode {
+  if (cell === null) return ''
+  if (tokens === undefined || tokens.length === 0) return renderWithCrMarks(cell.text)
+  if (tokens.length === 1 && tokens[0]!.color === undefined && !tokens[0]!.italic) return renderWithCrMarks(cell.text)
+  return tokens.map((tok, i) => (
+    <span
+      key={i}
+      style={tok.color === undefined && !tok.italic ? undefined : { color: tok.color, fontStyle: tok.italic ? 'italic' : undefined }}
+    >{renderWithCrMarks(tok.text)}</span>
+  ))
+}
+
+
+
+/**
+ * The spacer standing in for the rows above or below the window.
+ *
+ * It spans every column of the grid, so a blame gutter does not change it.
+ * @param height - px of rows it stands in for; nothing is rendered for 0.
+ */
+export function RowSpacer({ height }: { height: number }): ReactNode {
+  if (height <= 0) return null
+  return <span className={css.sideSpacer} style={{ height: `${height}px` }} aria-hidden="true" />
+}
+
+/**
+ * One side of one aligned row: its line-number cell and its code cell.
+ *
+ * Written once and used by all three columns the pane draws — the left side of
+ * a diff, the right side, and the dense index column beside the editor —
+ * because the three differ only in which cell they read, what hangs the block
+ * bar and whether a click arms the editor. Everything else about them, from
+ * the block outline to the CR markers, is the same in all three and was
+ * previously the same three times.
+ */
+export function SideCells({ row, side, index, rows, current, tokens, mark, minHeight, bar, armable, onArm }: {
+  row: SideRow
+  side: 'left' | 'right'
+  /** Index into `rows`, which is what the block outline keys on. */
+  index: number
+  rows: readonly SideRow[]
+  /** Whether this row belongs to the block the change walk is standing on. */
+  current: boolean
+  tokens: readonly HighlightRun[] | undefined
+  /**
+   * What marks this cell for measurement ({@link rowMark}), or undefined for
+   * "do not measure".
+   *
+   * The measured element is INSIDE the cell rather than the cell itself,
+   * because the cell carries the imposed `minHeight` below: measuring it would
+   * read back what was imposed, and a row that grew for a narrow pane could
+   * never shrink again when the pane was widened.
+   */
+  mark?: Record<string, string>
+  /** Imposed so both sides of a wrapped row stand the same height. */
+  minHeight?: number
+  bar?: ReactNode
+  /** The working-tree column, whose cells arm the editor when clicked. */
+  armable?: boolean
+  onArm?: MouseEventHandler<HTMLElement>
+}): ReactNode {
+  const hot = blockHotClass(rows, index, side, current)
+  const cell = side === 'left' ? row.left : row.right
+  const code = renderSideCode(cell, tokens)
+  const box = minHeight !== undefined && minHeight > 0 ? { minHeight: `${minHeight}px` } : undefined
+  return (
+    <>
+      <span className={`${sideNumClass(row, side)}${hot}`} style={box}>{cell === null ? '' : cell.line}</span>
+      <span
+        className={`${css.sideCode} ${sideCodeClass(row, side)}${hot}${armable === true ? ` ${css.sideArmable}` : ''}`}
+        style={box}
+        data-block={cell !== null && row.block >= 0 ? row.block : undefined}
+        onClick={onArm}
+      >
+        {mark === undefined ? code : <span className={css.sideFlow} {...mark}>{code}</span>}
+        {bar}
+      </span>
+    </>
+  )
+}

package/src/client/diff-nav.ts

@@ -234,6 +234,7 @@ export function blockTopsFromRows(
   blocks: readonly number[],
   rowH: number,
   offset = 0,
+  topOf?: (index: number) => number,
 ): readonly BlockTop[] {
   const tops: BlockTop[] = []
   const seen = new Set<number>()
@@ -241,7 +242,9 @@ export function blockTopsFromRows(
     const block = blocks[i]!
     if (!Number.isInteger(block) || block < 0 || seen.has(block)) continue
     seen.add(block)
-    tops.push({ block, top: offset + i * rowH })
+    // `i * rowH` is the answer only while every row is one line tall. With
+    // soft wrap on, the pane's height model is the one that knows.
+    tops.push({ block, top: offset + (topOf === undefined ? i * rowH : topOf(i)) })
   }
   return tops
 }

package/src/client/dir-tree.ts

@@ -36,10 +36,20 @@ interface BuildNode {
  * Fold a flat path list into a sorted directory tree carrying its files.
  * Root-level files live on no directory; the SEARCH ({@link searchPaths}) is
  * where they surface.
+ *
+ * `dirHints` names directories that exist with NO file under them yet — the
+ * collapsed entries of the ignored listing (`node_modules/`), whose children
+ * are only read when the reader expands them. A path list cannot express
+ * that: a node with no files and no children is indistinguishable from a
+ * path that was never mentioned. Hints only ever ADD an empty directory; a
+ * hint that lands on a name the path list recorded as a file is skipped,
+ * because the list is the primary source and a hint is hearsay next to it.
+ *
  * @param paths - repo-relative file paths, any order, no duplicates assumed.
+ * @param dirHints - repo-relative directory paths to show even while empty.
  * @returns the top-level directories, children and files sorted by name.
  */
-export function buildDirTree(paths: readonly string[]): readonly DirEntry[] {
+export function buildDirTree(paths: readonly string[], dirHints?: ReadonlySet<string>): readonly DirEntry[] {
   const rootNode: BuildNode = { name: '', path: '', files: [], children: new Map() }
   for (const path of paths) {
     if (path.length === 0) continue
@@ -59,6 +69,26 @@ export function buildDirTree(paths: readonly string[]): readonly DirEntry[] {
     node.files.push(parts[parts.length - 1]!)
   }
 
+  const addHint = (hint: string): void => {
+    if (hint.length === 0) return
+    const parts = hint.split('/')
+    let node = rootNode
+    for (let i = 0; i < parts.length - 1; i += 1) {
+      const name = parts[i]!
+      const child = node.children.get(name)
+      if (child !== undefined) { node = child; continue }
+      // The path list recorded this name as a file; the hint does not demote it.
+      if (node.files.includes(name)) return
+      const created: BuildNode = { name, path: parts.slice(0, i + 1).join('/'), files: [], children: new Map() }
+      node.children.set(name, created)
+      node = created
+    }
+    const last = parts[parts.length - 1]!
+    if (node.children.has(last) || node.files.includes(last)) return
+    node.children.set(last, { name: last, path: hint, files: [], children: new Map() })
+  }
+  if (dirHints !== undefined) for (const hint of dirHints) addHint(hint)
+
   const freeze = (node: BuildNode): DirEntry => {
     const children = [...node.children.values()].sort((a, b) => a.name.localeCompare(b.name)).map(freeze)
     const files = [...node.files].sort((a, b) => a.localeCompare(b))

package/src/client/file-rows.ts

@@ -162,6 +162,46 @@ export function searchRows(paths: readonly string[], needle: string, cap: number
   return out
 }
 
+/** What `git ls-files --others --ignored --exclude-standard --directory`
+ *  returned, split by kind: every ignored FILE (any depth, as long as no rule
+ *  swallowed its whole directory) and every directory git collapsed to one
+ *  line because it is ignored as a whole — the trailing slash is the only
+ *  thing that tells them apart, so it is the whole test.
+ *  @param entries - the listing verbatim, as `repoTree` carried it.
+ */
+export function splitIgnored(entries: readonly string[]): { files: readonly string[]; dirs: readonly string[] } {
+  const files: string[] = []
+  const dirs: string[] = []
+  for (const entry of entries) {
+    if (entry.length === 0) continue
+    if (entry.endsWith('/')) dirs.push(entry.slice(0, -1))
+    else files.push(entry)
+  }
+  return { files, dirs }
+}
+
+/**
+ * Whether a row is gitignored territory: an ignored file itself, a directory
+ * the listing collapsed, or anything living under one. Everything under a
+ * collapsed directory is ignored by inheritance, which is what makes the
+ * ancestor walk the whole rule.
+ *
+ * @param path - the row's repo-relative path.
+ * @param files - ignored file paths, from {@link splitIgnored}.
+ * @param dirs - collapsed directory paths, from {@link splitIgnored}.
+ */
+export function isIgnoredPath(
+  path: string,
+  files: ReadonlySet<string>,
+  dirs: ReadonlySet<string>,
+): boolean {
+  if (files.has(path) || dirs.has(path)) return true
+  for (const dir of ancestorsOf(path)) {
+    if (dirs.has(dir)) return true
+  }
+  return false
+}
+
 /**
  * The browsable path list: everything git tracks, plus files that exist on
  * disk but not in HEAD.

package/src/client/h-rail.ts

@@ -0,0 +1,70 @@
+/**
+ * Where a side-by-side column's horizontal scrollbar belongs.
+ *
+ * The pane scrolls vertically; each column scrolls horizontally on its own,
+ * which is what lets the divider mean something (one grid across both sides is
+ * sized by the widest line in the file, so dragging it moves nothing). The
+ * cost of that split is where the browser draws the column's scrollbar: at the
+ * bottom of the COLUMN, and the column is as tall as the file. On a
+ * two-thousand-line diff the only way to reach the control that scrolls
+ * sideways was to scroll all the way down first — and then scroll back up to
+ * see what it did.
+ *
+ * So the column's own scrollbar is hidden and a rail is stuck to the bottom of
+ * the pane instead, one per column, each a real scroller whose content is
+ * exactly as wide as its column's. Same geometry, so the two scroll positions
+ * map one to one; native, so it looks and behaves like every other scrollbar
+ * on the machine.
+ *
+ * This module is the part with no DOM in it: when a rail is warranted at all.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/h-rail
+ */
+
+/** A column's visible width and the width of what is inside it. */
+export interface RailMetric {
+  /** The column's client width — what the reader can see at once. */
+  readonly view: number
+  /** The column's scroll width — how wide the widest row made it. */
+  readonly content: number
+}
+
+/** Before anything has been measured, and for a column that is not mounted. */
+export const NO_RAIL: RailMetric = { view: 0, content: 0 }
+
+/**
+ * Whether a column overflows by enough to be worth a scrollbar.
+ *
+ * The one-pixel slack is not tidiness: a grid track rounds to a fraction, so a
+ * column whose longest line exactly fits still reports a scroll width a third
+ * of a pixel wider than its client width. Without the slack every file gets a
+ * rail, and every one of those rails scrolls nowhere.
+ *
+ * @param metric - the column's measured widths.
+ * @returns true when a rail should be shown for it.
+ */
+export function railNeeded(metric: RailMetric): boolean {
+  const { view, content } = metric
+  if (!Number.isFinite(view) || !Number.isFinite(content)) return false
+  if (view <= 0) return false
+  return content > view + 1
+}
+
+/** Whether the rail row is shown at all — either column overflowing is enough,
+ *  since the row is one sticky strip and a lone rail still needs its space. */
+export function railsShown(left: RailMetric, right: RailMetric): boolean {
+  return railNeeded(left) || railNeeded(right)
+}
+
+/**
+ * Whether two measurements are the same.
+ *
+ * The measuring effect runs on every render, so this is what keeps it from
+ * setting state on every render and rendering again forever.
+ *
+ * @param a - the measurement held in state.
+ * @param b - the one just read from the DOM.
+ */
+export function sameMetric(a: RailMetric, b: RailMetric): boolean {
+  return a.view === b.view && a.content === b.content
+}

package/src/client/ignored-cache.ts

@@ -0,0 +1,193 @@
+/**
+ * The lazily read children of ignored directories, held as a BOUNDED cache.
+ *
+ * Browsing `node_modules/` reads one level per click, and every level read
+ * stays around so folding and unfolding does not re-read the disk. Left
+ * alone that is a cache that only grows: a long session drilling through a
+ * dependency tree accumulates every level it ever opened, and "an unbounded
+ * cache is a leak with a nicer name".
+ *
+ * So the cache carries its own size and evicts, with one exception that is
+ * not negotiable: it never evicts a directory the reader is LOOKING at.
+ * Dropping the children of an expanded row would make the effect that fills
+ * it read them again, which would evict something else, which would be read
+ * again — a cache that fights the viewport spins forever. The cap is
+ * therefore a fuse against accumulated browsing, and the `keep` set is the
+ * floor it will not cut below.
+ *
+ * Pure: no React, no DOM, no RPC. `tests/ignored-cache.test.ts` loads it.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/ignored-cache
+ */
+
+import type { DirEntry } from './dir-tree.ts'
+
+/** One entry of a lazily listed ignored directory: a name plus whether
+ *  expanding it again makes sense. */
+export interface IgnoredChild {
+  readonly name: string
+  readonly dir: boolean
+}
+
+/** One directory's read, exactly as the host answered it. */
+export interface DirRead {
+  readonly entries: readonly IgnoredChild[]
+  /** Whether the host cut this directory's listing at its own cap. */
+  readonly truncated: boolean
+}
+
+/**
+ * Every directory read so far, plus the two things a bound needs: the order
+ * they were read in (the eviction queue, oldest first) and the total entry
+ * count, so a test can PROVE the bound instead of trusting it.
+ */
+export interface IgnoredCache {
+  readonly reads: Readonly<Record<string, DirRead>>
+  readonly order: readonly string[]
+  /** Total entries held across every directory. */
+  readonly size: number
+}
+
+/** Nothing read yet. One instance, so an untouched worktree does not
+ *  re-render the browser on every pass. */
+export const NO_IGNORED_READS: IgnoredCache = { reads: {}, order: [], size: 0 }
+
+/**
+ * Most entries held across all directories at once. A real level is a few
+ * hundred, so reaching this takes dozens of expansions of pathological
+ * directories; it is the fuse, not a working number.
+ */
+export const IGNORED_CACHE_CAP = 20_000
+
+/**
+ * Record one directory's children, evicting the oldest reads that nobody is
+ * looking at until the cache is back under the cap.
+ *
+ * @param cache - the cache as it stands.
+ * @param dir - repo-relative directory the read belongs to.
+ * @param read - what the host answered.
+ * @param keep - directories that must survive eviction: the ones expanded on
+ *               screen, and the ancestors of the open file (whose path must
+ *               stay in the browsable list or the editor would report it
+ *               vanished). The directory being written is always kept.
+ * @param cap - most entries to hold in total.
+ */
+export function rememberDir(
+  cache: IgnoredCache,
+  dir: string,
+  read: DirRead,
+  keep: ReadonlySet<string>,
+  cap: number = IGNORED_CACHE_CAP,
+): IgnoredCache {
+  const reads: Record<string, DirRead> = { ...cache.reads, [dir]: read }
+  const order = [...cache.order.filter(key => key !== dir), dir]
+  let size = cache.size - (cache.reads[dir]?.entries.length ?? 0) + read.entries.length
+
+  // Oldest first, skipping what is on screen. When everything left is kept,
+  // the walk simply ends: over the cap and holding only visible rows is the
+  // one state where the right move is to hold them.
+  let index = 0
+  while (size > cap && index < order.length) {
+    const victim = order[index]!
+    if (victim === dir || keep.has(victim)) { index += 1; continue }
+    size -= reads[victim]?.entries.length ?? 0
+    delete reads[victim]
+    order.splice(index, 1)
+  }
+  return { reads, order, size }
+}
+
+/** Whether any directory still held was cut at the host's per-directory cap.
+ *  Derived rather than sticky: a cut directory that has been evicted, or a
+ *  refresh that replaced the cache, stops claiming it. */
+export function anyDirTruncated(cache: IgnoredCache): boolean {
+  for (const read of Object.values(cache.reads)) {
+    if (read.truncated) return true
+  }
+  return false
+}
+
+/** Files plus subtree counts — the invariant every {@link DirEntry} carries. */
+function countOf(files: readonly string[], children: readonly DirEntry[]): number {
+  return files.length + children.reduce((sum, child) => sum + child.fileCount, 0)
+}
+
+/** Merge one directory's read into the node that stands for it. Names the
+ *  node already has win: the path list is the primary source, and a read that
+ *  disagrees with it must not split one name into two rows. */
+function withChildren(entry: DirEntry, read: DirRead): DirEntry {
+  const haveDirs = new Set(entry.children.map(child => child.name))
+  const haveFiles = new Set(entry.files)
+  const files = [...entry.files]
+  const children = [...entry.children]
+  for (const child of read.entries) {
+    if (haveDirs.has(child.name) || haveFiles.has(child.name)) continue
+    if (child.dir) {
+      haveDirs.add(child.name)
+      children.push({ name: child.name, path: `${entry.path}/${child.name}`, fileCount: 0, files: [], children: [] })
+    } else {
+      haveFiles.add(child.name)
+      files.push(child.name)
+    }
+  }
+  files.sort((a, b) => a.localeCompare(b))
+  children.sort((a, b) => a.name.localeCompare(b.name))
+  return { ...entry, files, children, fileCount: countOf(files, children) }
+}
+
+/** Rebuild only the spine down to `parts`, leaving every other node — and
+ *  every other subtree's identity — exactly as it was. Null when the path is
+ *  not in the tree, which is how a read for a directory a refresh dropped
+ *  becomes a no-op instead of an error. */
+function replaceAt(
+  dirs: readonly DirEntry[],
+  parts: readonly string[],
+  depth: number,
+  apply: (entry: DirEntry) => DirEntry,
+): readonly DirEntry[] | null {
+  const name = parts[depth]!
+  const index = dirs.findIndex(dir => dir.name === name)
+  if (index === -1) return null
+  const current = dirs[index]!
+  let next: DirEntry
+  if (depth === parts.length - 1) {
+    next = apply(current)
+  } else {
+    const grafted = replaceAt(current.children, parts, depth + 1, apply)
+    if (grafted === null) return null
+    next = { ...current, children: grafted, fileCount: countOf(current.files, grafted) }
+  }
+  const out = [...dirs]
+  out[index] = next
+  return out
+}
+
+/**
+ * Graft every read directory's children onto the tree built from the path
+ * list.
+ *
+ * This is the reason expanding an ignored directory is not O(repository):
+ * rebuilding the tree from a merged path list meant a fresh `Set`, a fresh
+ * `localeCompare` sort and a fresh walk over EVERY path on every click —
+ * measured at 140ms on a 50,000-path repository, synchronously, on the click.
+ * Grafting touches only the nodes on the path to each read directory, so the
+ * cost is the depth of what was clicked plus the width of what came back.
+ *
+ * Shallow directories are grafted first, so the empty node a parent's read
+ * creates exists by the time its own read is grafted onto it.
+ *
+ * @param tree - the tree from {@link buildDirTree} over the path list.
+ * @param cache - the directories read so far.
+ */
+export function attachReads(tree: readonly DirEntry[], cache: IgnoredCache): readonly DirEntry[] {
+  const dirs = Object.keys(cache.reads)
+  if (dirs.length === 0) return tree
+  const shallowFirst = [...dirs].sort((a, b) => a.split('/').length - b.split('/').length)
+  let out = tree
+  for (const dir of shallowFirst) {
+    if (dir.length === 0) continue
+    const grafted = replaceAt(out, dir.split('/'), 0, entry => withChildren(entry, cache.reads[dir]!))
+    if (grafted !== null) out = grafted
+  }
+  return out
+}

package/src/client/index.ts

@@ -181,16 +181,35 @@ export function apply(ctx: ClientContext): void {
           ) as { ok: true; value: { authors: AuthorEntry[]; truncated: boolean } } | { ok: false; error: { message?: string } }
           return result.ok ? result.value : null
         },
-        // Every path on HEAD — the path picker's raw material.
-        fetchRepoTree: async (worktreePath: string | undefined, signal: AbortSignal): Promise<{ paths: string[]; truncated: boolean } | null> => {
+        // Every path on HEAD — the path picker's raw material — plus the
+        // ignored entries the Files tab browses. The ignored fields are
+        // optional because a host half older than this client does not send
+        // them: the browser then simply has no ignored rows to show.
+        fetchRepoTree: async (worktreePath: string | undefined, signal: AbortSignal): Promise<{ paths: string[]; truncated: boolean; ignored?: string[]; ignoredTruncated?: boolean; ignoredError?: string } | null> => {
           const result = await connection.rpc.call(
             '/api',
             'gitWorkbench/repoTree',
             { args: { worktreePath: worktreePath ?? '' } },
             signal,
-          ) as { ok: true; value: { paths: string[]; truncated: boolean } } | { ok: false; error: { message?: string } }
+          ) as { ok: true; value: { paths: string[]; truncated: boolean; ignored?: string[]; ignoredTruncated?: boolean; ignoredError?: string } } | { ok: false; error: { message?: string } }
           return result.ok ? result.value : null
         },
+        // One level of one ignored directory, read from the filesystem: git
+        // collapses ignored directories by design, so the only way into
+        // `node_modules/` is to ask the disk directly (see the host method).
+        fetchIgnoredDir: async (worktreePath: string | undefined, dir: string, signal: AbortSignal): Promise<{ entries: { name: string; dir: boolean }[]; truncated: boolean } | null> => {
+          try {
+            const result = await connection.rpc.call(
+              '/api',
+              'gitWorkbench/ignoredDir',
+              { args: { worktreePath: worktreePath ?? '', dir } },
+              signal,
+            ) as { ok: true; value: { entries: { name: string; dir: boolean }[]; truncated: boolean } } | { ok: false; error: { message?: string } }
+            return result.ok ? result.value : null
+          } catch {
+            return null
+          }
+        },
         // Two refs compared as `base...head`, in the same shape as every other
         // view, so the drawer's tree and diff panes render it unchanged.
         fetchCompare: async (worktreePath: string | undefined, base: string, head: string, signal: AbortSignal): Promise<WorkbenchStats | null> => {