@ff-labs/fff-bun 0.5.3-nightly.ea1f980 → 0.6.0

package/examples/grep.ts

@@ -111,7 +111,6 @@ async function main() {
   console.log(`${DIM}Initializing index for: ${directory}${RESET}`);
   const createResult = FileFinder.create({
     basePath: directory,
-    warmupMmapCache: true,
   });
 
   if (!createResult.ok) {

package/examples/search.ts

@@ -8,10 +8,18 @@
  *
  * Indexes the specified directory (or cwd) and provides an interactive
  * search prompt with detailed metadata about results.
+ *
+ * Modes:
+ *   :files       - fuzzy file search (default)
+ *   :dirs        - fuzzy directory search
+ *   :mixed       - mixed file + directory search
  */
 
 import { FileFinder } from "../src/index";
+import type { DirItem, FileItem, MixedItem, Score } from "../src/index";
 import * as readline from "node:readline";
+import { join } from "node:path";
+import { homedir } from "node:os";
 
 const RESET = "\x1b[0m";
 const BOLD = "\x1b[1m";
@@ -20,8 +28,11 @@ const GREEN = "\x1b[32m";
 const YELLOW = "\x1b[33m";
 const BLUE = "\x1b[34m";
 const CYAN = "\x1b[36m";
+const MAGENTA = "\x1b[35m";
 const RED = "\x1b[31m";
 
+type SearchMode = "files" | "dirs" | "mixed";
+
 function formatGitStatus(status: string): string {
   switch (status) {
     case "modified":
@@ -43,12 +54,30 @@ function formatGitStatus(status: string): string {
 }
 
 function formatScore(score: number): string {
-  if (score >= 100) return `${GREEN}${score}${RESET}`;
-  if (score >= 50) return `${YELLOW}${score}${RESET}`;
-  if (score > 0) return `${DIM}${score}${RESET}`;
+  const s = String(score);
+  if (score >= 100) return `${GREEN}${s}${RESET}`;
+  if (score >= 50) return `${YELLOW}${s}${RESET}`;
+  if (score > 0) return `${DIM}${s}${RESET}`;
   return `${DIM}0${RESET}`;
 }
 
+/** Pad a plain string first, then wrap with ANSI color. */
+function padColor(
+  value: string,
+  width: number,
+  color: string,
+  align: "left" | "right" = "right",
+): string {
+  const padded = align === "right" ? value.padStart(width) : value.padEnd(width);
+  return `${color}${padded}${RESET}`;
+}
+
+function scoreColor(score: number): string {
+  if (score >= 100) return GREEN;
+  if (score >= 50) return YELLOW;
+  return DIM;
+}
+
 function formatSize(bytes: number): string {
   if (bytes < 1024) return `${bytes}B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
@@ -71,6 +100,68 @@ function formatTime(unixSeconds: number): string {
   return date.toLocaleDateString();
 }
 
+function formatModeTag(mode: SearchMode): string {
+  switch (mode) {
+    case "files":
+      return `${CYAN}files${RESET}`;
+    case "dirs":
+      return `${MAGENTA}dirs${RESET}`;
+    case "mixed":
+      return `${YELLOW}mixed${RESET}`;
+  }
+}
+
+function printScoreBreakdown(score: Score, indent: string) {
+  const breakdown: string[] = [];
+  if (score.baseScore > 0) breakdown.push(`base:${score.baseScore}`);
+  if (score.filenameBonus > 0) breakdown.push(`filename:+${score.filenameBonus}`);
+  if (score.frecencyBoost > 0) breakdown.push(`frecency:+${score.frecencyBoost}`);
+  if (score.comboMatchBoost > 0) breakdown.push(`combo:+${score.comboMatchBoost}`);
+  if (score.distancePenalty < 0) breakdown.push(`distance:${score.distancePenalty}`);
+  if (score.exactMatch) breakdown.push(`${GREEN}exact${RESET}`);
+  if (score.matchType) breakdown.push(`[${score.matchType}]`);
+
+  if (breakdown.length > 0) {
+    console.log(`${DIM}${indent}└─ ${breakdown.join(", ")}${RESET}`);
+  }
+}
+
+function printFileResult(item: FileItem, score: Score, showBreakdown: boolean) {
+  const git = formatGitStatus(item.gitStatus);
+  const sc = padColor(String(score.total), 5, scoreColor(score.total));
+  const size = formatSize(item.size).padStart(6);
+  const modified = formatTime(item.modified).padEnd(10);
+
+  console.log(`   ${git}  │ ${sc} │ ${size} │ ${modified} │ ${item.relativePath}`);
+
+  if (showBreakdown && score.total > 0) {
+    printScoreBreakdown(score, "      │       │        │            │  ");
+  }
+}
+
+function printDirResult(item: DirItem, score: Score, showBreakdown: boolean) {
+  const sc = padColor(String(score.total), 5, scoreColor(score.total));
+  const frecency = (
+    item.maxAccessFrecency > 0 ? `f:${item.maxAccessFrecency}` : "-"
+  ).padStart(6);
+
+  console.log(
+    `   ${MAGENTA}D${RESET}  │ ${sc} │ ${frecency} │ ${"".padEnd(10)} │ ${MAGENTA}${item.relativePath}${RESET}`,
+  );
+
+  if (showBreakdown && score.total > 0) {
+    printScoreBreakdown(score, "      │       │        │            │  ");
+  }
+}
+
+function printMixedResult(mixed: MixedItem, score: Score, showBreakdown: boolean) {
+  if (mixed.type === "file") {
+    printFileResult(mixed.item, score, showBreakdown);
+  } else {
+    printDirResult(mixed.item, score, showBreakdown);
+  }
+}
+
 async function main() {
   const targetDir = process.argv[2] || process.cwd();
 
@@ -83,10 +174,21 @@ async function main() {
     process.exit(1);
   }
 
-  // Create instance
+  // Use the same frecency + history databases as the Neovim plugin
+  // so the demo benefits from real access history.
+  const nvimCache = process.env.XDG_CACHE_HOME || join(homedir(), ".cache", "nvim");
+  const nvimData =
+    process.env.XDG_DATA_HOME || join(homedir(), ".local", "share", "nvim");
+  const frecencyDbPath = join(nvimCache, "fff_nvim");
+  const historyDbPath = join(nvimData, "fff_queries");
+
   console.log(`${DIM}Initializing index for: ${targetDir}${RESET}`);
+  console.log(`${DIM}Frecency DB: ${frecencyDbPath}${RESET}`);
   const createResult = FileFinder.create({
     basePath: targetDir,
+    frecencyDbPath,
+    historyDbPath,
+    useUnsafeNoLock: true,
   });
 
   if (!createResult.ok) {
@@ -128,91 +230,160 @@ async function main() {
     }
   }
 
+  let mode: SearchMode = "files";
+
   // Interactive search loop
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
   });
 
-  console.log(
-    `${BOLD}Enter a search query${RESET} (or 'q' to quit, empty for all files):\n`,
-  );
+  console.log(`\n${BOLD}Commands:${RESET}`);
+  console.log(`  ${DIM}:files${RESET}  - file search mode (default)`);
+  console.log(`  ${DIM}:dirs${RESET}   - directory search mode`);
+  console.log(`  ${DIM}:mixed${RESET}  - mixed files + directories mode`);
+  console.log(`  ${DIM}q${RESET}       - quit`);
+  console.log();
 
   const prompt = () => {
-    rl.question(`${CYAN}search>${RESET} `, (query) => {
-      if (query.toLowerCase() === "q" || query.toLowerCase() === "quit") {
+    rl.question(`${CYAN}[${formatModeTag(mode)}]>${RESET} `, (query) => {
+      const trimmed = query.trim();
+
+      if (trimmed.toLowerCase() === "q" || trimmed.toLowerCase() === "quit") {
         console.log(`\n${DIM}Goodbye!${RESET}`);
         finder.destroy();
         rl.close();
         process.exit(0);
       }
 
-      const searchStart = Date.now();
-      const result = finder.search(query, { pageSize: 15 });
-      const searchTime = Date.now() - searchStart;
-
-      if (!result.ok) {
-        console.log(`${RED}Search error: ${result.error}${RESET}\n`);
+      // Mode switching commands
+      if (trimmed === ":files") {
+        mode = "files";
+        console.log(`${GREEN}Switched to file search mode${RESET}\n`);
         prompt();
         return;
       }
-
-      const { items, scores, totalMatched, totalFiles } = result.value;
-
-      console.log();
-      console.log(
-        `${DIM}Found ${BOLD}${totalMatched}${RESET}${DIM} matches in ${totalFiles} files (${searchTime}ms)${RESET}`,
-      );
-      console.log();
-
-      if (items.length === 0) {
-        console.log(`${DIM}No matches found.${RESET}\n`);
+      if (trimmed === ":dirs") {
+        mode = "dirs";
+        console.log(`${MAGENTA}Switched to directory search mode${RESET}\n`);
         prompt();
         return;
       }
+      if (trimmed === ":mixed") {
+        mode = "mixed";
+        console.log(`${YELLOW}Switched to mixed search mode${RESET}\n`);
+        prompt();
+        return;
+      }
+
+      const searchStart = Date.now();
 
-      // Header
-      console.log(`${DIM}  Git │ Score │  Size  │  Modified  │ Path${RESET}`);
+      if (mode === "files") {
+        const result = finder.fileSearch(trimmed, { pageSize: 15 });
+        const searchTime = Date.now() - searchStart;
 
-      // Results
-      for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        const score = scores[i];
+        if (!result.ok) {
+          console.log(`${RED}Search error: ${result.error}${RESET}\n`);
+          prompt();
+          return;
+        }
 
-        const gitStatus = formatGitStatus(item.gitStatus);
-        const totalScore = formatScore(score.total);
-        const size = formatSize(item.size).padStart(6);
-        const modified = formatTime(item.modified).padEnd(10);
-        const path = item.relativePath;
+        const { items, scores, totalMatched, totalFiles } = result.value;
 
+        console.log();
         console.log(
-          `   ${gitStatus}  │ ${totalScore.padStart(5)} │ ${size} │ ${modified} │ ${path}`,
+          `${DIM}Found ${BOLD}${totalMatched}${RESET}${DIM} matches in ${totalFiles} files (${searchTime}ms)${RESET}`,
         );
+        console.log();
 
-        // Show score breakdown for top results
-        if (i < 3 && score.total > 0) {
-          const breakdown: string[] = [];
-          if (score.baseScore > 0) breakdown.push(`base:${score.baseScore}`);
-          if (score.filenameBonus > 0) breakdown.push(`filename:+${score.filenameBonus}`);
-          if (score.frecencyBoost > 0) breakdown.push(`frecency:+${score.frecencyBoost}`);
-          if (score.comboMatchBoost > 0)
-            breakdown.push(`combo:+${score.comboMatchBoost}`);
-          if (score.distancePenalty < 0)
-            breakdown.push(`distance:${score.distancePenalty}`);
-          if (score.exactMatch) breakdown.push(`${GREEN}exact${RESET}`);
-
-          if (breakdown.length > 0) {
-            console.log(
-              `${DIM}      │       │        │            │  └─ ${breakdown.join(", ")}${RESET}`,
-            );
-          }
+        if (items.length === 0) {
+          console.log(`${DIM}No matches found.${RESET}\n`);
+          prompt();
+          return;
         }
-      }
 
-      if (totalMatched > items.length) {
+        console.log(`${DIM}  Git │ Score │  Size  │  Modified  │ Path${RESET}`);
+
+        for (let i = 0; i < items.length; i++) {
+          printFileResult(items[i], scores[i], i < 3);
+        }
+
+        if (totalMatched > items.length) {
+          console.log(
+            `${DIM}      │       │        │            │ ... and ${totalMatched - items.length} more${RESET}`,
+          );
+        }
+      } else if (mode === "dirs") {
+        const result = finder.directorySearch(trimmed, { pageSize: 15 });
+        const searchTime = Date.now() - searchStart;
+
+        if (!result.ok) {
+          console.log(`${RED}Search error: ${result.error}${RESET}\n`);
+          prompt();
+          return;
+        }
+
+        const { items, scores, totalMatched, totalDirs } = result.value;
+
+        console.log();
+        console.log(
+          `${DIM}Found ${BOLD}${totalMatched}${RESET}${DIM} matches in ${totalDirs} directories (${searchTime}ms)${RESET}`,
+        );
+        console.log();
+
+        if (items.length === 0) {
+          console.log(`${DIM}No matches found.${RESET}\n`);
+          prompt();
+          return;
+        }
+
+        console.log(`${DIM}  Dir │ Score │ Frecnc │            │ Path${RESET}`);
+
+        for (let i = 0; i < items.length; i++) {
+          printDirResult(items[i], scores[i], i < 3);
+        }
+
+        if (totalMatched > items.length) {
+          console.log(
+            `${DIM}      │       │        │            │ ... and ${totalMatched - items.length} more${RESET}`,
+          );
+        }
+      } else {
+        // mixed mode
+        const result = finder.mixedSearch(trimmed, { pageSize: 20 });
+        const searchTime = Date.now() - searchStart;
+
+        if (!result.ok) {
+          console.log(`${RED}Search error: ${result.error}${RESET}\n`);
+          prompt();
+          return;
+        }
+
+        const { items, scores, totalMatched, totalFiles, totalDirs } = result.value;
+
+        console.log();
         console.log(
-          `${DIM}      │       │        │            │ ... and ${totalMatched - items.length} more${RESET}`,
+          `${DIM}Found ${BOLD}${totalMatched}${RESET}${DIM} matches (${totalFiles} files, ${totalDirs} dirs) (${searchTime}ms)${RESET}`,
         );
+        console.log();
+
+        if (items.length === 0) {
+          console.log(`${DIM}No matches found.${RESET}\n`);
+          prompt();
+          return;
+        }
+
+        console.log(`${DIM} Type │ Score │  Info  │  Modified  │ Path${RESET}`);
+
+        for (let i = 0; i < items.length; i++) {
+          printMixedResult(items[i], scores[i], i < 5);
+        }
+
+        if (totalMatched > items.length) {
+          console.log(
+            `${DIM}      │       │        │            │ ... and ${totalMatched - items.length} more${RESET}`,
+          );
+        }
       }
 
       console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ff-labs/fff-bun",
-  "version": "0.5.3-nightly.ea1f980",
+  "version": "0.6.0",
   "private": false,
   "description": "High-performance fuzzy file finder for Bun - perfect for LLM agent tools",
   "type": "module",
@@ -62,14 +62,14 @@
   },
   "homepage": "https://github.com/dmtrKovalenko/fff.nvim#readme",
   "optionalDependencies": {
-    "@ff-labs/fff-bin-darwin-arm64": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-darwin-x64": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-linux-x64-gnu": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-linux-arm64-gnu": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-linux-x64-musl": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-linux-arm64-musl": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-win32-x64": "0.5.3-nightly.ea1f980",
-    "@ff-labs/fff-bin-win32-arm64": "0.5.3-nightly.ea1f980"
+    "@ff-labs/fff-bin-darwin-arm64": "0.6.0",
+    "@ff-labs/fff-bin-darwin-x64": "0.6.0",
+    "@ff-labs/fff-bin-linux-x64-gnu": "0.6.0",
+    "@ff-labs/fff-bin-linux-arm64-gnu": "0.6.0",
+    "@ff-labs/fff-bin-linux-x64-musl": "0.6.0",
+    "@ff-labs/fff-bin-linux-arm64-musl": "0.6.0",
+    "@ff-labs/fff-bin-win32-x64": "0.6.0",
+    "@ff-labs/fff-bin-win32-arm64": "0.6.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",

package/src/ffi.ts

@@ -11,10 +11,14 @@
 import { CString, dlopen, FFIType, type Pointer, ptr, read } from "bun:ffi";
 import { findBinary } from "./download";
 import type {
+  DirItem,
+  DirSearchResult,
   FileItem,
   GrepMatch,
   GrepResult,
   Location,
+  MixedItem,
+  MixedSearchResult,
   Result,
   ScanProgress,
   Score,
@@ -46,7 +50,9 @@ const ffiDefinition = {
       FFIType.cstring, // frecency_db_path
       FFIType.cstring, // history_db_path
       FFIType.bool, // use_unsafe_no_lock
-      FFIType.bool, // warmup_mmap_cache
+      FFIType.bool, // enable_mmap_cache
+      FFIType.bool, // enable_content_indexing
+      FFIType.bool, // watch
       FFIType.bool, // ai_mode
     ],
     returns: FFIType.ptr,
@@ -71,6 +77,34 @@ const ffiDefinition = {
     returns: FFIType.ptr,
   },
 
+  // Directory search
+  fff_search_directories: {
+    args: [
+      FFIType.ptr, // handle
+      FFIType.cstring, // query
+      FFIType.cstring, // current_file
+      FFIType.u32, // max_threads
+      FFIType.u32, // page_index
+      FFIType.u32, // page_size
+    ],
+    returns: FFIType.ptr,
+  },
+
+  // Mixed search (files + directories)
+  fff_search_mixed: {
+    args: [
+      FFIType.ptr, // handle
+      FFIType.cstring, // query
+      FFIType.cstring, // current_file
+      FFIType.u32, // max_threads
+      FFIType.u32, // page_index
+      FFIType.u32, // page_size
+      FFIType.i32, // combo_boost_multiplier
+      FFIType.u32, // min_combo_count
+    ],
+    returns: FFIType.ptr,
+  },
+
   // Live grep (content search)
   fff_live_grep: {
     args: [
@@ -118,6 +152,10 @@ const ffiDefinition = {
     args: [FFIType.ptr],
     returns: FFIType.bool,
   },
+  fff_get_base_path: {
+    args: [FFIType.ptr],
+    returns: FFIType.ptr,
+  },
   fff_get_scan_progress: {
     args: [FFIType.ptr],
     returns: FFIType.ptr,
@@ -171,6 +209,34 @@ const ffiDefinition = {
     returns: FFIType.ptr,
   },
 
+  // Dir search result accessors / free
+  fff_free_dir_search_result: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  fff_dir_search_result_get_item: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+  fff_dir_search_result_get_score: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+
+  // Mixed search result accessors / free
+  fff_free_mixed_search_result: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  fff_mixed_search_result_get_item: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+  fff_mixed_search_result_get_score: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+
   // Grep result accessors / free
   fff_free_grep_result: {
     args: [FFIType.ptr],
@@ -355,7 +421,9 @@ export function ffiCreate(
   frecencyDbPath: string,
   historyDbPath: string,
   useUnsafeNoLock: boolean,
-  warmupMmapCache: boolean,
+  enableMmapCache: boolean,
+  enableContentIndexing: boolean,
+  watch: boolean,
   aiMode: boolean,
 ): Result<NativeHandle> {
   const library = loadLibrary();
@@ -364,7 +432,9 @@ export function ffiCreate(
     ptr(encodeString(frecencyDbPath)),
     ptr(encodeString(historyDbPath)),
     useUnsafeNoLock,
-    warmupMmapCache,
+    enableMmapCache,
+    enableContentIndexing,
+    watch,
     aiMode,
   );
 
@@ -417,18 +487,17 @@ const SR_LOC_COL = 36; // i32              (4)
 const SR_LOC_END_LINE = 40; // i32           (4)
 const SR_LOC_END_COL = 44; // i32           (4)
 
-// FffFileItem (80 bytes)
-const FI_PATH = 0; // *mut c_char (8)
-const FI_RELPATH = 8; // *mut c_char (8)
-const FI_FNAME = 16; // *mut c_char (8)
-const FI_GIT = 24; // *mut c_char (8)
-const FI_SIZE = 32; // u64         (8)
-const FI_MODIFIED = 40; // u64         (8)
-const FI_ACCESS = 48; // i64         (8)
-const FI_MODFR = 56; // i64         (8)
-const FI_TOTAL_FR = 64; // i64         (8)
-const _FI_BINARY = 72; // bool        (1 + 7 pad)
-const FI_SIZE_OF = 80;
+// FffFileItem (72 bytes)
+const FI_RELPATH = 0; // *mut c_char (8)
+const FI_FNAME = 8; // *mut c_char (8)
+const FI_GIT = 16; // *mut c_char (8)
+const FI_SIZE = 24; // u64         (8)
+const FI_MODIFIED = 32; // u64         (8)
+const FI_ACCESS = 40; // i64         (8)
+const FI_MODFR = 48; // i64         (8)
+const FI_TOTAL_FR = 56; // i64         (8)
+const _FI_BINARY = 64; // bool        (1 + 7 pad)
+const FI_SIZE_OF = 72;
 
 // FffScore (48 bytes)
 const SC_TOTAL = 0; // i32         (4)
@@ -454,7 +523,6 @@ function asPtr(n: number): Pointer {
 function readFileItemStruct(p: number): FileItem {
   const pp = asPtr(p);
   return {
-    path: readCString(read.ptr(pp, FI_PATH)) ?? "",
     relativePath: readCString(read.ptr(pp, FI_RELPATH)) ?? "",
     fileName: readCString(read.ptr(pp, FI_FNAME)) ?? "",
     gitStatus: readCString(read.ptr(pp, FI_GIT)) ?? "",
@@ -548,44 +616,251 @@ function parseSearchResult(resultPtr: Pointer | null): Result<SearchResult> {
   return { ok: true, value: result };
 }
 
+// ---------------------------------------------------------------------------
+// FffDirSearchResult byte offsets (must match #[repr(C)] layout on 64-bit)
+// { items: *mut, scores: *mut, count: u32, total_matched: u32, total_dirs: u32 }
+// ---------------------------------------------------------------------------
+const DSR_ITEMS = 0; // *mut FffDirItem  (8)
+const DSR_SCORES = 8; // *mut FffScore    (8)
+const DSR_COUNT = 16; // u32              (4)
+const DSR_MATCHED = 20; // u32              (4)
+const DSR_TOTAL_DIRS = 24; // u32              (4)
+
+// FffDirItem (24 bytes: 8 + 8 + 4 + 4pad)
+const DI_RELPATH = 0; // *mut c_char (8)
+const DI_DIRNAME = 8; // *mut c_char (8)
+const DI_MAX_FRECENCY = 16; // i32         (4)
+
+/**
+ * Read an FffDirItem struct at the given raw address.
+ */
+function readDirItemStruct(p: number): DirItem {
+  const pp = asPtr(p);
+  return {
+    relativePath: readCString(read.ptr(pp, DI_RELPATH)) ?? "",
+    dirName: readCString(read.ptr(pp, DI_DIRNAME)) ?? "",
+    maxAccessFrecency: read.i32(pp, DI_MAX_FRECENCY),
+  };
+}
+
+/**
+ * Parse an FffDirSearchResult from a raw FffResult pointer, then free native memory.
+ */
+function parseDirSearchResult(resultPtr: Pointer | null): Result<DirSearchResult> {
+  if (resultPtr === null) {
+    return err("FFI returned null pointer");
+  }
+
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+
+  if (envelope.handlePtr === 0) {
+    return err("fff_search_directories returned null search result");
+  }
+
+  const hp = asPtr(envelope.handlePtr);
+  const count = read.u32(hp, DSR_COUNT);
+  const totalMatched = read.u32(hp, DSR_MATCHED);
+  const totalDirs = read.u32(hp, DSR_TOTAL_DIRS);
+
+  const library = loadLibrary();
+
+  const items: DirItem[] = [];
+  const scores: Score[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const itemPtr = library.symbols.fff_dir_search_result_get_item(hp, i);
+    if (itemPtr !== null && (itemPtr as unknown as number) !== 0) {
+      items.push(readDirItemStruct(itemPtr as unknown as number));
+    }
+    const scorePtr = library.symbols.fff_dir_search_result_get_score(hp, i);
+    if (scorePtr !== null && (scorePtr as unknown as number) !== 0) {
+      scores.push(readScoreStruct(scorePtr as unknown as number));
+    }
+  }
+
+  // Free native dir search result
+  library.symbols.fff_free_dir_search_result(hp);
+
+  return { ok: true, value: { items, scores, totalMatched, totalDirs } };
+}
+
+// ---------------------------------------------------------------------------
+// FffMixedSearchResult byte offsets (must match #[repr(C)] layout on 64-bit)
+// { items: *mut, scores: *mut, count: u32, total_matched: u32, total_files: u32, total_dirs: u32, location: FffLocation }
+// ---------------------------------------------------------------------------
+const MSR_ITEMS = 0; // *mut FffMixedItem (8)
+const MSR_SCORES = 8; // *mut FffScore     (8)
+const MSR_COUNT = 16; // u32               (4)
+const MSR_MATCHED = 20; // u32               (4)
+const MSR_TOTAL_FILES = 24; // u32               (4)
+const MSR_TOTAL_DIRS = 28; // u32               (4)
+// FffLocation is inlined at offset 32
+const MSR_LOC_TAG = 32; // u8                (1 + 3 padding)
+const MSR_LOC_LINE = 36; // i32               (4)
+const MSR_LOC_COL = 40; // i32               (4)
+const MSR_LOC_END_LINE = 44; // i32               (4)
+const MSR_LOC_END_COL = 48; // i32               (4)
+
+// FffMixedItem (80 bytes)
+const MI_TYPE = 0; // u8          (1 + 7 pad)
+const MI_RELPATH = 8; // *mut c_char (8)
+const MI_DISPLAY = 16; // *mut c_char (8)
+const MI_GIT = 24; // *mut c_char (8)
+const MI_SIZE = 32; // u64         (8)
+const MI_MODIFIED = 40; // u64         (8)
+const MI_ACCESS = 48; // i64         (8)
+const MI_MODFR = 56; // i64         (8)
+const MI_TOTAL_FR = 64; // i64         (8)
+const MI_BINARY = 72; // bool        (1 + 7 pad)
+
+/**
+ * Read an FffMixedItem struct at the given raw address and return a MixedItem.
+ */
+function readMixedItemStruct(p: number): MixedItem {
+  const pp = asPtr(p);
+  const itemType = read.u8(pp, MI_TYPE);
+
+  if (itemType === 1) {
+    // Directory
+    return {
+      type: "directory",
+      item: {
+        relativePath: readCString(read.ptr(pp, MI_RELPATH)) ?? "",
+        dirName: readCString(read.ptr(pp, MI_DISPLAY)) ?? "",
+        maxAccessFrecency: Number(read.i64(pp, MI_ACCESS)),
+      },
+    };
+  }
+
+  // File (itemType === 0)
+  return {
+    type: "file",
+    item: {
+      relativePath: readCString(read.ptr(pp, MI_RELPATH)) ?? "",
+      fileName: readCString(read.ptr(pp, MI_DISPLAY)) ?? "",
+      gitStatus: readCString(read.ptr(pp, MI_GIT)) ?? "",
+      size: Number(read.u64(pp, MI_SIZE)),
+      modified: Number(read.u64(pp, MI_MODIFIED)),
+      accessFrecencyScore: Number(read.i64(pp, MI_ACCESS)),
+      modificationFrecencyScore: Number(read.i64(pp, MI_MODFR)),
+      totalFrecencyScore: Number(read.i64(pp, MI_TOTAL_FR)),
+    },
+  };
+}
+
+/**
+ * Parse an FffMixedSearchResult from a raw FffResult pointer, then free native memory.
+ */
+function parseMixedSearchResult(resultPtr: Pointer | null): Result<MixedSearchResult> {
+  if (resultPtr === null) {
+    return err("FFI returned null pointer");
+  }
+
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+
+  if (envelope.handlePtr === 0) {
+    return err("fff_search_mixed returned null search result");
+  }
+
+  const hp = asPtr(envelope.handlePtr);
+  const count = read.u32(hp, MSR_COUNT);
+  const totalMatched = read.u32(hp, MSR_MATCHED);
+  const totalFiles = read.u32(hp, MSR_TOTAL_FILES);
+  const totalDirs = read.u32(hp, MSR_TOTAL_DIRS);
+
+  // Read location
+  const locTag = read.u8(hp, MSR_LOC_TAG);
+  let location: Location | undefined;
+  if (locTag === 1) {
+    location = { type: "line", line: read.i32(hp, MSR_LOC_LINE) };
+  } else if (locTag === 2) {
+    location = {
+      type: "position",
+      line: read.i32(hp, MSR_LOC_LINE),
+      col: read.i32(hp, MSR_LOC_COL),
+    };
+  } else if (locTag === 3) {
+    location = {
+      type: "range",
+      start: { line: read.i32(hp, MSR_LOC_LINE), col: read.i32(hp, MSR_LOC_COL) },
+      end: {
+        line: read.i32(hp, MSR_LOC_END_LINE),
+        col: read.i32(hp, MSR_LOC_END_COL),
+      },
+    };
+  }
+
+  const library = loadLibrary();
+
+  const items: MixedItem[] = [];
+  const scores: Score[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const itemPtr = library.symbols.fff_mixed_search_result_get_item(hp, i);
+    if (itemPtr !== null && (itemPtr as unknown as number) !== 0) {
+      items.push(readMixedItemStruct(itemPtr as unknown as number));
+    }
+    const scorePtr = library.symbols.fff_mixed_search_result_get_score(hp, i);
+    if (scorePtr !== null && (scorePtr as unknown as number) !== 0) {
+      scores.push(readScoreStruct(scorePtr as unknown as number));
+    }
+  }
+
+  // Free native mixed search result
+  library.symbols.fff_free_mixed_search_result(hp);
+
+  const result: MixedSearchResult = {
+    items,
+    scores,
+    totalMatched,
+    totalFiles,
+    totalDirs,
+  };
+  if (location) {
+    result.location = location;
+  }
+  return { ok: true, value: result };
+}
+
 // ---------------------------------------------------------------------------
 // FffGrepMatch byte offsets (must match #[repr(C)] layout on 64-bit)
 // ---------------------------------------------------------------------------
 
 // Pointers (8 bytes each)
-const GM_PATH = 0;
-const GM_RELPATH = 8;
-const GM_FNAME = 16;
-const GM_GIT = 24;
-const GM_LINE_CONTENT = 32;
-const GM_MATCH_RANGES = 40;
-const GM_CTX_BEFORE = 48;
-const GM_CTX_AFTER = 56;
+const GM_RELPATH = 0;
+const GM_FNAME = 8;
+const GM_GIT = 16;
+const GM_LINE_CONTENT = 24;
+const GM_MATCH_RANGES = 32;
+const GM_CTX_BEFORE = 40;
+const GM_CTX_AFTER = 48;
 
 // 8-byte numeric fields
-const GM_SIZE = 64;
-const GM_MODIFIED = 72;
-const GM_TOTAL_FR = 80;
-const GM_ACCESS_FR = 88;
-const GM_MOD_FR = 96;
-const GM_LINE_NUM = 104;
-const GM_BYTE_OFF = 112;
+const GM_SIZE = 56;
+const GM_MODIFIED = 64;
+const GM_TOTAL_FR = 72;
+const GM_ACCESS_FR = 80;
+const GM_MOD_FR = 88;
+const GM_LINE_NUM = 96;
+const GM_BYTE_OFF = 104;
 
 // 4-byte fields
-const GM_COL = 120;
-const GM_MR_COUNT = 124;
-const GM_CTX_B_COUNT = 128;
-const GM_CTX_A_COUNT = 132;
+const GM_COL = 112;
+const GM_MR_COUNT = 116;
+const GM_CTX_B_COUNT = 120;
+const GM_CTX_A_COUNT = 124;
 
 // 2-byte
-const GM_FUZZY_SCORE = 136;
+const GM_FUZZY_SCORE = 128;
 // 1-byte
-const GM_HAS_FUZZY = 138;
-const GM_IS_BINARY = 139;
-const _GM_IS_DEF = 140;
+const GM_HAS_FUZZY = 130;
+const GM_IS_BINARY = 131;
+const _GM_IS_DEF = 132;
 
-// struct size: pad to 8-byte alignment → 144
-const GM_SIZE_OF = 144;
+// struct size: pad to 8-byte alignment → 136
+const GM_SIZE_OF = 136;
 
 // FffGrepResult
 const GR_ITEMS = 0; // *mut FffGrepMatch (8)
@@ -635,7 +910,6 @@ function readGrepMatchStruct(p: number): GrepMatch {
   const ctxAfterCount = read.u32(pp, GM_CTX_A_COUNT);
 
   const match: GrepMatch = {
-    path: readCString(read.ptr(pp, GM_PATH)) ?? "",
     relativePath: readCString(read.ptr(pp, GM_RELPATH)) ?? "",
     fileName: readCString(read.ptr(pp, GM_FNAME)) ?? "",
     gitStatus: readCString(read.ptr(pp, GM_GIT)) ?? "",
@@ -735,6 +1009,56 @@ export function ffiSearch(
   return parseSearchResult(resultPtr);
 }
 
+/**
+ * Perform fuzzy directory search.
+ */
+export function ffiSearchDirectories(
+  handle: NativeHandle,
+  query: string,
+  currentFile: string | null,
+  maxThreads: number,
+  pageIndex: number,
+  pageSize: number,
+): Result<DirSearchResult> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_search_directories(
+    handle,
+    ptr(encodeString(query)),
+    ptr(encodeString(currentFile ?? "")),
+    maxThreads,
+    pageIndex,
+    pageSize,
+  );
+  return parseDirSearchResult(resultPtr);
+}
+
+/**
+ * Perform mixed (files + directories) fuzzy search.
+ */
+export function ffiSearchMixed(
+  handle: NativeHandle,
+  query: string,
+  currentFile: string,
+  maxThreads: number,
+  pageIndex: number,
+  pageSize: number,
+  comboBoostMultiplier: number,
+  minComboCount: number,
+): Result<MixedSearchResult> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_search_mixed(
+    handle,
+    ptr(encodeString(query)),
+    ptr(encodeString(currentFile)),
+    maxThreads,
+    pageIndex,
+    pageSize,
+    comboBoostMultiplier,
+    minComboCount,
+  );
+  return parseMixedSearchResult(resultPtr);
+}
+
 /**
  * Live grep - search file contents.
  */
@@ -822,6 +1146,15 @@ export function ffiIsScanning(handle: NativeHandle): boolean {
   return library.symbols.fff_is_scanning(handle) as boolean;
 }
 
+/**
+ * Get the base path of the file picker.
+ */
+export function ffiGetBasePath(handle: NativeHandle): Result<string | null> {
+  const library = loadLibrary();
+  const resultPtr = library.symbols.fff_get_base_path(handle);
+  return parseStringResult(resultPtr);
+}
+
 // FffScanProgress { scanned_files_count: u64(8), is_scanning: bool(1), is_watcher_ready: bool(1), is_warmup_complete: bool(1) + pad }
 const SP_COUNT = 0; // u64 (8)
 const SP_SCANNING = 8; // bool (1)

package/src/finder.ts

@@ -12,6 +12,7 @@ import {
   ensureLoaded,
   ffiCreate,
   ffiDestroy,
+  ffiGetBasePath,
   ffiGetHistoricalQuery,
   ffiGetScanProgress,
   ffiHealthCheck,
@@ -22,6 +23,8 @@ import {
   ffiRestartIndex,
   ffiScanFiles,
   ffiSearch,
+  ffiSearchDirectories,
+  ffiSearchMixed,
   ffiTrackQuery,
   ffiWaitForScan,
   ffiWaitForWatcher,
@@ -30,10 +33,13 @@ import {
 } from "./ffi";
 
 import type {
+  DirSearchOptions,
+  DirSearchResult,
   GrepOptions,
   GrepResult,
   HealthCheck,
-  InitOptions,
+  InitOptions as FFFInitOptions,
+  MixedSearchResult,
   MultiGrepOptions,
   Result,
   ScanProgress,
@@ -101,13 +107,15 @@ export class FileFinder {
    * });
    * ```
    */
-  static create(options: InitOptions): Result<FileFinder> {
+  static create(options: FFFInitOptions): Result<FileFinder> {
     const result = ffiCreate(
       options.basePath,
       options.frecencyDbPath ?? "",
       options.historyDbPath ?? "",
       options.useUnsafeNoLock ?? false,
-      options.warmupMmapCache ?? false,
+      !(options.disableMmapCache ?? false),
+      !(options.disableContentIndexing ?? options.disableMmapCache ?? false),
+      !(options.disableWatch ?? false),
       options.aiMode ?? false,
     );
 
@@ -189,6 +197,77 @@ export class FileFinder {
     );
   }
 
+  /**
+   * Search for directories matching the query.
+   *
+   * @param query - Search query string
+   * @param options - Directory search options
+   * @returns Search results with matched directories and scores
+   *
+   * @example
+   * ```typescript
+   * const result = finder.directorySearch("components", { pageSize: 10 });
+   * if (result.ok) {
+   *   console.log(`Found ${result.value.totalMatched} directories`);
+   *   for (const item of result.value.items) {
+   *     console.log(item.relativePath);
+   *   }
+   * }
+   * ```
+   */
+  directorySearch(query: string, options?: DirSearchOptions): Result<DirSearchResult> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+
+    return ffiSearchDirectories(
+      guard.value,
+      query,
+      options?.currentFile ?? null,
+      options?.maxThreads ?? 0,
+      options?.pageIndex ?? 0,
+      options?.pageSize ?? 0,
+    );
+  }
+
+  /**
+   * Search for files and directories together (mixed search).
+   *
+   * Results are interleaved by total score in descending order.
+   *
+   * @param query - Search query string
+   * @param options - Search options
+   * @returns Mixed search results with files and directories interleaved by score
+   *
+   * @example
+   * ```typescript
+   * const result = finder.mixedSearch("main", { pageSize: 20 });
+   * if (result.ok) {
+   *   for (const entry of result.value.items) {
+   *     if (entry.type === "file") {
+   *       console.log(`File: ${entry.item.relativePath}`);
+   *     } else {
+   *       console.log(`Dir: ${entry.item.relativePath}`);
+   *     }
+   *   }
+   * }
+   * ```
+   */
+  mixedSearch(query: string, options?: SearchOptions): Result<MixedSearchResult> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+
+    return ffiSearchMixed(
+      guard.value,
+      query,
+      options?.currentFile ?? "",
+      options?.maxThreads ?? 0,
+      options?.pageIndex ?? 0,
+      options?.pageSize ?? 0,
+      options?.comboBoostMultiplier ?? 0,
+      options?.minComboCount ?? 0,
+    );
+  }
+
   /**
    * Search file contents (live grep).
    *
@@ -314,6 +393,15 @@ export class FileFinder {
     return ffiIsScanning(this.handle);
   }
 
+  /**
+   * Get the base path of the file picker (the root directory being indexed).
+   */
+  getBasePath(): Result<string | null> {
+    const guard = this.ensureAlive();
+    if (!guard.ok) return guard;
+    return ffiGetBasePath(guard.value);
+  }
+
   /**
    * Get the current scan progress.
    */

package/src/index.ts

@@ -52,6 +52,9 @@ export {
 
 export type {
   DbHealth,
+  DirItem,
+  DirSearchOptions,
+  DirSearchResult,
   FileItem,
   GrepCursor,
   GrepMatch,
@@ -61,6 +64,8 @@ export type {
   HealthCheck,
   InitOptions,
   Location,
+  MixedItem,
+  MixedSearchResult,
   MultiGrepOptions,
   Result,
   ScanProgress,

package/src/types.ts

@@ -30,12 +30,24 @@ export interface InitOptions {
   /** Use unsafe no-lock mode for databases (optional, defaults to false) */
   useUnsafeNoLock?: boolean;
   /**
-   * Pre-populate mmap caches for all files after the initial scan completes.
-   * When enabled, the first grep search will be as fast as subsequent ones
-   * at the cost of a longer scan time and higher initial memory usage.
+   * Disable mmap cache warmup after the initial scan. When mmap cache is
+   * enabled (the default), the first grep search is as fast as subsequent
+   * ones at the cost of background resources spent on awarming up the cache
+   */
+  disableMmapCache?: boolean;
+  /**
+   * Disable the content index built after the initial scan.
+   * Content indexing enables faster content-aware filtering during grep.
+   * When omitted, follows `disableMmapCache` for backward compatibility.
+   * (default: follows `disableMmapCache`)
+   */
+  disableContentIndexing?: boolean;
+  /**
+   * Disable the background file-system watcher. When the watcher is
+   * disabled, files are scanned once but not monitored for changes.
    * (default: false)
    */
-  warmupMmapCache?: boolean;
+  disableWatch?: boolean;
   /** enables optimizations for AI agent assistants. Provide as true if running via mcp/agent */
   aiMode?: boolean;
 }
@@ -62,8 +74,6 @@ export interface SearchOptions {
  * A file item in search results
  */
 export interface FileItem {
-  /** Absolute path to the file */
-  path: string;
   /** Path relative to the indexed directory */
   relativePath: string;
   /** File name only */
@@ -136,6 +146,72 @@ export interface SearchResult {
   location?: Location;
 }
 
+/**
+ * A directory item in search results
+ */
+export interface DirItem {
+  /** Path relative to the indexed directory (e.g., "src/components/") */
+  relativePath: string;
+  /** Last path segment (e.g., "components/" for "src/components/") */
+  dirName: string;
+  /** Maximum access frecency score among direct child files */
+  maxAccessFrecency: number;
+}
+
+/**
+ * Search options for directory search (subset of SearchOptions)
+ */
+export interface DirSearchOptions {
+  /** Maximum threads for parallel search (0 = auto) */
+  maxThreads?: number;
+  /** Current file path (for distance scoring) */
+  currentFile?: string;
+  /** Page index for pagination (default: 0) */
+  pageIndex?: number;
+  /** Page size for pagination (default: 100) */
+  pageSize?: number;
+}
+
+/**
+ * Search result from fuzzy directory search
+ */
+export interface DirSearchResult {
+  /** Matched directory items */
+  items: DirItem[];
+  /** Corresponding scores for each item */
+  scores: Score[];
+  /** Total number of directories that matched */
+  totalMatched: number;
+  /** Total number of indexed directories */
+  totalDirs: number;
+}
+
+/**
+ * A single item in a mixed (files + directories) search result
+ */
+export type MixedItem =
+  | { type: "file"; item: FileItem }
+  | { type: "directory"; item: DirItem };
+
+/**
+ * Search result from mixed (files + directories) fuzzy search.
+ * Items are interleaved by total score in descending order.
+ */
+export interface MixedSearchResult {
+  /** Matched items (files and directories interleaved by score) */
+  items: MixedItem[];
+  /** Corresponding scores for each item */
+  scores: Score[];
+  /** Total number of items (files + dirs) that matched */
+  totalMatched: number;
+  /** Total number of indexed files */
+  totalFiles: number;
+  /** Total number of indexed directories */
+  totalDirs: number;
+  /** Location parsed from query */
+  location?: Location;
+}
+
 /**
  * Scan progress information
  */
@@ -271,8 +347,6 @@ export interface GrepOptions {
  * A single grep match with file and line information
  */
 export interface GrepMatch {
-  /** Absolute path to the file */
-  path: string;
   /** Path relative to the indexed directory */
   relativePath: string;
   /** File name only */