@fresh-editor/fresh-editor 0.3.4 → 0.3.6

package/plugins/search_replace.ts

@@ -1,4 +1,27 @@
 /// <reference path="./lib/fresh.d.ts" />
+import {
+  button,
+  col,
+  flexSpacer,
+  hintBar,
+  key as widgetKey,
+  parseHintString,
+  raw,
+  row,
+  spacer,
+  type StyledSegment,
+  styledRow,
+  textInput,
+  textInputChar,
+  toggle,
+  tree,
+  treeNode,
+  type TreeNode,
+  type WidgetAction,
+  WidgetPanel,
+  type WidgetSpec,
+} from "./lib/widgets.ts";
+
 const editor = getEditor();
 
 /**
@@ -54,6 +77,28 @@ interface PanelState {
   cursorPos: number;
   // Virtual scroll offset for matches tree
   scrollOffset: number;
+  // Per-file expansion state mirrored from the Tree widget's host
+  // instance state. The widget owns expansion (host re-renders on
+  // disclosure click / Right / Left without the plugin reacting);
+  // this set is only read by the plugin's `activate` handler so
+  // Enter on a file row can toggle expansion via
+  // `panel.setExpandedKeys`. Both sets are cleared at the start of
+  // every fresh search.
+  expandedFileKeys: Set<string>;
+  // Memo of file-row keys we've already seen during the current
+  // search. Used by `buildMatchListSpec` to auto-expand newly-
+  // discovered files (default = expanded) without overriding user
+  // collapse state on previously-seen files.
+  knownFileKeys: Set<string>;
+  // Widget panel handle. The panel mounts a `Col[Raw{body}, HintBar{hints}]`
+  // spec — the body keeps the existing hand-rolled rendering for now,
+  // and the footer is built by the host's HintBar widget so its keys are
+  // styled consistently with every other plugin's footer (theme-keyed
+  // `ui.help_key_fg`). Subsequent migration passes will pull the
+  // search/replace inputs, the toggles, and the match tree out of
+  // `Raw` and into typed widgets. See
+  // `docs/internal/plugin-widget-library-design.md` §10.
+  widgetPanel: WidgetPanel | null;
 }
 let panel: PanelState | null = null;
 
@@ -123,7 +168,6 @@ function truncate(s: string, maxLen: number): string {
   const sLen = charLen(s);
   if (sLen <= maxLen) return s;
   if (maxLen <= 3) {
-    // Take first maxLen codepoints
     let result = "";
     let count = 0;
     for (const c of s) {
@@ -133,7 +177,6 @@ function truncate(s: string, maxLen: number): string {
     }
     return result;
   }
-  // Take first (maxLen-3) codepoints + "..."
   let result = "";
   let count = 0;
   for (const c of s) {
@@ -173,6 +216,8 @@ const modeBindings: [string, string][] = [
   ["S-Tab", "search_replace_shift_tab"],
   ["Up", "search_replace_nav_up"],
   ["Down", "search_replace_nav_down"],
+  ["PageUp", "search_replace_nav_page_up"],
+  ["PageDown", "search_replace_nav_page_down"],
   ["Left", "search_replace_nav_left"],
   ["Right", "search_replace_nav_right"],
   ["M-c", "search_replace_toggle_case"],
@@ -189,21 +234,14 @@ const modeBindings: [string, string][] = [
 
 editor.defineMode("search-replace-list", modeBindings, true, true);
 
-// Single handler for all character input (any keyboard layout, including Unicode)
-function insertCharAtCursor(ch: string): void {
-  if (!panel || panel.focusPanel !== "query") return;
-  const text = getActiveFieldText();
-  const pos = panel.cursorPos;
-  setActiveFieldText(text.slice(0, pos) + ch + text.slice(pos));
-  panel.cursorPos = pos + ch.length;
-  updatePanelContent();
-}
-
-// Handler for mode_text_input events dispatched by the mode system
+// Printable input flows through the widget runtime: mode_text_input
+// → widgetCommand(textInputChar(text)) → host computes new value +
+// cursor on the focused TextInput → widget_event "change" → plugin
+// updates its model from the event payload (see the widget_event
+// handler at the bottom of the file).
 function mode_text_input(args: { text: string }): void {
-  if (args && args.text) {
-    insertCharAtCursor(args.text);
-  }
+  if (!panel || !args?.text) return;
+  panel.widgetPanel?.command(textInputChar(args.text));
 }
 registerHandler("mode_text_input", mode_text_input);
 
@@ -252,16 +290,19 @@ interface FlatItem {
   matchIndex?: number;
 }
 
+// Emit every file row + every match row in declaration order. The
+// Tree widget filters out descendants of collapsed nodes at render
+// time — the plugin always sends the full hierarchy. Plugin code
+// that needs to map a `selected_index` back to the underlying match
+// (e.g. `doReplaceScoped`) walks this same flat list.
 function buildFlatItems(): FlatItem[] {
   if (!panel) return [];
   const items: FlatItem[] = [];
   for (let fi = 0; fi < panel.fileGroups.length; fi++) {
-    const group = panel.fileGroups[fi];
     items.push({ type: "file", fileIndex: fi });
-    if (group.expanded) {
-      for (let mi = 0; mi < group.matches.length; mi++) {
-        items.push({ type: "match", fileIndex: fi, matchIndex: mi });
-      }
+    const group = panel.fileGroups[fi];
+    for (let mi = 0; mi < group.matches.length; mi++) {
+      items.push({ type: "match", fileIndex: fi, matchIndex: mi });
     }
   }
   return items;
@@ -287,125 +328,333 @@ function getViewportHeight(): number {
 // Panel content builder — compact two-line control bar + match tree
 // =============================================================================
 
-function buildPanelEntries(): TextPropertyEntry[] {
-  if (!panel) return [];
-  const { searchPattern, replaceText, searchResults, fileGroups, focusPanel, queryField,
-    optionIndex, caseSensitive, useRegex, wholeWords, cursorPos } = panel;
-
+// Build the typed Row spec for the options line (3 toggles + Replace
+// All button). Was previously hand-built into entries with manual
+// byte-offset overlay arithmetic (see git history pre-widget); now
+// dispatched through the host's Toggle/Button widgets so styling,
+// theme keys, and focus affordance match every other plugin.
+function buildOptionsRowSpec(): WidgetSpec {
+  if (!panel) return col();
+  const { focusPanel, optionIndex, caseSensitive, useRegex, wholeWords } = panel;
   const W = Math.max(MIN_WIDTH, panel.viewportWidth - 2);
-  const entries: TextPropertyEntry[] = [];
+  const oFocus = focusPanel === "options";
 
-  const totalMatches = searchResults.length;
-  const fileCount = fileGroups.length;
+  // 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");
+  void oFocus;
+  void optionIndex;
+
+  return row(
+    spacer(1),
+    toggle(caseSensitive, caseLabel, { key: "case" }),
+    spacer(2),
+    toggle(useRegex, regexLabel, { key: "regex" }),
+    spacer(2),
+    toggle(wholeWords, wholeLabel, { key: "whole" }),
+    flexSpacer(),
+    button(replLabel, { intent: "primary", key: "replaceAll" }),
+  );
+}
 
-  // ── Line 1: Query fields + match count ──
+// 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
+// host's TextInput widget for both fields (theme-keyed focus + input
+// 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;
+  const totalMatches = panel.searchResults.length;
+  const fileCount = panel.fileGroups.length;
   const qFocusSearch = focusPanel === "query" && queryField === "search";
   const qFocusReplace = focusPanel === "query" && queryField === "replace";
-
-  // Build search field display with cursor
   const searchVal = searchPattern || "";
   const replaceVal = replaceText || "";
-  const searchCursorPos = qFocusSearch ? cursorPos : -1;
-  const replaceCursorPos = qFocusReplace ? cursorPos : -1;
-
-  const searchDisp = buildFieldDisplay(searchVal, searchCursorPos, 25);
-  const replDisp = buildFieldDisplay(replaceVal, replaceCursorPos, 25);
-
-  const searchLabel = " " + editor.t("panel.search_label") + " ";
-  const replSep = "  " + editor.t("panel.replace_label") + " ";
-  const truncatedSuffix = panel.truncated ? " " + editor.t("panel.limited") : "";
+  // The plugin tracks `cursorPos` as a character offset; the widget
+  // wants a UTF-8 byte offset. For ASCII they're equal; for the
+  // multi-byte case we convert via byteLen of the prefix.
+  const searchCursorByte = qFocusSearch ? byteLen(searchVal.substring(0, cursorPos)) : -1;
+  const replaceCursorByte = qFocusReplace ? byteLen(replaceVal.substring(0, cursorPos)) : -1;
+  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") : "");
 
-  const line1Text = searchLabel + searchDisp + replSep + replDisp + matchStats;
-  const line1 = padStr(line1Text, W);
-
-  const line1Overlays: InlineOverlay[] = [];
-  // Search label
-  line1Overlays.push({ start: byteLen(" "), end: byteLen(searchLabel), style: { fg: C.label } });
-  // Search value
-  const svStart = byteLen(searchLabel);
-  const svEnd = svStart + byteLen(searchDisp);
-  line1Overlays.push({ start: svStart, end: svEnd, style: { fg: C.value, bg: qFocusSearch ? C.inputBg : undefined } });
-  // Cursor highlight in search field
-  if (qFocusSearch) {
-    addCursorOverlay(searchVal, searchCursorPos, svStart + byteLen("["), line1Overlays);
-  }
-  // Replace label
-  const rlStart = svEnd;
-  const rlEnd = rlStart + byteLen(replSep);
-  line1Overlays.push({ start: rlStart, end: rlEnd, style: { fg: C.label } });
-  // Replace value
-  const rvStart = rlEnd;
-  const rvEnd = rvStart + byteLen(replDisp);
-  line1Overlays.push({ start: rvStart, end: rvEnd, style: { fg: C.value, bg: qFocusReplace ? C.inputBg : undefined } });
-  // Cursor highlight in replace field
-  if (qFocusReplace) {
-    addCursorOverlay(replaceVal, replaceCursorPos, rvStart + byteLen("["), line1Overlays);
-  }
-  // Stats
-  if (matchStats) {
-    const msStart = rvEnd;
-    if (panel.truncated && totalMatches > 0) {
-      // Color the count part normally, then the truncated suffix in warning color
-      const statsWithoutSuffix = "  " + editor.t("panel.match_stats", { count: String(totalMatches), files: String(fileCount) });
-      const countEnd = msStart + byteLen(statsWithoutSuffix);
-      line1Overlays.push({ start: msStart, end: countEnd, style: { fg: C.statusOk } });
-      const suffixEnd = countEnd + byteLen(truncatedSuffix);
-      line1Overlays.push({ start: countEnd, end: suffixEnd, style: { fg: [255, 180, 50] as RGB, bold: true } });
+  // 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 {
-      const msEnd = msStart + byteLen(matchStats);
-      line1Overlays.push({ start: msStart, end: msEnd, style: { fg: totalMatches > 0 ? C.statusOk : C.statusDim } });
+      overlays.push({
+        start: 0,
+        end: byteLen(matchStats),
+        style: { fg: totalMatches > 0 ? C.statusOk : C.statusDim },
+      });
     }
+    matchStatsEntries.push({ text: matchStats, inlineOverlays: overlays });
   }
 
-  entries.push({
-    text: line1 + "\n",
-    properties: { type: "query-line" },
-    inlineOverlays: line1Overlays,
-  });
-
-  // ── Line 2: Options toggles + Replace All button ──
-  const optCase = (caseSensitive ? "[v]" : "[ ]") + " " + editor.t("panel.case_toggle");
-  const optRegex = (useRegex ? "[v]" : "[ ]") + " " + editor.t("panel.regex_toggle");
-  const optWhole = (wholeWords ? "[v]" : "[ ]") + " " + editor.t("panel.whole_toggle");
-  const replBtn = "[" + editor.t("panel.replace_all_btn") + "]";
-
-  const line2Text = " " + optCase + "  " + optRegex + "  " + optWhole + "    " + replBtn;
-  const line2 = padStr(line2Text, W);
+  return row(
+    spacer(1),
+    textInput(searchVal, {
+      label: searchLabel,
+      focused: qFocusSearch,
+      cursorByte: searchCursorByte,
+      fieldWidth: 25,
+      key: "searchField",
+    }),
+    spacer(2),
+    textInput(replaceVal, {
+      label: replLabel,
+      focused: qFocusReplace,
+      cursorByte: replaceCursorByte,
+      fieldWidth: 25,
+      key: "replaceField",
+    }),
+    raw(matchStatsEntries),
+  );
+}
 
-  const line2Overlays: InlineOverlay[] = [];
-  const oFocus = focusPanel === "options";
+// Stable key for a flat tree item — used as the List item key so
+// click events bounce back to the same logical match across
+// re-renders. File rows use `file:<n>`; match rows use
+// `match:<file>/<m>`.
+function flatItemKey(item: FlatItem): string {
+  if (item.type === "file") return `file:${item.fileIndex}`;
+  return `match:${item.fileIndex}/${item.matchIndex}`;
+}
 
-  let pos = byteLen(" ");
-  function addToggleOverlay(text: string, idx: number): void {
-    const isOn = text.startsWith("[v]");
-    const isFoc = oFocus && optionIndex === idx;
-    const checkEnd = pos + byteLen(text.substring(0, 3));
-    line2Overlays.push({ start: pos, end: checkEnd, style: { fg: isOn ? C.toggleOn : C.toggleOff, bold: isFoc } });
-    const labelEnd = pos + byteLen(text);
-    line2Overlays.push({ start: checkEnd, end: labelEnd, style: { fg: C.label, bg: isFoc ? C.selectedBg : undefined, bold: isFoc } });
-    pos = labelEnd + byteLen("  ");
+// Render one flat tree item as a single TextPropertyEntry. The
+// Tree widget owns the indent (depth * 2 spaces) + disclosure glyph
+// (▶ / ▼) prefix and the selection bg — this function emits *just*
+// the row's content starting from offset 0 of the row's body. Files
+// pass `depth: 0, hasChildren: true`; matches pass `depth: 1,
+// hasChildren: false` (see `buildMatchListSpec`).
+//
+// Row content is described as a sequence of styled segments rather
+// than a pre-rendered string + offset overlays. The host concats
+// segments and computes the byte offsets natively in Rust, so the
+// plugin doesn't count codepoints or bytes for layout-piece widths
+// at all. Per-row freeform overlays (e.g. pattern-match highlights
+// inside the context substring) ride on the relevant segment via
+// its `overlays` field, addressed in char units relative to that
+// segment alone.
+function renderFlatItemEntry(item: FlatItem, W: number): TextPropertyEntry {
+  if (!panel) return { text: "" };
+  if (item.type === "file") {
+    const group = panel.fileGroups[item.fileIndex];
+    const badge = getFileExtBadge(group.relPath);
+    const matchCount = group.matches.length;
+    const selectedInFile = group.matches.filter(m => m.selected).length;
+    return styledRow(
+      [
+        { text: badge, style: { fg: C.fileIcon, bold: true } },
+        { text: " " },
+        { text: group.relPath, style: { fg: C.filePath } },
+        { text: ` (${selectedInFile}/${matchCount})` },
+      ],
+      {
+        // Host prefix at depth 0: disclosure (▶/▼) + space + checkbox
+        // ([v]/[ ]) + space = 6 cols.
+        padToChars: Math.max(0, W - 6),
+        properties: { type: "file-row", fileIndex: item.fileIndex },
+      },
+    );
+  }
+  // Match row. The Tree widget's prefix at depth=1 is 6 cols
+  // (4 indent + 2 alignment). Use the remaining width for content.
+  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();
+  // Host prefix consumes:
+  //   indent (depth=1) = 2
+  //   leaf-alignment   = 2 (in lieu of disclosure glyph)
+  //   checkbox + space = 4 ([v] + " ")
+  // Total: 8 cols.
+  const innerWidth = Math.max(0, W - 8);
+
+  // Best-effort context budget: enough room for the fixed leading
+  // pieces plus " - " plus the context itself. JS `.length` gives
+  // UTF-16 code-unit counts which match codepoint counts for the
+  // overwhelmingly-ASCII case (paths + line numbers); slight
+  // over-counting on rare non-BMP filenames just trims a little
+  // more of the context, which is fine.
+  const maxCtx = innerWidth - location.length - 3;
+  const displayCtx = truncate(context, Math.max(10, maxCtx));
+
+  // Pattern-match highlights inside the context substring. Emitted
+  // in segment-local char units; the host shifts them by the
+  // context segment's char start during entry concatenation.
+  const ctxOverlays: InlineOverlay[] = [];
+  if (panel.searchPattern) {
+    highlightMatches(displayCtx, panel.searchPattern, panel.useRegex, panel.caseSensitive, ctxOverlays);
   }
 
-  addToggleOverlay(optCase, 0);
-  addToggleOverlay(optRegex, 1);
-  addToggleOverlay(optWhole, 2);
+  const segments: StyledSegment[] = [
+    { text: location, style: { fg: C.lineNum } },
+    { text: " - " },
+    { text: displayCtx, overlays: ctxOverlays },
+  ];
 
-  // Replace All button
-  pos = byteLen(line2Text) - byteLen(replBtn);
-  const btnFoc = oFocus && optionIndex === 3;
-  line2Overlays.push({
-    start: pos, end: pos + byteLen(replBtn),
-    style: { fg: btnFoc ? C.buttonFg : C.button, bg: btnFoc ? C.button : undefined, bold: btnFoc },
+  return styledRow(segments, {
+    padToChars: innerWidth,
+    properties: { type: "match-row", fileIndex: item.fileIndex, matchIndex: item.matchIndex },
   });
+}
 
-  entries.push({
-    text: line2 + "\n",
-    properties: { type: "options-line" },
-    inlineOverlays: line2Overlays,
+// 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
+// routing, and host-managed expand/collapse — the plugin sends
+// the *full* hierarchy on every render and the host filters
+// children of collapsed file rows.
+function buildMatchListSpec(): WidgetSpec {
+  if (!panel) return col();
+  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),
+      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 },
+    }]);
+  }
+
+  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 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
+  // calculation that sized the previous List.
+  const fixedRows = 5;
+  const visibleRows = Math.max(3, getViewportHeight() - fixedRows);
+
+  return tree({
+    nodes,
+    itemKeys,
+    selectedIndex,
+    visibleRows,
+    expandedKeys: [...panel.expandedFileKeys],
+    checkable: true,
+    key: "matchTree",
   });
+}
+
+// Phase selector for `buildPanelEntries`. The hand-rolled options
+// row and line-1 query fields were extracted into typed widget specs
+// (`buildOptionsRowSpec`, `buildLine1Spec`); this parameter lets
+// callers ask for the body before the options row ("preOptions"),
+// the body after it ("postOptions"), or — for tests / fallback
+// paths — both with no gap ("all"). Today "preOptions" is empty
+// because line 1 lives in `buildLine1Spec`; the parameter remains
+// for symmetry and to keep the boundary explicit.
+type BuildPhase = "all" | "preOptions" | "postOptions";
+
+function buildPanelEntries(phase: BuildPhase = "all"): TextPropertyEntry[] {
+  if (!panel) return [];
+  const { searchPattern, replaceText, searchResults, fileGroups, focusPanel, queryField,
+    optionIndex, caseSensitive, useRegex, wholeWords, cursorPos } = panel;
+  // The line-1 + options-row variables are still destructured for
+  // readability with the rest of the function but are now consumed
+  // by `buildLine1Spec()` and `buildOptionsRowSpec()` (composed into
+  // the spec at update time).
+  void searchPattern;
+  void replaceText;
+  void searchResults;
+  void fileGroups;
+  void focusPanel;
+  void queryField;
+  void cursorPos;
+  void optionIndex;
+  void caseSensitive;
+  void useRegex;
+  void wholeWords;
+
+  const W = Math.max(MIN_WIDTH, panel.viewportWidth - 2);
+  const entries: TextPropertyEntry[] = [];
+
+  const totalMatches = searchResults.length;
+  const fileCount = fileGroups.length;
+
+  // ── Line 1 (search/replace fields + match-count stats) is now
+  //    rendered by `buildLine1Spec()` — see updatePanelContent. The
+  //    pre-options phase therefore returns no entries; the spec
+  //    composes the typed Row directly between the col children. ──
+
+  // ── Line 2 (options toggles + Replace All button) is now rendered
+  //    by the host as a `Row { Toggle, Toggle, Toggle, Spacer, Button }`
+  //    spec — see `buildOptionsRowSpec` and `updatePanelContent`.
+  //    `buildPanelEntries` is split into a "pre-options" half (this
+  //    function up to here) and a "post-options" tail (everything from
+  //    the separator onward). `updatePanelContent` weaves the spec
+  //    between them so the visual order stays identical to before. ──
+  if (phase === "preOptions") return entries;
+  // ── For phase==="postOptions", also drop the line-1 entry pushed
+  //    above so the caller can compose: `col(raw(pre), optionsRow,
+  //    raw(post), hintBar)` without duplicating line 1.
+  if (phase === "postOptions") entries.length = 0;
 
   // ── Separator ──
   const sepChar = "─";
@@ -427,122 +676,34 @@ function buildPanelEntries(): TextPropertyEntry[] {
     }],
   });
 
-  // ── Matches tree (virtual-scrolled) ──
-  const flatItems = buildFlatItems();
-  const fixedRows = 5;
-  const treeVisibleRows = Math.max(3, getViewportHeight() - fixedRows);
-
-  if (searchPattern && totalMatches === 0) {
-    entries.push({
-      text: padStr("  " + editor.t("panel.no_matches"), W) + "\n",
-      properties: { type: "empty" },
-      style: { fg: C.dim },
-    });
-  } else if (!searchPattern) {
-    entries.push({
-      text: padStr("  " + editor.t("panel.type_pattern"), W) + "\n",
-      properties: { type: "empty" },
-      style: { fg: C.dim },
-    });
-  } else {
-    let selectedLineIdx = focusPanel === "matches" ? panel.matchIndex : -1;
-
-    // Adjust scroll offset to keep selected line visible
-    if (selectedLineIdx >= 0) {
-      if (selectedLineIdx < panel.scrollOffset) {
-        panel.scrollOffset = selectedLineIdx;
-      }
-      if (selectedLineIdx >= panel.scrollOffset + treeVisibleRows) {
-        panel.scrollOffset = selectedLineIdx - treeVisibleRows + 1;
-      }
-    }
-    const maxOffset = Math.max(0, flatItems.length - treeVisibleRows);
-    if (panel.scrollOffset > maxOffset) panel.scrollOffset = maxOffset;
-    if (panel.scrollOffset < 0) panel.scrollOffset = 0;
-
-    // ONLY loop through the items that are literally on the screen right now
-    for (let i = panel.scrollOffset; i < panel.scrollOffset + treeVisibleRows; i++) {
-      if (i >= flatItems.length) break;
-      const item = flatItems[i];
-      const isSelected = focusPanel === "matches" && panel.matchIndex === i;
-
-      if (item.type === "file") {
-        const group = fileGroups[item.fileIndex];
-        const expandIcon = group.expanded ? "v" : ">";
-        const badge = getFileExtBadge(group.relPath);
-        const matchCount = group.matches.length;
-        const selectedInFile = group.matches.filter(m => m.selected).length;
-        const fileLineText = ` ${expandIcon} ${badge} ${group.relPath} (${selectedInFile}/${matchCount})`;
-
-        const fileOverlays: InlineOverlay[] = [];
-        const eiStart = byteLen(" ");
-        const eiEnd = eiStart + byteLen(expandIcon);
-        fileOverlays.push({ start: eiStart, end: eiEnd, style: { fg: C.expandIcon } });
-        const bgStart = eiEnd + byteLen(" ");
-        const bgEnd = bgStart + byteLen(badge);
-        fileOverlays.push({ start: bgStart, end: bgEnd, style: { fg: C.fileIcon, bold: true } });
-        const fpStart = bgEnd + byteLen(" ");
-        const fpEnd = fpStart + byteLen(group.relPath);
-        fileOverlays.push({ start: fpStart, end: fpEnd, style: { fg: C.filePath } });
-
-        entries.push({
-          text: padStr(fileLineText, W) + "\n",
-          properties: { type: "file-row", fileIndex: item.fileIndex },
-          style: isSelected ? { bg: C.selectedBg } : undefined,
-          inlineOverlays: fileOverlays,
-        });
-      } else {
-        const group = fileGroups[item.fileIndex];
-        const result = group.matches[item.matchIndex!];
-        const checkbox = result.selected ? "[v]" : "[ ]";
-        const location = `${group.relPath}:${result.match.line}`;
-        const context = result.match.context.trim();
-        const prefixText = `   ${isSelected ? ">" : " "} ${checkbox} `;
-        const maxCtx = W - charLen(prefixText) - charLen(location) - 3;
-        const displayCtx = truncate(context, Math.max(10, maxCtx));
-        const matchLineText = `${prefixText}${location} - ${displayCtx}`;
-
-        const inlines: InlineOverlay[] = [];
-        const cbStart = byteLen(`   ${isSelected ? ">" : " "} `);
-        const cbEnd = cbStart + byteLen(checkbox);
-        inlines.push({ start: cbStart, end: cbEnd, style: { fg: result.selected ? C.checkOn : C.checkOff } });
-        const locStart = cbEnd + byteLen(" ");
-        const locEnd = locStart + byteLen(location);
-        inlines.push({ start: locStart, end: locEnd, style: { fg: C.lineNum } });
-
-        if (panel.searchPattern) {
-          const ctxStart = locEnd + byteLen(" - ");
-          highlightMatches(displayCtx, panel.searchPattern, ctxStart, panel.useRegex, panel.caseSensitive, inlines);
-        }
-
-        entries.push({
-          text: padStr(matchLineText, W) + "\n",
-          properties: { type: "match-row", fileIndex: item.fileIndex, matchIndex: item.matchIndex },
-          style: isSelected ? { bg: C.selectedBg } : undefined,
-          inlineOverlays: inlines.length > 0 ? inlines : undefined,
-        });
-      }
-    }
-  }
-
-  // Scroll indicators
-  const canScrollUp = panel.scrollOffset > 0;
-  const canScrollDown = panel.scrollOffset + treeVisibleRows < flatItems.length;
-  const scrollHint = canScrollUp || canScrollDown
-    ? "  " + (canScrollUp ? "↑" : " ") + (canScrollDown ? "↓" : " ")
-    : "";
-
-  // ── Help bar ──
-  const helpText = " " + editor.t("panel.help") + scrollHint;
-  entries.push({
-    text: truncate(helpText, W) + "\n",
-    properties: { type: "help" },
-    style: { fg: C.help },
-  });
+  // ── Matches tree is now rendered by `buildMatchListSpec()` —
+  //    see `updatePanelContent`. The List widget owns scroll
+  //    offset (auto-clamps to keep selection in view) and click
+  //    routing. ──
 
+  // The help footer is no longer pushed here — it's now rendered by
+  // the host's HintBar widget (see updatePanelContent).
   return entries;
 }
 
+// Build the hint entries for the panel footer.
+//
+// Source of truth is the existing `panel.help` i18n string (format:
+// `Tab:section  ↑↓:nav  …`); `parseHintString` splits it into typed
+// `HintEntry[]` so the host's HintBar widget can style the keys
+// portion via the `ui.help_key_fg` theme key — matching every other
+// plugin's footer.
+function buildHelpHints(): HintEntry[] {
+  // Source of truth is the existing `panel.help` i18n string. The
+  // pre-widget version appended a `↑↓` scroll indicator computed
+  // from `panel.scrollOffset`; the List widget now owns scroll
+  // state, so the plugin no longer knows the scroll position.
+  // Scroll feedback is implicit (the visible window of items shifts
+  // visibly when navigating); explicit indicators can come back as
+  // a List-emitted prop once needed.
+  return parseHintString(editor.t("panel.help"));
+}
+
 // Build field display string: [value] with cursor
 function buildFieldDisplay(value: string, cursorPos: number, maxLen: number): string {
   const display = value.length > maxLen ? value.slice(0, maxLen - 1) + "…" : value;
@@ -564,8 +725,18 @@ function addCursorOverlay(value: string, cursorPos: number, fieldByteStart: numb
   overlays.push({ start: cursorBytePos, end: cursorByteEnd, style: { fg: [0, 0, 0], bg: C.cursorBg } });
 }
 
-// Highlight search pattern occurrences in a display string
-function highlightMatches(text: string, pattern: string, baseByteOffset: number, isRegex: boolean, caseSensitive: boolean, overlays: InlineOverlay[]): void {
+// Append pattern-match highlight overlays (one per occurrence) to
+// `overlays`. Offsets are in char (codepoint) units within `text`
+// itself — the caller is expected to attach `overlays` to a
+// segment whose body equals `text`, so the host shifts them into
+// entry-coordinate space during segment resolution.
+//
+// `text` and `pattern` are treated as JS UTF-16 strings. For BMP
+// content (which includes nearly all source code) UTF-16 code unit
+// indices and Unicode codepoint indices coincide, so `indexOf` /
+// `RegExp.exec` indices map directly to char offsets without a
+// per-overlay codepoint walk.
+function highlightMatches(text: string, pattern: string, isRegex: boolean, caseSensitive: boolean, overlays: InlineOverlay[]): void {
   if (!pattern) return;
   try {
     if (!isRegex) {
@@ -579,9 +750,7 @@ function highlightMatches(text: string, pattern: string, baseByteOffset: number,
       while (pos < searchText.length) {
         const idx = searchText.indexOf(searchPat, pos);
         if (idx < 0) break;
-        const startByte = baseByteOffset + byteLen(text.substring(0, idx));
-        const endByte = startByte + byteLen(text.substring(idx, idx + pattern.length));
-        overlays.push({ start: startByte, end: endByte, style: { bg: C.matchBg, fg: C.matchFg } });
+        overlays.push({ start: idx, end: idx + pattern.length, style: { bg: C.matchBg, fg: C.matchFg }, unit: "char" });
         pos = idx + pattern.length;
       }
     } else {
@@ -590,9 +759,7 @@ function highlightMatches(text: string, pattern: string, baseByteOffset: number,
       let m;
       while ((m = re.exec(text)) !== null) {
         if (m[0].length === 0) { re.lastIndex++; continue; }
-        const startByte = baseByteOffset + byteLen(text.substring(0, m.index));
-        const endByte = startByte + byteLen(m[0]);
-        overlays.push({ start: startByte, end: endByte, style: { bg: C.matchBg, fg: C.matchFg } });
+        overlays.push({ start: m.index, end: m.index + m[0].length, style: { bg: C.matchBg, fg: C.matchFg }, unit: "char" });
       }
     }
   } catch (_e) { /* invalid regex */ }
@@ -603,10 +770,50 @@ function highlightMatches(text: string, pattern: string, baseByteOffset: number,
 // =============================================================================
 
 function updatePanelContent(): void {
-  if (panel) {
-    // Refresh viewport width each time
-    panel.viewportWidth = getViewportWidth();
-    editor.setVirtualBufferContent(panel.resultsBufferId, buildPanelEntries());
+  if (!panel) return;
+  // Refresh viewport width each time
+  panel.viewportWidth = getViewportWidth();
+
+  // Migration step 4 (see docs/internal/plugin-widget-library-design.md
+  // §10): the entire visible panel is now typed widgets except for
+  // a single `Raw` separator entry.
+  //
+  //   * `Row{ Spacer, TextInput, Spacer, TextInput, Raw{ stats } }`
+  //                                       — search/replace inputs +
+  //                                       trailing match-count stats.
+  //   * `Row{ Toggle, Toggle, Toggle, Spacer, Button }`
+  //                                       — case/regex/whole + Replace All.
+  //   * `Raw{ separator entry }`         — matches divider.
+  //   * `List{ ... }` or `Raw{empty msg}` — virtual-scrolled match
+  //                                       rows (host owns scroll +
+  //                                       selection styling +
+  //                                       click routing).
+  //   * `HintBar{ ... }`                  — keyboard-hint footer.
+  if (!panel.widgetPanel) {
+    panel.widgetPanel = new WidgetPanel(panel.resultsBufferId);
+  }
+  panel.widgetPanel.set(
+    col(
+      buildLine1Spec(),
+      buildOptionsRowSpec(),
+      raw(buildPanelEntries("postOptions")),
+      buildMatchListSpec(),
+      hintBar(buildHelpHints()),
+    ),
+  );
+  // The Tree's `expandedKeys` field on the spec is initial-only —
+  // `mountWidgetPanel` seeds the host's instance state, and
+  // `updateWidgetPanel` ignores it (instance state is authoritative
+  // after first render). So we push expansion changes through the
+  // explicit mutator on every update; this covers the case where
+  // a new file group enters the result set in a later search and
+  // needs to be force-expanded by default. The mutator is a no-op
+  // when the tree isn't mounted yet (first `set()` call).
+  if (panel.searchPattern && panel.searchResults.length > 0) {
+    panel.widgetPanel.setExpandedKeys(
+      "matchTree",
+      [...panel.expandedFileKeys],
+    );
   }
 }
 
@@ -616,58 +823,99 @@ function updatePanelContent(): void {
 
 /** Current search generation — incremented on each new search to discard stale results. */
 let currentSearchGeneration = 0;
+/** The active search handle, kept so a superseding search can cancel it. */
+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;
 
 /**
- * Perform a streaming search. Results arrive incrementally per-file via the
- * progress callback and are merged into the panel state as they arrive.
- * Returns the final complete list of results.
+ * Perform a streaming search using a pull-based handle. The host writes
+ * matches at full speed into shared state; this loop drains them via
+ * `handle.take()` and rebuilds the UI between drains. There are no
+ * per-chunk callbacks crossing the FFI boundary, so the host's main
+ * thread is free to process input and render between pumps.
  */
 async function performSearch(pattern: string, silent?: boolean): Promise<SearchResult[]> {
   if (!panel) return [];
 
   const generation = ++currentSearchGeneration;
-  let lastUiUpdate = Date.now();
-  const UI_UPDATE_INTERVAL_MS = 100; // Force maximum 10 UI updates per second
+  // Each fresh search resets the per-file expansion set: previous
+  // results may have included files that don't appear in the new
+  // result set, and the user's collapse state for the *previous*
+  // result set isn't meaningful for the new one.
+  panel.expandedFileKeys.clear();
+  panel.knownFileKeys.clear();
+
+  // Cancel any in-flight search before kicking off a new one. Without
+  // this the prior search would keep walking the project until it
+  // hit max_results, wasting CPU.
+  if (activeSearchHandle) {
+    try { activeSearchHandle.cancel(); } catch (_e) { /* ignore */ }
+    activeSearchHandle = null;
+  }
 
   try {
     const fixedString = !panel.useRegex;
-    let allResults: SearchResult[] = [];
+    const allResults: SearchResult[] = [];
 
     // Whole-word filtering is done Rust-side so maxResults is respected correctly
-    const result = await editor.grepProjectStreaming(
-      pattern,
-      {
-        fixedString,
-        caseSensitive: panel.caseSensitive,
-        maxResults: MAX_RESULTS,
-        wholeWords: panel.wholeWords,
-      },
-      (matches: GrepMatch[], done: boolean) => {
-        // Discard if a newer search has started
-        if (generation !== currentSearchGeneration || !panel) return;
-
-        if (matches.length > 0) {
-          // Use push loop instead of allResults.concat() to save massive memory allocations
-          for (const m of matches) {
-            allResults.push({ match: m, selected: true });
-          }
-          panel.searchResults = allResults;
-        }
+    const handle = editor.beginSearch(pattern, {
+      fixedString,
+      caseSensitive: panel.caseSensitive,
+      maxResults: MAX_RESULTS,
+      wholeWords: panel.wholeWords,
+    });
+    activeSearchHandle = handle;
 
-        const now = Date.now();
-        // Only trigger the expensive UI rebuild if enough time passed or stream finished
-        if (done || now - lastUiUpdate > UI_UPDATE_INTERVAL_MS) {
-          panel.fileGroups = buildFileGroups(allResults);
-          updatePanelContent();
-          lastUiUpdate = now;
+    let truncated = false;
+    let producerError: string | null = null;
+
+    while (true) {
+      // Discard the in-flight search if a newer one started while we slept.
+      if (generation !== currentSearchGeneration || !panel) {
+        try { handle.cancel(); } catch (_e) { /* ignore */ }
+        return allResults;
+      }
+
+      const batch = handle.take();
+      if (batch.matches.length > 0) {
+        for (const m of batch.matches) {
+          allResults.push({ match: m, selected: true });
         }
+        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);
+        updatePanelContent();
       }
-    );
+
+      if (batch.done) {
+        truncated = batch.truncated;
+        producerError = batch.error ?? null;
+        break;
+      }
+
+      await editor.delay(SEARCH_PUMP_INTERVAL_MS);
+    }
+
+    if (activeSearchHandle === handle) {
+      activeSearchHandle = null;
+    }
 
     // Final state
     if (generation !== currentSearchGeneration || !panel) return allResults;
 
-    panel.truncated = !!(result && (result as any).truncated);
+    if (producerError) {
+      throw new Error(producerError);
+    }
+
+    panel.truncated = truncated;
 
     if (!silent) {
       if (allResults.length === 0) {
@@ -740,6 +988,9 @@ async function openPanel(): Promise<void> {
     truncated: false,
     cursorPos: prefill.length,
     scrollOffset: 0,
+    expandedFileKeys: new Set<string>(),
+    knownFileKeys: new Set<string>(),
+    widgetPanel: null,
   };
 
   try {
@@ -869,176 +1120,42 @@ async function rerunSearchQuiet(): Promise<void> {
 // Text editing handlers (inline editing of query fields)
 // =============================================================================
 
-function search_replace_backspace(): void {
-  if (!panel || panel.focusPanel !== "query") return;
-  const text = getActiveFieldText();
-  const pos = panel.cursorPos;
-  if (pos <= 0) return;
-  setActiveFieldText(text.slice(0, pos - 1) + text.slice(pos));
-  panel.cursorPos = pos - 1;
-  updatePanelContent();
-}
-registerHandler("search_replace_backspace", search_replace_backspace);
-
-function search_replace_delete(): void {
-  if (!panel || panel.focusPanel !== "query") return;
-  const text = getActiveFieldText();
-  const pos = panel.cursorPos;
-  if (pos >= text.length) return;
-  setActiveFieldText(text.slice(0, pos) + text.slice(pos + 1));
-  updatePanelContent();
-}
-registerHandler("search_replace_delete", search_replace_delete);
-
-function search_replace_home(): void {
-  if (!panel || panel.focusPanel !== "query") return;
-  panel.cursorPos = 0;
-  updatePanelContent();
-}
-registerHandler("search_replace_home", search_replace_home);
-
-function search_replace_end(): void {
-  if (!panel || panel.focusPanel !== "query") return;
-  panel.cursorPos = getActiveFieldText().length;
-  updatePanelContent();
+// All editing / navigation keys route through the widget runtime
+// via the smart `Key` dispatch — the host knows which widget is
+// focused and routes accordingly (Backspace into TextInput; Up/Down
+// across List rows; Enter/Space activate Toggle/Button/List;
+// printable Space inserts into TextInput; Tab/Shift+Tab cycles
+// focus). See WidgetAction::Key for the full table.
+function dispatch(action: WidgetAction): void {
+  panel?.widgetPanel?.command(action);
 }
-registerHandler("search_replace_end", search_replace_end);
 
-// =============================================================================
-// Navigation handlers
-// =============================================================================
-
-function search_replace_nav_down(): void {
-  if (!panel) return;
-  if (panel.focusPanel === "query") {
-    if (panel.queryField === "search") {
-      panel.queryField = "replace";
-      panel.cursorPos = panel.replaceText.length;
-    }
-    updatePanelContent();
-  } else if (panel.focusPanel === "options") {
-    if (panel.optionIndex < 3) { panel.optionIndex++; updatePanelContent(); }
-  } else {
-    const flat = buildFlatItems();
-    if (panel.matchIndex < flat.length - 1) { panel.matchIndex++; updatePanelContent(); }
-  }
-}
-registerHandler("search_replace_nav_down", search_replace_nav_down);
-
-function search_replace_nav_up(): void {
-  if (!panel) return;
-  if (panel.focusPanel === "query") {
-    if (panel.queryField === "replace") {
-      panel.queryField = "search";
-      panel.cursorPos = panel.searchPattern.length;
-    }
-    updatePanelContent();
-  } else if (panel.focusPanel === "options") {
-    if (panel.optionIndex > 0) { panel.optionIndex--; updatePanelContent(); }
-  } else {
-    if (panel.matchIndex > 0) { panel.matchIndex--; updatePanelContent(); }
-  }
-}
-registerHandler("search_replace_nav_up", search_replace_nav_up);
-
-function search_replace_tab(): void {
-  editor.debug("search_replace_tab CALLED, panel=" + (panel ? "yes" : "null"));
-  if (!panel) return;
-  if (panel.focusPanel === "query") {
-    if (panel.queryField === "search") {
-      // Search → Replace
-      panel.queryField = "replace";
-      panel.cursorPos = panel.replaceText.length;
-      updatePanelContent();
-      return;
-    } else {
-      // Replace → Options
-      panel.focusPanel = "options";
-    }
-  } else if (panel.focusPanel === "options") {
-    panel.focusPanel = "matches";
-  } else {
-    // Matches → Query/Search
-    panel.focusPanel = "query";
-    panel.queryField = "search";
-    panel.cursorPos = panel.searchPattern.length;
-  }
-  updatePanelContent();
-}
-registerHandler("search_replace_tab", search_replace_tab);
-
-function search_replace_shift_tab(): void {
-  if (!panel) return;
-  if (panel.focusPanel === "matches") {
-    panel.focusPanel = "options";
-  } else if (panel.focusPanel === "options") {
-    panel.focusPanel = "query";
-    panel.queryField = "replace";
-    panel.cursorPos = panel.replaceText.length;
-  } else {
-    if (panel.queryField === "replace") {
-      panel.queryField = "search";
-      panel.cursorPos = panel.searchPattern.length;
-    } else {
-      panel.focusPanel = "matches";
-    }
-  }
-  updatePanelContent();
-}
-registerHandler("search_replace_shift_tab", search_replace_shift_tab);
-
-function search_replace_nav_left(): void {
-  if (!panel) return;
-  // When in query panel, move cursor left
-  if (panel.focusPanel === "query") {
-    if (panel.cursorPos > 0) {
-      panel.cursorPos--;
-      updatePanelContent();
-    }
-    return;
-  }
-  if (panel.focusPanel !== "matches") return;
-  const flat = buildFlatItems();
-  const item = flat[panel.matchIndex];
-  if (!item) return;
-  if (item.type === "file") {
-    if (panel.fileGroups[item.fileIndex].expanded) {
-      panel.fileGroups[item.fileIndex].expanded = false;
-      updatePanelContent();
-    }
-  } else {
-    for (let i = panel.matchIndex - 1; i >= 0; i--) {
-      if (flat[i].type === "file" && flat[i].fileIndex === item.fileIndex) {
-        panel.matchIndex = i;
-        updatePanelContent();
-        break;
-      }
-    }
-  }
-}
-registerHandler("search_replace_nav_left", search_replace_nav_left);
-
-function search_replace_nav_right(): void {
-  if (!panel) return;
-  // When in query panel, move cursor right
-  if (panel.focusPanel === "query") {
-    const text = getActiveFieldText();
-    if (panel.cursorPos < text.length) {
-      panel.cursorPos++;
-      updatePanelContent();
-    }
-    return;
-  }
-  if (panel.focusPanel !== "matches") return;
-  const flat = buildFlatItems();
-  const item = flat[panel.matchIndex];
-  if (!item) return;
-  if (item.type === "file" && !panel.fileGroups[item.fileIndex].expanded) {
-    panel.fileGroups[item.fileIndex].expanded = true;
-    updatePanelContent();
-  }
-}
-registerHandler("search_replace_nav_right", search_replace_nav_right);
+registerHandler("search_replace_backspace", () => dispatch(widgetKey("Backspace")));
+registerHandler("search_replace_delete",    () => dispatch(widgetKey("Delete")));
+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")));
+registerHandler("search_replace_nav_page_up",   () => dispatch(widgetKey("PageUp")));
+registerHandler("search_replace_nav_page_down", () => dispatch(widgetKey("PageDown")));
+
+// Tab / Shift+Tab now cycle focus through the host's tabbable
+// widget set (declared in spec via `key`s — searchField,
+// replaceField, case, regex, whole, replaceAll, matchTree).
+// The host re-renders with focus styling on the new widget; the
+// plugin needn't track focusPanel/queryField/optionIndex anymore
+// (the legacy fields linger in PanelState until the rest of the
+// plugin migrates off them).
+registerHandler("search_replace_tab",       () => dispatch(widgetKey("Tab")));
+registerHandler("search_replace_shift_tab", () => dispatch(widgetKey("Shift+Tab")));
+
+// Left/Right route through the smart-key dispatcher: the host
+// expands/collapses Tree nodes (when the matchTree is focused) or
+// moves the TextInput cursor (when a search/replace field is
+// focused). Plugin no longer needs separate file-row expand
+// handling.
 
 // Global option toggles (Alt+C, Alt+R, Alt+W)
 function search_replace_toggle_case(): void {
@@ -1079,81 +1196,22 @@ registerHandler("search_replace_replace_scoped", search_replace_replace_scoped);
 // Action handlers
 // =============================================================================
 
-function search_replace_enter(): void {
-  editor.debug("search_replace_enter CALLED, panel=" + (panel ? "yes" : "null"));
-  if (!panel) return;
-  if (panel.focusPanel === "query") {
-    // Enter in query field = confirm and run search
-    if (panel.queryField === "search") {
-      // Move to replace field
-      panel.queryField = "replace";
-      panel.cursorPos = panel.replaceText.length;
-      updatePanelContent();
-    } else {
-      // Confirm replace field and run search
-      if (panel.searchPattern) {
-        rerunSearch().then(() => {
-          if (panel) {
-            panel.focusPanel = "matches";
-            panel.matchIndex = 0;
-            panel.scrollOffset = 0;
-            updatePanelContent();
-          }
-        });
-      }
-    }
-  } else if (panel.focusPanel === "options") {
-    if (panel.optionIndex === 3) {
-      doReplaceAll();
-    } else {
-      search_replace_space();
-    }
-  } else {
-    const flat = buildFlatItems();
-    const item = flat[panel.matchIndex];
-    if (!item) return;
-    if (item.type === "file") {
-      panel.fileGroups[item.fileIndex].expanded = !panel.fileGroups[item.fileIndex].expanded;
-      updatePanelContent();
-    } else {
-      const group = panel.fileGroups[item.fileIndex];
-      const result = group.matches[item.matchIndex!];
-      editor.openFileInSplit(panel.sourceSplitId, result.match.file, result.match.line, result.match.column);
-    }
-  }
-}
-registerHandler("search_replace_enter", search_replace_enter);
-
-function search_replace_space(): void {
-  if (!panel) return;
-  if (panel.focusPanel === "query") {
-    // Space in query field = insert space character
-    insertCharAtCursor(" ");
-    return;
-  }
-  if (panel.focusPanel === "options") {
-    if (panel.optionIndex === 0) { panel.caseSensitive = !panel.caseSensitive; updatePanelContent(); rerunSearchDebounced(); }
-    else if (panel.optionIndex === 1) { panel.useRegex = !panel.useRegex; updatePanelContent(); rerunSearchDebounced(); }
-    else if (panel.optionIndex === 2) { panel.wholeWords = !panel.wholeWords; updatePanelContent(); rerunSearchDebounced(); }
-    else if (panel.optionIndex === 3) { doReplaceAll(); }
-    return;
-  }
-  if (panel.focusPanel === "matches") {
-    const flat = buildFlatItems();
-    const item = flat[panel.matchIndex];
-    if (!item) return;
-    if (item.type === "file") {
-      const group = panel.fileGroups[item.fileIndex];
-      const allSelected = group.matches.every(m => m.selected);
-      for (const m of group.matches) m.selected = !allSelected;
-    } else {
-      const group = panel.fileGroups[item.fileIndex];
-      group.matches[item.matchIndex!].selected = !group.matches[item.matchIndex!].selected;
-    }
-    updatePanelContent();
-  }
-}
-registerHandler("search_replace_space", search_replace_space);
+// Enter / Space route to the widget runtime. The host decides what
+// each does based on the focused widget kind:
+//   * Toggle (case/regex/whole) → fires `widget_event` "toggle".
+//   * Button (replaceAll)       → fires `widget_event` "activate".
+//   * Tree   (matchTree)        → fires `widget_event` "activate"
+//                                  with the focused row's index/key.
+//                                  Plugin handler opens the match
+//                                  for leaf rows or toggles
+//                                  expansion for file rows.
+//   * TextInput + Space         → inserts " " (fires "change").
+//   * TextInput + Enter         → no-op (plugin can still bind a
+//                                  separate handler if it wants
+//                                  Enter to mean "submit").
+// Per-event handling lives in the `widget_event` listener below.
+registerHandler("search_replace_enter", () => dispatch(widgetKey("Enter")));
+registerHandler("search_replace_space", () => dispatch(widgetKey("Space")));
 
 async function doReplaceAll(): Promise<void> {
   if (!panel || panel.busy) return;
@@ -1238,6 +1296,7 @@ async function doReplaceScoped(): Promise<void> {
 
 function search_replace_close(): void {
   if (!panel) return;
+  panel.widgetPanel?.unmount();
   editor.closeBuffer(panel.resultsBufferId);
   if (panel.resultsSplitId !== panel.sourceSplitId) {
     editor.closeSplit(panel.resultsSplitId);
@@ -1290,10 +1349,214 @@ editor.on("prompt_cancelled", (args) => {
 
 editor.on("buffer_closed", (args) => {
   if (panel && args.buffer_id === panel.resultsBufferId) {
+    panel.widgetPanel?.unmount();
     panel = null;
   }
 });
 
+// Click → semantic event. The host hit-tests mouse clicks against the
+// mounted widget panel and fires `widget_event` for clicks that land
+// on a Toggle or Button. We dispatch on `widget_key` (set in
+// `buildOptionsRowSpec`); the existing keyboard-driven path
+// (Alt+C / Alt+R / Alt+W / Alt+Ret) still works unchanged.
+//
+// Mouse-click on a toggle should also focus it, so the user's next
+// Tab cycle starts from the clicked control. We do that by syncing
+// `focusPanel`/`optionIndex` to the clicked widget before applying
+// the state change.
+editor.on("widget_event", (args) => {
+  if (!panel || args.panel_id !== panel.widgetPanel?.id()) return;
+
+  // `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
+  // widget's instance state in place; we just sync the plugin's
+  // model. **No** `updatePanelContent()` here — the widget has
+  // already painted, and the rest of the spec doesn't depend on
+  // the field value. This is the IPC fast path discussed in §3
+  // of the design doc Q&A.
+  if (args.event_type === "change") {
+    const payload = args.payload as
+      | { value?: string; cursorByte?: number }
+      | undefined;
+    if (typeof payload?.value !== "string") return;
+    const cursorByte = typeof payload.cursorByte === "number"
+      ? payload.cursorByte
+      : payload.value.length;
+    if (args.widget_key === "searchField") {
+      panel.searchPattern = payload.value;
+      panel.cursorPos = byteToCharOffset(payload.value, cursorByte);
+      rerunSearchDebounced();
+    } else if (args.widget_key === "replaceField") {
+      panel.replaceText = payload.value;
+      panel.cursorPos = byteToCharOffset(payload.value, cursorByte);
+    }
+    return;
+  }
+
+  // `select` — fired when the user clicks a Tree row or the host
+  // moves selection (Up/Down). The host already updated the
+  // tree's selectedIndex in instance state; mirror it into the
+  // plugin model and skip re-emit.
+  if (args.event_type === "select") {
+    const idx = (args.payload as { index?: number } | undefined)?.index;
+    if (typeof idx === "number") {
+      panel.matchIndex = idx;
+    }
+    return;
+  }
+
+  // `expand` — fired when the host changes a Tree node's
+  // expansion state (Right/Left key, or click on the disclosure
+  // glyph). Mirror the change into our local set so a subsequent
+  // file-row Enter (which goes through `setExpandedKeys`) reads
+  // the right state.
+  if (args.event_type === "expand") {
+    const payload = args.payload as
+      | { key?: string; expanded?: boolean }
+      | undefined;
+    if (typeof payload?.key === "string" && typeof payload.expanded === "boolean") {
+      if (payload.expanded) panel.expandedFileKeys.add(payload.key);
+      else panel.expandedFileKeys.delete(payload.key);
+    }
+    return;
+  }
+
+  // `activate` — fired by Enter/Space on a focused Button or Tree.
+  // For the Replace All button: run replace. For the matchTree:
+  // open the focused match's source location, or toggle expansion
+  // for file rows (so Enter is a shortcut for Right/Left/click).
+  if (args.event_type === "activate") {
+    if (args.widget_key === "replaceAll") {
+      doReplaceAll();
+      return;
+    }
+    if (args.widget_key === "matchTree") {
+      const idx = (args.payload as { index?: number } | undefined)?.index;
+      if (typeof idx !== "number") return;
+      const flat = buildFlatItems();
+      const item = flat[idx];
+      if (!item) return;
+      if (item.type === "file") {
+        const k = `file:${item.fileIndex}`;
+        if (panel.expandedFileKeys.has(k)) {
+          panel.expandedFileKeys.delete(k);
+        } else {
+          panel.expandedFileKeys.add(k);
+        }
+        panel.widgetPanel?.setExpandedKeys(
+          "matchTree",
+          [...panel.expandedFileKeys],
+        );
+      } else {
+        const group = panel.fileGroups[item.fileIndex];
+        const result = group.matches[item.matchIndex!];
+        editor.openFileInSplit(
+          panel.sourceSplitId,
+          result.match.file,
+          result.match.line,
+          result.match.column,
+        );
+      }
+      return;
+    }
+  }
+
+  // `toggle` — fired by Enter/Space on a Toggle and by mouse click.
+  // The host fires the event but doesn't mutate the spec's
+  // `checked` field — the plugin owns its model and pushes the
+  // new state back via the targeted `setChecked` mutator (cheaper
+  // than a full spec re-emit). The search rerun happens
+  // independently on debounce; when it finishes it re-emits the
+  // full spec with new matches.
+  if (args.event_type === "toggle") {
+    const newChecked = (args.payload as { checked?: boolean } | undefined)
+      ?.checked;
+    if (typeof newChecked !== "boolean") return;
+    switch (args.widget_key) {
+      case "case":
+        panel.caseSensitive = newChecked;
+        panel.widgetPanel?.setChecked("case", newChecked);
+        rerunSearchDebounced();
+        break;
+      case "regex":
+        panel.useRegex = newChecked;
+        panel.widgetPanel?.setChecked("regex", newChecked);
+        rerunSearchDebounced();
+        break;
+      case "whole":
+        panel.wholeWords = newChecked;
+        panel.widgetPanel?.setChecked("whole", newChecked);
+        rerunSearchDebounced();
+        break;
+      case "matchTree": {
+        // The `[v]`/`[ ]` glyph on a tree row was clicked. Plugin
+        // owns the source-of-truth (`result.selected`) — flip it
+        // and push the new spec state via the targeted mutator.
+        // For file rows we cascade to every child match so a
+        // single click on the file checkbox checks/unchecks the
+        // whole file's matches at once.
+        const idx = (args.payload as { index?: number } | undefined)?.index;
+        if (typeof idx !== "number") return;
+        applyMatchTreeToggle(idx, newChecked);
+        break;
+      }
+    }
+  }
+});
+
+/// Toggle the selected state of a match-tree row at `idx` to
+/// `newChecked`. For a match row, just flips that match. For a
+/// file header, cascades to every child match. Updates the host's
+/// view via `setCheckedKeys` (one call per row that changed
+/// glyph) so the next render reflects the new state without a
+/// full spec re-emit.
+function applyMatchTreeToggle(idx: number, newChecked: boolean): void {
+  if (!panel) return;
+  const flat = buildFlatItems();
+  const item = flat[idx];
+  if (!item) return;
+  if (item.type === "match") {
+    const fileGroup = panel.fileGroups[item.fileIndex];
+    fileGroup.matches[item.matchIndex!].selected = newChecked;
+    const matchKey = flatItemKey(item);
+    panel.widgetPanel?.setCheckedKeys("matchTree", newChecked, [matchKey]);
+    // The file header's checked glyph is derived (all-or-nothing).
+    // After flipping a single match, recompute and push the file
+    // row's new state so it stays in sync with its children.
+    const fileAllSelected = fileGroup.matches.every(m => m.selected);
+    const fileKey = flatItemKey({ type: "file", fileIndex: item.fileIndex });
+    panel.widgetPanel?.setCheckedKeys("matchTree", fileAllSelected, [fileKey]);
+  } else {
+    // File row — cascade to every child.
+    const fileGroup = panel.fileGroups[item.fileIndex];
+    for (const m of fileGroup.matches) m.selected = newChecked;
+    const fileKey = flatItemKey(item);
+    const matchKeys = fileGroup.matches.map((_, mi) =>
+      flatItemKey({ type: "match", fileIndex: item.fileIndex, matchIndex: mi })
+    );
+    panel.widgetPanel?.setCheckedKeys(
+      "matchTree",
+      newChecked,
+      [fileKey, ...matchKeys],
+    );
+  }
+}
+
+// Convert a UTF-8 byte offset into a JS-string character offset,
+// because the host's TextInput cursor model uses bytes (matching the
+// inline-overlay coordinate space) but the plugin's existing code
+// stores `panel.cursorPos` as a char offset. Pure walk over the
+// string until we hit `byteOffset`.
+function byteToCharOffset(value: string, byteOffset: number): number {
+  let bytes = 0;
+  for (let i = 0; i < value.length; i++) {
+    if (bytes >= byteOffset) return i;
+    bytes += byteLen(value[i]);
+  }
+  return value.length;
+}
+
 editor.registerCommand(
   "%cmd.search_replace",
   "%cmd.search_replace_desc",