@young1lin/dsh-ui-gitworkbench 0.1.15 → 0.1.17

package/src/client/FileBrowser.tsx

@@ -23,12 +23,13 @@
  * @module @young1lin/dsh-ui-gitworkbench/client/FileBrowser
  */
 
-import { useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react'
 
 import css from './GitWorkbenchPanel.module.css'
 import { CodeEditor } from './CodeEditor.tsx'
 import { buildDirTree } from './dir-tree.ts'
-import { mergePaths, rootFiles, searchRows, treeRows, type FileRow } from './file-rows.ts'
+import { ancestorsOf, isIgnoredPath, mergePaths, rootFiles, searchRows, splitIgnored, treeRows, type FileRow } from './file-rows.ts'
+import { NO_IGNORED_READS, anyDirTruncated, attachReads, rememberDir, type DirRead } from './ignored-cache.ts'
 import { openAt, reconcilePlace, toggleDir, type FilesPlace } from './files-place.ts'
 import { sameList } from './stable-list.ts'
 import { PathDirGlyph, PathFileGlyph } from './glyphs.tsx'
@@ -44,7 +45,7 @@ import {
   DISARMED, applySaveOk, applySides, armEdit, armRefusal, isDirty, markConflict,
   type EditState, type WriteResult,
 } from './side-edit.ts'
-import type { BlameAnswer, BlameLine, FileImage, FileSides, SideLayer, Translate } from './GitWorkbenchPanel.tsx'
+import type { BlameAnswer, BlameLine, FileImage, FileSides, FilesTree, RepoTreeAnswer, SideLayer, Translate } from './GitWorkbenchPanel.tsx'
 
 /** Most search hits rendered at once — a one-letter query must not paint a
  *  whole repository into the DOM. */
@@ -61,8 +62,8 @@ const INDENT_EM = 0.85
 const FILES_PER_DIR = 100
 
 export function FileBrowser({
-  t, palette, statsPath, extraPaths, gen, treeStyle, treeRef, divider, place, onPlace, cached, onTree,
-  fetchRepoTree, fetchFileSides, writeChecked, fetchBlame, fetchFileImage, onSaved, onDirtyChange, onShowHistory,
+  t, palette, statsPath, extraPaths, gen, treeStyle, treeRef, divider, place, onPlace, cached, onTree, wrap,
+  fetchRepoTree, fetchIgnoredDir, fetchFileSides, writeChecked, fetchBlame, fetchFileImage, onSaved, onDirtyChange, onShowHistory,
 }: {
   t: Translate
   palette: string
@@ -78,7 +79,12 @@ export function FileBrowser({
   /** The drawer's own drag handle, passed in rather than imported, so this
    *  module does not import a value out of the panel that imports it. */
   divider: ReactNode
-  fetchRepoTree: (worktreePath: string | undefined, signal: AbortSignal) => Promise<{ paths: string[]; truncated: boolean } | null>
+  fetchRepoTree: (worktreePath: string | undefined, signal: AbortSignal) => Promise<RepoTreeAnswer | null>
+  /** One level of one ignored directory, read from the filesystem: git
+   *  collapses ignored directories by design and cannot be asked for their
+   *  contents scoped, so the expansion of a `node_modules/` row is a disk
+   *  read, not a git listing. */
+  fetchIgnoredDir: (worktreePath: string | undefined, dir: string, signal: AbortSignal) => Promise<DirRead | null>
   fetchFileSides: (worktreePath: string | undefined, path: string, layer: SideLayer, signal: AbortSignal) => Promise<FileSides | null>
   writeChecked: (worktreePath: string | undefined, path: string, text: string, expectedSha: string, signal: AbortSignal) => Promise<WriteResult | null>
   fetchBlame: (worktreePath: string | undefined, path: string, signal: AbortSignal) => Promise<BlameAnswer | null>
@@ -95,12 +101,20 @@ export function FileBrowser({
   place: FilesPlace
   onPlace: (next: FilesPlace) => void
   /** The last file list read, kept for the same reason: coming back should
-   *  render the tree, not blank it while the repository is re-read. */
-  cached: { readonly paths: readonly string[]; readonly truncated: boolean }
-  onTree: (next: { readonly paths: readonly string[]; readonly truncated: boolean }) => void
+   *  render the tree, not blank it while the repository is re-read. The
+   *  ignored fields carry the collapsed listing and every lazy directory's
+   *  read children. */
+  cached: FilesTree
+  /** An UPDATER rather than a value: lazy directory reads land concurrently,
+   *  and a write built from a tree that a sibling write already replaced
+   *  drops that sibling's children on the floor. */
+  onTree: (update: (prev: FilesTree) => FilesTree) => void
+  /** Soft wrap for the editor. The drawer's header owns the switch, so the
+   *  Files tab and the diff panes cannot disagree about it. */
+  wrap: boolean
 }): ReactNode {
   const { open, query, blameOn } = place
-  const { paths, truncated } = cached
+  const { paths, truncated, ignored, ignoredTruncated, ignoredError, children } = cached
   const expanded = useMemo(() => new Set(place.expanded), [place.expanded])
   /** A file that was open and is not in the repository any more. Reported
    *  rather than silently applied: a selection that clears itself with no
@@ -158,7 +172,19 @@ export function FileBrowser({
     void fetchRepoTree(statsPath, ctrl.signal)
       .then(answer => {
         if (!alive || answer === null) return
-        onTree({ paths: answer.paths, truncated: answer.truncated })
+        // A refresh starts the lazy children over: the tree they were read
+        // against is gone. The ignored fields are optional against an older
+        // host half, which then simply has no ignored rows to show.
+        onTree(() => ({
+          paths: answer.paths,
+          truncated: answer.truncated,
+          ignored: answer.ignored ?? [],
+          ignoredTruncated: answer.ignoredTruncated ?? false,
+          // Omitted, not undefined: the field says WHY the listing is missing,
+          // and a present-but-undefined key would read as an empty reason.
+          ...(answer.ignoredError !== undefined ? { ignoredError: answer.ignoredError } : {}),
+          children: NO_IGNORED_READS,
+        }))
       })
       .catch(() => { /* an old host half: the tree stays empty and says so */ })
     return () => { alive = false; ctrl.abort() }
@@ -246,9 +272,54 @@ export function FileBrowser({
   if (!sameList(extraHeld.current, extraPaths)) extraHeld.current = extraPaths
   const steadyExtra = extraHeld.current
 
-  const all = useMemo(() => mergePaths(paths, steadyExtra), [paths, steadyExtra])
-  const tree = useMemo(() => buildDirTree(all), [all])
-  const roots = useMemo(() => rootFiles(all), [all])
+  /** The ignored half of the listing, split by the trailing slash that is its
+   *  only kind marker: ignored files join the browsable list (they open,
+   *  edit and save through the same path untracked files already take);
+   *  collapsed directories become tree hints the rows below render as
+   *  expandable folders. */
+  const { files: ignoredFiles, dirs: collapsedDirs } = useMemo(() => splitIgnored(ignored), [ignored])
+  const ignoredFilesOf = useMemo(() => new Set(ignoredFiles), [ignoredFiles])
+  const collapsedOf = useMemo(() => new Set(collapsedDirs), [collapsedDirs])
+
+  /**
+   * The list git can speak for, and the tree over it. Both change only when
+   * the REPOSITORY is re-read — never when a folder is expanded, which is the
+   * whole point of the split below: merging the lazy children back into this
+   * list meant a fresh `Set`, a fresh `localeCompare` sort and a fresh tree
+   * walk over every path in the repository on every click (140ms at 50,000
+   * paths, measured, synchronously on the click).
+   */
+  const base = useMemo(
+    () => mergePaths(mergePaths(paths, steadyExtra), ignoredFiles),
+    [paths, steadyExtra, ignoredFiles],
+  )
+  /** Collapsed directories exist with nothing under them YET, and a path list
+   *  cannot express that; tracked directories are all implied by their files
+   *  and never need a hint. */
+  const baseTree = useMemo(() => buildDirTree(base, collapsedOf), [base, collapsedOf])
+  /** Everything read since, grafted onto the nodes it belongs to — work
+   *  proportional to what was clicked, not to the repository. */
+  const tree = useMemo(() => attachReads(baseTree, children), [baseTree, children])
+  const roots = useMemo(() => rootFiles(base), [base])
+
+  /** Lazy children as ordinary openable paths. The search and the
+   *  open-file reconciliation both read a flat list, so they get one — a
+   *  CONCATENATION, deliberately: `base` is already sorted and deduped, and
+   *  nothing under a collapsed directory can appear in it (git lists neither
+   *  ignored files nor untracked ones from inside a collapsed directory). */
+  const lazyFiles = useMemo(() => {
+    const out: string[] = []
+    for (const [dir, read] of Object.entries(children.reads)) {
+      for (const child of read.entries) if (!child.dir) out.push(`${dir}/${child.name}`)
+    }
+    return out.sort((a, b) => a.localeCompare(b))
+  }, [children])
+  const all = useMemo(
+    () => lazyFiles.length === 0 ? base : [...base, ...lazyFiles],
+    [base, lazyFiles],
+  )
+  /** Whether a directory the reader can still see was cut at the host's cap. */
+  const dirCut = useMemo(() => anyDirTruncated(children), [children])
   const rows = useMemo(
     () => query.trim().length > 0
       ? searchRows(all, query, SEARCH_CAP)
@@ -366,7 +437,34 @@ export function FileBrowser({
     onPlace(openAt(place, path))
   }
 
-  const foldDir = (path: string): void => { onPlace(toggleDir(place, path)) }
+  /** Directories whose children are in flight, so the effect further down
+   *  does not ask twice for the same one. */
+  const pendingDirs = useRef<Set<string>>(new Set())
+  /**
+   * How many times each directory has been expanded. A read belongs to ONE
+   * attempt: fold a directory while its read is in flight, expand it again,
+   * and the first read's answer — including its decision to fold the row back
+   * on failure — would otherwise land on the second attempt and undo the
+   * reader's click.
+   */
+  const attempts = useRef<Map<string, number>>(new Map())
+
+  const foldDir = (path: string): void => {
+    // Folding disowns whatever read is in flight for this row: its answer must
+    // not land on a later expansion, and a re-expand has to be free to ask
+    // again rather than wait on a read nobody will accept.
+    if (place.expanded.includes(path)) {
+      attempts.current.set(path, (attempts.current.get(path) ?? 0) + 1)
+      pendingDirs.current.delete(path)
+    }
+    onPlace(toggleDir(place, path))
+  }
+  /** Collapse a directory only if it stands open — the failure path of a
+   *  lazy read, where a plain toggle would re-open what the reader already
+   *  folded while the read was in flight. */
+  const foldIfOpen = (path: string): void => {
+    if (place.expanded.includes(path)) onPlace(toggleDir(place, path))
+  }
 
   const idRef = useRef(0)
   useEffect(() => { idRef.current += 1 }, [open])
@@ -416,8 +514,66 @@ export function FileBrowser({
    * their identity — would rebuild every row on every render, which is the
    * cost this memo exists to remove.
    */
-  const acts = useRef({ foldDir, openFile })
-  acts.current = { foldDir, openFile }
+  const acts = useRef({ foldDir, openFile, foldIfOpen })
+  acts.current = { foldDir, openFile, foldIfOpen }
+
+  /** What eviction must not touch: the directories standing open, and the
+   *  ancestors of the open file — whose path has to stay in the browsable
+   *  list, or the reconciliation below would report the open file vanished. */
+  const keepRef = useRef<ReadonlySet<string>>(new Set())
+  keepRef.current = useMemo(
+    () => new Set([...place.expanded, ...(open === null ? [] : ancestorsOf(open))]),
+    [place.expanded, open],
+  )
+
+  /** Read one ignored directory's children into the tree cache. A no-op when
+   *  they are already there or in flight. */
+  const loadDirChildren = useCallback((dir: string): void => {
+    if (pendingDirs.current.has(dir)) return
+    pendingDirs.current.add(dir)
+    const attempt = (attempts.current.get(dir) ?? 0) + 1
+    attempts.current.set(dir, attempt)
+    const settle = (): boolean => {
+      pendingDirs.current.delete(dir)
+      return attempts.current.get(dir) === attempt
+    }
+    void fetchIgnoredDir(statsPath, dir, new AbortController().signal)
+      .then(answer => {
+        if (!settle()) return // the reader folded this row and opened it again
+        if (answer === null) {
+          // The read failed — the host half went dark, or refused the path. Fold
+          // the row back: a folder standing open and empty forever reads as
+          // broken, one that declines to open reads as "nothing to ask again".
+          // The effect below retries once anything moves.
+          acts.current.foldIfOpen(dir)
+          return
+        }
+        // Merged inside the setState, against whatever tree is current: two
+        // reads can land before React re-renders either, and a write built
+        // from the tree this callback captured would drop the other's
+        // children — which the effect would then read again, and again.
+        onTree(prev => ({
+          ...prev,
+          children: rememberDir(prev.children, dir, answer, keepRef.current),
+        }))
+      })
+      .catch(() => { settle() })
+  }, [statsPath, fetchIgnoredDir, onTree])
+
+  // Any expanded directory in ignored territory whose children have not been
+  // read — one just clicked open, or one restored from a previous run; the
+  // PLACE survives restarts while the tree does not — gets them read now. The
+  // click itself is the plain folder toggle; children appear as they land,
+  // one level at a time, so no click can enumerate a whole ignored tree at
+  // once. A directory read while its parent is still unread grafts itself the
+  // moment the parent's read creates the node for it.
+  useEffect(() => {
+    for (const dir of place.expanded) {
+      if (children.reads[dir] === undefined && isIgnoredPath(dir, ignoredFilesOf, collapsedOf)) {
+        loadDirChildren(dir)
+      }
+    }
+  }, [place.expanded, children, ignoredFilesOf, collapsedOf, loadDirChildren])
 
   /**
    * `t` arrives in the host's slot props and its identity is not ours to rely
@@ -425,6 +581,8 @@ export function FileBrowser({
    * to change when the language does, and it costs one lookup per render.
    */
   const langKey = t('filesMore', { count: 0 })
+  /** Same trick for the ignored rows' title suffix. */
+  const ignoredLabel = t('filesIgnored')
 
   /**
    * The rendered rows.
@@ -436,7 +594,12 @@ export function FileBrowser({
    * the reader opens — the shape of "it gets laggy once there are a lot of
    * files".
    */
-  const list = useMemo(() => rows.map(row => (
+  const list = useMemo(() => rows.map(row => {
+    /** Ignored territory, by file or by descent from a collapsed directory.
+     *  The active row is exempt in the className below: being the file on
+     *  screen is the louder state, and the two must not fight. */
+    const ignored = row.kind !== 'more' && isIgnoredPath(row.path, ignoredFilesOf, collapsedOf)
+    return (
     <li key={rowKey(row)}>
       {row.kind === 'more' ? (
         <span
@@ -446,11 +609,13 @@ export function FileBrowser({
       ) : (
       <button
         type="button"
-        title={row.path}
+        title={ignored ? `${row.path} — ${ignoredLabel}` : row.path}
         aria-expanded={row.kind === 'dir' ? row.open : undefined}
         className={row.kind === 'file' && row.path === open
           ? `${css.fbRow} ${css.fbRowActive}`
-          : css.fbRow}
+          : ignored
+            ? `${css.fbRow} ${css.fbRowIgnored}`
+            : css.fbRow}
         style={{ paddingLeft: `${0.4 + row.depth * INDENT_EM}em` }}
         onClick={() => {
           row.kind === 'dir' ? acts.current.foldDir(row.path) : acts.current.openFile(row.path)
@@ -471,10 +636,11 @@ export function FileBrowser({
       </button>
       )}
     </li>
-  )),
+    )
+  }),
   // eslint-disable-next-line react-hooks/exhaustive-deps -- `t` is read through
   // `langKey`, and the handlers through `acts`; see both comments above.
-  [rows, open, langKey])
+  [rows, open, langKey, ignoredLabel, ignoredFilesOf, collapsedOf])
 
   return (
     <>
@@ -487,7 +653,13 @@ export function FileBrowser({
           aria-label={t('fileSearchPlaceholder')}
           onChange={event => { onPlace({ ...place, query: event.target.value }) }}
         />
-        {truncated ? <div className={css.fbNote}>{t('filesTruncated')}</div> : null}
+        {truncated || ignoredTruncated ? <div className={css.fbNote}>{t('filesTruncated')}</div> : null}
+        {/* Separate from the note above because the advice differs: the search
+            reads the path list, and entries a DIRECTORY read cut are not in
+            it. Derived from the cache, so folding or re-reading that directory
+            takes the note away instead of leaving it standing. */}
+        {dirCut ? <div className={css.fbNote}>{t('filesIgnoredCut')}</div> : null}
+        {ignoredError !== undefined ? <div className={css.fbNote}>{t('filesIgnoredFailed')}</div> : null}
         {rows.length === 0 ? (
           <div className={css.empty}>{all.length === 0 ? t('filesEmpty') : t('filesNoMatch')}</div>
         ) : (
@@ -648,6 +820,7 @@ export function FileBrowser({
                     onBlameClick={line => { setPicked(line) }}
                     notCommitted={t('blameUncommitted')}
                     readOnly={readOnly}
+                    wrap={wrap}
                   />
                 )}
             </div>

package/src/client/GitWorkbenchPanel.module.css

@@ -11,6 +11,7 @@
 @import './styles/history-filters.css';
 @import './styles/history.css';
 @import './styles/changes.css';
+@import './styles/rails.css';
 @import './styles/operations.css';
 @import './styles/controls.css';
 @import './styles/files.css';

package/src/client/GitWorkbenchPanel.tsx

@@ -72,9 +72,11 @@ import {
   opMessage, RefPicker, SettingsMenu, SourceChip, SyncBar,
 } from './WorkbenchControls.tsx'
 import { decodePlaces, encodePlaces, placeAt, withPlace, type FilesPlace, type FilesPlaces } from './files-place.ts'
+import { NO_IGNORED_READS, type DirRead, type IgnoredCache } from './ignored-cache.ts'
 import { useIdleValue } from './idle-value.ts'
 import { emptyQueryFilter, parseLogQuery, serializeLogQuery } from './log-filter-query.ts'
 import { nextAfterPlan, type DiscardAnswer, type DiscardPreview } from './discard-flow.ts'
+import { isPhantomModified } from './diff-model.ts'
 import { NO_PATHS, preferredFile } from './active-file.ts'
 import type { LogFilter } from '../log-filter.ts'
 import type { AuthorEntry } from '../shortlog.ts'
@@ -86,6 +88,7 @@ import { badgeRepeatsBranch, bindingChanged, branchOfWorktree, pathKey, probesCl
 import css from './GitWorkbenchPanel.module.css'
 
 export type * from './git-workbench-types.ts'
+export type { IgnoredChild } from './ignored-cache.ts'
 import type {
   BlameAnswer, BlockAsk, BlockMode, FileImage, FileSides, GitCommit, GitFile,
   GitOpName, GitOpPayload, GitOpResult, SideLayer, SyncStatus, Translate, WorkbenchStats,
@@ -114,7 +117,12 @@ type Props = PropsRuntime<'conversation.session.header.actions'> & {
    *  ref the history walks, so every listed author actually has commits there. */
   readonly fetchAuthors: (worktreePath: string | undefined, ref: string, signal: AbortSignal) => Promise<{ authors: readonly AuthorEntry[]; truncated: boolean } | null>
   /** Every path on HEAD — the path picker's raw material. */
-  readonly fetchRepoTree: (worktreePath: string | undefined, signal: AbortSignal) => Promise<{ paths: string[]; truncated: boolean } | null>
+  readonly fetchRepoTree: (worktreePath: string | undefined, signal: AbortSignal) => Promise<RepoTreeAnswer | null>
+  /** One level of one ignored directory, read from the filesystem — the step
+   *  behind expanding `node_modules/` in the Files tab. Null when the host
+   *  half is older than this client, which also sends no ignored entries, so
+   *  the call is never made. */
+  readonly fetchIgnoredDir: (worktreePath: string | undefined, dir: string, signal: AbortSignal) => Promise<DirRead | null>
   readonly fetchCompare: (worktreePath: string | undefined, base: string, head: string, signal: AbortSignal) => Promise<WorkbenchStats | null>
   readonly fetchStyle: (worktreePath: string | undefined, signal: AbortSignal) => Promise<StyleSettings | null>
   readonly saveStyle: (worktreePath: string | undefined, scope: StyleScope, entry: StyleEntry, signal: AbortSignal) => Promise<{ ok: boolean; error?: string }>
@@ -169,6 +177,10 @@ const STORE_FILES = 'dsh-ui-gitworkbench:files'
  *  field of the appearance object: that one is about colour, and this choice
  *  has to survive a build that adds a palette. */
 const STORE_HISTORY_LAYOUT = 'dsh-ui-gitworkbench:history-layout'
+/** Soft wrap, on or off. A reading preference rather than a project setting:
+ *  it says how THIS person wants long lines shown, so it lives beside the
+ *  pane sizes in localStorage rather than in the shared style store. */
+const STORE_WRAP = 'dsh-ui-gitworkbench:wrap'
 
 /** Dragged pane sizes in px; null on any of them keeps that pane's CSS default. */
 interface PaneWidths {
@@ -254,15 +266,44 @@ const EMPTY_STATS: WorkbenchStats = {
 /** How long the Files place must hold still before it is written. */
 const PLACES_WRITE_MS = 500
 
-/** One worktree's last-read file list. */
-interface FilesTree {
+/**
+ * What `repoTree` answers. The ignored fields are OPTIONAL because a host
+ * half older than this client sends none of them — the browser then simply
+ * has no ignored rows to show. Named rather than inlined so the panel, the
+ * drawer and the browser cannot drift apart on what crosses the wire.
+ */
+export interface RepoTreeAnswer {
+  paths: string[]
+  truncated: boolean
+  ignored?: string[]
+  ignoredTruncated?: boolean
+  /** Set when the ignored listing itself failed, so "nothing ignored" and
+   *  "could not ask" are not the same silence. */
+  ignoredError?: string
+}
+
+/** One worktree's last-read file list. Exported because the browser takes it
+ *  whole: one shape for the cache and the update, so the two cannot drift. */
+export interface FilesTree {
   readonly paths: readonly string[]
   readonly truncated: boolean
+  /** Ignored entries exactly as `repoTree` sent them: full paths for ignored
+   *  files, one trailing-slash line per directory a rule ignores whole. */
+  readonly ignored: readonly string[]
+  readonly ignoredTruncated: boolean
+  /** Why the ignored listing is missing, when it is. Absent on success — an
+   *  empty list then means the repository really has nothing ignored. */
+  readonly ignoredError?: string
+  /** Children read so far — the payload of every lazy expansion the reader
+   *  has made in this worktree, bounded and evicting (`ignored-cache.ts`). */
+  readonly children: IgnoredCache
 }
 
 /** A worktree nobody has opened the Files tab on yet. One instance, so an
  *  unvisited worktree does not re-render the browser on every pass. */
-const EMPTY_TREE: FilesTree = { paths: [], truncated: false }
+const EMPTY_TREE: FilesTree = {
+  paths: [], truncated: false, ignored: [], ignoredTruncated: false, children: NO_IGNORED_READS,
+}
 
 /** The overlay with nothing on it — one instance, so an empty overlay never
  *  re-renders the tree that receives it. */
@@ -296,7 +337,7 @@ function defaultBase(branches: readonly string[], head: string): string {
 
 
 
-export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetchFileDiff, fetchFileSides, writeChecked, fetchBlame, fetchFileImage, fetchWorktreeStatus, fetchSessionBinding, fetchCommitStats, fetchCommits, fetchAuthors, fetchRepoTree, fetchCompare, fetchStyle, saveStyle, fetchSync, runGitOp, fetchDiscardPlan }: Props) {
+export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetchFileDiff, fetchFileSides, writeChecked, fetchBlame, fetchFileImage, fetchWorktreeStatus, fetchSessionBinding, fetchCommitStats, fetchCommits, fetchAuthors, fetchRepoTree, fetchIgnoredDir, fetchCompare, fetchStyle, saveStyle, fetchSync, runGitOp, fetchDiscardPlan }: Props) {
   const worktreePath = useSessions((state: { byId?: Record<string, { cwd?: string } | undefined> }) =>
     state?.byId?.[sessionId]?.cwd) as string | undefined
   /** Whether the session's agent has a turn in flight — the store mirrors it
@@ -332,10 +373,17 @@ export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetch
   const rememberPlace = useCallback((key: string, next: FilesPlace): void => {
     setFilesPlaces(prev => withPlace(prev, key, next))
   }, [])
-  const rememberTree = useCallback((key: string, next: FilesTree): void => {
+  // An UPDATER, not a value: two lazy directory reads can land in the same
+  // microtask, before React has re-rendered either into the browser. Both
+  // would then build their write from the same stale tree and the first one's
+  // children would be silently dropped — which the effect below the browser
+  // notices and re-reads, turning N expanded directories into O(N²) disk
+  // reads. Folding the merge into the setState is what makes each write see
+  // the one before it.
+  const rememberTree = useCallback((key: string, update: (prev: FilesTree) => FilesTree): void => {
     setFilesTrees(prev => {
       const map = new Map(prev)
-      map.set(key, next)
+      map.set(key, update(prev.get(key) ?? EMPTY_TREE))
       return map
     })
   }, [])
@@ -421,6 +469,12 @@ export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetch
   const [historyLayout, setHistoryLayout] = useState<HistoryLayout>(
     () => readStored(STORE_HISTORY_LAYOUT, isHistoryLayout, DEFAULT_HISTORY_LAYOUT),
   )
+  /** Soft wrap. Default OFF, which is what the panes have always done: code is
+   *  written in columns, and wrapping it is a choice about one long file, not
+   *  a better default for every file. */
+  const [wrap, setWrap] = useState<boolean>(
+    () => readStored(STORE_WRAP, (value): value is boolean => typeof value === 'boolean', false),
+  )
   /** Per-project and global styling; both scopes, unresolved. */
   const [style, setStyle] = useState<StyleSettings>(EMPTY_SETTINGS)
   /** Whether dsh's resolved palette is currently dark. */
@@ -1126,6 +1180,22 @@ export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetch
     writeStored(STORE_HISTORY_LAYOUT, next)
   }
 
+  /**
+   * Turn soft wrap on or off, and remember it.
+   *
+   * A plain function, like every other handler below the two guards above:
+   * those `return null`s are the reason nothing past this point may be a HOOK.
+   * A `useCallback` here rendered fewer hooks than the previous pass on the
+   * frame the first stats arrived, which React reports as error #310 and the
+   * shell reports as "slot entry crashed" — the chip simply vanishes.
+   */
+  const toggleWrap = (): void => {
+    setWrap(prev => {
+      writeStored(STORE_WRAP, !prev)
+      return !prev
+    })
+  }
+
   /** Tab switch. No direction refetches the working tree: `viewKey` already
    *  separates the tabs' per-file diff caches, so bumping `gen` here only cost a
    *  redundant round trip. */
@@ -1229,6 +1299,8 @@ export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetch
           onHistoryLayout={applyHistoryLayout}
           onClose={() => setOpen(false)}
           onRefresh={refresh}
+          wrap={wrap}
+          onToggleWrap={toggleWrap}
           commitDraft={commitDraft}
           onCommitDraft={setCommitDraft}
           commitAmend={commitAmend}
@@ -1246,6 +1318,7 @@ export function GitWorkbenchPanel({ sessionId, useSessions, t, fetchStats, fetch
           writeChecked={writeChecked}
           fetchBlame={fetchBlame}
           fetchFileImage={fetchFileImage}
+          fetchIgnoredDir={fetchIgnoredDir}
           viewKey={viewKey}
           gen={gen}
           collapsed={collapsed}
@@ -1329,7 +1402,8 @@ interface DrawerProps {
   /** Author roster for the funnel popup's user picker. */
   fetchAuthors: (worktreePath: string | undefined, ref: string, signal: AbortSignal) => Promise<{ authors: readonly AuthorEntry[]; truncated: boolean } | null>
   /** Every path on HEAD — the path picker's raw material. */
-  fetchRepoTree: (worktreePath: string | undefined, signal: AbortSignal) => Promise<{ paths: string[]; truncated: boolean } | null>
+  fetchRepoTree: (worktreePath: string | undefined, signal: AbortSignal) => Promise<RepoTreeAnswer | null>
+  fetchIgnoredDir: (worktreePath: string | undefined, dir: string, signal: AbortSignal) => Promise<DirRead | null>
   /** Every local branch — the ref pickers' options, worktree or not. */
   branches: readonly string[]
   /** Branches that have a worktree, grouped to the top of every picker. */
@@ -1383,6 +1457,10 @@ interface DrawerProps {
   onHistoryLayout: (next: HistoryLayout) => void
   onClose: () => void
   onRefresh: () => void
+  /** Soft wrap, shared by every pane that shows code — the Files editor and
+   *  both diff views — because it is one reading preference, not three. */
+  wrap: boolean
+  onToggleWrap: () => void
   /** Commit draft, lifted so a tab switch cannot discard it. */
   commitDraft: string
   onCommitDraft: (next: string) => void
@@ -1423,11 +1501,11 @@ interface DrawerProps {
   filesPlaces: FilesPlaces
   onFilesPlace: (key: string, next: FilesPlace) => void
   filesTrees: ReadonlyMap<string, FilesTree>
-  onFilesTree: (key: string, next: FilesTree) => void
+  onFilesTree: (key: string, update: (prev: FilesTree) => FilesTree) => void
   onCollapsedChange: (next: Set<string>) => void
 }
 
-function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectCommit, hasMoreCommits, loadingMore, onLoadMoreCommits, historyRef, onHistoryRef, historyQuery, onHistoryQuery, historyError, fetchAuthors, fetchRepoTree, branches, worktreeBranches, branchesTruncated, baseRef, headRef, onBaseRef, onHeadRef, comparable, t, binding, worktrees, sessionPath, statsPath, onSwitchSource, segments, selected, onSelect, maximized, onToggleMaximized, theme, mode, family, onMode, onFamily, style, background, onStyle, width, onWidth, panes, onPane, onCommitsTall, historyLayout, onHistoryLayout, onClose, onRefresh, commitDraft, onCommitDraft, commitAmend, onCommitAmend, sync, treeLoading, historyLoading, busy, opResult, runOp, fetchDiscardPlan, onOpError, pendingTicks, onTick, fetchFileDiff, fetchFileSides, writeChecked, fetchBlame, fetchFileImage, viewKey, gen, collapsed, onCollapsedChange, filesPlaces, onFilesPlace, filesTrees, onFilesTree }: DrawerProps): ReactNode {
+function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectCommit, hasMoreCommits, loadingMore, onLoadMoreCommits, historyRef, onHistoryRef, historyQuery, onHistoryQuery, historyError, fetchAuthors, fetchRepoTree, fetchIgnoredDir, branches, worktreeBranches, branchesTruncated, baseRef, headRef, onBaseRef, onHeadRef, comparable, t, binding, worktrees, sessionPath, statsPath, onSwitchSource, segments, selected, onSelect, maximized, onToggleMaximized, theme, mode, family, onMode, onFamily, style, background, onStyle, width, onWidth, panes, onPane, onCommitsTall, historyLayout, onHistoryLayout, onClose, onRefresh, wrap, onToggleWrap, commitDraft, onCommitDraft, commitAmend, onCommitAmend, sync, treeLoading, historyLoading, busy, opResult, runOp, fetchDiscardPlan, onOpError, pendingTicks, onTick, fetchFileDiff, fetchFileSides, writeChecked, fetchBlame, fetchFileImage, viewKey, gen, collapsed, onCollapsedChange, filesPlaces, onFilesPlace, filesTrees, onFilesTree }: DrawerProps): ReactNode {
   // Empty stand-in while a commit's change set loads, so every hook below keeps a
   // stable shape and the panes simply render nothing.
   const body = shown ?? EMPTY_STATS
@@ -1457,7 +1535,7 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
   const rememberPlaceHere = useCallback(
     (next: FilesPlace) => { onFilesPlace(filesKey, next) }, [onFilesPlace, filesKey])
   const rememberTreeHere = useCallback(
-    (next: FilesTree) => { onFilesTree(filesKey, next) }, [onFilesTree, filesKey])
+    (update: (prev: FilesTree) => FilesTree) => { onFilesTree(filesKey, update) }, [onFilesTree, filesKey])
   const browsablePaths = useMemo(
     () => stats.files.filter(file => file.status !== 'deleted').map(file => file.path),
     [stats.files],
@@ -1477,6 +1555,11 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
   // content in the working tree and in every commit.
   const activeKey = active === null ? null : `${viewKey}\x1f${active}`
   const segment = bundled.length > 0 ? bundled : activeKey === null ? '' : fetched.get(activeKey) ?? ''
+  /** The CRLF phantom: listed modified, whole-file diff empty (see
+   *  {@link isPhantomModified}). Changes-tab only — history and compare list
+   *  files from real ref diffs, where an empty segment means a failed fetch,
+   *  and the phantom notice would mislead. */
+  const phantomListed = tab === 'changes' && isPhantomModified(activeFile?.status, segment)
 
   // On-demand diff for files absent from the bundled payload (cap-truncated
   // untracked files, oversize paths).
@@ -1822,6 +1905,14 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
               title={maximized ? t('restore') : t('maximize')}
               onClick={onToggleMaximized}
             ><ChromeGlyph of={maximized ? 'restore' : 'maximize'} /></button>
+            <button
+              type="button"
+              className={wrap ? `${css.btn} ${css.btnIcon} ${css.btnIconOn}` : `${css.btn} ${css.btnIcon}`}
+              aria-pressed={wrap}
+              aria-label={wrap ? t('wrapLinesOff') : t('wrapLines')}
+              title={wrap ? t('wrapLinesOff') : t('wrapLines')}
+              onClick={onToggleWrap}
+            ><ChromeGlyph of="wrap" /></button>
             <button
               type="button"
               className={`${css.btn} ${css.btnIcon}`}
@@ -1984,7 +2075,9 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
               onPlace={rememberPlaceHere}
               cached={filesTrees.get(filesKey) ?? EMPTY_TREE}
               onTree={rememberTreeHere}
+              wrap={wrap}
               fetchRepoTree={fetchRepoTree}
+              fetchIgnoredDir={fetchIgnoredDir}
               fetchFileSides={fetchFileSides}
               writeChecked={writeChecked}
               fetchBlame={fetchBlame}
@@ -2047,6 +2140,13 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
             ) : activeFile !== null && activeFile.previousPath !== undefined ? (
               <div className={css.renameLine}>{t('renamedFrom')} <code>{activeFile.previousPath}</code></div>
             ) : null}
+            {/* An empty compare result is usually the three-dot DIRECTION, not
+                "no differences": A...B diffs from the fork point up to B, so a
+                B that never moved past the fork shows nothing at all. Say so —
+                an empty tree with no word reads as a broken one. */}
+            {tab === 'compare' && comparable && shown !== null && body.files.length === 0 ? (
+              <div className={css.empty}>{t('compareEmptyHint', { base: baseRef ?? '', head: headRef ?? '' })}</div>
+            ) : null}
             {(shown === null && tab !== 'changes') || (tab === 'compare' && !comparable) ? null
               : activeFile !== null && activeFile.binary ? (
                 <div className={css.empty}>{t('binaryFile')}</div>
@@ -2055,6 +2155,7 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
                   t={t}
                   path={active}
                   palette={theme}
+                  wrap={wrap}
                   statsPath={statsPath}
                   fetchSides={fetchFileSides}
                   writeChecked={writeChecked}
@@ -2062,6 +2163,7 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
                   gen={gen}
                   fallbackSegment={segment}
                   fallbackLoading={loading && segment.length === 0}
+                  phantomListed={phantomListed}
                   onBlockAction={askBlockAction}
                   onSaved={onRefresh}
                   onDirtyChange={onSideDirty}
@@ -2069,7 +2171,7 @@ function Drawer({ stats, shown, tab, onSwitchTab, commits, commitHash, onSelectC
               ) : loading && segment.length === 0 ? (
                 <div className={css.empty}>{t('loadingDiff')}</div>
               ) : segment.length > 0 ? (
-                <DiffView segment={segment} path={active ?? ''} palette={theme} t={t} />
+                <DiffView segment={segment} path={active ?? ''} palette={theme} t={t} wrap={wrap} />
               ) : (
                 <div className={css.empty}>{t('noTextDiff')}</div>
               )}