@narumitw/pi-files 0.0.0-stage → 0.1.0

package/docs/migration.md

@@ -0,0 +1,105 @@
+# Migrate to Pi Files
+
+Pi Files replaces the repository's File Context and Edit Scope implementations with one owner. **Never load `pi-files` together with `pi-file-context` or `pi-edit-scope`.** Duplicate aliases, shortcuts, and guard handlers are not a coordination mechanism; load order cannot make co-loading safe.
+
+Repository retirement is approved. This does not authorize first publication, npm visibility changes, tags, release workflow dispatch, or npm deprecation notices. The read-only `@narumitw/pi-files` metadata query returned `E404` during implementation; Pi Files is not yet published. Use the local build until a release is explicitly approved.
+
+## Prepare
+
+1. Stop the current run and clear pending messages before changing permissions or resources. Record the complete scope target list and whether scope is active or blocked.
+2. Review the context queue. Submit or explicitly remove its snapshots before reload; they are intentionally in-memory only and are not migrated or restored from disk. Do not disable a restriction merely to perform migration.
+3. Record loaded extension sources in both Pi install scopes. Use `pi list` and inspect personal `settings.json` under `getAgentDir()` (normally `~/.pi/agent`) and trusted project `.pi/settings.json`. Also check explicit `-e` arguments, source paths, repository resource filters, and auto-discovered extension files.
+4. Preserve both existing user settings files and a copy of the verification session. Do not rename files, rewrite entry IDs, delete scope state, or remove notices to make recovery appear successful.
+
+Extensions still run with full user permissions. The [native stock-tool boundary](../README.md#-security-and-privacy) is not expanded by the merge, and the user-controlled external editor remains outside the guard.
+
+## Replace installed resources
+
+Personal and project managed npm roots are separate installation scopes. Deduplication within one root does not uninstall or disable another scope's resources. Different source identities, copied files, or explicit CLI resources can still expose a predecessor. A root manifest change cannot remove those installations.
+
+Remove or disable every predecessor resource **before loading the successor**, then reload or restart once the resource set is coherent. Removal changes package/resource registration, not extension-owned settings or session state.
+
+For npm sources matching these examples, remove personal registrations:
+
+```bash
+pi remove npm:@narumitw/pi-file-context
+pi remove npm:@narumitw/pi-edit-scope
+```
+
+From each affected project, remove project registrations independently:
+
+```bash
+pi remove --local npm:@narumitw/pi-file-context
+pi remove --local npm:@narumitw/pi-edit-scope
+```
+
+Use the exact recorded source if an installation uses another path, Git source, or version specification. Do not assume these example commands cover a local copy, a package resource filter, or an explicit `-e` argument. Inspect both scopes after removal.
+
+If a predecessor must remain installed for reference, disable all its extension resources instead. For a package declaration, an `extensions: []` filter loads none of that package's extensions. Apply filtering in the scope that owns the declaration and preserve unrelated resources. Remove old entrypoint selections from Git-repository filters; add `packages/pi-files/src/index.ts` if selecting the successor. Filters only narrow declared resources, so an old pinned repository revision without the successor must be updated first.
+
+Move auto-discovered predecessor extension files outside discovery roots, remove their explicit resource paths, or disable them through Pi's resource configuration. Remove predecessor `-e` arguments from launch scripts. Do not use duplicate command suffixes, shortcut precedence, or one blocking guard to hide a still-loaded predecessor.
+
+The current repository root manifest replaces both predecessor source entries with `./packages/pi-files/src/index.ts`. The archived trees under `deprecated/` are references, excluded from active workspaces and the default root entrypoint list. Installing this repository still enables its other declared extensions unless filtered.
+
+## Build and load the local successor
+
+From the repository root, with predecessor resources removed or disabled:
+
+```bash
+npm install
+npm run build
+pi -e ./packages/pi-files
+```
+
+The root build supplies Pi TUI Kit and generates the successor's `dist/index.ts`. Package-directory loading requires this build; its generated entry does not import back into `src`. Pi's bundled peers stay external. Local loading does not require a published Pi Files package, but dependency installation still requires registry access or an adequate npm cache; this is not a promise of an air-gapped install.
+
+For later sessions, choose the intended registration scope:
+
+1. Personal installation, from the repository root:
+
+   ```bash
+   pi install ./packages/pi-files
+   ```
+
+2. Project installation instead, from each affected project directory:
+
+   ```bash
+   pi install --local /absolute/path/to/pi-extensions/packages/pi-files
+   ```
+
+   Replace the example path with the built checkout path. The current directory selects which project receives the registration; it does not need to be the checkout.
+
+Choose one intended registration rather than loading the same checkout by several paths. Restart Pi or run `/reload` after changing resources. Settings and durable scope restore; queued context does not. Do not send built-in `/reload` as an RPC prompt command, where it can become model input.
+
+## What stays compatible
+
+| Area | Preserved behavior |
+| --- | --- |
+| Commands | `/file-context [browse\|remove]` keeps the dedicated context workflow; `/edit-scope`, `/scope`, and their `off` routes keep the dedicated scope workflow. `/files` adds the common manager, `browse`, and `off`. |
+| Context | Exact snapshots, order, limits, Git provenance, whole-file references, and one-time attachment retain their format. The `file-context-quotes` identity remains unchanged. Custom-triggered turns do not consume the queue. |
+| Scope state | `scope-state`, `scope-contract`, and `scope-context-anchor`, snapshot version 1, original entry IDs, state references, and historical notice bytes remain unchanged. |
+| Recovery | The active branch restores after reload, resume, fork, tree navigation, and compaction as applicable. Invalid or uncertain state stays blocked until repaired or explicitly ended. |
+| Settings | `openShortcut` remains in `<getAgentDir()>/pi-file-context.json`; `showHiddenFiles` remains in `<getAgentDir()>/pi-scope.json`. Unknown fields and existing values are preserved. |
+| Defaults | Browser shortcut is `ctrl+shift+x`; hidden scope discovery defaults to `false`. Settings remain user-only. |
+
+The settings basenames and historical `Scope` / `/scope` notice text are deliberate compatibility exceptions. There is no `pi-files.json`, project settings migration, file renaming, or automatic legacy-file deletion. Do not copy values into Pi's core settings file. See [context settings](file-context-reference.md#settings) and [scope settings](edit-scope-reference.md#settings-and-persistence).
+
+The new common Settings screen uses Pi's `SettingsList`. Only the reload-requiring shortcut action is blocked while context is queued; the hidden-file preference still applies immediately. Dedicated aliases keep their existing settings routes. A successful shortcut save remains saved if automatic reload fails; repair the reload problem and run `/reload` manually.
+
+## Verify the transition
+
+1. Confirm that only the successor owns these commands and the combined status widget. There must be no predecessor resource left loaded, even if no duplicate is visible.
+2. Open `/files`, `/file-context`, `/edit-scope`, and `/scope` in TUI mode. Check the common manager and both dedicated workflows without changing the allowed set. Review Status for the same branch and full targets recorded before migration.
+3. Confirm a restored active restriction still rejects unselected writes and unsupported tools. A blocked restriction must remain blocked; repair targets through scope management or explicitly end it only if that is the intended user action.
+4. Queue a disposable snapshot and confirm this does not authorize its path. Review or remove it without changing scope. Confirm applying or ending scope does not consume context.
+5. Check the two unchanged settings paths. Do not expect old queued snapshots to reappear after reload. Check current automated and manual evidence in [verification](verification.md).
+
+Scope cancellation and run completion do not end restrictions. The explorer and checked-file picker keep distinct Tab, Enter, Escape, input, and paste behavior. There is no combined quote-and-authorize action. See the full [context reference](file-context-reference.md) and [scope reference](edit-scope-reference.md) for discovery, validation, security, and recovery limits.
+
+## Rollback and recovery
+
+Stop the run before rollback. Submit or remove queued context if needed, record the loaded sources, remove or disable Pi Files, restore the predecessor resources together, and reload **without co-loading guards**. Build predecessor resources if their package entrypoints require it. Restore the coherent repository layout and root manifest together through Git recovery when rolling back a checkout.
+
+Retained settings basenames, version-1 scope entries, original entry IDs, and historical notice bytes permit predecessor restoration without rewriting the session. Use copied sessions to verify forward and reverse recovery. Do not delete state, change IDs, or discard anchors to recover unrestricted access. A failed or uncertain scope publication stays blocked until the user repairs the target set or explicitly ends the restriction. If restoration differs from the recorded branch state, stop guarded work and inspect recovery rather than bypassing it.
+
+Registry unpublication, visibility changes, npm deprecation, tags, releases, and release workflow dispatch are not rollback steps authorized by this merge.

package/docs/verification.md

@@ -0,0 +1,99 @@
+# Pi Files verification
+
+Pi Files has one extension factory and two independent domain services. The repository cutover replaces both predecessor entrypoints with `packages/pi-files/src/index.ts`; archived sources and tests remain under `deprecated/`. The maintainer authorized this retirement through the end-to-end implementation request. Publication and npm deprecation remain unauthorized.
+
+## Compatibility baseline
+
+Baseline commit: `30ef6143`. Before moving sources, all 33 predecessor suites passed: 597 tests passed and one existing path test was skipped. Direct tests require canonical `TMPDIR` on macOS, as the root test runner already provides; otherwise `/var` versus `/private/var` fixture expectations differ. No production path behavior was changed to hide that fixture issue.
+
+| Area | Preserved contract | Evidence |
+| --- | --- | --- |
+| Context | Ordered immutable snapshots; unchanged XML escaping, Git provenance, bounds, `file-context-quotes` identity, and custom-turn exclusion. | Migrated context, pending-quote, Git, search, preview, and external-editor suites. |
+| Permissions | Context never grants permission; scope never loads content or consumes context. | `files-integration.test.ts` tests attachment, apply/off, tree restoration, and concurrent owners. |
+| Durable scope | Snapshot version 1; `scope-state`, `scope-contract`, `scope-context-anchor`; original entry IDs and historical notice bytes. | `migration.test.ts` executes extracted predecessor pure readers and successor readers in both directions, including delayed publication and compaction recovery. |
+| Lifecycle | Scope restores on start/tree; context resets on start/shutdown, not same-manager tree navigation. Restrictions survive run completion and cancellation. | Migrated scope runtime/lifecycle tests and merged integration tests. |
+| Settings | User-only `pi-file-context.json` and `pi-scope.json`; unchanged fields/defaults; no canonical-file migration or automatic writes. | Existing store suites, generated-entry byte-preservation checks, and combined Settings tests. |
+| UI | Dedicated context explorer and checked-file picker; existing navigation, editing, paste, custom bindings, and cancellation. | Migrated UI/picker/explorer suites plus native common Settings tests. |
+| Loading | One factory, eager guard registration, lazy specialized UI, external Pi/Kit imports, exact generated paths. | Builder/eager-graph tests, generated-entry Jiti test, and clean production-install fixture. |
+
+The source guidance to prefer direct user-owned context selection is retained in the successor's `AGENTS.md`. Existing changelogs remain in the archives. The pending predecessor breadth-first Changeset is retained in its archive's `release-notes/`; its behavior is included in the successor's release intent instead of targeting a removed workspace.
+
+## Decision branches and safety review
+
+Tool-policy tests cover inactive, active, blocked, invalid, and uninitialized state; stock readers versus same-named replacements; selected versus unselected native writers; and shell, codemode, delegation, unknown tools, and `readOnlyHint` tools. Loadout tests cover the presence or absence of a stock direct writer and active native `codemode.mode=only`. The service does not change core settings or active tool definitions to make a loadout acceptable.
+
+Path tests cover exact canonical targets, lexical aliases, symlink changes, hard links, existing files, reservations, removed targets, workspace mismatch, and validation interrupted by cancellation or scope replacement. Uncertain state publication remains blocked even when a session append changed memory before disk failure. Scope, contract, path, policy, and settings implementations retain the predecessor's formats and enforcement decisions.
+
+The quote queue remains independent under ordinary/custom turns, duplicate-looking snapshots, limits, review/removal, scope apply/off, reload, tree navigation, and shutdown. Tests also cover two headless session managers sharing one no-op UI object. Missing or invalid context is not converted into edit authorization.
+
+External editing remains user-controlled and outside native-tool enforcement. Project trust, contained regular worktree targets, final-symlink rejection, mutation-queue ownership, process cancellation, terminal restoration, and preview reload retain their previous checks. This is not an OS sandbox or an attestation of arbitrary SDK tool overrides. Historical revisions remain read-only.
+
+### Lifecycle and ownership
+
+Services own resources by `sessionManager`. Each UI flow also has a cancellation controller; only one context, scope, or manager flow is active for an owner. Repeated context openings can join their existing flow. Other overlapping openings are rejected, and invalid arguments still receive their original usage error rather than joining an unrelated operation.
+
+Lifecycle hooks abort the common flow without awaiting the reload-dependent command. Waiting for that command would deadlock because `ctx.reload()` itself waits for shutdown. Domain cleanup drains native tasks and settings writes instead. Both common Settings and the legacy context settings route have regression tests where reload invokes shutdown/start from inside the command while scope remains active.
+
+Discovery and Git initialization promises are tracked separately, so one failure cannot hide a surviving sibling. Git contexts track their individual subprocess requests and drain them after explorer cancellation; initialization settles every read, and Git calls wait for child close before releasing ownership. Completed explorers release their Git context instead of retaining each project's status map for the session. File reads and external-editor processes also join the owner's native-work set. Consumer/widget errors do not skip cleanup. Held-task regression tests verify that shutdown waits for work to settle after cancellation or a sibling failure.
+
+Owner keys are captured before asynchronous work. A stale settings refresh returns without reading its invalidated context; shortcut writes combine the caller and owner signals. Permission operations revalidate ownership, revision, loadout, and targets. Cancellation closes transient UI, not a persisted restriction.
+
+### Settings and terminal compatibility
+
+The common screen uses Pi's native `SettingsList` and `getSettingsListTheme()`, an input submenu, and Kit's bounded frame with content-row mapping for mouse routing. The mapped frame implementation preserves the same framing rules as `renderBoundedFrame()`. Unknown fields and invalid-file protection stay in the two owning stores; queues provide in-process ordering, not a cross-process lock.
+
+Tests cover immediate hidden-file saves, queued/invalid context blocking only the shortcut, rapid action order, write failures and retry, reload failure, stale continuation, disposal, pending-write drain, input focus, paste, width/height limits, callback theme roles, terminal modes, and non-default keybindings. Host-owned disposal settles the local flow without calling Pi's `done()`, so native dialog-reset iteration and the replacement editor draft stay intact. Configured native actions retain their priority over remapped Escape; only Ctrl+C remains a hard cancel. The 63-case Settings suite includes real Pi reset methods, two dialogs, delayed writes, aliases, modifier order, legacy collisions, terminal modes, invalid bindings, and fallback selection. The explorer returns no cells for zero or unusable widths instead of forcing a one-cell frame; all seven modes have boundary regressions, and normal-width behavior is unchanged. Physical key delivery is not established by these tests.
+
+Compatibility exceptions are intentional: legacy commands keep their dedicated managers and settings routes; settings basenames and historical `/scope` notice text remain unchanged; the scope picker retains its bottom-overlay layout. The external editor does not become scope-enforced. The new combined widget uses only the `files` key, keeps the restriction and exit route separate from context summaries, and clears only its owned key.
+
+### Model-visible context
+
+No tools or prompt metadata are registered, activated, removed, or rewritten by this merge. Existing scope notice bytes, entry IDs, anchors, quote serialization, and additive publication are retained. Ordinary requests preserve normalized model-visible prefixes; compaction recovery remains deterministic and deduplicated after the original contract disappears. Merged tests exercise quote attachment with active scope and restoration; predecessor contract/runtime suites retain delayed-publication, branch, compaction, and normalized-prefix cases. Package, command-menu, and widget naming changes are not model-prefix transitions.
+
+## Verification evidence
+
+Applicable guides: `docs/extension-conventions.md`, `docs/extension-settings.md`, `docs/readme-conventions.md`, `docs/runtime-builder.md`, and the retained package guidance. Semantic review covers all touched areas above rather than treating root gates as a complete behavior audit.
+
+Completed verification:
+
+- Root `npm install` and `npm ls @narumitw/pi-tui-kit`: passed; the successor resolves to the workspace version satisfying its manifest floor.
+- `npm run check`: passed builds, Biome, package boundaries, and all workspace typechecks.
+- Final full `npm test`: 930 files passed; 20,215 tests passed and 34 skipped, with no unhandled errors. The emitted Settings test fixture was newer than its final source and included all 63 cases.
+- Final focused package/production suites: 39 files passed; 708 tests passed and one existing skip.
+- Native CLI smokes passed explicit generated loading, trusted-project generated auto-discovery, trust denial, RPC, print, JSON, observable scope/Files command rejection, and shutdown. No provider request was sent. The discovery fixture supplies a temporary dependency ancestor to model a real package installation under Jiti's lexical resolution.
+- Bidirectional migration, exact historical notice/anchor bytes, generated Jiti lazy browsing, and production Git-install fixtures passed.
+- Explicit successor build, `npm run package:pack -- files`, and actual temporary packing passed. The tarball contains 64 files, including runtime, source, documentation, changelog, README, and license; tests and build scripts are absent. Packed runtime hashes equal the validated generated output.
+- Clean tarball installation outside the workspace passed dependency resolution, actual CLI smokes, and a lazy browser/startup/shutdown smoke through that installation's own Pi SDK and Kit. Use canonical temporary paths on macOS; the initial `npm --prefix` fixture produced misleading local-file metadata across `/tmp` aliases, so the verified fixture installs from its canonical working directory.
+- Fenced-code-aware heading audits passed for 37 READMEs, with 85 local links/anchors checked. All 79 archived predecessor files retain exact content except the two explicit README warnings. Five scope policy/persistence modules are byte-identical, and eight compiler-normalized quote/discovery functions retain exact bodies.
+- Changesets status passed for the successor only. A read-only successor registry query returned E404; no package was published.
+- Final semantic review covered correctness, security, lifecycle, compatibility, regressions, and scope. Review-found native-work, host-disposal, native-key priority, and project-install-directory issues were fixed with representative regressions or corrected instructions. There are no intentional model-prefix changes or unresolved implementation findings.
+
+### Startup samples
+
+Separate-process samples used the existing startup benchmark, cold Jiti cache mode, one warm-up, and three measured runs per configuration on macOS/arm64. Values are medians, not a deterministic gate or a provider-latency claim.
+
+| Loadout | Package import time | First command response |
+| --- | --- | --- |
+| Archived predecessor source pair | 266 ms | 396.61 ms |
+| Successor source entrypoint | 199 ms | 329.20 ms |
+| Successor generated entrypoint | 147 ms | 275.59 ms |
+
+All samples used isolated agent directories and sent only command-discovery requests. An intermediate full test run had seven process-startup/deadline failures in four unchanged suites; all 53 tests in those suites passed on a focused rerun, and the final full gate passed without concurrent build/smoke commands or timeout changes. Existing unrelated Biome schema/version informational notices remain; checks exit successfully. Physical-terminal and unavailable-platform items below remain external handoff, not passing automated results.
+
+## Retained external handoff
+
+### Physical terminal and unavailable platforms
+
+Responsible role: terminal/platform tester. Prerequisites: the built successor and the recorded deterministic/offline loading evidence. Exercise browsing, content search, exact-line review, scope apply/off, external editing, hard cancellation, reload, custom keys, paste/IME, and narrow/fullscreen layouts on the target terminal. Exercise native Windows path behavior on Windows.
+
+Expected result: usable input, focus, terminal restoration, and the documented guard boundary. Unverified until performed: physical key delivery, subjective usability, unavailable-platform behavior, and native Windows editor launch. Do not claim those environments were verified. Record any discovered defect and its release impact before making a compatibility claim; deterministic checks do not establish product acceptance.
+
+### First publication
+
+Responsible role: package owner. Prerequisites: final implementation evidence, registry-name/ownership/visibility verification, and explicit publication approval. Approve and perform first publication through the repository's approved path; approve npm deprecation notices separately.
+
+Expected result: an independently installable successor with accurate migration instructions. Unverified until performed: registry ownership, first-publication visibility, and installation of the released npm artifact. No publication, visibility change, version tag, release workflow dispatch, or npm deprecation is authorized by this merge. Local tarball verification is not release approval.
+
+## Recovery
+
+Follow [migration and rollback](migration.md). Stop the run, record resource scopes and target state, remove or disable the currently active implementation, and reload a coherent successor or predecessor resource set without co-loading guards. Retain both settings files and the original session entries. Do not delete state or bypass a guard to recover unrestricted editing; uncertain restoration remains blocked until repaired or explicitly ended.

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@narumitw/pi-files",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Browse and attach file context, and independently limit native Pi edits to selected targets.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "file-explorer",
+    "git",
+    "context",
+    "quote",
+    "edit-scope",
+    "file-editing",
+    "allowlist"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/index.ts"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build-runtime.mjs",
+    "check": "npm run build && biome check . && npm run typecheck",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@narumitw/pi-tui-kit": "^0.69.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "1.5.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
+    "esbuild": "0.28.2",
+    "typescript": "7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/narumiruna/pi-extensions",
+    "directory": "packages/pi-files"
+  }
+}

package/src/content-search-session.ts

@@ -0,0 +1,204 @@
+import type { KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { Input, Key, matchesKey, type TUI, visibleWidth } from "@earendil-works/pi-tui";
+import { type ContentSearchMatch, searchProjectContents } from "./content-search.js";
+import { contentSearchCardCapacity, renderContentSearchScreen } from "./content-search-ui.js";
+import type { LoadedProjectTextFile } from "./file-context.js";
+
+interface ContentSearchSessionOptions {
+  tui: TUI;
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  files: readonly string[];
+  cwd?: string;
+  loadFile: (path: string, signal?: AbortSignal) => Promise<LoadedProjectTextFile>;
+  onPreview: (match: ContentSearchMatch) => void;
+  onReference: (path: string) => void;
+  onSwitchFiles: () => void;
+  onCancel: () => void;
+}
+
+export class ContentSearchSession {
+  private readonly input = new Input();
+  private matches: ContentSearchMatch[] = [];
+  private selectedIndex = 0;
+  private scrollOffset = 0;
+  private caseSensitive = false;
+  private fuzzy = false;
+  private truncated = false;
+  private skippedFiles = 0;
+  private loading = false;
+  private request = 0;
+  private controller: AbortController | undefined;
+  private error: string | undefined;
+  private disposed = false;
+
+  constructor(private readonly options: ContentSearchSessionOptions) {}
+
+  set focused(value: boolean) {
+    this.input.focused = value;
+  }
+
+  activate(): void {
+    this.disposed = false;
+    if (this.input.getValue().trim()) this.startSearch();
+  }
+
+  deactivate(): void {
+    this.focused = false;
+    this.cancelSearch();
+  }
+
+  render(width: number, availableRows: number, opening: boolean, externalError?: string): string[] {
+    const capacity = contentSearchCardCapacity(availableRows);
+    this.keepSelectionVisible(capacity);
+    const queryLabel = this.options.theme.fg("muted", "Search: ");
+    const queryWidth = Math.max(1, width - visibleWidth(queryLabel));
+    const queryLine = `${queryLabel}${this.input.render(queryWidth)[0] ?? ""}`;
+    return renderContentSearchScreen({
+      theme: this.options.theme,
+      width,
+      availableRows,
+      queryLine,
+      query: this.input.getValue(),
+      cwd: this.options.cwd,
+      matches: this.matches,
+      selectedIndex: this.selectedIndex,
+      scrollOffset: this.scrollOffset,
+      caseSensitive: this.caseSensitive,
+      fuzzy: this.fuzzy,
+      loading: this.loading,
+      opening,
+      truncated: this.truncated,
+      skippedFiles: this.skippedFiles,
+      error: externalError ?? this.error,
+    });
+  }
+
+  handleInput(data: string): void {
+    if (this.disposed) return;
+    if (matchesKey(data, Key.ctrl("f"))) {
+      this.options.onSwitchFiles();
+      return;
+    }
+    if (matchesKey(data, Key.escape)) {
+      this.options.onCancel();
+      return;
+    }
+    if (matchesKey(data, Key.alt("c"))) {
+      this.caseSensitive = !this.caseSensitive;
+      this.startSearch();
+      return;
+    }
+    if (matchesKey(data, Key.alt("f"))) {
+      this.fuzzy = !this.fuzzy;
+      this.startSearch();
+      return;
+    }
+    if (this.options.keybindings.matches(data, "tui.select.up")) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+      return;
+    }
+    if (this.options.keybindings.matches(data, "tui.select.down")) {
+      this.selectedIndex = Math.min(Math.max(0, this.matches.length - 1), this.selectedIndex + 1);
+      return;
+    }
+    if (this.options.keybindings.matches(data, "tui.select.pageUp")) {
+      this.selectedIndex = Math.max(0, this.selectedIndex - 10);
+      return;
+    }
+    if (this.options.keybindings.matches(data, "tui.select.pageDown")) {
+      this.selectedIndex = Math.min(Math.max(0, this.matches.length - 1), this.selectedIndex + 10);
+      return;
+    }
+    if (this.options.keybindings.matches(data, "tui.select.confirm")) {
+      const match = this.matches[this.selectedIndex];
+      if (match) this.options.onPreview(match);
+      return;
+    }
+    if (this.options.keybindings.matches(data, "tui.input.tab")) {
+      const match = this.matches[this.selectedIndex];
+      if (match) this.options.onReference(match.path);
+      return;
+    }
+
+    const previousQuery = this.input.getValue();
+    this.input.handleInput(data);
+    if (this.input.getValue() !== previousQuery) this.startSearch();
+  }
+
+  invalidate(): void {
+    this.input.invalidate();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.cancelSearch();
+  }
+
+  private startSearch(): void {
+    this.cancelSearch();
+    const query = this.input.getValue();
+    this.matches = [];
+    this.selectedIndex = 0;
+    this.scrollOffset = 0;
+    this.truncated = false;
+    this.skippedFiles = 0;
+    this.error = undefined;
+    if (!query.trim()) return;
+
+    const request = this.request;
+    const controller = new AbortController();
+    this.controller = controller;
+    this.loading = true;
+    void searchProjectContents(this.options.files, this.options.loadFile, query, {
+      caseSensitive: this.caseSensitive,
+      fuzzy: this.fuzzy,
+      signal: controller.signal,
+    })
+      .then((result) => {
+        if (!this.isCurrent(request, controller)) return;
+        this.matches = result.matches;
+        this.truncated = result.truncated;
+        this.skippedFiles = result.skippedFiles;
+      })
+      .catch((error: unknown) => {
+        if (this.isCurrent(request, controller) && !isAbortError(error)) {
+          this.error = formatError(error);
+        }
+      })
+      .finally(() => {
+        if (request === this.request) {
+          this.loading = false;
+          this.controller = undefined;
+        }
+        if (!this.disposed) this.options.tui.requestRender();
+      });
+  }
+
+  private cancelSearch(): void {
+    this.request += 1;
+    this.controller?.abort();
+    this.controller = undefined;
+    this.loading = false;
+  }
+
+  private isCurrent(request: number, controller: AbortController): boolean {
+    return !this.disposed && request === this.request && this.controller === controller && !controller.signal.aborted;
+  }
+
+  private keepSelectionVisible(capacity: number): void {
+    if (this.selectedIndex < this.scrollOffset) this.scrollOffset = this.selectedIndex;
+    if (this.selectedIndex >= this.scrollOffset + capacity) {
+      this.scrollOffset = this.selectedIndex - capacity + 1;
+    }
+  }
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+function formatError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/content-search-ui.ts

@@ -0,0 +1,159 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ContentMatchRange, ContentSearchMatch } from "./content-search.js";
+
+export const CONTENT_SEARCH_CARD_ROWS = 3;
+
+interface ContentSearchScreenOptions {
+  theme: Theme;
+  width: number;
+  availableRows: number;
+  queryLine: string;
+  query: string;
+  cwd?: string;
+  matches: readonly ContentSearchMatch[];
+  selectedIndex: number;
+  scrollOffset: number;
+  caseSensitive: boolean;
+  fuzzy: boolean;
+  loading: boolean;
+  opening: boolean;
+  truncated: boolean;
+  skippedFiles: number;
+  error?: string;
+}
+
+export function contentSearchCardCapacity(availableRows: number): number {
+  return Math.max(1, Math.floor((availableRows - 4) / CONTENT_SEARCH_CARD_ROWS));
+}
+
+export function renderContentSearchScreen(options: ContentSearchScreenOptions): string[] {
+  const { theme, width, availableRows } = options;
+  const capacity = contentSearchCardCapacity(availableRows);
+  const cwdLabel = options.cwd ? ` · cwd: ${escapeTerminalControls(options.cwd)}` : "";
+  const title = theme.fg("accent", theme.bold(`File Context · Content Search${cwdLabel}`));
+  const modes = theme.fg(
+    "muted",
+    `Case: ${options.caseSensitive ? "on" : "off"} · Fuzzy: ${options.fuzzy ? "on" : "off"} · Alt+C case · Alt+F fuzzy`,
+  );
+  const body: string[] = [];
+
+  if (options.error) {
+    body.push(theme.fg("error", `  Search failed: ${escapeTerminalControls(options.error)}`));
+  } else if (options.loading) {
+    body.push(theme.fg("warning", "  Searching…"));
+  } else if (!options.query.trim()) {
+    body.push(theme.fg("muted", "  Type text to search project contents"));
+  } else if (options.matches.length === 0) {
+    body.push(
+      theme.fg(
+        "muted",
+        `  No matches for "${escapeTerminalControls(options.query)}"${options.fuzzy ? "" : " · Alt+F enables fuzzy matching"}`,
+      ),
+    );
+  } else {
+    const visible = options.matches.slice(options.scrollOffset, options.scrollOffset + capacity);
+    for (let visibleIndex = 0; visibleIndex < visible.length; visibleIndex += 1) {
+      const index = options.scrollOffset + visibleIndex;
+      const match = visible[visibleIndex];
+      if (match) {
+        body.push(...renderContentSearchCard(match, index === options.selectedIndex, width, theme));
+      }
+    }
+  }
+
+  const count = `${options.matches.length}${options.truncated ? "+" : ""} matches`;
+  const skipped = options.skippedFiles > 0 ? ` · ${options.skippedFiles} skipped` : "";
+  const action = options.opening
+    ? "Opening…"
+    : `${count}${skipped} · ↑↓ navigate · Enter preview · Tab reference · Ctrl+F files · Esc cancel`;
+  return fitRows(
+    [
+      truncateToWidth(title, width, ""),
+      truncateToWidth(options.queryLine, width, ""),
+      truncateToWidth(modes, width, ""),
+      ...body.map((line) => truncateToWidth(line, width, "")),
+      truncateToWidth(theme.fg(options.opening ? "warning" : "muted", action), width, ""),
+    ],
+    availableRows,
+  );
+}
+
+export function highlightContentRanges(line: string, ranges: readonly ContentMatchRange[], theme: Theme): string {
+  let result = "";
+  let index = 0;
+  for (const range of ranges) {
+    const start = Math.max(index, Math.min(line.length, range.start));
+    const end = Math.max(start, Math.min(line.length, range.end));
+    result += escapeTerminalControls(line.slice(index, start));
+    result += theme.fg("warning", theme.bold(escapeTerminalControls(line.slice(start, end))));
+    index = end;
+  }
+  return result + escapeTerminalControls(line.slice(index));
+}
+
+function renderContentSearchCard(match: ContentSearchMatch, selected: boolean, width: number, theme: Theme): string[] {
+  if (width < 8) {
+    return [truncateToWidth(`${selected ? ">" : " "}${escapeTerminalControls(match.path)}`, width, "")];
+  }
+  const prefix = selected ? theme.fg("accent", "> ") : "  ";
+  const cardWidth = Math.max(4, width - visibleWidth(prefix));
+  const innerWidth = Math.max(1, cardWidth - 2);
+  const borderColor = selected ? "borderAccent" : "borderMuted";
+  const border = (text: string) => theme.fg(borderColor, text);
+  const rawTitle = ` ${escapeTerminalControls(match.path)} · L${match.lineNumber} `;
+  const title = truncateToWidth(rawTitle, innerWidth, "");
+  const titleFill = "─".repeat(Math.max(0, innerWidth - visibleWidth(title)));
+  const context = clipMatchContext(match, Math.max(1, innerWidth - 1));
+  const highlighted = highlightContentRanges(context.line, context.ranges, theme);
+  const content = truncateToWidth(` ${highlighted}`, innerWidth, "");
+  const contentFill = " ".repeat(Math.max(0, innerWidth - visibleWidth(content)));
+  const contentLine = `${border("│")}${content}${contentFill}${border("│")}`;
+  return [
+    `${prefix}${border("╭")}${title}${border(`${titleFill}╮`)}`,
+    `${" ".repeat(visibleWidth(prefix))}${selected ? theme.bg("selectedBg", contentLine) : contentLine}`,
+    `${" ".repeat(visibleWidth(prefix))}${border(`╰${"─".repeat(innerWidth)}╯`)}`,
+  ];
+}
+
+function clipMatchContext(
+  match: ContentSearchMatch,
+  maxCharacters: number,
+): { line: string; ranges: ContentMatchRange[] } {
+  const firstStart = match.ranges[0]?.start ?? 0;
+  const lastEnd = match.ranges.at(-1)?.end ?? firstStart;
+  const matchSpan = Math.max(1, lastEnd - firstStart);
+  const before = Math.max(0, Math.floor((maxCharacters - Math.min(matchSpan, maxCharacters)) / 3));
+  const rawStart = Math.max(0, firstStart - before);
+  const prefix = rawStart > 0 ? "…" : "";
+  const availableRawCharacters = Math.max(1, maxCharacters - prefix.length - 1);
+  let rawEnd = Math.min(match.line.length, rawStart + availableRawCharacters);
+  if (rawEnd < lastEnd) rawEnd = Math.min(match.line.length, lastEnd);
+  const suffix = rawEnd < match.line.length ? "…" : "";
+  const line = `${prefix}${match.line.slice(rawStart, rawEnd)}${suffix}`;
+  const ranges = match.ranges.flatMap((range): ContentMatchRange[] => {
+    const start = Math.max(rawStart, range.start);
+    const end = Math.min(rawEnd, range.end);
+    return end > start ? [{ start: prefix.length + start - rawStart, end: prefix.length + end - rawStart }] : [];
+  });
+  return { line, ranges };
+}
+
+function fitRows(lines: string[], height: number): string[] {
+  if (lines.length <= height) return lines;
+  if (height <= 1) return lines.slice(0, 1);
+  return [...lines.slice(0, height - 1), lines.at(-1) ?? ""];
+}
+
+function escapeTerminalControls(text: string): string {
+  return [...text]
+    .map((character) => {
+      if (character === "\t") return "    ";
+      const code = character.charCodeAt(0);
+      if (code <= 31 || (code >= 127 && code <= 159)) {
+        return `\\x${code.toString(16).padStart(2, "0")}`;
+      }
+      return character;
+    })
+    .join("");
+}