@legendapp/spark 0.0.1-next.2 → 0.0.1-next.4

package/vendor/node_modules/@legendapp/spark-file-system/macos/file-scanner/RNFileScannerCore.mm

@@ -0,0 +1,306 @@
+#import "RNFileScannerCore.h"
+
+@implementation RNFileScannerOptions
+
+- (instancetype)init
+{
+  if (self = [super init]) {
+    _allowedExtensions = [NSSet set];
+    _batchSize = 64;
+    _includeHidden = NO;
+    _includeStats = NO;
+    _skipLookup = @{};
+  }
+  return self;
+}
+
+@end
+
+NSString *RNFileScannerNormalizePath(NSString *path)
+{
+  if (![path isKindOfClass:NSString.class] || path.length == 0) {
+    return @"";
+  }
+
+  NSString *normalized = path;
+  if ([normalized hasPrefix:@"file://"]) {
+    NSURL *url = [NSURL URLWithString:normalized];
+    if (url.path.length > 0) {
+      normalized = url.path;
+    }
+  }
+
+  normalized = [normalized stringByExpandingTildeInPath].stringByStandardizingPath;
+  while ([normalized hasSuffix:@"/"] && normalized.length > 1) {
+    normalized = [normalized substringToIndex:normalized.length - 1];
+  }
+  return normalized;
+}
+
+NSString *RNFileScannerRelativePath(NSString *fullPath, NSString *rootPath)
+{
+  NSString *normalizedFullPath = RNFileScannerNormalizePath(fullPath);
+  NSString *normalizedRoot = RNFileScannerNormalizePath(rootPath);
+  if (normalizedFullPath.length == 0 || normalizedRoot.length == 0) {
+    return normalizedFullPath;
+  }
+
+  if ([normalizedFullPath isEqualToString:normalizedRoot]) {
+    return normalizedFullPath.lastPathComponent ?: normalizedFullPath;
+  }
+
+  NSString *rootPrefix = [normalizedRoot stringByAppendingString:@"/"];
+  if ([normalizedFullPath hasPrefix:rootPrefix]) {
+    NSString *relativePath = [normalizedFullPath substringFromIndex:rootPrefix.length];
+    return relativePath.length > 0 ? relativePath : (normalizedFullPath.lastPathComponent ?: normalizedFullPath);
+  }
+
+  return normalizedFullPath;
+}
+
+NSArray<NSString *> *RNFileScannerNormalizeRoots(NSArray<NSString *> *paths)
+{
+  NSMutableArray<NSString *> *roots = [NSMutableArray array];
+  for (id rawPath in paths) {
+    NSString *normalized = RNFileScannerNormalizePath([rawPath isKindOfClass:NSString.class] ? rawPath : @"");
+    if (normalized.length > 0) {
+      [roots addObject:normalized];
+    }
+  }
+  return roots;
+}
+
+NSSet<NSString *> *RNFileScannerExtensionsFromArray(NSArray<NSString *> *extensions, NSArray<NSString *> *defaultExtensions)
+{
+  NSArray<NSString *> *source = extensions.count > 0 ? extensions : defaultExtensions;
+  NSMutableSet<NSString *> *normalized = [NSMutableSet set];
+  for (id value in source) {
+    if (![value isKindOfClass:NSString.class]) {
+      continue;
+    }
+    NSString *extension = [[(NSString *)value lowercaseString] stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet];
+    if ([extension hasPrefix:@"."]) {
+      extension = [extension substringFromIndex:1];
+    }
+    if (extension.length > 0) {
+      [normalized addObject:extension];
+    }
+  }
+  return normalized;
+}
+
+NSDictionary<NSNumber *, NSSet<NSString *> *> *RNFileScannerSkipLookupFromArray(NSArray *skipEntries)
+{
+  if (![skipEntries isKindOfClass:NSArray.class]) {
+    return @{};
+  }
+
+  NSMutableDictionary<NSNumber *, NSMutableSet<NSString *> *> *lookup = [NSMutableDictionary dictionary];
+  for (id rawEntry in skipEntries) {
+    if (![rawEntry isKindOfClass:NSDictionary.class]) {
+      continue;
+    }
+    NSDictionary *entry = (NSDictionary *)rawEntry;
+    NSNumber *rootIndex = [entry[@"rootIndex"] isKindOfClass:NSNumber.class] ? entry[@"rootIndex"] : nil;
+    NSString *relativePath = [entry[@"relativePath"] isKindOfClass:NSString.class] ? entry[@"relativePath"] : nil;
+    if (!rootIndex || relativePath.length == 0) {
+      continue;
+    }
+    NSNumber *rootKey = @([rootIndex unsignedIntegerValue]);
+    NSMutableSet<NSString *> *rootSet = lookup[rootKey];
+    if (!rootSet) {
+      rootSet = [NSMutableSet set];
+      lookup[rootKey] = rootSet;
+    }
+    [rootSet addObject:relativePath];
+  }
+
+  NSMutableDictionary<NSNumber *, NSSet<NSString *> *> *immutable = [NSMutableDictionary dictionaryWithCapacity:lookup.count];
+  [lookup enumerateKeysAndObjectsUsingBlock:^(NSNumber *key, NSMutableSet<NSString *> *value, BOOL *stop) {
+    immutable[key] = [value copy];
+  }];
+  return immutable;
+}
+
+NSDictionary *RNFileScannerDefaultFileItem(NSURL *fileURL,
+                                           NSString *rootPath,
+                                           NSUInteger rootIndex,
+                                           NSString *relativePath,
+                                           BOOL skipped,
+                                           BOOL includeStats)
+{
+  NSMutableDictionary *item = [@{
+    @"rootIndex": @(rootIndex),
+    @"relativePath": relativePath ?: fileURL.path ?: @"",
+    @"fileName": fileURL.lastPathComponent ?: relativePath ?: fileURL.path ?: @"",
+    @"absolutePath": fileURL.path ?: @"",
+    @"extension": fileURL.pathExtension.lowercaseString ?: @"",
+  } mutableCopy];
+
+  if (skipped) {
+    item[@"skipped"] = @YES;
+  }
+
+  if (includeStats) {
+    NSDictionary<NSFileAttributeKey, id> *attributes = [[NSFileManager defaultManager] attributesOfItemAtPath:fileURL.path error:nil];
+    NSNumber *fileSize = attributes[NSFileSize];
+    NSDate *modifiedDate = attributes[NSFileModificationDate];
+    if ([fileSize isKindOfClass:NSNumber.class]) {
+      item[@"size"] = fileSize;
+    }
+    if ([modifiedDate isKindOfClass:NSDate.class]) {
+      item[@"modifiedTime"] = @([modifiedDate timeIntervalSince1970] * 1000.0);
+    }
+  }
+
+  return item;
+}
+
+NSDictionary *RNFileScannerRun(NSArray<NSString *> *paths,
+                               RNFileScannerOptions *options,
+                               RNFileScannerMapFileBlock mapFile,
+                               RNFileScannerEmitBatchBlock emitBatch,
+                               RNFileScannerProgressBlock emitProgress,
+                               BOOL (^isCancelled)(void))
+{
+  NSArray<NSString *> *roots = RNFileScannerNormalizeRoots(paths);
+  NSUInteger totalRoots = roots.count;
+  if (totalRoots == 0) {
+    return @{@"totalFiles": @0, @"totalRoots": @0, @"errors": @[]};
+  }
+
+  RNFileScannerOptions *scanOptions = options ?: [RNFileScannerOptions new];
+  NSUInteger batchSize = scanOptions.batchSize > 0 ? scanOptions.batchSize : 64;
+  NSSet<NSString *> *allowedExtensions = scanOptions.allowedExtensions ?: [NSSet set];
+  NSMutableArray<NSString *> *errors = [NSMutableArray array];
+  NSUInteger totalFiles = 0;
+  NSUInteger completedRoots = 0;
+  NSFileManager *fileManager = [NSFileManager defaultManager];
+
+  for (NSUInteger rootIndex = 0; rootIndex < roots.count; rootIndex++) {
+    if (isCancelled && isCancelled()) break;
+    @autoreleasepool {
+      NSString *rootPath = roots[rootIndex];
+      BOOL isDirectory = NO;
+      BOOL exists = [fileManager fileExistsAtPath:rootPath isDirectory:&isDirectory];
+      if (!exists) {
+        [errors addObject:[NSString stringWithFormat:@"Root not found: %@", rootPath]];
+        completedRoots += 1;
+        if (emitProgress) {
+          emitProgress(rootIndex, completedRoots, totalRoots);
+        }
+        continue;
+      }
+
+      if (!isDirectory) {
+        NSURL *fileURL = [NSURL fileURLWithPath:rootPath isDirectory:NO];
+        NSString *extension = fileURL.pathExtension.lowercaseString ?: @"";
+        if (allowedExtensions.count == 0 || [allowedExtensions containsObject:extension]) {
+          NSString *relativePath = fileURL.lastPathComponent ?: rootPath;
+          BOOL skipped = [scanOptions.skipLookup[@(rootIndex)] containsObject:relativePath];
+          NSDictionary *item = mapFile
+            ? mapFile(fileURL, rootPath.stringByDeletingLastPathComponent ?: rootPath, rootIndex, relativePath, skipped)
+            : RNFileScannerDefaultFileItem(fileURL, rootPath.stringByDeletingLastPathComponent ?: rootPath, rootIndex, relativePath, skipped, scanOptions.includeStats);
+          if (item) {
+            totalFiles += 1;
+            if (emitBatch) {
+              emitBatch(@[item], rootIndex, completedRoots, totalRoots);
+            }
+          }
+        }
+        completedRoots += 1;
+        if (emitProgress) {
+          emitProgress(rootIndex, completedRoots, totalRoots);
+        }
+        continue;
+      }
+
+      NSDirectoryEnumerationOptions enumerationOptions = NSDirectoryEnumerationSkipsPackageDescendants;
+      if (!scanOptions.includeHidden) {
+        enumerationOptions |= NSDirectoryEnumerationSkipsHiddenFiles;
+      }
+
+      NSURL *rootURL = [NSURL fileURLWithPath:rootPath isDirectory:YES];
+      NSDirectoryEnumerator<NSURL *> *enumerator =
+        [fileManager enumeratorAtURL:rootURL
+          includingPropertiesForKeys:@[NSURLIsDirectoryKey]
+                             options:enumerationOptions
+                        errorHandler:^BOOL(NSURL *url, NSError *error) {
+                          @synchronized(errors) {
+                            [errors addObject:error.localizedDescription ?: @"Unknown scan error"];
+                          }
+                          return YES;
+                        }];
+
+      if (!enumerator) {
+        [errors addObject:[NSString stringWithFormat:@"Failed to enumerate: %@", rootPath]];
+        completedRoots += 1;
+        if (emitProgress) {
+          emitProgress(rootIndex, completedRoots, totalRoots);
+        }
+        continue;
+      }
+
+      NSMutableArray<NSDictionary *> *batch = [NSMutableArray arrayWithCapacity:batchSize];
+      for (NSURL *fileURL in enumerator) {
+        if (isCancelled && isCancelled()) break;
+        NSNumber *isDirectoryValue = nil;
+        [fileURL getResourceValue:&isDirectoryValue forKey:NSURLIsDirectoryKey error:nil];
+        if (isDirectoryValue.boolValue) {
+          continue;
+        }
+
+        NSString *extension = fileURL.pathExtension.lowercaseString ?: @"";
+        if (allowedExtensions.count > 0 && ![allowedExtensions containsObject:extension]) {
+          continue;
+        }
+
+        NSString *relativePath = RNFileScannerRelativePath(fileURL.path, rootPath);
+        BOOL skipped = [scanOptions.skipLookup[@(rootIndex)] containsObject:relativePath];
+        NSDictionary *item = mapFile
+          ? mapFile(fileURL, rootPath, rootIndex, relativePath, skipped)
+          : RNFileScannerDefaultFileItem(fileURL, rootPath, rootIndex, relativePath, skipped, scanOptions.includeStats);
+        if (!item) {
+          continue;
+        }
+
+        [batch addObject:item];
+        totalFiles += 1;
+        if (batch.count >= batchSize) {
+          if (emitBatch) {
+            emitBatch([batch copy], rootIndex, completedRoots, totalRoots);
+          }
+          [batch removeAllObjects];
+        }
+      }
+
+      if ((!isCancelled || !isCancelled()) && batch.count > 0 && emitBatch) {
+        emitBatch([batch copy], rootIndex, completedRoots, totalRoots);
+      }
+
+      if (isCancelled && isCancelled()) break;
+      completedRoots += 1;
+      if (emitProgress) {
+        emitProgress(rootIndex, completedRoots, totalRoots);
+      }
+    }
+  }
+
+  return @{@"totalFiles": @(totalFiles), @"totalRoots": @(totalRoots), @"errors": errors};
+}
+
+NSString *RNFileScannerJSONString(id object)
+{
+  id value = object ?: [NSNull null];
+  NSData *data = [NSJSONSerialization dataWithJSONObject:value options:0 error:nil];
+  return data ? [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] : @"null";
+}
+
+id RNFileScannerJSONObjectFromString(NSString *json)
+{
+  if (![json isKindOfClass:NSString.class] || json.length == 0) {
+    return nil;
+  }
+  NSData *data = [json dataUsingEncoding:NSUTF8StringEncoding];
+  return data ? [NSJSONSerialization JSONObjectWithData:data options:0 error:nil] : nil;
+}

package/vendor/node_modules/@legendapp/spark-file-system/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/spark-file-system",
-  "version": "0.0.1-next.2",
+  "version": "0.0.1-next.4",
   "license": "MIT",
   "main": "src/index.ts",
   "react-native": "src/index.ts",
@@ -21,14 +21,17 @@
     "jsSrcsDir": "src",
     "ios": {
       "modulesProvider": {
-        "NativeDesktopFileSystem": "RNDesktopFileSystem"
-      }
+        "NativeDesktopFileSystem": "RNDesktopFileSystem",
+        "NativeFileScanner": "RNFileScanner"
+      },
+      "componentProvider": {}
     }
   },
   "spark": {
     "sdk": true,
     "nativeModules": [
-      "NativeDesktopFileSystem"
+      "NativeDesktopFileSystem",
+      "NativeFileScanner"
     ],
     "pod": "RNDesktopFileSystem",
     "platforms": [
@@ -40,8 +43,7 @@
     ]
   },
   "dependencies": {
-    "@legendapp/spark-desktop-app": "0.0.1-next.2",
-    "base64-js": "1.5.1"
+    "@legendapp/spark-desktop-app": "0.0.1-next.4"
   },
   "private": true
 }

package/vendor/node_modules/@legendapp/spark-file-system/src/NativeDesktopFileSystem.ts

@@ -5,4 +5,4 @@ export interface Spec extends TurboModule {
   addListener(eventName: string): void;
   removeListeners(count: number): void;
 }
-export default TurboModuleRegistry.getEnforcing<Spec>("NativeDesktopFileSystem");
+export default TurboModuleRegistry.get<Spec>("NativeDesktopFileSystem");

package/vendor/node_modules/@legendapp/spark-file-system/src/file-scanner/NativeFileScanner.ts

@@ -0,0 +1,11 @@
+import type { TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+  scanFiles(id: string, pathsJson: string, optionsJson: string): Promise<string>;
+  cancelScan(id: string): Promise<void>;
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.get<Spec>("NativeFileScanner");

package/vendor/node_modules/@legendapp/spark-file-system/src/file-scanner/index.ts

@@ -0,0 +1,93 @@
+import { NativeEventEmitter, Platform } from "react-native";
+import { SparkError, invokeNative, parseNativeResult, type Availability, type Subscription } from "@legendapp/spark-desktop-app/src/contracts";
+import { nativePath } from "@legendapp/spark-desktop-app/src/contracts/path";
+import Native from "./NativeFileScanner";
+export interface FileScanSkipEntry { relativePath: string; rootIndex: number }
+export interface ScannedFile {
+  path: string;
+  name: string;
+  extension: string;
+  relativePath: string;
+  rootIndex: number;
+  modifiedAt?: number;
+  size?: number;
+  skipped: boolean;
+}
+export interface FileScanProgress { completedRoots: number; rootIndex: number; totalRoots: number }
+export interface FileScanBatch extends FileScanProgress { files: ScannedFile[] }
+export interface FileScanResult { totalFiles: number; totalRoots: number; errors: string[] }
+export interface FileScanOptions {
+  extensions?: readonly string[];
+  batchSize?: number;
+  includeHidden?: boolean;
+  includeStats?: boolean;
+  /** Marks known entries as skipped in emitted batches; it does not exclude their names. */
+  skip?: readonly FileScanSkipEntry[];
+  onBatch?: (event: FileScanBatch) => void;
+  onProgress?: (event: FileScanProgress) => void;
+  /** Cancellation is cooperative between filesystem operations; the promise waits for native work to stop. */
+  signal?: AbortSignal;
+}
+export function getFileScanAvailability(): Availability {
+  if (Platform.OS !== "macos") return { available: false, reason: "unsupported-platform" };
+  return Native ? { available: true } : { available: false, reason: "missing-module" };
+}
+const count = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object";
+function progress(value: unknown, roots: number): FileScanProgress {
+  if (!record(value) || !count(value.rootIndex) || value.rootIndex >= roots || !count(value.completedRoots) || value.completedRoots > roots || value.totalRoots !== roots) throw new SparkError("E_INVALID_DATA", "Invalid scan progress");
+  return { rootIndex: value.rootIndex, completedRoots: value.completedRoots, totalRoots: value.totalRoots };
+}
+function scannedFile(value: unknown, roots: number): ScannedFile {
+  if (!record(value) || !count(value.rootIndex) || value.rootIndex >= roots || typeof value.absolutePath !== "string" || !value.absolutePath.startsWith("/") || typeof value.fileName !== "string" || typeof value.relativePath !== "string" || typeof value.extension !== "string" || (value.size !== undefined && !count(value.size)) || (value.modifiedTime !== undefined && (typeof value.modifiedTime !== "number" || !Number.isFinite(value.modifiedTime))) || (value.skipped !== undefined && typeof value.skipped !== "boolean")) throw new SparkError("E_INVALID_DATA", "Invalid scanned file");
+  return { path: value.absolutePath, name: value.fileName, extension: value.extension, relativePath: value.relativePath, rootIndex: value.rootIndex, size: value.size, modifiedAt: value.modifiedTime, skipped: value.skipped ?? false };
+}
+let nextScan = 0;
+export async function scanFiles(paths: readonly string[], options: FileScanOptions = {}): Promise<FileScanResult> {
+  if (!Array.isArray(paths)) throw new SparkError("E_INVALID_ARGUMENT", "Expected scan paths");
+  const roots = Array.from(paths, path => nativePath(path, Platform.OS));
+  if (!options || typeof options !== "object") throw new SparkError("E_INVALID_ARGUMENT", "Expected scan options");
+  for (const key of Object.keys(options)) if (!["extensions", "batchSize", "includeHidden", "includeStats", "skip", "onBatch", "onProgress", "signal"].includes(key)) throw new SparkError("E_UNSUPPORTED_OPTION", `Unsupported scan option: ${key}`);
+  if (options.batchSize !== undefined && (!count(options.batchSize) || options.batchSize < 1 || options.batchSize > 10000)) throw new SparkError("E_INVALID_ARGUMENT", "batchSize must be between 1 and 10000");
+  for (const value of [options.includeHidden, options.includeStats]) if (value !== undefined && typeof value !== "boolean") throw new SparkError("E_INVALID_ARGUMENT", "Scan flags must be boolean");
+  for (const value of [options.onBatch, options.onProgress]) if (value !== undefined && typeof value !== "function") throw new SparkError("E_INVALID_ARGUMENT", "Scan callbacks must be functions");
+  if (options.extensions !== undefined && (!Array.isArray(options.extensions) || options.extensions.some(value => typeof value !== "string" || !/^[a-z0-9][a-z0-9_-]*$/i.test(value)))) throw new SparkError("E_INVALID_ARGUMENT", "Expected file extensions without dots or wildcards");
+  if (options.skip !== undefined && (!Array.isArray(options.skip) || options.skip.some(value => !value || !count(value.rootIndex) || value.rootIndex >= roots.length || typeof value.relativePath !== "string" || !value.relativePath || value.relativePath.startsWith("/") || value.relativePath.split("/").includes("..")))) throw new SparkError("E_INVALID_ARGUMENT", "Invalid skipped file entry");
+  const availability = getFileScanAvailability();
+  if (!availability.available) throw new SparkError(availability.reason === "unsupported-platform" ? "E_UNSUPPORTED_PLATFORM" : "E_MODULE_UNAVAILABLE", "File scanning requires a macOS host with NativeFileScanner installed");
+  const { signal, onBatch, onProgress, extensions, ...nativeOptions } = options;
+  if (signal !== undefined && (!signal || typeof signal.aborted !== "boolean" || typeof signal.addEventListener !== "function" || typeof signal.removeEventListener !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Expected an AbortSignal");
+  const aborted = () => new SparkError("E_ABORTED", "File scan aborted", { cause: signal?.reason });
+  if (signal?.aborted) throw aborted();
+  const id = `scan-${Date.now()}-${++nextScan}`;
+  const subscriptions: Subscription[] = [];
+  let callbackError: unknown;
+  let callbackFailed = false;
+  let cancellation: Promise<void> | undefined;
+  const cancel = () => { cancellation ??= invokeNative(() => Native!.cancelScan(id)); void cancellation.catch(() => undefined); };
+  const deliver = (value: unknown, callback: (value: Record<string, unknown>) => void) => {
+    if (!record(value) || value.id !== id || signal?.aborted || callbackFailed) return;
+    try { callback(value); } catch (error) { callbackFailed = true; callbackError = error; cancel(); }
+  };
+  try {
+    const emitter = new NativeEventEmitter(Native!);
+    if (onProgress) subscriptions.push(emitter.addListener("onFileScanProgress", value => deliver(value, event => onProgress?.(progress(event, roots.length)))));
+    if (onBatch) subscriptions.push(emitter.addListener("onFileScanBatch", value => deliver(value, event => {
+      const snapshot = progress(event, roots.length);
+      if (!Array.isArray(event.files)) throw new SparkError("E_INVALID_DATA", "Invalid scan batch");
+      const files = event.files.map((file: unknown) => scannedFile(file, roots.length));
+      onBatch?.({ ...snapshot, files });
+    })));
+    signal?.addEventListener("abort", cancel, { once: true });
+    let json: string;
+    try { json = await invokeNative(() => Native!.scanFiles(id, JSON.stringify(roots), JSON.stringify({ ...nativeOptions, allowedExtensions: extensions }))); }
+    catch (error) { if (callbackFailed) throw callbackError; if (signal?.aborted) throw aborted(); throw error; }
+    if (callbackFailed) throw callbackError;
+    if (signal?.aborted) throw aborted();
+    return parseNativeResult(json, (value): value is FileScanResult => !!value && typeof value === "object" && "totalFiles" in value && count(value.totalFiles) && "totalRoots" in value && value.totalRoots === roots.length && "errors" in value && Array.isArray(value.errors) && value.errors.every(error => typeof error === "string"));
+  } finally {
+    signal?.removeEventListener("abort", cancel);
+    subscriptions.forEach(subscription => subscription.remove());
+    if (cancellation) await cancellation;
+  }
+}

package/vendor/node_modules/@legendapp/spark-file-system/src/handles.ts

@@ -1,4 +1,5 @@
-import { fromByteArray, toByteArray } from "base64-js";
+import { SparkError, asyncRegistration } from "@legendapp/spark-desktop-app/src/contracts";
+import { nativeBytes } from "@legendapp/spark-desktop-app/src/contracts/native-buffer";
 export const MAX_CHUNK_SIZE = 1024 * 1024;
 export type FileMode = "read" | "readWrite" | "write" | "createNew";
 export type FileHandle = {
@@ -7,39 +8,72 @@ export type FileHandle = {
   flush(): Promise<void>;
   close(): Promise<void>;
 };
+export class FileCleanupError extends SparkError {
+  readonly operationFailed: boolean;
+  readonly operationError: unknown;
+  readonly cleanupError: unknown;
+  readonly retryCleanup: () => Promise<void>;
+
+  constructor(operationFailed: boolean, operationError: unknown, cleanupError: unknown, retryCleanup: () => Promise<void>) {
+    const cause = operationFailed
+      ? new AggregateError([operationError, cleanupError], "File operation and handle cleanup both failed")
+      : cleanupError;
+    super("E_NATIVE", operationFailed ? "File operation and handle cleanup both failed" : "File handle cleanup failed", { cause });
+    this.name = "FileCleanupError";
+    this.operationFailed = operationFailed;
+    this.operationError = operationError;
+    this.cleanupError = cleanupError;
+    this.retryCleanup = retryCleanup;
+  }
+}
 export type FileCall = <T>(method: string, args: object) => Promise<T>;
-function offset(value: number) { if (!Number.isSafeInteger(value) || value < 0) throw new RangeError("Offset must be a nonnegative safe integer"); }
-function length(value: number) { if (!Number.isInteger(value) || value < 1 || value > MAX_CHUNK_SIZE) throw new RangeError("Chunk size must be between 1 byte and 1 MiB"); }
-function aborted(signal?: AbortSignal) { if (signal?.aborted) throw signal.reason ?? new Error("File operation aborted"); }
+function offset(value: number) { if (!Number.isSafeInteger(value) || value < 0) throw new SparkError("E_INVALID_ARGUMENT", "Offset must be a nonnegative safe integer"); }
+function length(value: number) { if (!Number.isInteger(value) || value < 1 || value > MAX_CHUNK_SIZE) throw new SparkError("E_INVALID_ARGUMENT", "Chunk size must be between 1 byte and 1 MiB"); }
+function aborted(signal?: AbortSignal) { if (signal?.aborted) throw new SparkError("E_ABORTED", signal.reason instanceof Error ? signal.reason.message : "File operation aborted", { cause: signal.reason }); }
 /** Positional I/O: handles have no shared cursor. Calls are serialized natively. */
 export async function createFileHandle(call: FileCall, path: string, mode: FileMode = "read"): Promise<FileHandle> {
-  if (!["read", "readWrite", "write", "createNew"].includes(mode)) throw new TypeError("Invalid file mode");
+  if (!["read", "readWrite", "write", "createNew"].includes(mode)) throw new SparkError("E_INVALID_ARGUMENT", "Invalid file mode");
   const id = await call<string>("openFile", { path, mode });
-  let closing: Promise<void> | undefined;
-  const active = () => { if (closing) throw new Error("File handle is closed"); };
+  if (typeof id !== "string" || !id) throw new SparkError("E_INVALID_DATA", "Invalid file handle ID");
+  let closed = false;
+  const cleanup = asyncRegistration(() => { closed = true; }, () => call<void>("closeFile", { id }));
+  const active = () => { if (closed) throw new SparkError("E_CLOSED", "File handle is closed"); };
   return {
-    async read(size, position) { active(); length(size); offset(position); if (!Number.isSafeInteger(position + size)) throw new RangeError("Read range exceeds safe integer bounds"); return toByteArray(await call<string>("readChunk", { id, length: size, offset: position })); },
-    async write(bytes, position) { active(); if (!(bytes instanceof Uint8Array)) throw new TypeError("Expected Uint8Array"); offset(position); if (!Number.isSafeInteger(position + bytes.byteLength)) throw new RangeError("Write range exceeds safe integer bounds"); if (!bytes.length) return 0; length(bytes.length); return call<number>("writeChunk", { id, base64: fromByteArray(bytes), offset: position }); },
+    async read(size, position) { active(); length(size); offset(position); if (!Number.isSafeInteger(position + size)) throw new SparkError("E_INVALID_ARGUMENT", "Read range exceeds safe integer bounds"); const bytes = nativeBytes(await call<ArrayBuffer>("readChunk", { id, length: size, offset: position })); if (bytes.length > size) throw new SparkError("E_INVALID_DATA", "Read exceeded requested length"); return bytes; },
+    async write(bytes, position) { active(); if (!(bytes instanceof Uint8Array)) throw new SparkError("E_INVALID_ARGUMENT", "Expected Uint8Array"); offset(position); if (!Number.isSafeInteger(position + bytes.byteLength)) throw new SparkError("E_INVALID_ARGUMENT", "Write range exceeds safe integer bounds"); if (!bytes.length) return 0; length(bytes.length); const written = await call<number>("writeChunk", { id, bytes, offset: position }); if (written !== bytes.length) throw new SparkError("E_NATIVE", "Native write did not write the complete chunk"); return written; },
     async flush() { active(); await call("flushFile", { id }); },
-    close() { return closing ??= call<void>("closeFile", { id }); },
+    close() { return cleanup.remove(); },
   };
 }
 export type ReadChunksOptions = { offset?: number; chunkSize?: number; signal?: AbortSignal };
 export async function* iterateFile(open: () => Promise<FileHandle>, options: ReadChunksOptions = {}) {
   let position = options.offset ?? 0; offset(position); const size = options.chunkSize ?? 64 * 1024; length(size); aborted(options.signal);
   const file = await open();
+  let operationFailed = false, operationError: unknown;
   try {
     for (;;) { aborted(options.signal); const bytes = await file.read(size, position); aborted(options.signal); if (!bytes.length) break; position += bytes.length; yield bytes; }
-  } finally { await file.close(); }
+  } catch (error) { operationFailed = true; operationError = error; }
+  finally {
+    try { await file.close(); }
+    catch (cleanupError) { throw new FileCleanupError(operationFailed, operationError, cleanupError, () => file.close()); }
+  }
+  if (operationFailed) throw operationError;
 }
 export async function writeFileChunks(open: () => Promise<FileHandle>, chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, signal?: AbortSignal) {
   aborted(signal); const file = await open(); let position = 0;
+  let operationFailed = false, operationError: unknown;
   try {
     for await (const bytes of chunks) {
       aborted(signal);
-      if (!(bytes instanceof Uint8Array)) throw new TypeError("Expected Uint8Array chunks");
+      if (!(bytes instanceof Uint8Array)) throw new SparkError("E_INVALID_ARGUMENT", "Expected Uint8Array chunks");
       for (let start = 0; start < bytes.length; start += MAX_CHUNK_SIZE) { aborted(signal); const part = bytes.subarray(start, start + MAX_CHUNK_SIZE); position += await file.write(part, position); }
     }
-    aborted(signal); await file.flush(); return position;
-  } finally { await file.close(); }
+    aborted(signal); await file.flush();
+  } catch (error) { operationFailed = true; operationError = error; }
+  finally {
+    try { await file.close(); }
+    catch (cleanupError) { throw new FileCleanupError(operationFailed, operationError, cleanupError, () => file.close()); }
+  }
+  if (operationFailed) throw operationError;
+  return position;
 }