@plannotator/ui 0.25.0 → 0.27.0

package/README.md

@@ -30,6 +30,38 @@ configurePlannotatorUI({
 
 Anything you don't pass keeps Plannotator's default. A few component-specific overrides (e.g. an "open in editor" diff action) are passed as props where you render that component.
 
+### Resize-handle seams (`ResizeHandle` / `useResizablePanel`)
+
+The sidebar/panel resize handle exposes seams for hosts that want different edge interactions (e.g. no hover reveal, click-to-collapse). All default to today's behavior — pass nothing and it's unchanged.
+
+- **Suppress / restyle the hover reveal.** The inner visible track carries a `[data-resize-track]` attribute (same host-CSS pattern as the collapse button's `[data-collapse]`), and `ResizeHandle` takes a `trackClassName` prop. To kill the pop-in from host CSS:
+  ```css
+  [data-resize-track] { background: none !important; }
+  ```
+- **Click-to-collapse anywhere on the handle.** The handle can't tell a click from a drag-start on its own — the hook owns the pointer state machine. Pass `onClick` to `useResizablePanel`; it fires on pointer-up only when the pointer never traveled past `clickThreshold` (default 4px), so a genuine click on the full-width handle can collapse the panel while drags still resize:
+  ```ts
+  const resize = useResizablePanel({ storageKey, side: "left", onSnapClose: collapse, onClick: collapse });
+  ```
+
+Building your own tooltip and removing the built-in double-click reset are host-side concerns (override `onDoubleClick` where you render the handle).
+
+### Markdown editor extensions + wiki links (`MarkdownEditor` / `InlineMarkdown`)
+
+- **`MarkdownEditor` takes CM6 extensions.** `extensions?: readonly Extension[]` (from `@codemirror/state`) is forwarded verbatim into the underlying editor — the seam for `wikiLinks(config)`, `y-codemirror.next` collab bindings, custom keymaps.
+
+  > **⚠️ Captured once per `documentId` — not reactive.** The engine reads the array a single time at document mount; swapping the array later is silently ignored until a `documentId` change remounts. Pass a stable reference, and feed changing data through extension config callbacks that close over live state (refs/getters) — never through new arrays.
+
+- **`wikiLinks` is re-exported from `@plannotator/ui/components/MarkdownEditor`** together with `WikiLinksConfig`, `WikiLinkSuggestion`, `WikiLinkResolvedTarget`, `WikiLinkStatus`. Import it from there — `@plannotator/atomic-editor` stays off the supported-import list:
+  ```tsx
+  import { MarkdownEditor, wikiLinks } from "@plannotator/ui/components/MarkdownEditor";
+
+  const editorExtensions = [wikiLinks({ suggest, resolve, onOpen })]; // stable reference!
+  <MarkdownEditor markdown={md} documentId={docId} editorHandleRef={ref} extensions={editorExtensions} />
+  ```
+- **The viewer resolves wiki-links synchronously.** `InlineMarkdown` takes `resolveLinkedDoc?: (target) => { label?; status?: 'active' | 'deleted' } | null` — called with the raw stored target (opaque ids like `doc_01XYZ`, no `.md` normalization). Return a `label` to display live titles (stored label is the fallback, target the last resort); return `status: 'deleted'` for a muted non-link ("Document deleted") instead of a live link. Absent or `null` → rendering is unchanged. Sync-only by design: back it with an in-memory cache.
+
+Requires `@plannotator/markdown-editor ^0.3.2` and `@plannotator/atomic-editor ^0.7.0`. See HANDOFF.md § "Wiki-link seams (0.27.0)".
+
 ## Consuming it (e.g. from Workspaces)
 
 ```bash

package/components/InlineMarkdown.tsx

@@ -443,12 +443,28 @@ function emitPlainTextWithBareUrls(
 export const InlineMarkdown: React.FC<{
   text: string;
   onOpenLinkedDoc?: (path: string) => void;
+  /**
+   * SYNCHRONOUS wiki-link resolution (host-backed, e.g. an in-memory cache).
+   * Called with the RAW stored target of a `[[target]]` / `[[target|label]]`
+   * wiki-link — before any path normalization (no `.md` appended), so opaque
+   * ids like `doc_01XYZ` arrive verbatim.
+   *
+   * Absent, or returning null/undefined → exactly today's rendering (stored
+   * label, live link). `label` → displayed instead of the stored label (the
+   * stored label is the fallback, the target the last resort). `status:
+   * 'deleted'` → a muted, non-interactive span (no anchor, no link icon,
+   * `onOpenLinkedDoc` is NOT wired) titled "Document deleted".
+   *
+   * Deliberately sync-only: no async variant, no loading states. Back it
+   * with a cache you keep hydrated.
+   */
+  resolveLinkedDoc?: (target: string) => { label?: string; status?: 'active' | 'deleted' } | null;
   onOpenCodeFile?: (path: string) => void;
   onNavigateAnchor?: (hash: string) => void;
   imageBaseDir?: string;
   onImageClick?: (src: string, alt: string) => void;
   githubRepo?: string;
-}> = ({ text, onOpenLinkedDoc, onOpenCodeFile, onNavigateAnchor, imageBaseDir, onImageClick, githubRepo }) => {
+}> = ({ text, onOpenLinkedDoc, resolveLinkedDoc, onOpenCodeFile, onNavigateAnchor, imageBaseDir, onImageClick, githubRepo }) => {
   const validation = useCodePathValidation();
   const parts: React.ReactNode[] = [];
   let remaining = text;
@@ -614,6 +630,7 @@ export const InlineMarkdown: React.FC<{
             onImageClick={onImageClick}
             text={match[1]}
             onOpenLinkedDoc={onOpenLinkedDoc}
+            resolveLinkedDoc={resolveLinkedDoc}
             onOpenCodeFile={onOpenCodeFile}
             onNavigateAnchor={onNavigateAnchor}
             githubRepo={githubRepo}
@@ -636,6 +653,7 @@ export const InlineMarkdown: React.FC<{
               onImageClick={onImageClick}
               text={match[1]}
               onOpenLinkedDoc={onOpenLinkedDoc}
+              resolveLinkedDoc={resolveLinkedDoc}
               onOpenCodeFile={onOpenCodeFile}
               onNavigateAnchor={onNavigateAnchor}
               githubRepo={githubRepo}
@@ -658,6 +676,7 @@ export const InlineMarkdown: React.FC<{
             onImageClick={onImageClick}
             text={match[1]}
             onOpenLinkedDoc={onOpenLinkedDoc}
+            resolveLinkedDoc={resolveLinkedDoc}
             onOpenCodeFile={onOpenCodeFile}
             onNavigateAnchor={onNavigateAnchor}
             githubRepo={githubRepo}
@@ -679,6 +698,7 @@ export const InlineMarkdown: React.FC<{
             onImageClick={onImageClick}
             text={match[1]}
             onOpenLinkedDoc={onOpenLinkedDoc}
+            resolveLinkedDoc={resolveLinkedDoc}
             onOpenCodeFile={onOpenCodeFile}
             onNavigateAnchor={onNavigateAnchor}
             githubRepo={githubRepo}
@@ -701,6 +721,7 @@ export const InlineMarkdown: React.FC<{
             onImageClick={onImageClick}
             text={match[1]}
             onOpenLinkedDoc={onOpenLinkedDoc}
+            resolveLinkedDoc={resolveLinkedDoc}
             onOpenCodeFile={onOpenCodeFile}
             onNavigateAnchor={onNavigateAnchor}
             githubRepo={githubRepo}
@@ -834,12 +855,28 @@ export const InlineMarkdown: React.FC<{
     match = remaining.match(/^\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/);
     if (match) {
       const target = match[1].trim();
-      const display = match[2]?.trim() || target;
+      const storedLabel = match[2]?.trim();
+      // Host resolution gets the RAW target (pre-`.md` normalization): host
+      // targets are opaque doc ids, not paths. null → today's rendering.
+      const resolution = resolveLinkedDoc?.(target) ?? null;
+      const display = resolution?.label || storedLabel || target;
       const targetPath = /\.(mdx?|txt|html?)$/i.test(target)
         ? target
         : `${target}.md`;
 
-      if (onOpenLinkedDoc) {
+      if (resolution?.status === 'deleted') {
+        // Deleted doc: muted NON-link — no anchor, no pointer, no link icon —
+        // even when onOpenLinkedDoc is present.
+        parts.push(
+          <span
+            key={key++}
+            className="text-muted-foreground line-through decoration-muted-foreground/60"
+            title="Document deleted"
+          >
+            {display}
+          </span>,
+        );
+      } else if (onOpenLinkedDoc) {
         parts.push(
           <a
             key={key++}
@@ -1061,6 +1098,7 @@ export const InlineMarkdown: React.FC<{
             key={key++}
             text={before}
             onOpenLinkedDoc={onOpenLinkedDoc}
+            resolveLinkedDoc={resolveLinkedDoc}
             onOpenCodeFile={onOpenCodeFile}
             onNavigateAnchor={onNavigateAnchor}
             githubRepo={githubRepo}

package/components/MarkdownEditor.tsx

@@ -3,11 +3,37 @@ import {
   MarkdownEditor as PackagedMarkdownEditor,
   type MarkdownEditorHandle,
 } from '@plannotator/markdown-editor';
+import type { Extension } from '@codemirror/state';
 import '@plannotator/markdown-editor/themes/plannotator.css';
 import { useTheme } from './ThemeProvider';
 
 export type { MarkdownEditorHandle };
 
+/* Wiki-links, re-exported through the ui surface. @plannotator/ui is the single
+   supported contract for hosts — do NOT import @plannotator/atomic-editor
+   directly (it's outside the import allowlist). Build the extension with
+   wikiLinks(config) and pass it through the `extensions` prop below; the
+   capture-once-per-documentId caveat on `extensions` applies (config callbacks
+   like suggest/resolve/onOpen may close over live state). */
+export { wikiLinks } from '@plannotator/atomic-editor';
+export type {
+  WikiLinksConfig,
+  WikiLinkSuggestion,
+  WikiLinkResolvedTarget,
+  WikiLinkStatus,
+} from '@plannotator/atomic-editor';
+
+/* The engine's other opt-in UI extensions, re-exported for the same reason:
+   slashCommands() is a Notion-style insert menu on `/` at the start of a
+   line; selectionToolbar() is a floating bold/italic/strike/code/link bar
+   over selected text (multi-line and table-cell aware). Both compose
+   through the `extensions` prop and theme via the --atomic-editor-menu-*
+   CSS variables. */
+export { defaultSlashCommands, slashCommandSource, slashCommands } from '@plannotator/atomic-editor';
+export type { SlashCommandItem, SlashCommandsConfig } from '@plannotator/atomic-editor';
+export { selectionToolbar } from '@plannotator/atomic-editor';
+export type { SelectionToolbarConfig, InlineFormat } from '@plannotator/atomic-editor';
+
 /* Grid-mode card utilities stay here (not in the package): they're Plannotator
    design-system Tailwind classes, and this file is @source-scanned. */
 const GRID_CARD_CLASSES = 'px-5 md:px-8 lg:px-10 xl:px-12 shadow-xl border border-border/50';
@@ -27,6 +53,26 @@ interface MarkdownEditorProps {
   /** Theme color mode. Defaults to the ThemeProvider's resolved mode (Plannotator
       passes nothing); a host without ThemeProvider can supply it directly. */
   mode?: React.ComponentProps<typeof PackagedMarkdownEditor>['mode'];
+  /**
+   * Extra CodeMirror 6 extensions, forwarded verbatim to the underlying editor
+   * (e.g. `wikiLinks(config)`, collaboration bindings like y-codemirror.next).
+   * They are appended after the editor's built-ins, so they compose on top —
+   * use `Prec.high` from `@codemirror/state` when an extension must beat a
+   * built-in keymap. Build them against YOUR copy of the `@codemirror/*`
+   * packages; two live copies of `@codemirror/state` break the editor.
+   *
+   * ⚠️ CAPTURED ONCE PER `documentId` — NOT reactive. The engine reads this
+   * array a single time, when it mounts the document (keyed on `documentId`).
+   * Swapping in a different array afterwards does NOT re-apply it: the change
+   * is silently ignored until the next remount (i.e. a `documentId` change).
+   * Therefore:
+   *   - pass a stable reference (module constant, or `useMemo` keyed on
+   *     `documentId`), and
+   *   - never encode changing data in the array itself. Extension config
+   *     callbacks MAY close over live state (refs/getters) — that is the
+   *     supported way to feed dynamic data into a mounted editor.
+   */
+  extensions?: readonly Extension[];
 }
 
 /* Theme-bridging shim around @plannotator/markdown-editor. App.tsx renders its

package/components/ResizeHandle.tsx

@@ -1,8 +1,22 @@
 import React from 'react';
+import { createPortal } from 'react-dom';
 import type { ResizeHandleProps as BaseProps } from '../hooks/useResizablePanel';
 
 interface Props extends BaseProps {
   className?: string;
+  /**
+   * Extra classes for the inner visible track (the 4px bar that reveals on
+   * hover). `className` only reaches the outer wrapper, so this is the seam for
+   * restyling or suppressing the hover affordance. The track also carries a
+   * `[data-resize-track]` attribute (same pattern as `[data-collapse]`) so a
+   * host can target it from plain CSS — e.g. to kill the hover reveal:
+   * `[data-resize-track] { background: none !important; }`.
+   */
+  trackClassName?: string;
+  /** Suppress the hover color-change on the track entirely (no pop-in). */
+  hideHoverTrack?: boolean;
+  /** Cursor-following hint shown while hovering the handle (hidden mid-drag). */
+  tooltip?: React.ReactNode;
   /** When provided, renders a hover-reveal collapse button centered on the
    *  handle (prototype's gutter affordance). Chevron direction follows `side`:
    *  a left sidebar collapses leftward, a right sidebar rightward. */
@@ -34,53 +48,78 @@ export const ResizeHandle: React.FC<Props> = ({
   onDoubleClick,
   style,
   className,
+  trackClassName,
+  hideHoverTrack,
+  tooltip,
   side,
   onCollapse,
-}) => (
-  <div
-    className={`relative w-0 cursor-col-resize flex-shrink-0 group${className ? ` ${className}` : ''}`}
-  >
-    {/* Visible track — 4px wide, centered on the zero-width layout box,
-        invisible until hover/drag. */}
-    <div className={`absolute inset-y-0 -left-0.5 -right-0.5 transition-colors ${
-      isDragging ? 'bg-transparent' : 'group-hover:bg-border'
-    }`} />
-    {/* Wider grab/touch zone — must never have zero width (see `side` docs).
-        Pointer events + setPointerCapture live here; touch-action:none (from
-        style) stops touch drags from scroll-hijacking. */}
+}) => {
+  const [tip, setTip] = React.useState<{ x: number; y: number } | null>(null);
+  const showTip = tooltip != null && tip != null && !isDragging;
+
+  return (
     <div
-      className={`absolute inset-y-0 ${
-        side === 'left' ? '-right-2 -left-1' :
-        side === 'right' ? '-right-3 left-0' :
-        '-inset-x-2'
-      }`}
-      style={style}
-      onPointerDown={onPointerDown}
-      onDoubleClick={onDoubleClick}
-    />
-    {/* Hover-reveal collapse button, centered on the handle. stopPropagation on
-        pointerdown so clicking it never starts a drag. Hidden mid-drag. */}
-    {onCollapse && !isDragging && (
-      <button
-        type="button"
-        onPointerDown={(e) => e.stopPropagation()}
-        onClick={(e) => {
-          e.stopPropagation();
-          onCollapse();
-        }}
-        title="Collapse sidebar"
-        aria-label="Collapse sidebar"
-        data-collapse={side}
-        className="absolute top-1/2 left-1/2 z-20 flex h-6 w-4 -translate-x-1/2 -translate-y-1/2 items-center justify-center before:absolute before:-inset-2 before:content-[''] rounded-sm bg-surface-1 text-muted-foreground/60 opacity-0 ring-1 ring-border/40 transition-opacity hover:text-foreground group-hover:opacity-100 group-hover/sidebar:opacity-100"
-      >
-        <svg className="size-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            d={side === 'right' ? 'M9 5l7 7-7 7' : 'M15 19l-7-7 7-7'}
-          />
-        </svg>
-      </button>
-    )}
-  </div>
-);
+      className={`relative w-0 cursor-col-resize flex-shrink-0 group${className ? ` ${className}` : ''}`}
+    >
+      {/* Visible track — 4px wide, centered on the zero-width layout box,
+          invisible until hover/drag. `data-resize-track` + `trackClassName` are
+          host seams for restyling/suppressing the hover reveal. */}
+      <div
+        data-resize-track={side ?? ''}
+        className={`absolute inset-y-0 -left-0.5 -right-0.5 transition-colors ${
+          isDragging || hideHoverTrack ? 'bg-transparent' : 'group-hover:bg-border'
+        }${trackClassName ? ` ${trackClassName}` : ''}`}
+      />
+      {/* Wider grab/touch zone — must never have zero width (see `side` docs).
+          Pointer events + setPointerCapture live here; touch-action:none (from
+          style) stops touch drags from scroll-hijacking. */}
+      <div
+        className={`absolute inset-y-0 ${
+          side === 'left' ? '-right-2 -left-1' :
+          side === 'right' ? '-right-3 left-0' :
+          '-inset-x-2'
+        }`}
+        style={style}
+        onPointerDown={onPointerDown}
+        onDoubleClick={onDoubleClick}
+        onPointerMove={tooltip != null && !isDragging ? (e) => setTip({ x: e.clientX, y: e.clientY }) : undefined}
+        onPointerLeave={tooltip != null ? () => setTip(null) : undefined}
+      />
+      {/* Cursor-following hint. pointer-events-none so it never blocks the drag;
+          portaled to body so the zero-width parent doesn't clip it. */}
+      {showTip && typeof document !== 'undefined' && createPortal(
+        <div
+          style={{ position: 'fixed', left: tip.x + 14, top: tip.y + 16, zIndex: 100 }}
+          className="pointer-events-none whitespace-nowrap rounded-md bg-surface-1 px-2 py-1 text-xs text-foreground shadow-md ring-1 ring-border/60"
+        >
+          {tooltip}
+        </div>,
+        document.body,
+      )}
+      {/* Hover-reveal collapse button, centered on the handle. stopPropagation on
+          pointerdown so clicking it never starts a drag. Hidden mid-drag. */}
+      {onCollapse && !isDragging && (
+        <button
+          type="button"
+          onPointerDown={(e) => e.stopPropagation()}
+          onClick={(e) => {
+            e.stopPropagation();
+            onCollapse();
+          }}
+          title="Collapse sidebar"
+          aria-label="Collapse sidebar"
+          data-collapse={side}
+          className="absolute top-1/2 left-1/2 z-20 flex h-6 w-4 -translate-x-1/2 -translate-y-1/2 items-center justify-center before:absolute before:-inset-2 before:content-[''] rounded-sm bg-surface-1 text-muted-foreground/60 opacity-0 ring-1 ring-border/40 transition-opacity hover:text-foreground group-hover:opacity-100 group-hover/sidebar:opacity-100"
+        >
+          <svg className="size-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              d={side === 'right' ? 'M9 5l7 7-7 7' : 'M15 19l-7-7 7-7'}
+            />
+          </svg>
+        </button>
+      )}
+    </div>
+  );
+};

package/components/html-viewer/HtmlViewer.tsx

@@ -1,4 +1,4 @@
-import React, {
+import {
   forwardRef,
   useCallback,
   useEffect,

package/components/html-viewer/useHtmlAnnotation.ts

@@ -52,7 +52,6 @@ function postToIframe(iframe: HTMLIFrameElement | null, msg: Record<string, unkn
 
 export function useHtmlAnnotation({
   iframeRef,
-  annotations,
   onAddAnnotation,
   onSelectAnnotation,
   selectedAnnotationId,

package/components/sidebar/FileBrowser.tsx

@@ -6,6 +6,7 @@
  */
 
 import React from "react";
+import { Search, X } from "lucide-react";
 import type { VaultNode } from "../../types";
 import type { DirState } from "../../hooks/useFileBrowser";
 import { CountBadge } from "./CountBadge";
@@ -42,6 +43,40 @@ interface AggregateWorkspaceChange {
   files: number;
 }
 
+const FILE_EXTENSION_RE = /\.(mdx?|txt|html?)$/i;
+
+function normalizeFilterText(value: string): string {
+  return value.replace(/\\/g, "/").toLowerCase();
+}
+
+export function getFileTreeFilterTokens(query: string): string[] {
+  return normalizeFilterText(query)
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function nodeMatchesFilter(node: VaultNode, tokens: string[]): boolean {
+  if (tokens.length === 0) return true;
+  const displayName = node.name.replace(FILE_EXTENSION_RE, "");
+  const haystack = normalizeFilterText(`${node.name} ${displayName} ${node.path}`);
+  return tokens.every((token) => haystack.includes(token));
+}
+
+export function filterFileTree(nodes: VaultNode[], tokens: string[]): VaultNode[] {
+  if (tokens.length === 0) return nodes;
+
+  return nodes.flatMap((node) => {
+    if (node.type === "file") return nodeMatchesFilter(node, tokens) ? [node] : [];
+
+    if (nodeMatchesFilter(node, tokens)) return [node];
+
+    const children = filterFileTree(node.children ?? [], tokens);
+    if (children.length === 0) return [];
+    return [{ ...node, children }];
+  });
+}
+
 export function normalizePathForLookup(path: string): string {
   return normalizeBrowserPath(path);
 }
@@ -207,21 +242,26 @@ const TreeNode: React.FC<{
   highlightedFiles?: Set<string>;
   editStatuses?: Map<string, FileEditStatus>;
   workspaceStatus?: WorkspaceStatusPayload;
-}> = ({ node, depth, dirPath, expandedFolders, onToggleFolder, onSelectFile, activeFile, annotationCounts, highlightedFiles, editStatuses, workspaceStatus }) => {
+  forceExpandFolders?: boolean;
+}> = ({ node, depth, dirPath, expandedFolders, onToggleFolder, onSelectFile, activeFile, annotationCounts, highlightedFiles, editStatuses, workspaceStatus, forceExpandFolders = false }) => {
   const folderKey = `${dirPath}:${node.path}`;
   const absolutePath = `${dirPath}/${node.path}`;
-  const isExpanded = expandedFolders.has(folderKey);
+  const isExpanded = forceExpandFolders || expandedFolders.has(folderKey);
   const isActive = node.type === "file" && absolutePath === activeFile;
   const paddingLeft = 8 + depth * 14;
 
   if (node.type === "folder") {
     const aggregateCount = annotationCounts ? getAggregateCount(node, dirPath, annotationCounts, workspaceStatus) : 0;
     const aggregateChange = getAggregateWorkspaceChange(node, dirPath, workspaceStatus);
+    const folderButtonClassName = forceExpandFolders
+      ? "file-tree-folder w-full flex items-center gap-1.5 py-1 px-2 text-[11px] text-muted-foreground transition-colors rounded-sm cursor-default disabled:opacity-100"
+      : "file-tree-folder w-full flex items-center gap-1.5 py-1 px-2 text-[11px] text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors rounded-sm";
     return (
       <>
         <button
+          disabled={forceExpandFolders}
           onClick={() => onToggleFolder(folderKey)}
-          className="file-tree-folder w-full flex items-center gap-1.5 py-1 px-2 text-[11px] text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors rounded-sm"
+          className={folderButtonClassName}
           style={{ paddingLeft }}
         >
           <svg
@@ -261,6 +301,7 @@ const TreeNode: React.FC<{
             highlightedFiles={highlightedFiles}
             editStatuses={editStatuses}
             workspaceStatus={workspaceStatus}
+            forceExpandFolders={forceExpandFolders}
           />
         ))}
       </>
@@ -348,7 +389,8 @@ const DirSection: React.FC<{
   annotationCounts?: Map<string, number>;
   highlightedFiles?: Set<string>;
   editStatuses?: Map<string, FileEditStatus>;
-}> = ({ dir, expandedFolders, onToggleFolder, onSelectFile, activeFile, onRetry, annotationCounts, highlightedFiles, editStatuses }) => {
+  forceExpandFolders?: boolean;
+}> = ({ dir, expandedFolders, onToggleFolder, onSelectFile, activeFile, onRetry, annotationCounts, highlightedFiles, editStatuses, forceExpandFolders = false }) => {
   const workspaceStatus = React.useMemo(() => normalizeWorkspaceStatus(dir.workspaceStatus), [dir.workspaceStatus]);
 
   if (dir.isLoading) {
@@ -397,6 +439,7 @@ const DirSection: React.FC<{
           highlightedFiles={highlightedFiles}
           editStatuses={editStatuses}
           workspaceStatus={workspaceStatus}
+          forceExpandFolders={forceExpandFolders}
         />
       ))}
     </div>
@@ -417,6 +460,30 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
   highlightedFiles,
   editStatuses,
 }) => {
+  const [isFilterOpen, setIsFilterOpen] = React.useState(false);
+  const [filterQuery, setFilterQuery] = React.useState("");
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const deferredFilterQuery = React.useDeferredValue(filterQuery);
+  const filterTokens = React.useMemo(() => getFileTreeFilterTokens(deferredFilterQuery), [deferredFilterQuery]);
+  const isFiltering = filterTokens.length > 0;
+  const showFilterInput = isFilterOpen || filterQuery.trim().length > 0;
+  const visibleDirs = React.useMemo(() => {
+    if (!isFiltering) return dirs;
+    return dirs
+      .map((dir) => ({ ...dir, tree: filterFileTree(dir.tree, filterTokens) }))
+      .filter((dir) => dir.isLoading || dir.error || dir.tree.length > 0);
+  }, [dirs, filterTokens, isFiltering]);
+  const handleFilterBlur = React.useCallback((event: React.FocusEvent<HTMLDivElement>) => {
+    if (filterQuery.trim()) return;
+    if (event.currentTarget.contains(event.relatedTarget)) return;
+    setIsFilterOpen(false);
+  }, [filterQuery]);
+
+  React.useEffect(() => {
+    if (!showFilterInput) return;
+    inputRef.current?.focus();
+  }, [showFilterInput]);
+
   if (dirs.length === 0) {
     return (
       <div className="p-3 text-[11px] text-muted-foreground">
@@ -454,8 +521,66 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
           {workspaceTotals.deletions > 0 && <span className={`deletions ${workspaceTotals.additions > 0 ? "" : "ml-auto"}`}>-{workspaceTotals.deletions}</span>}
         </div>
       )}
-      {dirs.map((dir) => {
-        const isCollapsed = collapsedDirs.has(dir.path);
+      <div className="border-b border-border/20 px-2 py-0.5">
+        {showFilterInput ? (
+          <div
+            onBlur={handleFilterBlur}
+            className="flex h-6 items-center gap-1.5 rounded-sm bg-muted/25 px-1.5 text-muted-foreground focus-within:bg-muted/40"
+          >
+            <Search size={12} className="shrink-0 text-muted-foreground/55" aria-hidden="true" />
+            <input
+              ref={inputRef}
+              type="search"
+              value={filterQuery}
+              onChange={(event) => setFilterQuery(event.target.value)}
+              onKeyDown={(event) => {
+                if (event.key !== "Escape") return;
+                if (filterQuery) setFilterQuery("");
+                else setIsFilterOpen(false);
+              }}
+              placeholder="Filter"
+              aria-label="Filter files"
+              autoComplete="off"
+              spellCheck={false}
+              data-lpignore="true"
+              data-1p-ignore
+              className="file-browser-filter-input h-full min-w-0 flex-1 bg-transparent p-0 text-[16px] leading-4 text-foreground outline-none placeholder:text-muted-foreground/45 sm:text-[11px]"
+            />
+            {filterQuery && (
+              <button
+                type="button"
+                onClick={() => {
+                  setFilterQuery("");
+                  inputRef.current?.focus();
+                }}
+                className="flex h-5 w-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground/55 hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:bg-muted"
+                aria-label="Clear file filter"
+                title="Clear file filter"
+              >
+                <X size={12} aria-hidden="true" />
+              </button>
+            )}
+          </div>
+        ) : (
+          <button
+            type="button"
+            onClick={() => setIsFilterOpen(true)}
+            className="flex h-6 w-full items-center gap-1.5 rounded-sm px-1.5 text-left text-[10px] text-muted-foreground hover:bg-muted/40 hover:text-foreground focus-visible:outline-none focus-visible:bg-muted/50 focus-visible:text-foreground"
+            aria-label="Filter files"
+            title="Filter files"
+          >
+            <Search size={12} className="shrink-0 text-muted-foreground/55" aria-hidden="true" />
+            <span className="truncate">Filter</span>
+          </button>
+        )}
+      </div>
+      {isFiltering && visibleDirs.length === 0 && (
+        <div className="px-3 py-8 text-center text-[11px] text-muted-foreground">
+          No files match "{deferredFilterQuery.trim()}"
+        </div>
+      )}
+      {visibleDirs.map((dir) => {
+        const isCollapsed = !isFiltering && collapsedDirs.has(dir.path);
         return (
           <div key={dir.path}>
             <button
@@ -488,6 +613,7 @@ export const FileBrowser: React.FC<FileBrowserProps> = ({
                 annotationCounts={annotationCounts}
                 highlightedFiles={highlightedFiles}
                 editStatuses={editStatuses}
+                forceExpandFolders={isFiltering}
               />
             )}
           </div>