@ff-labs/fff-bun 0.2.4-dev.233679d → 0.2.4-dev.8d9ef38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ff-labs/fff-bun",
-  "version": "0.2.4-dev.233679d",
+  "version": "0.2.4-dev.8d9ef38",
   "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.2.4-dev.233679d",
-    "@ff-labs/fff-bin-darwin-x64": "0.2.4-dev.233679d",
-    "@ff-labs/fff-bin-linux-x64-gnu": "0.2.4-dev.233679d",
-    "@ff-labs/fff-bin-linux-arm64-gnu": "0.2.4-dev.233679d",
-    "@ff-labs/fff-bin-linux-x64-musl": "0.2.4-dev.233679d",
-    "@ff-labs/fff-bin-linux-arm64-musl": "0.2.4-dev.233679d",
-    "@ff-labs/fff-bin-win32-x64": "0.2.4-dev.233679d",
-    "@ff-labs/fff-bin-win32-arm64": "0.2.4-dev.233679d"
+    "@ff-labs/fff-bin-darwin-arm64": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-darwin-x64": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-linux-x64-gnu": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-linux-arm64-gnu": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-linux-x64-musl": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-linux-arm64-musl": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-win32-x64": "0.2.4-dev.8d9ef38",
+    "@ff-labs/fff-bin-win32-arm64": "0.2.4-dev.8d9ef38"
   },
   "devDependencies": {
     "@types/bun": "^1.3.8",

package/src/ffi.ts

@@ -10,8 +10,16 @@
 
 import { CString, dlopen, FFIType, type Pointer, ptr, read } from "bun:ffi";
 import { findBinary } from "./download";
-import type { FileItem, Location, Result, Score, SearchResult } from "./types";
-import { err } from "./types";
+import type {
+  FileItem,
+  GrepMatch,
+  GrepResult,
+  Location,
+  Result,
+  Score,
+  SearchResult,
+} from "./types";
+import { createGrepCursor, err } from "./types";
 
 /** Grep mode constants matching the C API (u8). */
 const GREP_MODE_PLAIN = 0;
@@ -144,7 +152,7 @@ const ffiDefinition = {
     returns: FFIType.ptr,
   },
 
-  // Search result accessors
+  // Search result accessors / free
   fff_free_search_result: {
     args: [FFIType.ptr],
     returns: FFIType.void,
@@ -158,6 +166,16 @@ const ffiDefinition = {
     returns: FFIType.ptr,
   },
 
+  // Grep result accessors / free
+  fff_free_grep_result: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
+  fff_grep_result_get_match: {
+    args: [FFIType.ptr, FFIType.u32],
+    returns: FFIType.ptr,
+  },
+
   // Memory management
   fff_free_result: {
     args: [FFIType.ptr],
@@ -167,6 +185,10 @@ const ffiDefinition = {
     args: [FFIType.ptr],
     returns: FFIType.void,
   },
+  fff_free_scan_progress: {
+    args: [FFIType.ptr],
+    returns: FFIType.void,
+  },
 } as const;
 
 type FFFLibrary = ReturnType<typeof dlopen<typeof ffiDefinition>>;
@@ -219,59 +241,100 @@ function snakeToCamel(obj: unknown): unknown {
 
   const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
-    const camelKey = key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+    const camelKey = key.replace(/_([a-z])/g, (_, letter) =>
+      letter.toUpperCase(),
+    );
     result[camelKey] = snakeToCamel(value);
   }
   return result;
 }
 
+// ---------------------------------------------------------------------------
+// FffResult byte offsets (must match #[repr(C)] layout on 64-bit)
+// { success: bool(1+7pad), error: *char(8), handle: *void(8), int_value: i64(8) }
+// ---------------------------------------------------------------------------
+const RES_SUCCESS   = 0;   // bool (1 + 7 padding)
+const RES_ERROR     = 8;   // *mut c_char (8)
+const RES_HANDLE    = 16;  // *mut c_void (8)
+const RES_INT_VALUE = 24;  // i64         (8)
+
 /**
- * Parse a FffResult from the FFI return value.
- *
- * The result is a pointer to a struct:
- *   { success: bool, data: *char, error: *char, handle: *void }
- *
- * Layout (with alignment padding):
- *   offset  0: success (bool, 1 byte + 7 padding)
- *   offset  8: data pointer (8 bytes)
- *   offset 16: error pointer (8 bytes)
- *   offset 24: handle pointer (8 bytes)
+ * Read the FffResult envelope: check success, extract payload, free envelope.
+ * On error returns a Result<never>. On success returns the raw handle pointer and int_value.
  */
-function parseResult<T>(resultPtr: Pointer | null): Result<T> {
+function readResultEnvelope(resultPtr: Pointer | null): { success: true; handlePtr: number; intValue: number } | Result<never> {
   if (resultPtr === null) {
     return err("FFI returned null pointer");
   }
 
-  const success = read.u8(resultPtr, 0) !== 0;
-  const dataPtr = read.ptr(resultPtr, 8);
-  const errorPtr = read.ptr(resultPtr, 16);
-
+  const success = read.u8(resultPtr, RES_SUCCESS) !== 0;
   const library = loadLibrary();
 
-  if (success) {
-    const data = readCString(dataPtr);
-    // Free the result
-    library.symbols.fff_free_result(resultPtr);
-
-    if (data === null || data === "") {
-      return { ok: true, value: undefined as T };
-    }
-
-    try {
-      const parsed = JSON.parse(data);
-      // Convert snake_case to camelCase for TypeScript consumers
-      const transformed = snakeToCamel(parsed) as T;
-      return { ok: true, value: transformed };
-    } catch {
-      // For simple values like "true" or numbers
-      return { ok: true, value: data as T };
-    }
-  } else {
+  if (!success) {
+    const errorPtr = read.ptr(resultPtr, RES_ERROR);
     const errorMsg = readCString(errorPtr) || "Unknown error";
-    // Free the result
     library.symbols.fff_free_result(resultPtr);
     return err(errorMsg);
   }
+
+  const handlePtr = read.ptr(resultPtr, RES_HANDLE);
+  const intValue = Number(read.i64(resultPtr, RES_INT_VALUE));
+  library.symbols.fff_free_result(resultPtr);
+  return { success: true, handlePtr, intValue };
+}
+
+/** Parse a FffResult that carries a bool in int_value (0 = false, nonzero = true). */
+function parseBoolResult(resultPtr: Pointer | null): Result<boolean> {
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+  return { ok: true, value: envelope.intValue !== 0 };
+}
+
+/** Parse a FffResult that carries an integer in int_value. */
+function parseIntResult(resultPtr: Pointer | null): Result<number> {
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+  return { ok: true, value: envelope.intValue };
+}
+
+/** Parse a FffResult that carries a string in handle (freed with fff_free_string). */
+function parseStringResult(resultPtr: Pointer | null): Result<string | null> {
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+
+  if (envelope.handlePtr === 0) return { ok: true, value: null };
+
+  const library = loadLibrary();
+  const str = readCString(envelope.handlePtr);
+  library.symbols.fff_free_string(asPtr(envelope.handlePtr));
+  return { ok: true, value: str };
+}
+
+/** Parse a FffResult that carries a JSON string in handle. */
+function parseJsonResult<T>(resultPtr: Pointer | null): Result<T> {
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+
+  if (envelope.handlePtr === 0) return { ok: true, value: undefined as T };
+
+  const library = loadLibrary();
+  const jsonStr = readCString(envelope.handlePtr);
+  library.symbols.fff_free_string(asPtr(envelope.handlePtr));
+
+  if (jsonStr === null || jsonStr === "") return { ok: true, value: undefined as T };
+
+  try {
+    return { ok: true, value: snakeToCamel(JSON.parse(jsonStr)) as T };
+  } catch {
+    return { ok: true, value: jsonStr as T };
+  }
+}
+
+/** Parse a FffResult with no payload (void, success/error only). */
+function parseVoidResult(resultPtr: Pointer | null): Result<void> {
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+  return { ok: true, value: undefined };
 }
 
 /**
@@ -304,9 +367,9 @@ export function ffiCreate(
     return err("FFI returned null pointer");
   }
 
-  const success = read.u8(resultPtr, 0) !== 0;
-  const errorPtr = read.ptr(resultPtr, 16);
-  const handlePtr = read.ptr(resultPtr, 24);
+  const success = read.u8(resultPtr, RES_SUCCESS) !== 0;
+  const errorPtr = read.ptr(resultPtr, RES_ERROR);
+  const handlePtr = read.ptr(resultPtr, RES_HANDLE);
 
   if (success) {
     const handle = handlePtr as unknown as Pointer;
@@ -337,43 +400,43 @@ export function ffiDestroy(handle: NativeHandle): void {
 // ---------------------------------------------------------------------------
 
 // FffSearchResult { items: *mut, scores: *mut, count: u32, total_matched: u32, total_files: u32, location: FffLocation }
-const SR_ITEMS    = 0;   // *mut FffFileItem (8)
-const SR_SCORES   = 8;   // *mut FffScore    (8)
-const SR_COUNT    = 16;  // u32              (4)
-const SR_MATCHED  = 20;  // u32              (4)
-const SR_TOTAL    = 24;  // u32              (4)
+const SR_ITEMS = 0; // *mut FffFileItem (8)
+const SR_SCORES = 8; // *mut FffScore    (8)
+const SR_COUNT = 16; // u32              (4)
+const SR_MATCHED = 20; // u32              (4)
+const SR_TOTAL = 24; // u32              (4)
 // FffLocation is inlined at offset 28
-const SR_LOC_TAG  = 28;  // u8               (1 + 3 padding)
-const SR_LOC_LINE = 32;  // i32              (4)
-const SR_LOC_COL  = 36;  // i32              (4)
+const SR_LOC_TAG = 28; // u8               (1 + 3 padding)
+const SR_LOC_LINE = 32; // i32              (4)
+const SR_LOC_COL = 36; // i32              (4)
 const SR_LOC_END_LINE = 40; // i32           (4)
-const SR_LOC_END_COL  = 44; // 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;
+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;
 
 // FffScore (48 bytes)
-const SC_TOTAL    = 0;   // i32         (4)
-const SC_BASE     = 4;   // i32         (4)
-const SC_FNAME    = 8;   // i32         (4)
-const SC_SPECIAL  = 12;  // i32         (4)
-const SC_FREC     = 16;  // i32         (4)
-const SC_DIST     = 20;  // i32         (4)
-const SC_CURFILE  = 24;  // i32         (4)
-const SC_COMBO    = 28;  // i32         (4)
-const SC_EXACT    = 32;  // bool        (1 + 7 pad)
-const SC_MTYPE    = 40;  // *mut c_char (8)
-const SC_SIZE_OF  = 48;
+const SC_TOTAL = 0; // i32         (4)
+const SC_BASE = 4; // i32         (4)
+const SC_FNAME = 8; // i32         (4)
+const SC_SPECIAL = 12; // i32         (4)
+const SC_FREC = 16; // i32         (4)
+const SC_DIST = 20; // i32         (4)
+const SC_CURFILE = 24; // i32         (4)
+const SC_COMBO = 28; // i32         (4)
+const SC_EXACT = 32; // bool        (1 + 7 pad)
+const SC_MTYPE = 40; // *mut c_char (8)
+const SC_SIZE_OF = 48;
 
 /** Cast a number (raw address from pointer math) to Pointer for read.*. */
 function asPtr(n: number): Pointer {
@@ -386,15 +449,15 @@ 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)) ?? "",
-    size:                      Number(read.u64(pp, FI_SIZE)),
-    modified:                  Number(read.u64(pp, FI_MODIFIED)),
-    accessFrecencyScore:       Number(read.i64(pp, FI_ACCESS)),
+    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)) ?? "",
+    size: Number(read.u64(pp, FI_SIZE)),
+    modified: Number(read.u64(pp, FI_MODIFIED)),
+    accessFrecencyScore: Number(read.i64(pp, FI_ACCESS)),
     modificationFrecencyScore: Number(read.i64(pp, FI_MODFR)),
-    totalFrecencyScore:        Number(read.i64(pp, FI_TOTAL_FR)),
+    totalFrecencyScore: Number(read.i64(pp, FI_TOTAL_FR)),
   };
 }
 
@@ -404,16 +467,16 @@ function readFileItemStruct(p: number): FileItem {
 function readScoreStruct(p: number): Score {
   const pp = asPtr(p);
   return {
-    total:               read.i32(pp, SC_TOTAL),
-    baseScore:           read.i32(pp, SC_BASE),
-    filenameBonus:       read.i32(pp, SC_FNAME),
-    specialFilenameBonus:read.i32(pp, SC_SPECIAL),
-    frecencyBoost:       read.i32(pp, SC_FREC),
-    distancePenalty:     read.i32(pp, SC_DIST),
-    currentFilePenalty:  read.i32(pp, SC_CURFILE),
-    comboMatchBoost:     read.i32(pp, SC_COMBO),
-    exactMatch:          read.u8(pp, SC_EXACT) !== 0,
-    matchType:           readCString(read.ptr(pp, SC_MTYPE)) ?? "",
+    total: read.i32(pp, SC_TOTAL),
+    baseScore: read.i32(pp, SC_BASE),
+    filenameBonus: read.i32(pp, SC_FNAME),
+    specialFilenameBonus: read.i32(pp, SC_SPECIAL),
+    frecencyBoost: read.i32(pp, SC_FREC),
+    distancePenalty: read.i32(pp, SC_DIST),
+    currentFilePenalty: read.i32(pp, SC_CURFILE),
+    comboMatchBoost: read.i32(pp, SC_COMBO),
+    exactMatch: read.u8(pp, SC_EXACT) !== 0,
+    matchType: readCString(read.ptr(pp, SC_MTYPE)) ?? "",
   };
 }
 
@@ -425,33 +488,19 @@ function parseSearchResult(resultPtr: Pointer | null): Result<SearchResult> {
     return err("FFI returned null pointer");
   }
 
-  const success = read.u8(resultPtr, 0) !== 0;
-  const errorPtr = read.ptr(resultPtr, 16);
-  const handlePtr = read.ptr(resultPtr, 24);
-
-  const library = loadLibrary();
-
-  if (!success) {
-    const errorMsg = readCString(errorPtr) || "Unknown error";
-    library.symbols.fff_free_result(resultPtr);
-    return err(errorMsg);
-  }
-
-  // Free the FffResult envelope (does NOT free handle)
-  library.symbols.fff_free_result(resultPtr);
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
 
-  if (handlePtr === 0) {
+  if (envelope.handlePtr === 0) {
     return err("fff_search returned null search result");
   }
 
-  // Read FffSearchResult struct from handlePtr
-  // Cast number to Pointer for Bun's read.* type requirements
-  const hp = handlePtr as unknown as Pointer;
-  const count        = read.u32(hp, SR_COUNT);
+  const hp = asPtr(envelope.handlePtr);
+  const count = read.u32(hp, SR_COUNT);
   const totalMatched = read.u32(hp, SR_MATCHED);
-  const totalFiles   = read.u32(hp, SR_TOTAL);
-  const itemsBase    = read.ptr(hp, SR_ITEMS);
-  const scoresBase   = read.ptr(hp, SR_SCORES);
+  const totalFiles = read.u32(hp, SR_TOTAL);
+  const itemsBase = read.ptr(hp, SR_ITEMS);
+  const scoresBase = read.ptr(hp, SR_SCORES);
 
   // Read location
   const locTag = read.u8(hp, SR_LOC_TAG);
@@ -459,12 +508,19 @@ function parseSearchResult(resultPtr: Pointer | null): Result<SearchResult> {
   if (locTag === 1) {
     location = { type: "line", line: read.i32(hp, SR_LOC_LINE) };
   } else if (locTag === 2) {
-    location = { type: "position", line: read.i32(hp, SR_LOC_LINE), col: read.i32(hp, SR_LOC_COL) };
+    location = {
+      type: "position",
+      line: read.i32(hp, SR_LOC_LINE),
+      col: read.i32(hp, SR_LOC_COL),
+    };
   } else if (locTag === 3) {
     location = {
       type: "range",
       start: { line: read.i32(hp, SR_LOC_LINE), col: read.i32(hp, SR_LOC_COL) },
-      end: { line: read.i32(hp, SR_LOC_END_LINE), col: read.i32(hp, SR_LOC_END_COL) },
+      end: {
+        line: read.i32(hp, SR_LOC_END_LINE),
+        col: read.i32(hp, SR_LOC_END_COL),
+      },
     };
   }
 
@@ -478,7 +534,7 @@ function parseSearchResult(resultPtr: Pointer | null): Result<SearchResult> {
   }
 
   // Free native search result
-  library.symbols.fff_free_search_result(hp);
+  loadLibrary().symbols.fff_free_search_result(hp);
 
   const result: SearchResult = { items, scores, totalMatched, totalFiles };
   if (location) {
@@ -487,6 +543,172 @@ function parseSearchResult(resultPtr: Pointer | null): Result<SearchResult> {
   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;
+
+// 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;
+
+// 4-byte fields
+const GM_COL = 120;
+const GM_MR_COUNT = 124;
+const GM_CTX_B_COUNT = 128;
+const GM_CTX_A_COUNT = 132;
+
+// 2-byte
+const GM_FUZZY_SCORE = 136;
+// 1-byte
+const GM_HAS_FUZZY = 138;
+const GM_IS_BINARY = 139;
+const _GM_IS_DEF = 140;
+
+// struct size: pad to 8-byte alignment → 144
+const GM_SIZE_OF = 144;
+
+// FffGrepResult
+const GR_ITEMS = 0; // *mut FffGrepMatch (8)
+const GR_COUNT = 8; // u32 (4)
+const GR_MATCHED = 12; // u32 (4)
+const GR_FILES_SEARCHED = 16; // u32 (4)
+const GR_TOTAL_FILES = 20; // u32 (4)
+const GR_FILTERED = 24; // u32 (4)
+const GR_NEXT_OFFSET = 28; // u32 (4)
+const GR_REGEX_ERR = 32; // *mut c_char (8)
+
+// FffMatchRange (8 bytes)
+const MR_START = 0;
+const MR_END = 4;
+const MR_SIZE = 8;
+
+/**
+ * Read a C string array (char**) at the given pointer, with `count` elements.
+ */
+function readCStringArray(base: number, count: number): string[] {
+  if (count === 0 || base === 0) return [];
+  const result: string[] = [];
+  const bp = asPtr(base);
+  for (let i = 0; i < count; i++) {
+    const strPtr = read.ptr(bp, i * 8); // each pointer is 8 bytes
+    result.push(readCString(strPtr) ?? "");
+  }
+  return result;
+}
+
+/**
+ * Read an FffGrepMatch struct at the given raw address.
+ */
+function readGrepMatchStruct(p: number): GrepMatch {
+  const pp = asPtr(p);
+  const matchRangesPtr = read.ptr(pp, GM_MATCH_RANGES);
+  const matchRangesCount = read.u32(pp, GM_MR_COUNT);
+  const matchRanges: [number, number][] = [];
+  for (let i = 0; i < matchRangesCount; i++) {
+    const base = matchRangesPtr + i * MR_SIZE;
+    const bp = asPtr(base);
+    matchRanges.push([read.u32(bp, MR_START), read.u32(bp, MR_END)]);
+  }
+
+  const hasFuzzy = read.u8(pp, GM_HAS_FUZZY) !== 0;
+  const ctxBeforeCount = read.u32(pp, GM_CTX_B_COUNT);
+  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)) ?? "",
+    lineContent: readCString(read.ptr(pp, GM_LINE_CONTENT)) ?? "",
+    size: Number(read.u64(pp, GM_SIZE)),
+    modified: Number(read.u64(pp, GM_MODIFIED)),
+    totalFrecencyScore: Number(read.i64(pp, GM_TOTAL_FR)),
+    accessFrecencyScore: Number(read.i64(pp, GM_ACCESS_FR)),
+    modificationFrecencyScore: Number(read.i64(pp, GM_MOD_FR)),
+    isBinary: read.u8(pp, GM_IS_BINARY) !== 0,
+    lineNumber: Number(read.u64(pp, GM_LINE_NUM)),
+    col: read.u32(pp, GM_COL),
+    byteOffset: Number(read.u64(pp, GM_BYTE_OFF)),
+    matchRanges,
+  };
+
+  if (hasFuzzy) {
+    match.fuzzyScore = read.u16(pp, GM_FUZZY_SCORE);
+  }
+  if (ctxBeforeCount > 0) {
+    match.contextBefore = readCStringArray(
+      read.ptr(pp, GM_CTX_BEFORE),
+      ctxBeforeCount,
+    );
+  }
+  if (ctxAfterCount > 0) {
+    match.contextAfter = readCStringArray(
+      read.ptr(pp, GM_CTX_AFTER),
+      ctxAfterCount,
+    );
+  }
+
+  return match;
+}
+
+/**
+ * Parse an FffGrepResult from a raw FffResult pointer, then free native memory.
+ */
+function parseGrepResult(resultPtr: Pointer | null): Result<GrepResult> {
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+
+  if (envelope.handlePtr === 0) {
+    return err("grep returned null result");
+  }
+
+  const hp = asPtr(envelope.handlePtr);
+  const count = read.u32(hp, GR_COUNT);
+  const totalMatched = read.u32(hp, GR_MATCHED);
+  const totalFilesSearched = read.u32(hp, GR_FILES_SEARCHED);
+  const totalFiles = read.u32(hp, GR_TOTAL_FILES);
+  const filteredFileCount = read.u32(hp, GR_FILTERED);
+  const nextFileOffset = read.u32(hp, GR_NEXT_OFFSET);
+  const regexErrPtr = read.ptr(hp, GR_REGEX_ERR);
+  const regexFallbackError = readCString(regexErrPtr) ?? undefined;
+  const itemsBase = read.ptr(hp, GR_ITEMS);
+
+  const items: GrepMatch[] = [];
+  for (let i = 0; i < count; i++) {
+    items.push(readGrepMatchStruct(itemsBase + i * GM_SIZE_OF));
+  }
+
+  loadLibrary().symbols.fff_free_grep_result(hp);
+
+  const grepResult: GrepResult = {
+    items,
+    totalMatched,
+    totalFilesSearched,
+    totalFiles,
+    filteredFileCount,
+    nextCursor: nextFileOffset > 0 ? createGrepCursor(nextFileOffset) : null,
+  };
+  if (regexFallbackError) {
+    grepResult.regexFallbackError = regexFallbackError;
+  }
+  return { ok: true, value: grepResult };
+}
+
 /**
  * Perform fuzzy search.
  */
@@ -530,7 +752,7 @@ export function ffiLiveGrep(
   beforeContext: number,
   afterContext: number,
   classifyDefinitions: boolean,
-): Result<unknown> {
+): Result<GrepResult> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_live_grep(
     handle,
@@ -546,7 +768,7 @@ export function ffiLiveGrep(
     afterContext,
     classifyDefinitions,
   );
-  return parseResult<unknown>(resultPtr);
+  return parseGrepResult(resultPtr);
 }
 
 /**
@@ -565,7 +787,7 @@ export function ffiMultiGrep(
   beforeContext: number,
   afterContext: number,
   classifyDefinitions: boolean,
-): Result<unknown> {
+): Result<GrepResult> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_multi_grep(
     handle,
@@ -581,7 +803,7 @@ export function ffiMultiGrep(
     afterContext,
     classifyDefinitions,
   );
-  return parseResult<unknown>(resultPtr);
+  return parseGrepResult(resultPtr);
 }
 
 /**
@@ -590,7 +812,7 @@ export function ffiMultiGrep(
 export function ffiScanFiles(handle: NativeHandle): Result<void> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_scan_files(handle);
-  return parseResult<void>(resultPtr);
+  return parseVoidResult(resultPtr);
 }
 
 /**
@@ -601,33 +823,54 @@ export function ffiIsScanning(handle: NativeHandle): boolean {
   return library.symbols.fff_is_scanning(handle) as boolean;
 }
 
+// FffScanProgress { scanned_files_count: u64(8), is_scanning: bool(1+7pad) }
+const SP_COUNT    = 0;  // u64 (8)
+const SP_SCANNING = 8;  // bool (1 + 7 pad)
+
 /**
  * Get scan progress.
  */
-export function ffiGetScanProgress(handle: NativeHandle): Result<unknown> {
+export function ffiGetScanProgress(handle: NativeHandle): Result<{ scannedFilesCount: number; isScanning: boolean }> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_get_scan_progress(handle);
-  return parseResult<unknown>(resultPtr);
+  const envelope = readResultEnvelope(resultPtr);
+  if (!("success" in envelope)) return envelope;
+
+  if (envelope.handlePtr === 0) {
+    return err("scan progress returned null");
+  }
+
+  const hp = asPtr(envelope.handlePtr);
+  const result = {
+    scannedFilesCount: Number(read.u64(hp, SP_COUNT)),
+    isScanning: read.u8(hp, SP_SCANNING) !== 0,
+  };
+  library.symbols.fff_free_scan_progress(hp);
+  return { ok: true, value: result };
 }
 
 /**
  * Wait for scan to complete.
  */
-export function ffiWaitForScan(handle: NativeHandle, timeoutMs: number): Result<boolean> {
+export function ffiWaitForScan(
+  handle: NativeHandle,
+  timeoutMs: number,
+): Result<boolean> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_wait_for_scan(handle, BigInt(timeoutMs));
-  const result = parseResult<boolean | string>(resultPtr);
-  if (!result.ok) return result;
-  return { ok: true, value: result.value === true || result.value === "true" };
+  return parseBoolResult(resultPtr);
 }
 
 /**
  * Restart index in new path.
  */
-export function ffiRestartIndex(handle: NativeHandle, newPath: string): Result<void> {
+export function ffiRestartIndex(
+  handle: NativeHandle,
+  newPath: string,
+): Result<void> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_restart_index(handle, ptr(encodeString(newPath)));
-  return parseResult<void>(resultPtr);
+  return parseVoidResult(resultPtr);
 }
 
 /**
@@ -636,12 +879,7 @@ export function ffiRestartIndex(handle: NativeHandle, newPath: string): Result<v
 export function ffiRefreshGitStatus(handle: NativeHandle): Result<number> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_refresh_git_status(handle);
-  const result = parseResult<number | string>(resultPtr);
-  if (!result.ok) return result;
-  return {
-    ok: true,
-    value: typeof result.value === "number" ? result.value : parseInt(result.value, 10),
-  };
+  return parseIntResult(resultPtr);
 }
 
 /**
@@ -658,9 +896,7 @@ export function ffiTrackQuery(
     ptr(encodeString(query)),
     ptr(encodeString(filePath)),
   );
-  const result = parseResult<boolean | string>(resultPtr);
-  if (!result.ok) return result;
-  return { ok: true, value: result.value === true || result.value === "true" };
+  return parseBoolResult(resultPtr);
 }
 
 /**
@@ -672,10 +908,7 @@ export function ffiGetHistoricalQuery(
 ): Result<string | null> {
   const library = loadLibrary();
   const resultPtr = library.symbols.fff_get_historical_query(handle, BigInt(offset));
-  const result = parseResult<string | null>(resultPtr);
-  if (!result.ok) return result;
-  if (result.value === null || result.value === "null") return { ok: true, value: null };
-  return result as Result<string>;
+  return parseStringResult(resultPtr);
 }
 
 /**
@@ -692,7 +925,7 @@ export function ffiHealthCheck(
     handle ?? (0 as unknown as Pointer),
     ptr(encodeString(testPath)),
   );
-  return parseResult<unknown>(resultPtr);
+  return parseJsonResult<unknown>(resultPtr);
 }
 
 /**

package/src/finder.ts

@@ -40,7 +40,7 @@ import type {
   SearchResult,
 } from "./types";
 
-import { createGrepCursor, err } from "./types";
+import { err } from "./types";
 
 /**
  * FileFinder - Fast file finder with fuzzy search
@@ -228,7 +228,7 @@ export class FileFinder {
     const guard = this.ensureAlive();
     if (!guard.ok) return guard;
 
-    const result = ffiLiveGrep(
+    return ffiLiveGrep(
       guard.value,
       query,
       options?.mode ?? "plain",
@@ -242,8 +242,6 @@ export class FileFinder {
       options?.afterContext ?? 0,
       false,
     );
-
-    return transformGrepResult(result);
   }
 
   /**
@@ -279,7 +277,7 @@ export class FileFinder {
       return err("patterns array must have at least 1 element");
     }
 
-    const result = ffiMultiGrep(
+    return ffiMultiGrep(
       guard.value,
       options.patterns.join("\n"),
       options.constraints ?? "",
@@ -293,8 +291,6 @@ export class FileFinder {
       options.afterContext ?? 0,
       false,
     );
-
-    return transformGrepResult(result);
   }
 
   /**
@@ -435,20 +431,3 @@ export class FileFinder {
   }
 }
 
-function transformGrepResult(result: Result<unknown>): Result<GrepResult> {
-  if (!result.ok) {
-    return result;
-  }
-  const raw = result.value as Record<string, unknown>;
-  const nextFileOffset = raw.nextFileOffset as number;
-  const grepResult: GrepResult = {
-    items: raw.items as GrepResult["items"],
-    totalMatched: raw.totalMatched as number,
-    totalFilesSearched: raw.totalFilesSearched as number,
-    totalFiles: raw.totalFiles as number,
-    filteredFileCount: raw.filteredFileCount as number,
-    nextCursor: nextFileOffset > 0 ? createGrepCursor(nextFileOffset) : null,
-    regexFallbackError: raw.regexFallbackError as string | undefined,
-  };
-  return { ok: true, value: grepResult };
-}