@stigmer/react 3.1.1 → 3.1.3

package/src/workspace/WorkspaceEditor.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useState, useCallback, useEffect, type KeyboardEvent } from "react";
+import { cn } from "@stigmer/theme";
 import type { UseWorkspaceEntriesReturn } from "./useWorkspaceEntries.js";
 import type { UseGitHubConnectionReturn } from "../github/useGitHubConnection.js";
 import { GitHubRepoPicker } from "../github/GitHubRepoPicker.js";
@@ -136,11 +137,11 @@ export function WorkspaceEditor({
 
   if (activePanel === "github" && enableGitHub) {
     return (
-      <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+      <div className={cn("space-y-2", className)}>
         <button
           type="button"
           onClick={goBack}
-          className="inline-flex items-center gap-1 text-[0.65rem] text-muted-foreground hover:text-foreground transition-colors"
+          className="inline-flex items-center gap-1 rounded-sm text-[0.65rem] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           <ChevronLeftIcon />
           Back
@@ -180,7 +181,7 @@ export function WorkspaceEditor({
   // ---------------------------------------------------------------------------
 
   return (
-    <div className={["space-y-2", className].filter(Boolean).join(" ")}>
+    <div className={cn("space-y-2", className)}>
       {/* Entry list */}
       {workspace.entries.length > 0 && (
         <div className="relative">
@@ -202,10 +203,10 @@ export function WorkspaceEditor({
                   </span>
                 )}
                 <span
-                  className={[
+                  className={cn(
                     "min-w-0 flex-1 truncate text-foreground",
-                    entry.type === "local" ? "[direction:rtl] text-left" : "",
-                  ].join(" ")}
+                    entry.type === "local" && "[direction:rtl] text-left",
+                  )}
                   title={entry.name}
                 >
                   <bdi>{entry.name}</bdi>
@@ -214,7 +215,7 @@ export function WorkspaceEditor({
                   type="button"
                   onClick={() => workspace.remove(entry.id)}
                   disabled={disabled}
-                  className="shrink-0 text-muted-foreground hover:text-destructive disabled:pointer-events-none"
+                  className="shrink-0 rounded-sm text-muted-foreground transition-colors hover:text-destructive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none"
                   aria-label={`Remove ${entry.name}`}
                 >
                   <XIcon />
@@ -237,7 +238,7 @@ export function WorkspaceEditor({
               if (path) workspace.addLocalPath(path);
             }}
             disabled={disabled}
-            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover disabled:pointer-events-none disabled:opacity-40"
+            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
           >
             <FolderIcon />
             <span className="flex-1 text-left">Browse Folder</span>
@@ -248,7 +249,7 @@ export function WorkspaceEditor({
             type="button"
             onClick={() => setActivePanel("github")}
             disabled={disabled}
-            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover disabled:pointer-events-none disabled:opacity-40"
+            className="flex w-full items-center gap-2 rounded-md px-2.5 py-2 text-xs text-foreground transition-colors hover:bg-accent-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-40"
           >
             <GitHubIcon />
             <span className="flex-1 text-left">Connect GitHub</span>
@@ -307,14 +308,14 @@ function GitHubPanel({
               <button
                 type="button"
                 onClick={() => connection.connect(redirectUri, { popup: true })}
-                className="rounded-md px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+                className="rounded-md px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 Try again
               </button>
               <button
                 type="button"
                 onClick={() => connection.connect(redirectUri)}
-                className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background hover:bg-foreground-hover transition-colors"
+                className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background transition-colors hover:bg-foreground-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
               >
                 <GitHubIcon />
                 <span>Continue with redirect</span>
@@ -325,7 +326,7 @@ function GitHubPanel({
           <button
             type="button"
             onClick={() => connection.connect(redirectUri, { popup: true })}
-            className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background hover:bg-foreground-hover transition-colors"
+            className="inline-flex items-center gap-2 rounded-md bg-foreground px-3 py-1.5 text-xs text-background transition-colors hover:bg-foreground-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
           >
             <GitHubIcon />
             <span>Connect GitHub</span>
@@ -353,7 +354,7 @@ function GitHubPanel({
         <button
           type="button"
           onClick={connection.disconnect}
-          className="text-[0.6rem] text-muted-foreground hover:text-destructive transition-colors"
+          className="rounded-sm text-[0.6rem] text-muted-foreground transition-colors hover:text-destructive focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           Disconnect
         </button>
@@ -392,6 +393,7 @@ function ManualGitPanel({
     <div className="space-y-2">
       <input
         type="url"
+        aria-label="Git repository URL"
         placeholder="https://github.com/org/repo.git"
         value={url}
         onChange={(e) => onUrlChange(e.target.value)}
@@ -401,6 +403,7 @@ function ManualGitPanel({
       />
       <input
         type="text"
+        aria-label="Branch (optional)"
         placeholder="Branch (optional)"
         value={branch}
         onChange={(e) => onBranchChange(e.target.value)}
@@ -411,7 +414,7 @@ function ManualGitPanel({
         <button
           type="button"
           onClick={onCancel}
-          className="rounded-md px-2.5 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+          className="rounded-md px-2.5 py-1 text-xs text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
         >
           Cancel
         </button>
@@ -419,7 +422,7 @@ function ManualGitPanel({
           type="button"
           onClick={onAdd}
           disabled={!url.trim()}
-          className="rounded-md bg-primary px-2.5 py-1 text-xs text-primary-foreground hover:bg-primary-hover transition-colors disabled:opacity-40"
+          className="rounded-md bg-primary px-2.5 py-1 text-xs text-primary-foreground transition-colors hover:bg-primary-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-40"
         >
           Add
         </button>
@@ -453,7 +456,7 @@ function GitHubConnectingState({ onCancel }: { onCancel: () => void }) {
       <button
         type="button"
         onClick={onCancel}
-        className="text-[0.65rem] text-muted-foreground hover:text-foreground transition-colors"
+        className="rounded-sm text-[0.65rem] text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
       >
         Cancel
       </button>

package/src/workspace/WorkspaceFileLister.ts

@@ -12,6 +12,17 @@ export interface WorkspaceFileEntry {
   readonly path: string;
   /** Whether this entry is a directory. */
   readonly isDirectory: boolean;
+  /**
+   * Marks this entry as an advisory notice rather than an openable file — for
+   * example a "listing truncated" message when a repository exceeds the
+   * backend's entry limit. When `true`, `path` carries the human-readable
+   * message. Consumers must not treat a notice as a real file: it is stripped
+   * from the openable listing (never a tree leaf, never a search hit) and is
+   * surfaced instead as a single `truncated` banner (see `workspaceListingCache`).
+   *
+   * Optional and additive: listers that never truncate simply omit it.
+   */
+  readonly notice?: true;
 }
 
 /**

package/src/workspace/WorkspaceFileReader.ts

@@ -0,0 +1,57 @@
+// Content-fetch capability — the byte-reading sibling of WorkspaceFileLister.
+// Domain: workspace. Injected by the host (DD-004) so the SDK never learns how
+// bytes are fetched: GitHub Contents/blob on web, Tauri fs on desktop.
+
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+
+/**
+ * Shared soft cap for a single file read, enforced identically on web and
+ * desktop so both substrates truncate at the same boundary. Files larger than
+ * this return their first {@link MAX_WORKSPACE_FILE_READ_BYTES} bytes in `text`
+ * with `truncated: true`; `size` still reports the full file size.
+ */
+export const MAX_WORKSPACE_FILE_READ_BYTES = 1_048_576; // 1 MiB
+
+/**
+ * Decoded content (plus metadata) for a single workspace file.
+ *
+ * `text` is `null` whenever the bytes are not displayable as UTF-8 — either
+ * binary (`isBinary`) or an undecodable byte sequence (`encoding: "unknown"`).
+ * The renderer uses `isBinary`/`text === null` for its fallback state.
+ */
+export interface WorkspaceFileContent {
+  /** Decoded UTF-8 text, or `null` when binary or undecodable. */
+  readonly text: string | null;
+  /** Whether the bytes were detected as binary (NUL-byte heuristic). */
+  readonly isBinary: boolean;
+  /** Full file size in bytes — independent of truncation. */
+  readonly size: number;
+  /** How the backend delivered the bytes. `"none"` is GitHub's >1 MB signal. */
+  readonly encoding: "utf-8" | "base64" | "none" | "unknown";
+  /** `true` when `text` holds only the first {@link MAX_WORKSPACE_FILE_READ_BYTES} bytes. */
+  readonly truncated?: boolean;
+}
+
+/**
+ * Platform-injected callback that reads the content of a single workspace file.
+ *
+ * The byte-reading sibling of {@link WorkspaceFileLister}:
+ * the SDK calls it when a user opens a file; the platform decides *how* the
+ * bytes are fetched (GitHub on web, Tauri on desktop).
+ *
+ * Two distinct failure axes — do not conflate them:
+ * - Returns `null` **only** when the substrate is unsupported for this entry
+ *   (git-on-desktop, local-on-web, missing token, non-GitHub URL). This is the
+ *   honest "unavailable here" state, mirroring the lister's null contract.
+ * - **Throws** on a genuine failure (404, network error, 5xx, unreadable file,
+ *   a directory path). Consumers catch this into a distinct error state — a
+ *   clicked file that 404s is "failed to load," not "unsupported here."
+ *
+ * `path` is repo-relative for git entries and root-relative for local entries —
+ * exactly the strings the matching `WorkspaceFileLister` emits, so a file-tree
+ * node path can be handed straight to the reader with no transformation.
+ */
+export type WorkspaceFileReader = (
+  entry: WorkspaceEntry,
+  path: string,
+) => Promise<WorkspaceFileContent | null>;

package/src/workspace/WorkspaceFileSearch.tsx

@@ -0,0 +1,452 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type KeyboardEvent,
+} from "react";
+import { cn } from "@stigmer/theme";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+import type { WorkspaceFileLister } from "./WorkspaceFileLister.js";
+import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
+import {
+  useWorkspaceFileSearch,
+  type WorkspaceFileSearchGroup,
+} from "./useWorkspaceFileSearch.js";
+import type { WorkspaceFileMatch } from "./matchWorkspaceFiles.js";
+
+/** Cap on rendered rows — keeps the DOM bounded on huge repositories. */
+const MAX_RESULTS = 200;
+
+/** Props for {@link WorkspaceFileSearch}. */
+export interface WorkspaceFileSearchProps {
+  /** All workspace entries to search across. */
+  readonly entries: readonly WorkspaceEntry[];
+  /** Platform-injected file lister. `undefined` → search is unavailable. */
+  readonly lister: WorkspaceFileLister | undefined;
+  /** Opens a result in the viewer. */
+  readonly onOpenFile: (entryId: string, path: string) => void;
+  /** The file currently open in the viewer, highlighted in the results. */
+  readonly selectedFile?: SelectedWorkspaceFile | null;
+  /** Additional CSS classes for the root element. */
+  readonly className?: string;
+}
+
+/** A rendered result, carrying its owning entry and flat index for keyboard nav. */
+interface FlatResult {
+  readonly entryId: string;
+  readonly entry: WorkspaceEntry;
+  readonly match: WorkspaceFileMatch;
+}
+
+/**
+ * Workspace-wide filename/path search surface.
+ *
+ * Searches the already-loaded listings across every workspace entry (via
+ * {@link useWorkspaceFileSearch}) and opens a hit in the viewer through
+ * `onOpenFile` — the same seam a file-tree click uses. Filename-first by design;
+ * content search is a separate substrate-specific capability (DD-09).
+ *
+ * Keyboard/a11y follows the platform's combobox+listbox pattern (see
+ * `mcp-server/McpServerPicker`): the input is a `role="combobox"` driving
+ * `aria-activedescendant`, results are a `role="listbox"` of `role="option"`
+ * rows, and ArrowUp/Down move a virtual focus with Enter to open — focus stays
+ * in the input. All visual properties flow through `--stgm-*` tokens (DD-005).
+ */
+export function WorkspaceFileSearch({
+  entries,
+  lister,
+  onOpenFile,
+  selectedFile,
+  className,
+}: WorkspaceFileSearchProps) {
+  const [query, setQuery] = useState("");
+  const [focusIndex, setFocusIndex] = useState(-1);
+
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listboxId = useId();
+  const optionId = useCallback(
+    (index: number) => `${listboxId}-opt-${index}`,
+    [listboxId],
+  );
+
+  const { groups, totalMatches, isLoading, isUnsupported } =
+    useWorkspaceFileSearch({ entries, lister, query });
+
+  // Flat, capped view of every rendered match — the index space the keyboard
+  // and `aria-activedescendant` share with the grouped render below.
+  const flatResults = useMemo<readonly FlatResult[]>(() => {
+    const flat: FlatResult[] = [];
+    for (const group of groups) {
+      for (const match of group.matches) {
+        if (flat.length >= MAX_RESULTS) return flat;
+        flat.push({ entryId: group.entry.id, entry: group.entry, match });
+      }
+    }
+    return flat;
+  }, [groups]);
+
+  // A new query invalidates the previous virtual focus.
+  useEffect(() => {
+    setFocusIndex(-1);
+  }, [query]);
+
+  // Autofocus on mount — the user switched into Search intending to type.
+  useEffect(() => {
+    inputRef.current?.focus();
+  }, []);
+
+  // Keep the virtually-focused option in view (no-op where unsupported, e.g. tests).
+  useEffect(() => {
+    if (focusIndex < 0) return;
+    const el =
+      typeof document !== "undefined"
+        ? document.getElementById(optionId(focusIndex))
+        : null;
+    el?.scrollIntoView?.({ block: "nearest" });
+  }, [focusIndex, optionId]);
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        setFocusIndex((prev) =>
+          prev < flatResults.length - 1 ? prev + 1 : prev,
+        );
+      } else if (e.key === "ArrowUp") {
+        e.preventDefault();
+        setFocusIndex((prev) => (prev > 0 ? prev - 1 : -1));
+      } else if (e.key === "Enter") {
+        e.preventDefault();
+        const target = flatResults[focusIndex];
+        if (target) onOpenFile(target.entryId, target.match.path);
+      }
+    },
+    [flatResults, focusIndex, onOpenFile],
+  );
+
+  const trimmed = query.trim();
+  const showGroupHeaders = groups.length > 1;
+
+  // A concise, screen-reader-only summary of the current result state. It lives
+  // in a persistent polite live region (below) so status changes are announced
+  // even as the visible states — which live in separate, unmounting branches —
+  // swap. Deliberately terse: never the result list itself, only its shape.
+  const statusMessage = isUnsupported
+    ? ""
+    : trimmed.length === 0
+      ? ""
+      : isLoading && totalMatches === 0 && groups.length === 0
+        ? "Searching files…"
+        : groups.length === 0
+          ? `No files matching ${trimmed}.`
+          : totalMatches > flatResults.length
+            ? `Showing the first ${flatResults.length} of ${totalMatches} matching files.`
+            : `${flatResults.length} matching ${flatResults.length === 1 ? "file" : "files"}.`;
+
+  return (
+    <div className={cn("flex h-full flex-col", className)}>
+      <div role="status" aria-live="polite" className="sr-only">
+        {statusMessage}
+      </div>
+      <div className="flex items-center gap-1.5 border-b border-border px-2 py-1.5">
+        <SearchIcon />
+        <input
+          ref={inputRef}
+          type="text"
+          role="combobox"
+          aria-expanded
+          aria-controls={listboxId}
+          aria-activedescendant={
+            focusIndex >= 0 ? optionId(focusIndex) : undefined
+          }
+          value={query}
+          onChange={(e) => setQuery(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder="Search files by name…"
+          disabled={isUnsupported}
+          className={cn(
+            "min-w-0 flex-1 bg-transparent text-xs text-foreground",
+            "placeholder:text-muted-foreground",
+            "focus-visible:outline-none disabled:cursor-not-allowed",
+          )}
+          aria-label="Search workspace files by name"
+        />
+        {trimmed.length > 0 && (
+          <button
+            type="button"
+            onClick={() => {
+              setQuery("");
+              inputRef.current?.focus();
+            }}
+            className="shrink-0 text-muted-foreground transition-colors hover:text-foreground"
+            aria-label="Clear search"
+          >
+            <ClearIcon />
+          </button>
+        )}
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto">
+        {isUnsupported ? (
+          <MessageState>File search isn&rsquo;t available here.</MessageState>
+        ) : trimmed.length === 0 ? (
+          <MessageState>
+            Search files by name across the whole workspace.
+          </MessageState>
+        ) : isLoading && totalMatches === 0 && groups.length === 0 ? (
+          <MessageState>Searching…</MessageState>
+        ) : groups.length === 0 ? (
+          <MessageState>
+            No files matching &ldquo;{trimmed}&rdquo;.
+          </MessageState>
+        ) : (
+          <>
+            <ul
+              id={listboxId}
+              role="listbox"
+              aria-label="Search results"
+              className="py-0.5"
+            >
+              {renderRows({
+                groups,
+                showGroupHeaders,
+                selectedFile: selectedFile ?? null,
+                focusIndex,
+                optionId,
+                onOpenFile,
+              })}
+            </ul>
+            {totalMatches > flatResults.length && (
+              <p className="border-t border-border px-3 py-1.5 text-[0.65rem] text-muted-foreground">
+                Showing the first {flatResults.length} of {totalMatches} matches
+                — refine your search to narrow the list.
+              </p>
+            )}
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Result rows — a single pass over groups that keeps the flat match index
+// aligned with `flatResults` (and thus keyboard focus / aria-activedescendant).
+// ---------------------------------------------------------------------------
+
+function renderRows({
+  groups,
+  showGroupHeaders,
+  selectedFile,
+  focusIndex,
+  optionId,
+  onOpenFile,
+}: {
+  readonly groups: readonly WorkspaceFileSearchGroup[];
+  readonly showGroupHeaders: boolean;
+  readonly selectedFile: SelectedWorkspaceFile | null;
+  readonly focusIndex: number;
+  readonly optionId: (index: number) => string;
+  readonly onOpenFile: (entryId: string, path: string) => void;
+}) {
+  const rows: React.ReactNode[] = [];
+  let matchIndex = 0;
+
+  for (const group of groups) {
+    if (showGroupHeaders) {
+      rows.push(<GroupHeader key={`h:${group.entry.id}`} name={group.entry.name} />);
+    }
+
+    for (const match of group.matches) {
+      if (matchIndex >= MAX_RESULTS) break;
+      const index = matchIndex++;
+      const isOpen =
+        selectedFile?.entryId === group.entry.id &&
+        selectedFile.path === match.path;
+      rows.push(
+        <ResultRow
+          key={`${group.entry.id}:${match.path}`}
+          id={optionId(index)}
+          match={match}
+          isFocused={index === focusIndex}
+          isOpen={isOpen}
+          onOpen={() => onOpenFile(group.entry.id, match.path)}
+        />,
+      );
+    }
+
+    if (group.truncated) {
+      rows.push(
+        <GroupNotice key={`t:${group.entry.id}`}>
+          Partial listing — too many files to search in full.
+        </GroupNotice>,
+      );
+    }
+    if (group.error) {
+      rows.push(
+        <GroupNotice key={`e:${group.entry.id}`} isError>
+          Couldn&rsquo;t list files: {group.error.message}
+        </GroupNotice>,
+      );
+    }
+
+    if (matchIndex >= MAX_RESULTS) break;
+  }
+
+  return rows;
+}
+
+function ResultRow({
+  id,
+  match,
+  isFocused,
+  isOpen,
+  onOpen,
+}: {
+  readonly id: string;
+  readonly match: WorkspaceFileMatch;
+  readonly isFocused: boolean;
+  readonly isOpen: boolean;
+  readonly onOpen: () => void;
+}) {
+  const lastSlash = match.path.lastIndexOf("/");
+  const basename = match.path.slice(lastSlash + 1);
+  const dir = lastSlash >= 0 ? match.path.slice(0, lastSlash) : "";
+
+  // The `role="option"` IS the interactive leaf of the listbox (keyboard
+  // activation flows through the combobox input's Enter handler +
+  // aria-activedescendant). It must not nest another interactive control — a
+  // button inside would violate WCAG 4.1.2 (axe `nested-interactive`). So the
+  // click handler and row styling live on the option itself.
+  return (
+    <li
+      id={id}
+      role="option"
+      aria-selected={isFocused}
+      aria-current={isOpen ? "true" : undefined}
+      onClick={onOpen}
+      className={cn(
+        "flex cursor-pointer items-baseline gap-1.5 px-3 py-1 text-xs transition-colors",
+        isFocused && "bg-muted",
+        isOpen && "bg-muted font-medium text-foreground",
+        !isFocused && !isOpen && "hover:bg-muted",
+      )}
+    >
+      <span className="truncate text-foreground">
+        <HighlightedPath
+          text={basename}
+          offset={lastSlash + 1}
+          matchStart={match.matchStart}
+          matchEnd={match.matchEnd}
+        />
+      </span>
+      {dir && (
+        <span className="truncate text-[0.65rem] text-muted-foreground">
+          <HighlightedPath
+            text={dir}
+            offset={0}
+            matchStart={match.matchStart}
+            matchEnd={match.matchEnd}
+          />
+        </span>
+      )}
+    </li>
+  );
+}
+
+/**
+ * Renders a slice of the path (`text`, starting at `offset` within the full
+ * path), emphasizing the intersection with the match range `[matchStart,
+ * matchEnd)`. Non-overlapping slices render plain.
+ */
+function HighlightedPath({
+  text,
+  offset,
+  matchStart,
+  matchEnd,
+}: {
+  readonly text: string;
+  readonly offset: number;
+  readonly matchStart: number;
+  readonly matchEnd: number;
+}) {
+  const localStart = Math.max(0, matchStart - offset);
+  const localEnd = Math.min(text.length, matchEnd - offset);
+
+  if (localStart >= localEnd) return <>{text}</>;
+
+  return (
+    <>
+      {text.slice(0, localStart)}
+      <span className="font-semibold text-foreground">
+        {text.slice(localStart, localEnd)}
+      </span>
+      {text.slice(localEnd)}
+    </>
+  );
+}
+
+function GroupHeader({ name }: { readonly name: string }) {
+  return (
+    <li
+      role="presentation"
+      className="truncate px-3 pb-0.5 pt-2 text-[0.6rem] font-medium uppercase tracking-wide text-muted-foreground"
+    >
+      {name}
+    </li>
+  );
+}
+
+function GroupNotice({
+  children,
+  isError,
+}: {
+  readonly children: React.ReactNode;
+  readonly isError?: boolean;
+}) {
+  return (
+    <li
+      role="presentation"
+      className={cn(
+        "px-3 py-1 text-[0.65rem]",
+        isError ? "text-destructive" : "text-muted-foreground",
+      )}
+    >
+      {children}
+    </li>
+  );
+}
+
+function MessageState({ children }: { readonly children: React.ReactNode }) {
+  return (
+    <div className="flex h-full items-center justify-center p-8 text-center text-xs text-muted-foreground">
+      {children}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Inline SVG icons (SDK independence — no lucide dependency)
+// ---------------------------------------------------------------------------
+
+function SearchIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" className="shrink-0 text-muted-foreground" aria-hidden="true">
+      <circle cx="5.25" cy="5.25" r="3.5" />
+      <path d="M7.75 7.75L10.5 10.5" />
+    </svg>
+  );
+}
+
+function ClearIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+      <path d="M3 3L9 9M9 3L3 9" />
+    </svg>
+  );
+}