@fgv/ts-web-extras 5.0.2 → 5.1.0-0

package/src/packlets/file-tree/localStorageTreeAccessors.ts

@@ -0,0 +1,377 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { DetailedResult, fail, Result, succeed, succeedWithDetail } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
+import { isJsonObject, type JsonObject } from '@fgv/ts-json-base';
+
+/**
+ * Configuration for LocalStorageTreeAccessors.
+ * @public
+ */
+export interface ILocalStorageTreeParams<TCT extends string = string>
+  extends FileTree.IFileTreeInitParams<TCT> {
+  /**
+   * Map of directory path prefixes to localStorage keys.
+   * Files under each prefix are stored in the corresponding localStorage key.
+   * Example: \{ '/data/ingredients': 'myapp:ingredients:v1' \}
+   */
+  pathToKeyMap: Record<string, string>;
+
+  /**
+   * Storage instance to use. Defaults to window.localStorage.
+   * Can be overridden for testing with mock storage.
+   */
+  storage?: Storage;
+
+  /**
+   * If true, automatically sync changes to localStorage on every modification.
+   * If false (default), changes are only synced when syncToDisk() is called.
+   */
+  autoSync?: boolean;
+}
+
+/**
+ * Browser localStorage-backed file tree accessors with persistence support.
+ *
+ * Maps filesystem-like directory paths to localStorage keys, where each key stores
+ * multiple collections as a JSON object. This provides a general-purpose implementation
+ * for browser-based file tree persistence without requiring File System Access API.
+ *
+ * Storage format per key: `{ "collection-id": "<raw file content>" }`
+ * File paths map as: `/data/ingredients/collection-id.yaml` → stored in key for `/data/ingredients`
+ *
+ * Legacy format (v1): `{ "collection-id": { ...parsedJsonObject } }` is auto-migrated on load.
+ *
+ * @public
+ */
+export class LocalStorageTreeAccessors<TCT extends string = string>
+  extends FileTree.InMemoryTreeAccessors<TCT>
+  implements FileTree.IPersistentFileTreeAccessors<TCT>
+{
+  private readonly _storage: Storage;
+  private readonly _pathToKeyMap: Map<string, string>;
+  private readonly _keyToPathMap: Map<string, string>;
+  private readonly _dirtyFiles: Set<string>;
+  private readonly _autoSync: boolean;
+
+  /**
+   * Private constructor. Use fromStorage() factory method instead.
+   * @internal
+   */
+  private constructor(
+    files: FileTree.IInMemoryFile<TCT>[],
+    storage: Storage,
+    pathToKeyMap: Map<string, string>,
+    params?: ILocalStorageTreeParams<TCT>
+  ) {
+    super(files, params);
+    this._storage = storage;
+    this._pathToKeyMap = pathToKeyMap;
+    this._keyToPathMap = new Map(Array.from(pathToKeyMap.entries()).map(([k, v]) => [v, k]));
+    this._dirtyFiles = new Set();
+    this._autoSync = params?.autoSync ?? false;
+  }
+
+  /**
+   * Create LocalStorageTreeAccessors from browser localStorage.
+   * Loads all collections from the configured storage keys.
+   *
+   * @param params - Configuration including path-to-key mappings
+   * @returns Result containing the accessors or an error
+   * @public
+   */
+  public static fromStorage<TCT extends string = string>(
+    params: ILocalStorageTreeParams<TCT>
+  ): Result<LocalStorageTreeAccessors<TCT>> {
+    try {
+      const storage = params.storage ?? (typeof window !== 'undefined' ? window.localStorage : undefined);
+      if (!storage) {
+        return fail('localStorage is not available');
+      }
+
+      const pathToKeyMap = new Map(Object.entries(params.pathToKeyMap));
+      const files = this._loadFromStorage<TCT>(storage, pathToKeyMap, params);
+
+      return succeed(new LocalStorageTreeAccessors<TCT>(files, storage, pathToKeyMap, params));
+      /* c8 ignore next 4 - defensive: outer catch for unexpected errors */
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to create LocalStorageTreeAccessors: ${message}`);
+    }
+  }
+
+  /**
+   * Load all files from localStorage based on path-to-key mappings.
+   * @internal
+   */
+  private static _loadFromStorage<TCT extends string = string>(
+    storage: Storage,
+    pathToKeyMap: Map<string, string>,
+    params?: ILocalStorageTreeParams<TCT>
+  ): FileTree.IInMemoryFile<TCT>[] {
+    const files: FileTree.IInMemoryFile<TCT>[] = [];
+
+    for (const [dataPath, storageKey] of pathToKeyMap.entries()) {
+      const rawJson = storage.getItem(storageKey);
+      if (!rawJson) {
+        continue;
+      }
+
+      try {
+        const parsed: unknown = JSON.parse(rawJson);
+        if (!isJsonObject(parsed)) {
+          continue;
+        }
+
+        for (const [collectionId, contents] of Object.entries(parsed)) {
+          // Support both new format (string values) and legacy format (JsonObject values)
+          let rawContent: string;
+          let extension: string;
+          if (typeof contents === 'string') {
+            rawContent = contents;
+            // Infer extension: if content looks like JSON, use .json; otherwise .yaml
+            extension = this._looksLikeJson(contents) ? '.json' : '.yaml';
+          } else if (isJsonObject(contents)) {
+            // Legacy format: migrate by stringifying
+            rawContent = JSON.stringify(contents);
+            extension = '.json';
+          } else {
+            continue;
+          }
+
+          const filePath = this._joinPath(dataPath, `${collectionId}${extension}`);
+          const contentType = params?.inferContentType
+            ? params.inferContentType(filePath, undefined).orDefault()
+            : undefined;
+
+          files.push({
+            path: filePath,
+            contents: rawContent,
+            contentType
+          });
+        }
+      } catch {
+        // Skip corrupted data
+        continue;
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Heuristic check: does the content look like JSON?
+   * @internal
+   */
+  private static _looksLikeJson(content: string): boolean {
+    const trimmed = content.trimStart();
+    return trimmed.startsWith('{') || trimmed.startsWith('[');
+  }
+
+  /**
+   * Join path components, handling leading/trailing slashes.
+   * @internal
+   */
+  private static _joinPath(base: string, name: string): string {
+    const cleanBase = base.endsWith('/') ? base.slice(0, -1) : base;
+    const cleanName = name.startsWith('/') ? name.slice(1) : name;
+    return `${cleanBase}/${cleanName}`;
+  }
+
+  /**
+   * Get the storage key for a given file path.
+   * @internal
+   */
+  private _getStorageKeyForPath(path: string): string | undefined {
+    // Find the longest matching prefix
+    let bestMatch: { prefix: string; key: string } | undefined;
+    for (const [prefix, key] of this._pathToKeyMap.entries()) {
+      if (path.startsWith(prefix)) {
+        if (!bestMatch || prefix.length > bestMatch.prefix.length) {
+          bestMatch = { prefix, key };
+        }
+      }
+    }
+    return bestMatch?.key;
+  }
+
+  /**
+   * Get the data path prefix for a given file path.
+   * @internal
+   */
+  private _getDataPathForPath(path: string): string | undefined {
+    for (const prefix of this._pathToKeyMap.keys()) {
+      if (path.startsWith(prefix)) {
+        return prefix;
+      }
+    }
+    /* c8 ignore next 2 - coverage intermittently missed in full suite */
+    return undefined;
+  }
+
+  /**
+   * Extract collection ID from a file path.
+   * Example: '/data/ingredients/my-collection.yaml' → 'my-collection'
+   * @internal
+   */
+  private _getCollectionIdFromPath(path: string): string {
+    const dataPath = this._getDataPathForPath(path);
+    /* c8 ignore next 3 - coverage intermittently missed in full suite */
+    if (!dataPath) {
+      return path;
+    }
+
+    const relativePath = path.slice(dataPath.length);
+    const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
+
+    // Remove any file extension
+    const dotIndex = cleanPath.lastIndexOf('.');
+    return dotIndex > 0 ? cleanPath.slice(0, dotIndex) : cleanPath;
+  }
+
+  /**
+   * Sync a single dirty file to localStorage.
+   * @internal
+   */
+  private _syncFile(path: string): Result<void> {
+    const storageKey = this._getStorageKeyForPath(path);
+    if (!storageKey) {
+      return fail(`No storage key configured for path: ${path}`);
+    }
+
+    const collectionId = this._getCollectionIdFromPath(path);
+    const contentsResult = this.getFileContents(path);
+    if (contentsResult.isFailure()) {
+      return fail(`Failed to get file contents for ${path}: ${contentsResult.message}`);
+    }
+
+    try {
+      const contents = contentsResult.value;
+
+      // Load existing data from storage
+      const existingJson = this._storage.getItem(storageKey);
+      let existing: Record<string, unknown> = {};
+      if (existingJson) {
+        try {
+          const parsed = JSON.parse(existingJson);
+          if (isJsonObject(parsed)) {
+            existing = parsed as Record<string, unknown>;
+          }
+        } catch {
+          // Start fresh if corrupted
+        }
+      }
+
+      // Store raw content string (content-agnostic: JSON, YAML, etc.)
+      existing[collectionId] = contents;
+      this._storage.setItem(storageKey, JSON.stringify(existing));
+
+      return succeed(undefined);
+      /* c8 ignore next 4 - defensive: only triggers on storage quota or similar runtime errors */
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return fail(`Failed to sync file ${path}: ${message}`);
+    }
+  }
+
+  /**
+   * Sync all dirty files to localStorage.
+   * @returns Result indicating success or failure
+   * @public
+   */
+  public async syncToDisk(): Promise<Result<void>> {
+    if (this._dirtyFiles.size === 0) {
+      return succeed(undefined);
+    }
+
+    const errors: string[] = [];
+    for (const path of this._dirtyFiles) {
+      const result = this._syncFile(path);
+      if (result.isFailure()) {
+        errors.push(result.message);
+      }
+    }
+
+    if (errors.length > 0) {
+      return fail(`Failed to sync ${errors.length} file(s): ${errors.join('; ')}`);
+    }
+
+    this._dirtyFiles.clear();
+    return succeed(undefined);
+  }
+
+  /**
+   * Check if there are unsaved changes.
+   * @returns True if there are dirty files
+   * @public
+   */
+  public isDirty(): boolean {
+    return this._dirtyFiles.size > 0;
+  }
+
+  /**
+   * Get list of file paths with unsaved changes.
+   * @returns Array of dirty file paths
+   * @public
+   */
+  public getDirtyPaths(): string[] {
+    return Array.from(this._dirtyFiles);
+  }
+
+  /**
+   * Save file contents. Marks file as dirty and optionally auto-syncs.
+   * @param path - File path
+   * @param contents - New file contents
+   * @returns Result with the saved contents or error
+   * @public
+   */
+  public saveFileContents(path: string, contents: string): Result<string> {
+    const result = super.saveFileContents(path, contents);
+    if (result.isSuccess()) {
+      this._dirtyFiles.add(path);
+      if (this._autoSync) {
+        const syncResult = this._syncFile(path);
+        if (syncResult.isSuccess()) {
+          this._dirtyFiles.delete(path);
+        } else {
+          return fail(syncResult.message);
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Check if a file is mutable and return persistence detail.
+   * @param path - File path to check
+   * @returns DetailedResult with mutability status and 'persistent' detail if mutable
+   * @public
+   */
+  public fileIsMutable(path: string): DetailedResult<boolean, FileTree.SaveDetail> {
+    const baseResult = super.fileIsMutable(path);
+    if (baseResult.isSuccess() && baseResult.value === true) {
+      return succeedWithDetail(true, 'persistent');
+    }
+    return baseResult;
+  }
+}

package/src/test/mocks/idb-keyval.ts

@@ -0,0 +1,5 @@
+export const createStore = jest.fn(() => ({}));
+export const get = jest.fn();
+export const set = jest.fn();
+export const del = jest.fn();
+export const keys = jest.fn();

package/src/test/unit/browserHashProvider.test.ts

@@ -21,7 +21,7 @@
  */
 
 import '@fgv/ts-utils-jest';
-import { BrowserHashProvider } from '../../packlets/crypto';
+import { BrowserHashProvider } from '../../packlets/crypto-utils';
 
 describe('BrowserHashProvider', () => {
   describe('hashString', () => {

package/src/test/unit/directoryHandleStore.test.ts

@@ -0,0 +1,251 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import '@fgv/ts-utils-jest';
+import {
+  DirectoryHandleStore,
+  DEFAULT_DIRECTORY_HANDLE_DB,
+  DEFAULT_DIRECTORY_HANDLE_STORE
+} from '../../packlets/file-tree/directoryHandleStore';
+import type { FileSystemDirectoryHandle } from '../../packlets/file-api-types';
+
+import { get, set, del, keys, createStore } from 'idb-keyval';
+
+const mockGet = jest.mocked(get);
+const mockSet = jest.mocked(set);
+const mockDel = jest.mocked(del);
+const mockKeys = jest.mocked(keys);
+const mockCreateStore = jest.mocked(createStore);
+
+function makeMockHandle(name: string): FileSystemDirectoryHandle {
+  return {
+    kind: 'directory',
+    name,
+    isSameEntry: jest.fn(),
+    queryPermission: jest.fn(),
+    requestPermission: jest.fn(),
+    getDirectoryHandle: jest.fn(),
+    getFileHandle: jest.fn(),
+    removeEntry: jest.fn(),
+    resolve: jest.fn(),
+    keys: jest.fn(),
+    values: jest.fn(),
+    entries: jest.fn(),
+    [Symbol.asyncIterator]: jest.fn()
+  } as FileSystemDirectoryHandle;
+}
+
+describe('DirectoryHandleStore', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('constants', () => {
+    test('DEFAULT_DIRECTORY_HANDLE_DB has expected value', () => {
+      expect(DEFAULT_DIRECTORY_HANDLE_DB).toBe('chocolate-lab-storage');
+    });
+
+    test('DEFAULT_DIRECTORY_HANDLE_STORE has expected value', () => {
+      expect(DEFAULT_DIRECTORY_HANDLE_STORE).toBe('directory-handles');
+    });
+  });
+
+  describe('constructor', () => {
+    test('uses default db and store names', () => {
+      new DirectoryHandleStore();
+      expect(mockCreateStore).toHaveBeenCalledWith(
+        DEFAULT_DIRECTORY_HANDLE_DB,
+        DEFAULT_DIRECTORY_HANDLE_STORE
+      );
+    });
+
+    test('uses custom db and store names', () => {
+      new DirectoryHandleStore('custom-db', 'custom-store');
+      expect(mockCreateStore).toHaveBeenCalledWith('custom-db', 'custom-store');
+    });
+  });
+
+  describe('save', () => {
+    test('saves a handle successfully', async () => {
+      mockSet.mockResolvedValue(undefined);
+      const store = new DirectoryHandleStore();
+      const handle = makeMockHandle('my-dir');
+
+      const result = await store.save('my-dir', handle);
+
+      expect(result).toSucceed();
+      expect(mockSet).toHaveBeenCalledWith('my-dir', handle, expect.anything());
+    });
+
+    test('returns failure when set throws', async () => {
+      mockSet.mockRejectedValue(new Error('IndexedDB unavailable'));
+      const store = new DirectoryHandleStore();
+      const handle = makeMockHandle('my-dir');
+
+      const result = await store.save('my-dir', handle);
+
+      expect(result).toFailWith(/IndexedDB unavailable/);
+    });
+  });
+
+  describe('load', () => {
+    test('returns the handle when found', async () => {
+      const handle = makeMockHandle('my-dir');
+      mockGet.mockResolvedValue(handle);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.load('my-dir');
+
+      expect(result).toSucceedWith(handle);
+      expect(mockGet).toHaveBeenCalledWith('my-dir', expect.anything());
+    });
+
+    test('returns undefined when not found', async () => {
+      mockGet.mockResolvedValue(undefined);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.load('missing');
+
+      expect(result).toSucceedWith(undefined);
+    });
+
+    test('returns failure when get throws', async () => {
+      mockGet.mockRejectedValue(new Error('read error'));
+      const store = new DirectoryHandleStore();
+
+      const result = await store.load('my-dir');
+
+      expect(result).toFailWith(/read error/);
+    });
+  });
+
+  describe('remove', () => {
+    test('removes a handle successfully', async () => {
+      mockDel.mockResolvedValue(undefined);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.remove('my-dir');
+
+      expect(result).toSucceed();
+      expect(mockDel).toHaveBeenCalledWith('my-dir', expect.anything());
+    });
+
+    test('returns failure when del throws', async () => {
+      mockDel.mockRejectedValue(new Error('delete error'));
+      const store = new DirectoryHandleStore();
+
+      const result = await store.remove('my-dir');
+
+      expect(result).toFailWith(/delete error/);
+    });
+  });
+
+  describe('getAllLabels', () => {
+    test('returns all keys', async () => {
+      mockKeys.mockResolvedValue(['dir-a', 'dir-b']);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAllLabels();
+
+      expect(result).toSucceedWith(['dir-a', 'dir-b']);
+      expect(mockKeys).toHaveBeenCalledWith(expect.anything());
+    });
+
+    test('returns empty array when no keys', async () => {
+      mockKeys.mockResolvedValue([]);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAllLabels();
+
+      expect(result).toSucceedWith([]);
+    });
+
+    test('returns failure when keys throws', async () => {
+      mockKeys.mockRejectedValue(new Error('keys error'));
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAllLabels();
+
+      expect(result).toFailWith(/keys error/);
+    });
+  });
+
+  describe('getAll', () => {
+    test('returns all label/handle pairs', async () => {
+      const handleA = makeMockHandle('dir-a');
+      const handleB = makeMockHandle('dir-b');
+      mockKeys.mockResolvedValue(['dir-a', 'dir-b']);
+      mockGet.mockResolvedValueOnce(handleA).mockResolvedValueOnce(handleB);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAll();
+
+      expect(result).toSucceedAndSatisfy((entries) => {
+        expect(entries).toHaveLength(2);
+        expect(entries[0]).toEqual({ label: 'dir-a', handle: handleA });
+        expect(entries[1]).toEqual({ label: 'dir-b', handle: handleB });
+      });
+    });
+
+    test('returns empty array when no handles stored', async () => {
+      mockKeys.mockResolvedValue([]);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAll();
+
+      expect(result).toSucceedWith([]);
+    });
+
+    test('skips entries where handle is undefined', async () => {
+      const handleA = makeMockHandle('dir-a');
+      mockKeys.mockResolvedValue(['dir-a', 'dir-b']);
+      mockGet.mockResolvedValueOnce(handleA).mockResolvedValueOnce(undefined);
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAll();
+
+      expect(result).toSucceedAndSatisfy((entries) => {
+        expect(entries).toHaveLength(1);
+        expect(entries[0]).toEqual({ label: 'dir-a', handle: handleA });
+      });
+    });
+
+    test('returns failure when getAllLabels fails', async () => {
+      mockKeys.mockRejectedValue(new Error('keys error'));
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAll();
+
+      expect(result).toFailWith(/keys error/);
+    });
+
+    test('returns failure when load fails for a key', async () => {
+      mockKeys.mockResolvedValue(['dir-a']);
+      mockGet.mockRejectedValue(new Error('load error'));
+      const store = new DirectoryHandleStore();
+
+      const result = await store.getAll();
+
+      expect(result).toFailWith(/load error/);
+    });
+  });
+});

package/src/test/unit/fileApiTypes.test.ts

@@ -279,6 +279,18 @@ describe('File API Types', () => {
 
       await expect(safeShowOpenFilePicker(mockWindow)).rejects.toThrow('User cancelled file picker');
     });
+
+    test('returns null when user cancels (AbortError)', async () => {
+      const abortError = new DOMException('The user aborted a request.', 'AbortError');
+      const mockWindow = {
+        showOpenFilePicker: jest.fn().mockRejectedValue(abortError),
+        showSaveFilePicker: jest.fn(),
+        showDirectoryPicker: jest.fn()
+      } as unknown as WindowWithFsAccess;
+
+      const result = await safeShowOpenFilePicker(mockWindow);
+      expect(result).toBeNull();
+    });
   });
 
   describe('safeShowSaveFilePicker', () => {
@@ -357,6 +369,18 @@ describe('File API Types', () => {
 
       await expect(safeShowSaveFilePicker(mockWindow)).rejects.toThrow('Save operation failed');
     });
+
+    test('returns null when user cancels (AbortError)', async () => {
+      const abortError = new DOMException('The user aborted a request.', 'AbortError');
+      const mockWindow = {
+        showOpenFilePicker: jest.fn(),
+        showSaveFilePicker: jest.fn().mockRejectedValue(abortError),
+        showDirectoryPicker: jest.fn()
+      } as unknown as WindowWithFsAccess;
+
+      const result = await safeShowSaveFilePicker(mockWindow);
+      expect(result).toBeNull();
+    });
   });
 
   describe('safeShowDirectoryPicker', () => {
@@ -441,6 +465,18 @@ describe('File API Types', () => {
 
       await expect(safeShowDirectoryPicker(mockWindow)).rejects.toThrow('Directory access denied');
     });
+
+    test('returns null when user cancels (AbortError)', async () => {
+      const abortError = new DOMException('The user aborted a request.', 'AbortError');
+      const mockWindow = {
+        showOpenFilePicker: jest.fn(),
+        showSaveFilePicker: jest.fn(),
+        showDirectoryPicker: jest.fn().mockRejectedValue(abortError)
+      } as unknown as WindowWithFsAccess;
+
+      const result = await safeShowDirectoryPicker(mockWindow);
+      expect(result).toBeNull();
+    });
   });
 
   describe('integration tests', () => {