@fresh-editor/fresh-editor 0.3.6 → 0.3.8

package/plugins/search_replace.ts

@@ -68,10 +68,28 @@ interface PanelState {
   caseSensitive: boolean;
   useRegex: boolean;
   wholeWords: boolean;
+  // Scope (§1): when false, results are restricted to `sourceBufferPath`.
+  // `sourceBufferPath` is the absolute path of the buffer that was
+  // active when the panel opened; `sourceBufferRelPath` is the
+  // cwd-relative display form. Empty path means the source buffer was
+  // unsaved/virtual; in that case the "current file" mode degrades to
+  // "no matches" and the toggle visually still flips, but the user
+  // can't usefully restrict to an unnamed buffer.
+  allFiles: boolean;
+  sourceBufferPath: string;
+  sourceBufferRelPath: string;
   // Layout
   viewportWidth: number;
   // State
   busy: boolean;
+  /** True once the current `searchPattern` has been used to run a real
+   * search to completion. Reset whenever the pattern is mutated (or a
+   * search-affecting toggle changes). Distinguishes "user is typing,
+   * no search has happened" from "search ran and found nothing", so we
+   * don't show a misleading "No matches" placeholder before any work
+   * has been done. See §17 of
+   * `docs/internal/search-replace-scope-replan-on-widgets.md`. */
+  searchPerformed: boolean;
   truncated: boolean;
   // Inline editing cursor position
   cursorPos: number;
@@ -109,6 +127,57 @@ const SEARCH_DEBOUNCE_MS = 150;
 
 let searchDebounceGeneration = 0;
 
+/** Most-recent-first history of search patterns, capped at HISTORY_MAX.
+ *  Up arrow in the search field walks back into older entries; Down
+ *  walks forward. Persistence across editor restarts is a follow-up.
+ *  See §11 of docs/internal/search-replace-scope-replan-on-widgets.md. */
+const searchHistory: string[] = [];
+const HISTORY_MAX = 20;
+/** -1 = not navigating history. 0..searchHistory.length-1 = currently
+ *  displaying the history entry at that index. */
+let historyIndex = -1;
+/** Whatever the user had in the search field before they pressed Up
+ *  to enter history-walk mode. Restored when they Down past the most
+ *  recent history entry. */
+let historySavedPattern: string | null = null;
+/** Most recent widget_event we saw a widget_key for. Used to decide
+ *  whether Up/Down should walk history (when focus appears to be on
+ *  the search field) or fall through to the widget runtime. The
+ *  widget runtime doesn't expose focus directly to the plugin, but
+ *  every event that's relevant (change/select/toggle/activate/expand)
+ *  carries widget_key. Best-effort proxy. */
+let lastFocusedWidget: string | null = null;
+
+function historyPush(pattern: string): void {
+  if (!pattern) return;
+  const existing = searchHistory.indexOf(pattern);
+  if (existing === 0) return;
+  if (existing > 0) searchHistory.splice(existing, 1);
+  searchHistory.unshift(pattern);
+  if (searchHistory.length > HISTORY_MAX) {
+    searchHistory.length = HISTORY_MAX;
+  }
+}
+
+// "Has the user settled on this query?" lives on a separate timer
+// from the 150ms search debounce. Pushing to history on every
+// debounce tick captures intermediate prefixes (typing "foo bar"
+// in fits and starts → "f", "fo", "foo", … all end up in history).
+// Wait 2 seconds of pattern-stability before pushing; any change
+// cancels the pending push.
+const HISTORY_SETTLE_MS = 2000;
+let historySettleGeneration = 0;
+function scheduleHistoryPush(pattern: string): void {
+  if (!pattern) return;
+  const gen = ++historySettleGeneration;
+  editor.delay(HISTORY_SETTLE_MS).then(() => {
+    if (gen !== historySettleGeneration) return;
+    if (!panel || panel.searchPattern !== pattern) return;
+    if (historyIndex >= 0) return; // walking history; not user input
+    historyPush(pattern);
+  });
+}
+
 // =============================================================================
 // Colors
 // =============================================================================
@@ -197,6 +266,10 @@ function getActiveFieldText(): string {
 function setActiveFieldText(text: string): void {
   if (!panel) return;
   if (panel.queryField === "search") {
+    if (panel.searchPattern !== text) {
+      // Pattern changed → any cached result no longer applies. See §17.
+      panel.searchPerformed = false;
+    }
     panel.searchPattern = text;
   } else {
     panel.replaceText = text;
@@ -335,22 +408,31 @@ function getViewportHeight(): number {
 // theme keys, and focus affordance match every other plugin.
 function buildOptionsRowSpec(): WidgetSpec {
   if (!panel) return col();
-  const { focusPanel, optionIndex, caseSensitive, useRegex, wholeWords } = panel;
+  const { focusPanel, optionIndex, caseSensitive, useRegex, wholeWords, allFiles } = panel;
   const W = Math.max(MIN_WIDTH, panel.viewportWidth - 2);
   const oFocus = focusPanel === "options";
 
-  // The flex Spacer fills whatever's left of the row so the
-  // "Replace All" button right-aligns regardless of label width or
-  // panel width. No more byteLen-summing of labels.
   const caseLabel = editor.t("panel.case_toggle");
   const regexLabel = editor.t("panel.regex_toggle");
   const wholeLabel = editor.t("panel.whole_toggle");
-  const replLabel = editor.t("panel.replace_all_btn");
+  const allFilesLabel = editor.t("panel.all_files_toggle");
+  // Replace All button label tracks scope (§1):
+  //   * allFiles=true  → "Replace All (Alt+Ret)"
+  //   * allFiles=false → "Replace All in <file> (Alt+Ret)"
+  // sourceBufferRelPath is empty for an unsaved buffer, in which
+  // case we fall back to the all-files label since restricting to
+  // a path-less buffer can't match anything anyway.
+  const replLabel = (!allFiles && panel.sourceBufferRelPath)
+    ? editor.t("panel.replace_all_in_file_btn", { file: panel.sourceBufferRelPath })
+    : editor.t("panel.replace_all_btn");
   void oFocus;
   void optionIndex;
+  void W;
 
   return row(
     spacer(1),
+    toggle(allFiles, allFilesLabel, { key: "allFiles" }),
+    spacer(2),
     toggle(caseSensitive, caseLabel, { key: "case" }),
     spacer(2),
     toggle(useRegex, regexLabel, { key: "regex" }),
@@ -361,6 +443,22 @@ function buildOptionsRowSpec(): WidgetSpec {
   );
 }
 
+// Build the scope-info row shown only when allFiles=false. Tells the
+// user which single file the search is restricted to. When allFiles=true
+// the function returns an empty col() (the spec composer skips it).
+function buildScopeRowSpec(): WidgetSpec {
+  if (!panel) return col();
+  if (panel.allFiles) return col();
+  const label = panel.sourceBufferRelPath
+    ? editor.t("panel.scope_row_file", { file: panel.sourceBufferRelPath })
+    : editor.t("panel.scope_row_unnamed");
+  return raw([{
+    text: " " + label,
+    properties: { type: "scope-row" },
+    style: { fg: C.label, italic: true },
+  }]);
+}
+
 // Build the typed Row spec for line 1 (search + replace fields with
 // trailing match-count stats). Was previously hand-rolled with two
 // `buildFieldDisplay` calls + manual cursor overlays; now uses the
@@ -368,11 +466,52 @@ function buildOptionsRowSpec(): WidgetSpec {
 // background, cursor highlight at the right byte position). The
 // match-stats portion stays in Raw because it has bespoke
 // truncated-warning styling (`[255, 180, 50]`) and isn't a control.
-function buildLine1Spec(): WidgetSpec {
-  if (!panel) return col();
-  const { searchPattern, replaceText, focusPanel, queryField, cursorPos, truncated } = panel;
+// Build just the matchStats text + inline overlays. Pulled out of
+// `buildLine1Spec` so the streaming pump can refresh it via the
+// `setRawEntries` mutation on the keyed `matchStats` raw widget —
+// without re-emitting the full panel spec (which forces js_to_json
+// over the entire 5 000-node tree and blocks the JS thread).
+function buildMatchStatsEntries(): TextPropertyEntry[] {
+  if (!panel) return [];
   const totalMatches = panel.searchResults.length;
   const fileCount = panel.fileGroups.length;
+  const truncated = panel.truncated;
+  const truncatedSuffix = truncated ? " " + editor.t("panel.limited") : "";
+  let matchStats = "";
+  if (totalMatches > 0) {
+    matchStats = "  " + editor.t("panel.match_stats", { count: String(totalMatches), files: String(fileCount) }) + truncatedSuffix;
+  } else if (panel.busy && panel.searchPattern) {
+    matchStats = "  " + editor.t("panel.searching");
+  } else if (panel.searchPattern && panel.searchPerformed && !panel.busy) {
+    matchStats = "  " + editor.t("panel.no_matches");
+  }
+  if (matchStats.length === 0) return [];
+  const overlays: InlineOverlay[] = [];
+  if (truncated && totalMatches > 0) {
+    const statsWithoutSuffix = "  " + editor.t("panel.match_stats", {
+      count: String(totalMatches),
+      files: String(fileCount),
+    });
+    const countEnd = byteLen(statsWithoutSuffix);
+    overlays.push({ start: 0, end: countEnd, style: { fg: C.statusOk } });
+    overlays.push({
+      start: countEnd,
+      end: countEnd + byteLen(truncatedSuffix),
+      style: { fg: [255, 180, 50] as RGB, bold: true },
+    });
+  } else {
+    overlays.push({
+      start: 0,
+      end: byteLen(matchStats),
+      style: { fg: totalMatches > 0 ? C.statusOk : C.statusDim },
+    });
+  }
+  return [{ text: matchStats, inlineOverlays: overlays }];
+}
+
+function buildLine1Spec(): WidgetSpec {
+  if (!panel) return col();
+  const { searchPattern, replaceText, focusPanel, queryField, cursorPos } = panel;
   const qFocusSearch = focusPanel === "query" && queryField === "search";
   const qFocusReplace = focusPanel === "query" && queryField === "replace";
   const searchVal = searchPattern || "";
@@ -385,39 +524,6 @@ function buildLine1Spec(): WidgetSpec {
   const searchLabel = editor.t("panel.search_label");
   const replLabel = editor.t("panel.replace_label");
 
-  const truncatedSuffix = truncated ? " " + editor.t("panel.limited") : "";
-  const matchStats = totalMatches > 0
-    ? "  " + editor.t("panel.match_stats", { count: String(totalMatches), files: String(fileCount) }) + truncatedSuffix
-    : (searchPattern ? "  " + editor.t("panel.no_matches") : "");
-
-  // Build the matchStats inline-overlay-styled Raw cell for the row.
-  // Truncated case keeps the warning-color tail; otherwise the whole
-  // stats string uses the ok/dim color depending on result presence.
-  const matchStatsEntries: TextPropertyEntry[] = [];
-  if (matchStats.length > 0) {
-    const overlays: InlineOverlay[] = [];
-    if (truncated && totalMatches > 0) {
-      const statsWithoutSuffix = "  " + editor.t("panel.match_stats", {
-        count: String(totalMatches),
-        files: String(fileCount),
-      });
-      const countEnd = byteLen(statsWithoutSuffix);
-      overlays.push({ start: 0, end: countEnd, style: { fg: C.statusOk } });
-      overlays.push({
-        start: countEnd,
-        end: countEnd + byteLen(truncatedSuffix),
-        style: { fg: [255, 180, 50] as RGB, bold: true },
-      });
-    } else {
-      overlays.push({
-        start: 0,
-        end: byteLen(matchStats),
-        style: { fg: totalMatches > 0 ? C.statusOk : C.statusDim },
-      });
-    }
-    matchStatsEntries.push({ text: matchStats, inlineOverlays: overlays });
-  }
-
   return row(
     spacer(1),
     textInput(searchVal, {
@@ -435,7 +541,7 @@ function buildLine1Spec(): WidgetSpec {
       fieldWidth: 25,
       key: "replaceField",
     }),
-    raw(matchStatsEntries),
+    raw(buildMatchStatsEntries(), "matchStats"),
   );
 }
 
@@ -490,7 +596,20 @@ function renderFlatItemEntry(item: FlatItem, W: number): TextPropertyEntry {
   const group = panel.fileGroups[item.fileIndex];
   const result = group.matches[item.matchIndex!];
   const location = `${group.relPath}:${result.match.line}`;
-  const context = result.match.context.trim();
+  // Hard-cap the context length BEFORE any per-codepoint work below.
+  // Minified CSS / JSON / single-line generated files routinely have
+  // match context strings 5 000-50 000 chars long. The downstream
+  // `truncate()` does `for (const c of s)` (per-codepoint iteration
+  // + O(N²) string concatenation in QuickJS); at 5 000 chars and 50
+  // items per flush that adds up to several hundred ms of JS work
+  // per pump iteration, blocking Tab and other queued requests.
+  // A panel viewport is at most a few hundred chars wide, so anything
+  // past ~512 chars is invisible anyway.
+  const CONTEXT_HARD_CAP = 512;
+  const rawCtx = result.match.context;
+  const context = (rawCtx.length > CONTEXT_HARD_CAP
+    ? rawCtx.slice(0, CONTEXT_HARD_CAP)
+    : rawCtx).trim();
   // Host prefix consumes:
   //   indent (depth=1) = 2
   //   leaf-alignment   = 2 (in lieu of disclosure glyph)
@@ -527,6 +646,35 @@ function renderFlatItemEntry(item: FlatItem, W: number): TextPropertyEntry {
   });
 }
 
+// Convert a slice of `FlatItem`s into the corresponding TreeNodes.
+// Pulled out of `buildMatchListSpec` so the streaming path can use it
+// to build deltas for `appendTreeNodes` — it must produce nodes
+// identical to the full-spec rebuild for the same items, so
+// auto-expand of first-seen file rows happens here.
+function flatItemsToTreeNodes(
+  flatItems: FlatItem[],
+  itemKeys: string[],
+  W: number,
+): TreeNode[] {
+  return flatItems.map((item, i) => {
+    const entry = renderFlatItemEntry(item, W);
+    if (item.type === "file") {
+      const k = itemKeys[i];
+      if (!panel!.knownFileKeys.has(k)) {
+        panel!.knownFileKeys.add(k);
+        panel!.expandedFileKeys.add(k);
+      }
+      // File-row checkbox derives from children: checked iff every
+      // match in this file is selected.
+      const fileChecked = panel!.fileGroups[item.fileIndex].matches.every(m => m.selected);
+      return treeNode(entry, { depth: 0, hasChildren: true, checked: fileChecked });
+    }
+    const matchSelected = panel!.fileGroups[item.fileIndex]
+      .matches[item.matchIndex!].selected;
+    return treeNode(entry, { depth: 1, hasChildren: false, checked: matchSelected });
+  });
+}
+
 // Build the typed spec for the matches body — either a Tree widget
 // (when there are matches) or a Raw cell with the empty/prompt
 // message. The Tree widget owns scroll, selection styling, click
@@ -538,52 +686,39 @@ function buildMatchListSpec(): WidgetSpec {
   const W = Math.max(MIN_WIDTH, panel.viewportWidth - 2);
   const totalMatches = panel.searchResults.length;
 
-  if (panel.searchPattern && totalMatches === 0) {
-    return raw([{
-      text: padStr("  " + editor.t("panel.no_matches"), W),
+  // Empty-state branches: pristine / searching / no-results /
+  // pattern-set-but-no-search-yet. See §17 of
+  // docs/internal/search-replace-scope-replan-on-widgets.md.
+  //
+  // When the pattern is mutated while a previous search's results are
+  // still in panel.searchResults, render the stale results (fall
+  // through to the Tree branch below) until the next search
+  // completes — dropping back to "Type a search pattern above"
+  // mid-edit feels jumpy.
+  const emptyState = (key: string) =>
+    raw([{
+      text: padStr("  " + editor.t(key), W),
       properties: { type: "empty" },
       style: { fg: C.dim },
     }]);
-  }
   if (!panel.searchPattern) {
-    return raw([{
-      text: padStr("  " + editor.t("panel.type_pattern"), W),
-      properties: { type: "empty" },
-      style: { fg: C.dim },
-    }]);
+    return emptyState("panel.type_pattern");
+  }
+  if (panel.busy && totalMatches === 0) {
+    return emptyState("panel.searching");
+  }
+  if (totalMatches === 0 && panel.searchPerformed && !panel.busy) {
+    return emptyState("panel.no_matches");
+  }
+  if (totalMatches === 0) {
+    // Pattern in flight but no search has run yet (and no cached
+    // results). Same friendly hint as pristine.
+    return emptyState("panel.type_pattern");
   }
 
   const flatItems = buildFlatItems();
   const itemKeys = flatItems.map(flatItemKey);
-  // Track the file-row keys present in this render. Newly-discovered
-  // file groups are auto-added to `expandedFileKeys` (default state =
-  // expanded). Files the user has collapsed remain absent from the
-  // set; we never re-add a key that's already known but currently
-  // collapsed, since `clearedThisRender` would tag them as "first
-  // time seen". Tracking is via the per-search reset in
-  // `performSearch`: at the start of a search the set is empty, so
-  // every file is auto-added on its first appearance, then user
-  // collapse events remove them.
-  const nodes: TreeNode[] = flatItems.map((item, i) => {
-    const entry = renderFlatItemEntry(item, W);
-    if (item.type === "file") {
-      const k = itemKeys[i];
-      if (!panel!.knownFileKeys.has(k)) {
-        panel!.knownFileKeys.add(k);
-        panel!.expandedFileKeys.add(k);
-      }
-      // File-row checkbox derives from children: checked iff every
-      // match in this file is selected. Mixed (some selected, some
-      // not) renders as `[ ]` for v1 — adding a tristate `[~]`
-      // glyph is a future host-side option but not needed to wire
-      // the toggle path end-to-end.
-      const fileChecked = panel!.fileGroups[item.fileIndex].matches.every(m => m.selected);
-      return treeNode(entry, { depth: 0, hasChildren: true, checked: fileChecked });
-    }
-    const matchSelected = panel!.fileGroups[item.fileIndex]
-      .matches[item.matchIndex!].selected;
-    return treeNode(entry, { depth: 1, hasChildren: false, checked: matchSelected });
-  });
+  const nodes = flatItemsToTreeNodes(flatItems, itemKeys, W);
   const selectedIndex = panel.focusPanel === "matches" ? panel.matchIndex : -1;
   // Tree visible rows = panel viewport height minus the chrome
   // (line 1 + options row + separator + footer = 4 rows) — same
@@ -796,7 +931,8 @@ function updatePanelContent(): void {
     col(
       buildLine1Spec(),
       buildOptionsRowSpec(),
-      raw(buildPanelEntries("postOptions")),
+      buildScopeRowSpec(),
+      raw(buildPanelEntries("postOptions"), "separator"),
       buildMatchListSpec(),
       hintBar(buildHelpHints()),
     ),
@@ -828,6 +964,50 @@ let activeSearchHandle: SearchHandle | null = null;
 /** Pump cadence between successive `take()` drains (ms). The host writes
  * matches at full speed; this knob bounds the UI rebuild rate. */
 const SEARCH_PUMP_INTERVAL_MS = 50;
+/** Number of `buildFlatItems()` entries the streaming path has already
+ *  pushed to the host via `appendTreeNodes`. Zero means "no streaming
+ *  append has happened for the current search"; the first batch of
+ *  results will do a full `updatePanelContent()` instead so the Tree
+ *  exists for subsequent appends. Reset at the start of each search
+ *  and after `batch.done` (which forces a full re-emit). */
+let lastStreamingFlatCount = 0;
+
+/** Absolute-path → index-into-`panel.fileGroups`, maintained while a
+ *  search is streaming so each new match locates its file group in
+ *  O(1) instead of triggering a full `buildFileGroups(allResults)`
+ *  rebuild (which is O(N) per batch and pins the JS event loop on
+ *  large result sets). Cleared at the start of each search. */
+let streamingFileIndexByPath: Map<string, number> | null = null;
+
+/** Carryover queue: matches the host handed us in a `take()` but that
+ *  we haven't processed yet because the batch was too big to drain in
+ *  a single pump iteration. Drained CHUNK at a time inside the pump
+ *  loop; `take()` is only re-called once this is empty so we don't
+ *  flood the queue.  Reset at the start of each search. */
+let pendingMatches: GrepMatch[] = [];
+
+/** Pending tree-append delta that hasn't been flushed to the host yet.
+ *  Each pump chunk pushes its `FlatItem[]` here; the loop coalesces
+ *  several chunks worth before firing one `appendTreeNodes` IPC, so
+ *  the host's main thread isn't pinned servicing ~20 ms IPCs back to
+ *  back during a long streaming search. */
+let pendingTreeDeltaItems: FlatItem[] = [];
+/** Parallel pending list of new file-row keys whose expansion state
+ *  must be pushed to the host on the next flush. */
+let pendingNewExpandedKeys: string[] = [];
+/** Wall-clock ms of the last UI flush (the last appendTreeNodes IPC).
+ *  Compared against UI_FLUSH_INTERVAL_MS to decide when to flush. */
+let lastUiFlush = 0;
+/** Don't flush more often than this. */
+const UI_FLUSH_INTERVAL_MS = 80;
+/** Hard cap on each `appendTreeNodes` flush payload. Each TreeNode in
+ *  the payload costs ~60 µs in `js_to_json` + `serde_json::from_value`
+ *  on the JS thread (measured: AppendTreeNodes(1296) = 88 ms).
+ *  Larger payloads → longer per-iteration JS block → user input
+ *  (Tab, typed char, Esc) waits in the plugin thread's request
+ *  channel. Keeping the cap at ~100 keeps each flush ≤ 10 ms so
+ *  queued Tab requests can interleave between pump iterations. */
+const UI_FLUSH_MAX_DELTA = 100;
 
 /**
  * Perform a streaming search using a pull-based handle. The host writes
@@ -846,6 +1026,21 @@ async function performSearch(pattern: string, silent?: boolean): Promise<SearchR
   // result set isn't meaningful for the new one.
   panel.expandedFileKeys.clear();
   panel.knownFileKeys.clear();
+  // New search → reset the streaming-append checkpoint. The first
+  // batch of results will trigger a full `updatePanelContent()`
+  // (mounting the empty Tree); subsequent batches append deltas to
+  // that mounted Tree.
+  lastStreamingFlatCount = 0;
+  streamingFileIndexByPath = new Map();
+  pendingMatches = [];
+  pendingTreeDeltaItems = [];
+  pendingNewExpandedKeys = [];
+  lastUiFlush = 0;
+  // Reset accumulating state so a re-search (debounce from typing,
+  // toggle flip, scope change) starts from empty rather than
+  // appending to the previous run's results.
+  panel.searchResults = [];
+  panel.fileGroups = [];
 
   // Cancel any in-flight search before kicking off a new one. Without
   // this the prior search would keep walking the project until it
@@ -878,30 +1073,168 @@ async function performSearch(pattern: string, silent?: boolean): Promise<SearchR
         return allResults;
       }
 
-      const batch = handle.take();
-      if (batch.matches.length > 0) {
-        for (const m of batch.matches) {
-          allResults.push({ match: m, selected: true });
+      // Drain matches in chunks of at most CHUNK per pump iteration.
+      // `pendingMatches` accumulates anything the host gave us that we
+      // haven't processed yet. This caps the per-iteration synchronous
+      // JS work at O(CHUNK) so the event loop yields back to the host
+      // promptly — without this, a single batch of 3000+ matches takes
+      // ~700ms of JS time and queues every user keypress (Tab, typed
+      // chars, Esc) for the duration of the search.
+      //
+      // Only call `handle.take()` when our queue is empty, so the host
+      // doesn't keep us flooded; the producer pauses when the take()
+      // returns nothing left to drain.
+      let batchDone = false;
+      let batchTruncated = false;
+      let batchError: string | null = null;
+      if (pendingMatches.length === 0) {
+        const batch = handle.take();
+        batchDone = batch.done;
+        batchTruncated = batch.truncated;
+        batchError = batch.error ?? null;
+        for (const m of batch.matches) pendingMatches.push(m);
+      }
+      // Hard cap on per-iteration work. Each match in the chunk turns
+      // into a TreeNode in the `appendTreeNodes` flush, and each
+      // TreeNode costs ~60 µs in `js_to_json` + `from_value` on the
+      // JS thread. Keeping the chunk small means each pump iteration
+      // stays ≤ ~10 ms — short enough that queued Tab/typed-char
+      // requests interleave smoothly between iterations.
+      const CHUNK = 80;
+      const chunkSize = Math.min(CHUNK, pendingMatches.length);
+      const chunk = pendingMatches.splice(0, chunkSize);
+      const moreInQueue = pendingMatches.length > 0;
+      const deltaItems: FlatItem[] = [];
+      const newExpandedKeys: string[] = []; // file rows added this batch
+      for (const m of chunk) {
+        // §1 scope filter: when scope is "current file only", drop
+        // matches from any other path. Done client-side because the
+        // host grep API is project-wide. Empty sourceBufferPath
+        // (unsaved buffer) filters everything out by design.
+        if (!panel.allFiles && m.file !== panel.sourceBufferPath) continue;
+        const result: SearchResult = { match: m, selected: true };
+        allResults.push(result);
+        let fileIdx = streamingFileIndexByPath?.get(m.file);
+        if (fileIdx === undefined) {
+          fileIdx = panel.fileGroups.length;
+          streamingFileIndexByPath?.set(m.file, fileIdx);
+          panel.fileGroups.push({
+            relPath: getRelativePath(m.file),
+            absPath: m.file,
+            expanded: true,
+            matches: [],
+          });
+          deltaItems.push({ type: "file", fileIndex: fileIdx });
+          const fileKey = `file:${fileIdx}`;
+          panel.expandedFileKeys.add(fileKey);
+          panel.knownFileKeys.add(fileKey);
+          newExpandedKeys.push(fileKey);
         }
-        panel.searchResults = allResults;
-        panel.fileGroups = buildFileGroups(allResults);
-        updatePanelContent();
-      } else if (batch.done) {
-        // Final iteration with no new matches still needs a UI flush
-        // when the previous tick ended on a non-empty batch but didn't
-        // know it was the last one.
-        panel.searchResults = allResults;
-        panel.fileGroups = buildFileGroups(allResults);
+        const matchIdx = panel.fileGroups[fileIdx].matches.length;
+        panel.fileGroups[fileIdx].matches.push(result);
+        deltaItems.push({ type: "match", fileIndex: fileIdx, matchIndex: matchIdx });
+      }
+      panel.searchResults = allResults;
+      // Coalesce the per-chunk delta into a pending buffer. Each
+      // `appendTreeNodes` IPC costs ~20 ms on the host (spec mutation
+      // + Tree-visible-rows recompute + virtual-buffer repaint).
+      // Flushing every 250-match chunk means 20+ IPCs over a 5 000-
+      // match search — that pile of host main-thread work is exactly
+      // when queued Tab / typed-key events sit waiting. Flush only
+      // every UI_FLUSH_INTERVAL_MS so the user sees the result list
+      // grow at a steady ~5 Hz while leaving the host free to dispatch
+      // input events between flushes.
+      for (const it of deltaItems) pendingTreeDeltaItems.push(it);
+      for (const k of newExpandedKeys) pendingNewExpandedKeys.push(k);
+      const nowMs = Date.now();
+      const producerFinished = batchDone && pendingMatches.length === 0;
+      const dueToFlush =
+        producerFinished ||
+        pendingTreeDeltaItems.length >= UI_FLUSH_MAX_DELTA ||
+        nowMs - lastUiFlush >= UI_FLUSH_INTERVAL_MS;
+      if (
+        dueToFlush &&
+        pendingTreeDeltaItems.length > 0 &&
+        panel.widgetPanel &&
+        lastStreamingFlatCount > 0
+      ) {
+        const W = Math.max(MIN_WIDTH, panel.viewportWidth - 2);
+        const flushed = pendingTreeDeltaItems;
+        const flushedNewExp = pendingNewExpandedKeys;
+        pendingTreeDeltaItems = [];
+        pendingNewExpandedKeys = [];
+        const newItemKeys = flushed.map(flatItemKey);
+        const newNodes = flatItemsToTreeNodes(flushed, newItemKeys, W);
+        panel.widgetPanel.appendTreeNodes("matchTree", newNodes, newItemKeys);
+        lastStreamingFlatCount += flushed.length;
+        lastUiFlush = nowMs;
+        if (flushedNewExp.length > 0) {
+          panel.widgetPanel.setExpandedKeys(
+            "matchTree",
+            [...panel.expandedFileKeys],
+          );
+        }
+      } else if (lastStreamingFlatCount === 0 && panel.fileGroups.length > 0) {
+        // First time we have any results — mount the Tree via a full
+        // panel update. Subsequent batches use the cheap append path.
+        // Also drain the pending buffer into the spec since
+        // updatePanelContent rebuilds from `panel.fileGroups` directly.
+        pendingTreeDeltaItems = [];
+        pendingNewExpandedKeys = [];
         updatePanelContent();
+        lastStreamingFlatCount = panel.fileGroups.length + panel.searchResults.length;
+        lastUiFlush = nowMs;
+      }
+      if (producerFinished) {
+        // Streaming finished. The tree is already current in the host
+        // via the per-batch `appendTreeNodes` mutations — its nodes
+        // don't need refreshing. The only state that drifted is the
+        // small chrome strings: the matchStats label next to the
+        // input fields, and the "Matches (N in M files)" header in
+        // the separator. Update them in place via `setRawEntries`
+        // (a few-hundred-byte mutation) instead of re-emitting the
+        // full panel spec — the latter would force `js_to_json` over
+        // every TreeNode (~447 bytes × 5 000 nodes = 2.2 MB) and
+        // block the JS thread for ~1 second, exactly when user input
+        // piles up unread in the request channel. See the
+        // RESOLVE_CB_DONE dur_us=1095122 case in the perf trace.
+        if (panel.widgetPanel) {
+          if (panel.fileGroups.length === 0) {
+            // Special case: 0 matches. The matches body is an
+            // empty-state `raw()`, not a `tree()` — we have to swap
+            // widget kinds, which `setRawEntries` alone can't do.
+            // The full re-emit here is cheap because the tree is
+            // empty (no per-node serialization cost).
+            updatePanelContent();
+          } else {
+            panel.widgetPanel.setRawEntries("matchStats", buildMatchStatsEntries());
+            panel.widgetPanel.setRawEntries("separator", buildPanelEntries("postOptions"));
+          }
+        }
+        lastStreamingFlatCount = 0;
+        pendingTreeDeltaItems = [];
+        pendingNewExpandedKeys = [];
+      }
+      // Also refresh the matchStats label on every streaming flush so
+      // the count updates in real time as results stream in.
+      if (!producerFinished && dueToFlush && panel.widgetPanel) {
+        panel.widgetPanel.setRawEntries("matchStats", buildMatchStatsEntries());
+        panel.widgetPanel.setRawEntries("separator", buildPanelEntries("postOptions"));
       }
 
-      if (batch.done) {
-        truncated = batch.truncated;
-        producerError = batch.error ?? null;
+      if (producerFinished) {
+        truncated = batchTruncated;
+        producerError = batchError;
         break;
       }
 
-      await editor.delay(SEARCH_PUMP_INTERVAL_MS);
+      // Yield to the JS event loop between chunks. `delay(0)` is
+      // enough — it lets queued plugin handlers (Tab, typed input,
+      // Esc) run between our streaming work. When there's no
+      // carryover, wait the usual pump interval so we don't hot-loop
+      // on `handle.take()`.
+      const yieldMs = moreInQueue ? 0 : SEARCH_PUMP_INTERVAL_MS;
+      await editor.delay(yieldMs);
     }
 
     if (activeSearchHandle === handle) {
@@ -939,30 +1272,40 @@ async function performSearch(pattern: string, silent?: boolean): Promise<SearchR
 // Panel lifecycle
 // =============================================================================
 
-async function openPanel(): Promise<void> {
+async function openPanel(opts?: { allFiles?: boolean }): Promise<void> {
   // Try to pre-fill search from editor selection
   let prefill = "";
+  let sourceBufferPath = "";
   try {
+    const activeId = editor.getActiveBufferId();
+    sourceBufferPath = editor.getBufferPath(activeId) || "";
     const cursor = editor.getPrimaryCursor();
     if (cursor && cursor.selection) {
       const start = Math.min(cursor.selection.start, cursor.selection.end);
       const end = Math.max(cursor.selection.start, cursor.selection.end);
       if (end - start > 0 && end - start < 200) {
-        const bufferId = editor.getActiveBufferId();
-        const text = await editor.getBufferText(bufferId, start, end);
+        const text = await editor.getBufferText(activeId, start, end);
         if (text && !text.includes("\n")) {
           prefill = text;
         }
       }
     }
-  } catch (_e) { /* no selection */ }
+  } catch (_e) { /* no selection / no buffer */ }
+
+  const allFiles = opts?.allFiles ?? true;
+  const sourceBufferRelPath = sourceBufferPath ? getRelativePath(sourceBufferPath) : "";
 
   if (panel) {
     panel.focusPanel = "query";
     panel.queryField = "search";
     if (prefill) panel.searchPattern = prefill;
     panel.cursorPos = panel.searchPattern.length;
+    // Re-opening from a different file/scope refreshes scope context.
+    panel.allFiles = allFiles;
+    panel.sourceBufferPath = sourceBufferPath;
+    panel.sourceBufferRelPath = sourceBufferRelPath;
     updatePanelContent();
+    if (panel.searchPattern) rerunSearchDebounced();
     return;
   }
 
@@ -983,8 +1326,12 @@ async function openPanel(): Promise<void> {
     caseSensitive: false,
     useRegex: false,
     wholeWords: false,
+    allFiles,
+    sourceBufferPath,
+    sourceBufferRelPath,
     viewportWidth: DEFAULT_WIDTH,
     busy: false,
+    searchPerformed: false,
     truncated: false,
     cursorPos: prefill.length,
     scrollOffset: 0,
@@ -1075,19 +1422,42 @@ async function executeReplacements(results?: SearchResult[]): Promise<string> {
 
 async function rerunSearch(): Promise<void> {
   if (!panel || !panel.searchPattern) return;
-  if (panel.busy) return; // guard against re-entrant search
+  // No `panel.busy` early-return: if a search is already running for
+  // an older pattern (e.g. user typed "pr" then "proj"), we want the
+  // newer search to start NOW, not after the old one finishes
+  // walking the project. `performSearch` increments
+  // `currentSearchGeneration` and cancels the prior handle; the older
+  // in-flight `performSearch` sees the gen mismatch on its next
+  // pump tick and bails out without writing to panel state.
+  searchDebounceGeneration++;
+  // Capture the generation this rerunSearch will own once performSearch
+  // increments it. If a newer rerunSearch slots in while we're awaiting,
+  // currentSearchGeneration moves past `myGen` and we know not to
+  // finalize busy/searchPerformed for this stale invocation.
+  const myGen = currentSearchGeneration + 1;
   panel.truncated = false;
   panel.busy = true;
   panel.matchIndex = 0;
   panel.scrollOffset = 0;
-  const results = await performSearch(panel.searchPattern);
-  // performSearch already updates panel.searchResults/fileGroups incrementally;
-  // just ensure final state is consistent
-  if (panel) {
-    panel.searchResults = results;
-    panel.fileGroups = buildFileGroups(results);
+  await performSearch(panel.searchPattern);
+  // performSearch maintains panel.searchResults / panel.fileGroups
+  // incrementally during streaming and pushes matchStats / separator
+  // updates via cheap targeted mutations on batch.done — no full
+  // spec re-emit needed here. Only finalize busy + searchPerformed
+  // if we are still the latest search; the busy flip drives the
+  // "No matches" empty-state branch in `buildMatchListSpec`, so
+  // when totalMatches===0 we also need to refresh the matches Raw
+  // (a tiny mutation) so the user sees the empty-state label.
+  if (panel && currentSearchGeneration === myGen) {
     panel.busy = false;
-    updatePanelContent();
+    panel.searchPerformed = true;
+    // Only one tiny mutation needed: refresh matchStats since it
+    // depends on the busy flag and searchPerformed (showing
+    // "No matches" vs "Searching…"). The tree's nodes already
+    // reflect the final state — no full re-emit needed.
+    if (panel.widgetPanel) {
+      panel.widgetPanel.setRawEntries("matchStats", buildMatchStatsEntries());
+    }
   }
 }
 
@@ -1104,6 +1474,7 @@ function rerunSearchDebounced(): void {
 async function rerunSearchQuiet(): Promise<void> {
   if (!panel || !panel.searchPattern) return;
   if (panel.busy) return;
+  searchDebounceGeneration++;
   panel.busy = true;
   const results = await performSearch(panel.searchPattern, true);
   if (panel) {
@@ -1112,6 +1483,7 @@ async function rerunSearchQuiet(): Promise<void> {
     panel.matchIndex = 0;
     panel.scrollOffset = 0;
     panel.busy = false;
+    panel.searchPerformed = true;
     updatePanelContent();
   }
 }
@@ -1136,8 +1508,63 @@ registerHandler("search_replace_home",      () => dispatch(widgetKey("Home")));
 registerHandler("search_replace_end",       () => dispatch(widgetKey("End")));
 registerHandler("search_replace_nav_left",  () => dispatch(widgetKey("Left")));
 registerHandler("search_replace_nav_right", () => dispatch(widgetKey("Right")));
-registerHandler("search_replace_nav_up",    () => dispatch(widgetKey("Up")));
-registerHandler("search_replace_nav_down",  () => dispatch(widgetKey("Down")));
+/** Apply a stored history entry to the search field. Mutates the
+ *  widget's value via setValue so the host instance state stays in
+ *  sync with the plugin's panel.searchPattern, and triggers a
+ *  debounced re-search. See §11. */
+function applyHistoryEntry(text: string): void {
+  if (!panel || !panel.widgetPanel) return;
+  panel.searchPattern = text;
+  panel.cursorPos = text.length;
+  panel.searchPerformed = false;
+  panel.widgetPanel.setValue("searchField", text, byteLen(text));
+  rerunSearchDebounced();
+}
+
+/** Whether Up/Down should be intercepted for history walk (instead of
+ *  being passed to the focused widget). True only when the most recent
+ *  widget_event indicated focus was on the search field. */
+function shouldInterceptForHistory(): boolean {
+  return lastFocusedWidget === "searchField" || lastFocusedWidget === null;
+}
+
+registerHandler("search_replace_nav_up", () => {
+  if (!panel) return;
+  if (shouldInterceptForHistory()) {
+    if (searchHistory.length === 0) return;
+    if (historyIndex < 0) {
+      // Entering history walk — snapshot what the user had typed so
+      // a Down past the most recent entry restores it.
+      historySavedPattern = panel.searchPattern;
+      historyIndex = 0;
+    } else if (historyIndex < searchHistory.length - 1) {
+      historyIndex += 1;
+    } else {
+      return; // already at the oldest entry
+    }
+    applyHistoryEntry(searchHistory[historyIndex]);
+    return;
+  }
+  dispatch(widgetKey("Up"));
+});
+registerHandler("search_replace_nav_down", () => {
+  if (!panel) return;
+  if (shouldInterceptForHistory() && historyIndex >= 0) {
+    if (historyIndex > 0) {
+      historyIndex -= 1;
+      applyHistoryEntry(searchHistory[historyIndex]);
+      return;
+    }
+    // Down past the most recent entry → exit history walk and restore
+    // whatever the user had typed before they hit Up.
+    historyIndex = -1;
+    const restore = historySavedPattern ?? "";
+    historySavedPattern = null;
+    applyHistoryEntry(restore);
+    return;
+  }
+  dispatch(widgetKey("Down"));
+});
 registerHandler("search_replace_nav_page_up",   () => dispatch(widgetKey("PageUp")));
 registerHandler("search_replace_nav_page_down", () => dispatch(widgetKey("PageDown")));
 
@@ -1213,13 +1640,49 @@ registerHandler("search_replace_replace_scoped", search_replace_replace_scoped);
 registerHandler("search_replace_enter", () => dispatch(widgetKey("Enter")));
 registerHandler("search_replace_space", () => dispatch(widgetKey("Space")));
 
+/** Lock against re-entrant Replace All / Replace Scoped. Set as soon
+ *  as doReplaceAll/doReplaceScoped enters and cleared in a try/finally
+ *  around the whole flow. Without this, a user mashing Alt+Enter
+ *  during a streaming search produces N stacked confirmation prompts
+ *  once the search finishes — the host queues each keystroke and
+ *  drains them all when the JS event loop frees up; by then
+ *  `panel.busy` is false so the busy guard doesn't fire. */
+let replaceInProgress = false;
+
 async function doReplaceAll(): Promise<void> {
-  if (!panel || panel.busy) return;
+  if (!panel) return;
+  if (panel.busy) {
+    // Search is still streaming. Don't block silently — tell the user
+    // to wait, and don't queue the replace. (The host's event
+    // dispatcher would otherwise hold the keystroke and run it when
+    // the pump finishes, which feels like an unexplained delay.)
+    editor.setStatus(editor.t("status.replace_wait_for_search"));
+    return;
+  }
+  if (replaceInProgress) {
+    // First Alt+Enter is already showing its prompt or running the
+    // rewrites. Drop the duplicate so we don't stack prompts.
+    return;
+  }
+  replaceInProgress = true;
+  try {
+    await doReplaceAllInner();
+  } finally {
+    replaceInProgress = false;
+  }
+}
+
+async function doReplaceAllInner(): Promise<void> {
+  if (!panel) return;
   const selected = panel.searchResults.filter(r => r.selected);
   if (selected.length === 0) {
     editor.setStatus(editor.t("status.no_items_selected"));
     return;
   }
+  // The user committed to this pattern by triggering Replace All —
+  // a clear "settle" signal, so commit it to history now even if the
+  // 2s scheduleHistoryPush hasn't fired yet.
+  if (historyIndex < 0) historyPush(panel.searchPattern);
   // Confirm before applying.  Replacements write to disk immediately; Undo
   // only covers files that remain open in this session (see bug #1 report).
   const fileCount = new Set(selected.map(r => r.match.file)).size;
@@ -1251,7 +1714,22 @@ async function doReplaceAll(): Promise<void> {
 }
 
 async function doReplaceScoped(): Promise<void> {
-  if (!panel || panel.busy || panel.focusPanel !== "matches") return;
+  if (!panel || panel.focusPanel !== "matches") return;
+  if (panel.busy) {
+    editor.setStatus(editor.t("status.replace_wait_for_search"));
+    return;
+  }
+  if (replaceInProgress) return;
+  replaceInProgress = true;
+  try {
+    await doReplaceScopedInner();
+  } finally {
+    replaceInProgress = false;
+  }
+}
+
+async function doReplaceScopedInner(): Promise<void> {
+  if (!panel) return;
   const flat = buildFlatItems();
   const item = flat[panel.matchIndex];
   if (!item) return;
@@ -1263,6 +1741,8 @@ async function doReplaceScoped(): Promise<void> {
     const result = panel.fileGroups[item.fileIndex].matches[item.matchIndex!];
     if (result.selected) toReplace = [result];
   }
+  // Same as doReplaceAll: explicit commit, push immediately.
+  if (historyIndex < 0) historyPush(panel.searchPattern);
 
   if (toReplace.length === 0) {
     editor.setStatus(editor.t("status.no_selected"));
@@ -1296,12 +1776,30 @@ async function doReplaceScoped(): Promise<void> {
 
 function search_replace_close(): void {
   if (!panel) return;
+  // If the user actually ran a search to completion with this
+  // pattern (results were observed) and isn't walking history,
+  // treat panel-close as a settle and commit to history. The
+  // searchPerformed guard avoids capturing half-typed patterns
+  // that never made it past the empty-state.
+  if (
+    historyIndex < 0
+    && panel.searchPattern
+    && panel.searchPerformed
+  ) {
+    historyPush(panel.searchPattern);
+  }
+  const sourceSplitId = panel.sourceSplitId;
   panel.widgetPanel?.unmount();
   editor.closeBuffer(panel.resultsBufferId);
   if (panel.resultsSplitId !== panel.sourceSplitId) {
     editor.closeSplit(panel.resultsSplitId);
   }
   panel = null;
+  // Restore focus to the split the user came from. Without this,
+  // `getActiveBufferId()` on the next invocation can return the
+  // utility dock's leftover buffer, and the §1 current-file scope
+  // shows "(unsaved buffer)" instead of the real filename.
+  editor.focusSplit(sourceSplitId);
   editor.setStatus(editor.t("status.closed"));
 }
 registerHandler("search_replace_close", search_replace_close);
@@ -1315,6 +1813,14 @@ function start_search_replace(): void {
 }
 registerHandler("start_search_replace", start_search_replace);
 
+// §1: open the panel with scope already restricted to the active
+// buffer. Useful when the user wants single-file search/replace from
+// the keymap without flipping the toggle by hand.
+function start_search_replace_in_buffer(): void {
+  openPanel({ allFiles: false });
+}
+registerHandler("start_search_replace_in_buffer", start_search_replace_in_buffer);
+
 // =============================================================================
 // Event handlers (resize updates width)
 // =============================================================================
@@ -1367,6 +1873,15 @@ editor.on("buffer_closed", (args) => {
 editor.on("widget_event", (args) => {
   if (!panel || args.panel_id !== panel.widgetPanel?.id()) return;
 
+  // Track most-recent focused widget so Up/Down can decide whether to
+  // walk search history (search field) or pass through to the widget
+  // runtime (matches tree, toggles, button). The widget runtime
+  // doesn't expose focus to the plugin directly; this best-effort
+  // proxy is good enough for the history-walk gesture. See §11.
+  if (typeof args.widget_key === "string" && args.widget_key.length > 0) {
+    lastFocusedWidget = args.widget_key;
+  }
+
   // `change` — fired for TextInput edits (Backspace, Delete,
   // arrows, Home/End, mode_text_input). Payload carries the new
   // value and cursor byte offset. The host already updated the
@@ -1384,9 +1899,28 @@ editor.on("widget_event", (args) => {
       ? payload.cursorByte
       : payload.value.length;
     if (args.widget_key === "searchField") {
-      panel.searchPattern = payload.value;
+      if (panel.searchPattern !== payload.value) {
+        // Pattern mutated by the user; cached "no matches" / result
+        // set no longer reflects this query. See §17.
+        panel.searchPerformed = false;
+        // User-driven typing exits any in-flight history walk so a
+        // subsequent Up doesn't snap back to a history entry under
+        // the cursor. See §11.
+        historyIndex = -1;
+        historySavedPattern = null;
+        panel.searchPattern = payload.value;
+        panel.cursorPos = byteToCharOffset(payload.value, cursorByte);
+        updatePanelContent();
+        rerunSearchDebounced();
+        scheduleHistoryPush(payload.value);
+        return;
+      }
+      // Cursor-only update (Left/Right arrows, Home/End, click reposition):
+      // the search field's text is unchanged, so don't re-run the search
+      // or perturb the history-settle timer. Just sync the plugin's
+      // cached cursor position so the next render shows the cursor in
+      // the right place.
       panel.cursorPos = byteToCharOffset(payload.value, cursorByte);
-      rerunSearchDebounced();
     } else if (args.widget_key === "replaceField") {
       panel.replaceText = payload.value;
       panel.cursorPos = byteToCharOffset(payload.value, cursorByte);
@@ -1449,6 +1983,10 @@ editor.on("widget_event", (args) => {
           [...panel.expandedFileKeys],
         );
       } else {
+        // Opening a result is a "this is the search I wanted" signal —
+        // commit it to history immediately, regardless of how long
+        // the pattern has been stable. See §11 follow-up.
+        if (historyIndex < 0) historyPush(panel.searchPattern);
         const group = panel.fileGroups[item.fileIndex];
         const result = group.matches[item.matchIndex!];
         editor.openFileInSplit(
@@ -1474,6 +2012,18 @@ editor.on("widget_event", (args) => {
       ?.checked;
     if (typeof newChecked !== "boolean") return;
     switch (args.widget_key) {
+      case "allFiles":
+        // Scope flip (§1). Push the new checked state back to the
+        // widget instance and rebuild the whole spec so the scope
+        // row + Replace All button label switch in lock-step. Then
+        // re-run the search so the results pane reflects the new
+        // scope (the search itself is project-wide; filtering
+        // happens in performSearch).
+        panel.allFiles = newChecked;
+        panel.widgetPanel?.setChecked("allFiles", newChecked);
+        updatePanelContent();
+        rerunSearchDebounced();
+        break;
       case "case":
         panel.caseSensitive = newChecked;
         panel.widgetPanel?.setChecked("case", newChecked);
@@ -1564,4 +2114,11 @@ editor.registerCommand(
   null
 );
 
+editor.registerCommand(
+  "%cmd.search_replace_in_buffer",
+  "%cmd.search_replace_in_buffer_desc",
+  "start_search_replace_in_buffer",
+  null
+);
+
 editor.debug("Search & Replace plugin loaded");