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

package/config/jest.config.json

@@ -12,5 +12,8 @@
     }
   },
   "collectCoverage": true,
-  "coverageReporters": ["text", "lcov", "html"]
+  "coverageReporters": ["text", "lcov", "html"],
+  "moduleNameMapper": {
+    "^idb-keyval$": "<rootDir>/lib/test/mocks/idb-keyval.js"
+  }
 }

package/config/typedoc.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "extends": ["@fgv/heft-dual-rig/profiles/default/config/typedoc.base.json"],
+  "entryPoints": ["../src/index.ts"],
+  "out": "../docs"
+}

package/dist/index.js

@@ -29,8 +29,8 @@
  *
  * @packageDocumentation
  */
-// Export crypto functionality
-export * from './packlets/crypto';
+import * as CryptoUtils from './packlets/crypto-utils';
+export { CryptoUtils };
 // Export file tree functionality
 export * from './packlets/file-tree';
 // Export helper functions

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;GASG;AAEH,8BAA8B;AAC9B,cAAc,mBAAmB,CAAC;AAElC,iCAAiC;AACjC,cAAc,sBAAsB,CAAC;AAErC,0BAA0B;AAC1B,cAAc,oBAAoB,CAAC;AAEnC,sCAAsC;AACtC,cAAc,2BAA2B,CAAC;AAE1C,uBAAuB;AACvB,cAAc,sBAAsB,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible utilities and FileTree implementations.\n *\n * This library provides browser-compatible alternatives to Node.js-specific functionality,\n * including Web Crypto API-based hashing, File API-based file tree implementations,\n * and URL parameter parsing utilities.\n * All exports are designed to be tree-shakeable for optimal bundle size.\n *\n * @packageDocumentation\n */\n\n// Export crypto functionality\nexport * from './packlets/crypto';\n\n// Export file tree functionality\nexport * from './packlets/file-tree';\n\n// Export helper functions\nexport * from './packlets/helpers';\n\n// Export File System Access API types\nexport * from './packlets/file-api-types';\n\n// Export URL utilities\nexport * from './packlets/url-utils';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;GASG;AAEH,OAAO,KAAK,WAAW,MAAM,yBAAyB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,CAAC;AAEvB,iCAAiC;AACjC,cAAc,sBAAsB,CAAC;AAErC,0BAA0B;AAC1B,cAAc,oBAAoB,CAAC;AAEnC,sCAAsC;AACtC,cAAc,2BAA2B,CAAC;AAE1C,uBAAuB;AACvB,cAAc,sBAAsB,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible utilities and FileTree implementations.\n *\n * This library provides browser-compatible alternatives to Node.js-specific functionality,\n * including Web Crypto API-based hashing, File API-based file tree implementations,\n * and URL parameter parsing utilities.\n * All exports are designed to be tree-shakeable for optimal bundle size.\n *\n * @packageDocumentation\n */\n\nimport * as CryptoUtils from './packlets/crypto-utils';\nexport { CryptoUtils };\n\n// Export file tree functionality\nexport * from './packlets/file-tree';\n\n// Export helper functions\nexport * from './packlets/helpers';\n\n// Export File System Access API types\nexport * from './packlets/file-api-types';\n\n// Export URL utilities\nexport * from './packlets/url-utils';\n"]}

package/dist/packlets/crypto-utils/browserCryptoProvider.js

@@ -0,0 +1,254 @@
+// Copyright (c) 2024 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.
+/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */
+import { captureResult, Failure, Success } from '@fgv/ts-utils';
+import { CryptoUtils } from '@fgv/ts-extras';
+const CryptoConstants = CryptoUtils.Constants;
+/**
+ * Extracts an `ArrayBuffer` from a Uint8Array, handling the potential SharedArrayBuffer case.
+ * @param arr - The Uint8Array to extract from
+ * @returns An `ArrayBuffer` containing a copy of the data.
+ */
+function toArrayBuffer(arr) {
+    // Create a new ArrayBuffer and copy the data - this handles both ArrayBuffer and SharedArrayBuffer
+    const buffer = new ArrayBuffer(arr.byteLength);
+    new Uint8Array(buffer).set(arr);
+    return buffer;
+}
+/**
+ * Browser implementation of `ICryptoProvider` using the Web Crypto API.
+ * Uses AES-256-GCM for authenticated encryption.
+ *
+ * Note: This provider requires a browser environment with Web Crypto API support.
+ * In Node.js 15+, Web Crypto is available via globalThis.crypto or require('crypto').webcrypto.
+ *
+ * @public
+ */
+export class BrowserCryptoProvider {
+    /**
+     * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
+     * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
+     */
+    constructor(cryptoApi) {
+        if (cryptoApi) {
+            this._crypto = cryptoApi;
+        }
+        else if (typeof globalThis !== 'undefined' && globalThis.crypto) {
+            this._crypto = globalThis.crypto;
+        }
+        else if (typeof window !== 'undefined' && window.crypto) {
+            this._crypto = window.crypto;
+        }
+        else {
+            throw new Error('Web Crypto API not available');
+        }
+    }
+    /**
+     * Encrypts plaintext using AES-256-GCM.
+     * @param plaintext - UTF-8 string to encrypt
+     * @param key - 32-byte encryption key
+     * @returns `Success` with encryption result, or `Failure` with an error.
+     */
+    async encrypt(plaintext, key) {
+        if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
+            return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        try {
+            // Generate random IV
+            const iv = this._crypto.getRandomValues(new Uint8Array(CryptoConstants.GCM_IV_SIZE));
+            // Import the key
+            const cryptoKey = await this._crypto.subtle.importKey('raw', toArrayBuffer(key), { name: 'AES-GCM' }, false, ['encrypt']);
+            // Encode plaintext to bytes
+            const encoder = new TextEncoder();
+            const plaintextBytes = encoder.encode(plaintext);
+            // Encrypt (Web Crypto appends auth tag to ciphertext)
+            const encryptedWithTag = await this._crypto.subtle.encrypt({
+                name: 'AES-GCM',
+                iv: iv,
+                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+            }, cryptoKey, plaintextBytes);
+            // Split ciphertext and auth tag (auth tag is last 16 bytes)
+            const encryptedArray = new Uint8Array(encryptedWithTag);
+            const encryptedData = encryptedArray.slice(0, encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+            const authTag = encryptedArray.slice(encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);
+            return Success.with({
+                iv,
+                authTag,
+                encryptedData
+            });
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return Failure.with(`Encryption failed: ${message}`);
+        }
+    }
+    /**
+     * Decrypts ciphertext using AES-256-GCM.
+     * @param encryptedData - Encrypted bytes
+     * @param key - 32-byte decryption key
+     * @param iv - Initialization vector (12 bytes)
+     * @param authTag - GCM authentication tag (16 bytes)
+     * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.
+     */
+    async decrypt(encryptedData, key, iv, authTag) {
+        if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {
+            return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);
+        }
+        if (iv.length !== CryptoConstants.GCM_IV_SIZE) {
+            return Failure.with(`IV must be ${CryptoConstants.GCM_IV_SIZE} bytes, got ${iv.length}`);
+        }
+        if (authTag.length !== CryptoConstants.GCM_AUTH_TAG_SIZE) {
+            return Failure.with(`Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`);
+        }
+        try {
+            // Import the key
+            const cryptoKey = await this._crypto.subtle.importKey('raw', toArrayBuffer(key), { name: 'AES-GCM' }, false, ['decrypt']);
+            // Web Crypto expects ciphertext + auth tag concatenated
+            const encryptedWithTag = new Uint8Array(encryptedData.length + authTag.length);
+            encryptedWithTag.set(encryptedData);
+            encryptedWithTag.set(authTag, encryptedData.length);
+            // Decrypt
+            const decrypted = await this._crypto.subtle.decrypt({
+                name: 'AES-GCM',
+                iv: toArrayBuffer(iv),
+                tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits
+            }, cryptoKey, encryptedWithTag);
+            // Decode to string
+            const decoder = new TextDecoder();
+            return Success.with(decoder.decode(decrypted));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return Failure.with(`Decryption failed: ${message}`);
+        }
+    }
+    /**
+     * Generates a random 32-byte key suitable for AES-256.
+     * @returns Success with generated key, or Failure with error
+     */
+    async generateKey() {
+        try {
+            return Success.with(this._crypto.getRandomValues(new Uint8Array(CryptoConstants.AES_256_KEY_SIZE)));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return Failure.with(`Key generation failed: ${message}`);
+        }
+    }
+    /**
+     * Derives a key from a password using PBKDF2.
+     * @param password - Password string
+     * @param salt - Salt bytes (should be at least 16 bytes)
+     * @param iterations - Number of iterations (recommend 100000+)
+     * @returns Success with derived 32-byte key, or Failure with error
+     */
+    async deriveKey(password, salt, iterations) {
+        if (iterations < 1) {
+            return Failure.with('Iterations must be at least 1');
+        }
+        if (salt.length < 8) {
+            return Failure.with('Salt should be at least 8 bytes');
+        }
+        try {
+            // Encode password
+            const encoder = new TextEncoder();
+            const passwordBytes = encoder.encode(password);
+            // Import password as key material
+            const keyMaterial = await this._crypto.subtle.importKey('raw', passwordBytes, 'PBKDF2', false, [
+                'deriveBits'
+            ]);
+            // Derive key bits
+            const derivedBits = await this._crypto.subtle.deriveBits({
+                name: 'PBKDF2',
+                salt: toArrayBuffer(salt),
+                iterations: iterations,
+                hash: 'SHA-256'
+            }, keyMaterial, CryptoConstants.AES_256_KEY_SIZE * 8 // bits
+            );
+            return Success.with(new Uint8Array(derivedBits));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return Failure.with(`Key derivation failed: ${message}`);
+        }
+    }
+    // ============================================================================
+    // Platform Utility Methods
+    // ============================================================================
+    /**
+     * Generates cryptographically secure random bytes.
+     * @param length - Number of bytes to generate
+     * @returns Success with random bytes, or Failure with error
+     */
+    generateRandomBytes(length) {
+        if (length < 1) {
+            return Failure.with('Length must be at least 1');
+        }
+        try {
+            return Success.with(this._crypto.getRandomValues(new Uint8Array(length)));
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return Failure.with(`Random bytes generation failed: ${message}`);
+        }
+    }
+    /**
+     * Encodes binary data to base64 string.
+     * @param data - Binary data to encode
+     * @returns Base64-encoded string
+     */
+    toBase64(data) {
+        // Convert Uint8Array to binary string, then to base64
+        let binary = '';
+        for (let i = 0; i < data.length; i++) {
+            binary += String.fromCharCode(data[i]);
+        }
+        return btoa(binary);
+    }
+    /**
+     * Decodes base64 string to binary data.
+     * @param base64 - Base64-encoded string
+     * @returns Success with decoded bytes, or Failure if invalid base64
+     */
+    fromBase64(base64) {
+        try {
+            const binary = atob(base64);
+            const bytes = new Uint8Array(binary.length);
+            for (let i = 0; i < binary.length; i++) {
+                bytes[i] = binary.charCodeAt(i);
+            }
+            return Success.with(bytes);
+        }
+        catch (e) {
+            return Failure.with('Invalid base64 string');
+        }
+    }
+}
+/**
+ * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web
+ * Crypto API is available.
+ * @returns `Success` with provider, or `Failure` if not available
+ * @public
+ */
+export function createBrowserCryptoProvider() {
+    return captureResult(() => new BrowserCryptoProvider());
+}
+/* c8 ignore stop */
+//# sourceMappingURL=browserCryptoProvider.js.map

package/dist/packlets/crypto-utils/browserCryptoProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserCryptoProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserCryptoProvider.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2024 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/* c8 ignore start - Browser-only implementation cannot be tested in Node.js environment */\nimport { captureResult, Failure, Result, Success } from '@fgv/ts-utils';\nimport { CryptoUtils } from '@fgv/ts-extras';\n\ntype ICryptoProvider = CryptoUtils.ICryptoProvider;\ntype IEncryptionResult = CryptoUtils.IEncryptionResult;\nconst CryptoConstants = CryptoUtils.Constants;\n\n/**\n * Extracts an `ArrayBuffer` from a Uint8Array, handling the potential SharedArrayBuffer case.\n * @param arr - The Uint8Array to extract from\n * @returns An `ArrayBuffer` containing a copy of the data.\n */\nfunction toArrayBuffer(arr: Uint8Array): ArrayBuffer {\n  // Create a new ArrayBuffer and copy the data - this handles both ArrayBuffer and SharedArrayBuffer\n  const buffer = new ArrayBuffer(arr.byteLength);\n  new Uint8Array(buffer).set(arr);\n  return buffer;\n}\n\n/**\n * Browser implementation of `ICryptoProvider` using the Web Crypto API.\n * Uses AES-256-GCM for authenticated encryption.\n *\n * Note: This provider requires a browser environment with Web Crypto API support.\n * In Node.js 15+, Web Crypto is available via globalThis.crypto or require('crypto').webcrypto.\n *\n * @public\n */\nexport class BrowserCryptoProvider implements ICryptoProvider {\n  private readonly _crypto: Crypto;\n\n  /**\n   * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.\n   * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)\n   */\n  public constructor(cryptoApi?: Crypto) {\n    if (cryptoApi) {\n      this._crypto = cryptoApi;\n    } else if (typeof globalThis !== 'undefined' && globalThis.crypto) {\n      this._crypto = globalThis.crypto;\n    } else if (typeof window !== 'undefined' && window.crypto) {\n      this._crypto = window.crypto;\n    } else {\n      throw new Error('Web Crypto API not available');\n    }\n  }\n\n  /**\n   * Encrypts plaintext using AES-256-GCM.\n   * @param plaintext - UTF-8 string to encrypt\n   * @param key - 32-byte encryption key\n   * @returns `Success` with encryption result, or `Failure` with an error.\n   */\n  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>> {\n    if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {\n      return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);\n    }\n\n    try {\n      // Generate random IV\n      const iv = this._crypto.getRandomValues(new Uint8Array(CryptoConstants.GCM_IV_SIZE));\n\n      // Import the key\n      const cryptoKey = await this._crypto.subtle.importKey(\n        'raw',\n        toArrayBuffer(key),\n        { name: 'AES-GCM' },\n        false,\n        ['encrypt']\n      );\n\n      // Encode plaintext to bytes\n      const encoder = new TextEncoder();\n      const plaintextBytes = encoder.encode(plaintext);\n\n      // Encrypt (Web Crypto appends auth tag to ciphertext)\n      const encryptedWithTag = await this._crypto.subtle.encrypt(\n        {\n          name: 'AES-GCM',\n          iv: iv,\n          tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits\n        },\n        cryptoKey,\n        plaintextBytes\n      );\n\n      // Split ciphertext and auth tag (auth tag is last 16 bytes)\n      const encryptedArray = new Uint8Array(encryptedWithTag);\n      const encryptedData = encryptedArray.slice(\n        0,\n        encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE\n      );\n      const authTag = encryptedArray.slice(encryptedArray.length - CryptoConstants.GCM_AUTH_TAG_SIZE);\n      return Success.with({\n        iv,\n        authTag,\n        encryptedData\n      });\n    } catch (e) {\n      const message = e instanceof Error ? e.message : String(e);\n      return Failure.with(`Encryption failed: ${message}`);\n    }\n  }\n\n  /**\n   * Decrypts ciphertext using AES-256-GCM.\n   * @param encryptedData - Encrypted bytes\n   * @param key - 32-byte decryption key\n   * @param iv - Initialization vector (12 bytes)\n   * @param authTag - GCM authentication tag (16 bytes)\n   * @returns `Success` with decrypted UTF-8 string, or `Failure` with an error.\n   */\n  public async decrypt(\n    encryptedData: Uint8Array,\n    key: Uint8Array,\n    iv: Uint8Array,\n    authTag: Uint8Array\n  ): Promise<Result<string>> {\n    if (key.length !== CryptoConstants.AES_256_KEY_SIZE) {\n      return Failure.with(`Key must be ${CryptoConstants.AES_256_KEY_SIZE} bytes, got ${key.length}`);\n    }\n    if (iv.length !== CryptoConstants.GCM_IV_SIZE) {\n      return Failure.with(`IV must be ${CryptoConstants.GCM_IV_SIZE} bytes, got ${iv.length}`);\n    }\n    if (authTag.length !== CryptoConstants.GCM_AUTH_TAG_SIZE) {\n      return Failure.with(\n        `Auth tag must be ${CryptoConstants.GCM_AUTH_TAG_SIZE} bytes, got ${authTag.length}`\n      );\n    }\n\n    try {\n      // Import the key\n      const cryptoKey = await this._crypto.subtle.importKey(\n        'raw',\n        toArrayBuffer(key),\n        { name: 'AES-GCM' },\n        false,\n        ['decrypt']\n      );\n\n      // Web Crypto expects ciphertext + auth tag concatenated\n      const encryptedWithTag = new Uint8Array(encryptedData.length + authTag.length);\n      encryptedWithTag.set(encryptedData);\n      encryptedWithTag.set(authTag, encryptedData.length);\n\n      // Decrypt\n      const decrypted = await this._crypto.subtle.decrypt(\n        {\n          name: 'AES-GCM',\n          iv: toArrayBuffer(iv),\n          tagLength: CryptoConstants.GCM_AUTH_TAG_SIZE * 8 // bits\n        },\n        cryptoKey,\n        encryptedWithTag\n      );\n\n      // Decode to string\n      const decoder = new TextDecoder();\n      return Success.with(decoder.decode(decrypted));\n    } catch (e) {\n      const message = e instanceof Error ? e.message : String(e);\n      return Failure.with(`Decryption failed: ${message}`);\n    }\n  }\n\n  /**\n   * Generates a random 32-byte key suitable for AES-256.\n   * @returns Success with generated key, or Failure with error\n   */\n  public async generateKey(): Promise<Result<Uint8Array>> {\n    try {\n      return Success.with(this._crypto.getRandomValues(new Uint8Array(CryptoConstants.AES_256_KEY_SIZE)));\n    } catch (e) {\n      const message = e instanceof Error ? e.message : String(e);\n      return Failure.with(`Key generation failed: ${message}`);\n    }\n  }\n\n  /**\n   * Derives a key from a password using PBKDF2.\n   * @param password - Password string\n   * @param salt - Salt bytes (should be at least 16 bytes)\n   * @param iterations - Number of iterations (recommend 100000+)\n   * @returns Success with derived 32-byte key, or Failure with error\n   */\n  public async deriveKey(\n    password: string,\n    salt: Uint8Array,\n    iterations: number\n  ): Promise<Result<Uint8Array>> {\n    if (iterations < 1) {\n      return Failure.with('Iterations must be at least 1');\n    }\n    if (salt.length < 8) {\n      return Failure.with('Salt should be at least 8 bytes');\n    }\n\n    try {\n      // Encode password\n      const encoder = new TextEncoder();\n      const passwordBytes = encoder.encode(password);\n\n      // Import password as key material\n      const keyMaterial = await this._crypto.subtle.importKey('raw', passwordBytes, 'PBKDF2', false, [\n        'deriveBits'\n      ]);\n\n      // Derive key bits\n      const derivedBits = await this._crypto.subtle.deriveBits(\n        {\n          name: 'PBKDF2',\n          salt: toArrayBuffer(salt),\n          iterations: iterations,\n          hash: 'SHA-256'\n        },\n        keyMaterial,\n        CryptoConstants.AES_256_KEY_SIZE * 8 // bits\n      );\n\n      return Success.with(new Uint8Array(derivedBits));\n    } catch (e) {\n      const message = e instanceof Error ? e.message : String(e);\n      return Failure.with(`Key derivation failed: ${message}`);\n    }\n  }\n\n  // ============================================================================\n  // Platform Utility Methods\n  // ============================================================================\n\n  /**\n   * Generates cryptographically secure random bytes.\n   * @param length - Number of bytes to generate\n   * @returns Success with random bytes, or Failure with error\n   */\n  public generateRandomBytes(length: number): Result<Uint8Array> {\n    if (length < 1) {\n      return Failure.with('Length must be at least 1');\n    }\n    try {\n      return Success.with(this._crypto.getRandomValues(new Uint8Array(length)));\n    } catch (e) {\n      const message = e instanceof Error ? e.message : String(e);\n      return Failure.with(`Random bytes generation failed: ${message}`);\n    }\n  }\n\n  /**\n   * Encodes binary data to base64 string.\n   * @param data - Binary data to encode\n   * @returns Base64-encoded string\n   */\n  public toBase64(data: Uint8Array): string {\n    // Convert Uint8Array to binary string, then to base64\n    let binary = '';\n    for (let i = 0; i < data.length; i++) {\n      binary += String.fromCharCode(data[i]);\n    }\n    return btoa(binary);\n  }\n\n  /**\n   * Decodes base64 string to binary data.\n   * @param base64 - Base64-encoded string\n   * @returns Success with decoded bytes, or Failure if invalid base64\n   */\n  public fromBase64(base64: string): Result<Uint8Array> {\n    try {\n      const binary = atob(base64);\n      const bytes = new Uint8Array(binary.length);\n      for (let i = 0; i < binary.length; i++) {\n        bytes[i] = binary.charCodeAt(i);\n      }\n      return Success.with(bytes);\n    } catch (e) {\n      return Failure.with('Invalid base64 string');\n    }\n  }\n}\n\n/**\n * Creates a {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider} if Web\n * Crypto API is available.\n * @returns `Success` with provider, or `Failure` if not available\n * @public\n */\nexport function createBrowserCryptoProvider(): Result<BrowserCryptoProvider> {\n  return captureResult(() => new BrowserCryptoProvider());\n}\n/* c8 ignore stop */\n"]}

package/dist/packlets/crypto-utils/browserHashProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserHashProvider.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/browserHashProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAU,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IAC9B;;;;;OAKG;IACI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,IAAY,EAAE,YAAoB,SAAS;QACxE,IAAI,CAAC;YACH,yCAAyC;YACzC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;gBACnB,OAAO,IAAI,CAAC,kDAAkD,CAAC,CAAC;YAClE,CAAC;YAED,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACxC,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;YACrE,MAAM,SAAS,GAAG,IAAI,UAAU,CAAC,UAAU,CAAC,CAAC;YAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC;iBAClC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;iBAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;YAEZ,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,4BAA4B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpG,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,CAAC,SAAS,CAC3B,KAAe,EACf,YAAoB,SAAS,EAC7B,YAAoB,GAAG;QAEvB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;CACF","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\nimport { Result, succeed, fail } from '@fgv/ts-utils';\n\n/**\n * Browser-compatible hash provider using the Web Crypto API.\n * Supports common hash algorithms available in browsers.\n * @public\n */\nexport class BrowserHashProvider {\n  /**\n   * Hash a string using the specified algorithm.\n   * @param data - The string to hash\n   * @param algorithm - The hash algorithm to use\n   * @returns Promise resolving to the hex-encoded hash\n   */\n  public static async hashString(data: string, algorithm: string = 'SHA-256'): Promise<Result<string>> {\n    try {\n      /* c8 ignore next 3 - defense in depth */\n      if (!crypto.subtle) {\n        return fail('Web Crypto API not available in this environment');\n      }\n\n      const encoder = new TextEncoder();\n      const dataBuffer = encoder.encode(data);\n      const hashBuffer = await crypto.subtle.digest(algorithm, dataBuffer);\n      const hashArray = new Uint8Array(hashBuffer);\n      const hashHex = Array.from(hashArray)\n        .map((b) => b.toString(16).padStart(2, '0'))\n        .join('');\n\n      return succeed(hashHex);\n    } catch (error) {\n      return fail(`Hash computation failed: ${error instanceof Error ? error.message : String(error)}`);\n    }\n  }\n\n  /**\n   * Hash multiple strings concatenated with a separator.\n   * @param parts - Array of strings to concatenate and hash\n   * @param algorithm - The hash algorithm to use\n   * @param separator - Separator to use between parts (default: '|')\n   * @returns Promise resolving to the hex-encoded hash\n   */\n  public static async hashParts(\n    parts: string[],\n    algorithm: string = 'SHA-256',\n    separator: string = '|'\n  ): Promise<Result<string>> {\n    const combined = parts.join(separator);\n    return this.hashString(combined, algorithm);\n  }\n}\n"]}

package/dist/packlets/{crypto → crypto-utils}/index.js

@@ -24,4 +24,5 @@
  * @packageDocumentation
  */
 export * from './browserHashProvider';
+export * from './browserCryptoProvider';
 //# sourceMappingURL=index.js.map

package/dist/packlets/crypto-utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/crypto-utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;GAGG;AAEH,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * Browser-compatible cryptographic utilities using the Web Crypto API.\n * @packageDocumentation\n */\n\nexport * from './browserHashProvider';\nexport * from './browserCryptoProvider';\n"]}

package/dist/packlets/file-api-types/index.js

@@ -55,7 +55,15 @@ export function isDirectoryHandle(handle) {
  */
 export async function safeShowOpenFilePicker(window, options) {
     if (supportsFileSystemAccess(window)) {
-        return window.showOpenFilePicker(options);
+        try {
+            return await window.showOpenFilePicker(options);
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                return null;
+            }
+            throw error;
+        }
     }
     return null;
 }
@@ -68,7 +76,15 @@ export async function safeShowOpenFilePicker(window, options) {
  */
 export async function safeShowSaveFilePicker(window, options) {
     if (supportsFileSystemAccess(window)) {
-        return window.showSaveFilePicker(options);
+        try {
+            return await window.showSaveFilePicker(options);
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                return null;
+            }
+            throw error;
+        }
     }
     return null;
 }
@@ -81,7 +97,15 @@ export async function safeShowSaveFilePicker(window, options) {
  */
 export async function safeShowDirectoryPicker(window, options) {
     if (supportsFileSystemAccess(window)) {
-        return window.showDirectoryPicker(options);
+        try {
+            return await window.showDirectoryPicker(options);
+        }
+        catch (error) {
+            if (error instanceof DOMException && error.name === 'AbortError') {
+                return null;
+            }
+            throw error;
+        }
     }
     return null;
 }

package/dist/packlets/file-api-types/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/file-api-types/index.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * File System Access API type definitions and utilities for browser compatibility.\n * @packageDocumentation\n */\n\n// Local type definitions for File System Access API\n// Based on https://wicg.github.io/file-system-access/\n\n/**\n * File System Access API methods available on Window\n * @public\n */\nexport interface IFsAccessApis {\n  showDirectoryPicker(options?: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle>;\n  showOpenFilePicker(options?: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle[]>;\n  showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle>;\n}\n\n/**\n * Window interface extended with File System Access API\n * @public\n */\nexport type WindowWithFsAccess = Window & IFsAccessApis;\n\n/**\n * Base interface for file system handles\n * @public\n */\nexport interface FileSystemHandle {\n  readonly kind: 'file' | 'directory';\n  readonly name: string;\n  isSameEntry(other: FileSystemHandle): Promise<boolean>;\n  queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;\n  requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;\n}\n\n/**\n * File handle interface\n * @public\n */\nexport interface FileSystemFileHandle extends FileSystemHandle {\n  readonly kind: 'file';\n  getFile(): Promise<File>;\n  createWritable(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;\n}\n\n/**\n * Directory handle interface\n * @public\n */\nexport interface FileSystemDirectoryHandle extends FileSystemHandle {\n  readonly kind: 'directory';\n  getDirectoryHandle(\n    name: string,\n    options?: FileSystemGetDirectoryOptions\n  ): Promise<FileSystemDirectoryHandle>;\n  getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle>;\n  removeEntry(name: string, options?: FileSystemRemoveOptions): Promise<void>;\n  resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;\n  keys(): AsyncIterableIterator<string>;\n  values(): AsyncIterableIterator<FileSystemHandle>;\n  entries(): AsyncIterableIterator<[string, FileSystemHandle]>;\n  [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;\n}\n\n/**\n * Permission descriptor for file system handles\n * @public\n */\nexport interface FileSystemHandlePermissionDescriptor {\n  mode?: 'read' | 'readwrite';\n}\n\n/**\n * Options for creating writable file streams\n * @public\n */\nexport interface FileSystemCreateWritableOptions {\n  keepExistingData?: boolean;\n}\n\n/**\n * Options for getting directory handles\n * @public\n */\nexport interface FileSystemGetDirectoryOptions {\n  create?: boolean;\n}\n\n/**\n * Options for getting file handles\n * @public\n */\nexport interface FileSystemGetFileOptions {\n  create?: boolean;\n}\n\n/**\n * Options for removing entries\n * @public\n */\nexport interface FileSystemRemoveOptions {\n  recursive?: boolean;\n}\n\n/**\n * Writable file stream interface\n * @public\n */\nexport interface FileSystemWritableFileStream extends WritableStream {\n  write(data: BufferSource | Blob | string): Promise<void>;\n  seek(position: number): Promise<void>;\n  truncate(size: number): Promise<void>;\n}\n\n/**\n * Directory picker options\n * @public\n */\nexport interface ShowDirectoryPickerOptions {\n  id?: string;\n  mode?: 'read' | 'readwrite';\n  startIn?: FileSystemHandle | WellKnownDirectory;\n}\n\n/**\n * File picker options\n * @public\n */\nexport interface ShowOpenFilePickerOptions {\n  multiple?: boolean;\n  excludeAcceptAllOption?: boolean;\n  id?: string;\n  startIn?: FileSystemHandle | WellKnownDirectory;\n  types?: FilePickerAcceptType[];\n}\n\n/**\n * Save file picker options\n * @public\n */\nexport interface ShowSaveFilePickerOptions {\n  excludeAcceptAllOption?: boolean;\n  id?: string;\n  startIn?: FileSystemHandle | WellKnownDirectory;\n  suggestedName?: string;\n  types?: FilePickerAcceptType[];\n}\n\n/**\n * File picker accept type\n * @public\n */\nexport interface FilePickerAcceptType {\n  description?: string;\n  accept: Record<string, string | string[]>;\n}\n\n/**\n * Well-known directory type\n * @public\n */\nexport type WellKnownDirectory = 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos';\n\n/**\n * Type guard to check if the browser supports the File System Access API\n * @param window - The window object to check\n * @returns True if the window supports File System Access API\n * @public\n */\nexport function supportsFileSystemAccess(window: Window): window is WindowWithFsAccess {\n  return 'showOpenFilePicker' in window && 'showSaveFilePicker' in window && 'showDirectoryPicker' in window;\n}\n\n/**\n * Type guard to check if a FileSystemHandle is a file handle\n * @param handle - The handle to check\n * @returns True if the handle is a FileSystemFileHandle\n * @public\n */\nexport function isFileHandle(handle: FileSystemHandle): handle is FileSystemFileHandle {\n  return handle.kind === 'file';\n}\n\n/**\n * Type guard to check if a FileSystemHandle is a directory handle\n * @param handle - The handle to check\n * @returns True if the handle is a FileSystemDirectoryHandle\n * @public\n */\nexport function isDirectoryHandle(handle: FileSystemHandle): handle is FileSystemDirectoryHandle {\n  return handle.kind === 'directory';\n}\n\n/**\n * Safely access showOpenFilePicker with proper type checking\n * @param window - The window object\n * @param options - Options for the file picker\n * @returns Promise with file handles or null if not supported\n * @public\n */\nexport async function safeShowOpenFilePicker(\n  window: Window,\n  options?: ShowOpenFilePickerOptions\n): Promise<FileSystemFileHandle[] | null> {\n  if (supportsFileSystemAccess(window)) {\n    return window.showOpenFilePicker(options);\n  }\n  return null;\n}\n\n/**\n * Safely access showSaveFilePicker with proper type checking\n * @param window - The window object\n * @param options - Options for the file picker\n * @returns Promise with file handle or null if not supported\n * @public\n */\nexport async function safeShowSaveFilePicker(\n  window: Window,\n  options?: ShowSaveFilePickerOptions\n): Promise<FileSystemFileHandle | null> {\n  if (supportsFileSystemAccess(window)) {\n    return window.showSaveFilePicker(options);\n  }\n  return null;\n}\n\n/**\n * Safely access showDirectoryPicker with proper type checking\n * @param window - The window object\n * @param options - Options for the directory picker\n * @returns Promise with directory handle or null if not supported\n * @public\n */\nexport async function safeShowDirectoryPicker(\n  window: Window,\n  options?: ShowDirectoryPickerOptions\n): Promise<FileSystemDirectoryHandle | null> {\n  if (supportsFileSystemAccess(window)) {\n    return window.showDirectoryPicker(options);\n  }\n  return null;\n}\n\n/**\n * Export data as JSON file using legacy blob download method.\n * Creates a temporary download link and triggers file download.\n * @param data - Data to export as JSON\n * @param filename - Name for the downloaded file\n * @public\n */\nexport function exportAsJson(data: unknown, filename: string): void {\n  const json = JSON.stringify(data, null, 2);\n  const blob = new Blob([json], { type: 'application/json' });\n  const url = URL.createObjectURL(blob);\n\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = filename;\n  document.body.appendChild(a);\n  a.click();\n  document.body.removeChild(a);\n  URL.revokeObjectURL(url);\n}\n\n/**\n * Export data using File System Access API with fallback to blob download.\n * @param data - Data to export as JSON\n * @param suggestedName - Suggested filename for the save dialog\n * @param description - Description for file type filter (default: 'JSON files')\n * @param window - Window object for API access (default: globalThis.window)\n * @returns Promise resolving to true if saved via File System Access API, false if fallback used\n * @public\n */\nexport async function exportUsingFileSystemAPI(\n  data: unknown,\n  suggestedName: string,\n  description: string = 'JSON files',\n  window: Window = globalThis.window\n): Promise<boolean> {\n  if (!supportsFileSystemAccess(window)) {\n    // Fallback to blob download\n    exportAsJson(data, suggestedName);\n    return false;\n  }\n\n  try {\n    const fileHandle = await safeShowSaveFilePicker(window, {\n      suggestedName,\n      types: [\n        {\n          description,\n          accept: {\n            'application/json': ['.json']\n          }\n        }\n      ]\n    });\n\n    if (!fileHandle) {\n      // User cancelled - fallback to blob download\n      exportAsJson(data, suggestedName);\n      return false;\n    }\n\n    const json = JSON.stringify(data, null, 2);\n    const writable = await fileHandle.createWritable();\n    await writable.write(json);\n    await writable.close();\n\n    return true;\n  } catch (error) {\n    // Handle errors by falling back to blob download\n    if ((error as Error).name === 'AbortError') {\n      // User cancelled - fallback\n      exportAsJson(data, suggestedName);\n      return false;\n    }\n    // Other errors - re-throw as they indicate a real problem\n    throw error;\n  }\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/packlets/file-api-types/index.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2025 Erik Fortune\n *\n * Permission is hereby granted, free of charge, to any person obtaining a copy\n * of this software and associated documentation files (the \"Software\"), to deal\n * in the Software without restriction, including without limitation the rights\n * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n * copies of the Software, and to permit persons to whom the Software is\n * furnished to do so, subject to the following conditions:\n *\n * The above copyright notice and this permission notice shall be included in all\n * copies or substantial portions of the Software.\n *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\n/**\n * File System Access API type definitions and utilities for browser compatibility.\n * @packageDocumentation\n */\n\n// Local type definitions for File System Access API\n// Based on https://wicg.github.io/file-system-access/\n\n/**\n * File System Access API methods available on Window\n * @public\n */\nexport interface IFsAccessApis {\n  showDirectoryPicker(options?: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle>;\n  showOpenFilePicker(options?: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle[]>;\n  showSaveFilePicker(options?: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle>;\n}\n\n/**\n * Window interface extended with File System Access API\n * @public\n */\nexport type WindowWithFsAccess = Window & IFsAccessApis;\n\n/**\n * Base interface for file system handles\n * @public\n */\nexport interface FileSystemHandle {\n  readonly kind: 'file' | 'directory';\n  readonly name: string;\n  isSameEntry(other: FileSystemHandle): Promise<boolean>;\n  queryPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;\n  requestPermission(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;\n}\n\n/**\n * File handle interface\n * @public\n */\nexport interface FileSystemFileHandle extends FileSystemHandle {\n  readonly kind: 'file';\n  getFile(): Promise<File>;\n  createWritable(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;\n}\n\n/**\n * Directory handle interface\n * @public\n */\nexport interface FileSystemDirectoryHandle extends FileSystemHandle {\n  readonly kind: 'directory';\n  getDirectoryHandle(\n    name: string,\n    options?: FileSystemGetDirectoryOptions\n  ): Promise<FileSystemDirectoryHandle>;\n  getFileHandle(name: string, options?: FileSystemGetFileOptions): Promise<FileSystemFileHandle>;\n  removeEntry(name: string, options?: FileSystemRemoveOptions): Promise<void>;\n  resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;\n  keys(): AsyncIterableIterator<string>;\n  values(): AsyncIterableIterator<FileSystemHandle>;\n  entries(): AsyncIterableIterator<[string, FileSystemHandle]>;\n  [Symbol.asyncIterator](): AsyncIterableIterator<[string, FileSystemHandle]>;\n}\n\n/**\n * Permission descriptor for file system handles\n * @public\n */\nexport interface FileSystemHandlePermissionDescriptor {\n  mode?: 'read' | 'readwrite';\n}\n\n/**\n * Options for creating writable file streams\n * @public\n */\nexport interface FileSystemCreateWritableOptions {\n  keepExistingData?: boolean;\n}\n\n/**\n * Options for getting directory handles\n * @public\n */\nexport interface FileSystemGetDirectoryOptions {\n  create?: boolean;\n}\n\n/**\n * Options for getting file handles\n * @public\n */\nexport interface FileSystemGetFileOptions {\n  create?: boolean;\n}\n\n/**\n * Options for removing entries\n * @public\n */\nexport interface FileSystemRemoveOptions {\n  recursive?: boolean;\n}\n\n/**\n * Writable file stream interface\n * @public\n */\nexport interface FileSystemWritableFileStream extends WritableStream {\n  write(data: BufferSource | Blob | string): Promise<void>;\n  seek(position: number): Promise<void>;\n  truncate(size: number): Promise<void>;\n}\n\n/**\n * Directory picker options\n * @public\n */\nexport interface ShowDirectoryPickerOptions {\n  id?: string;\n  mode?: 'read' | 'readwrite';\n  startIn?: FileSystemHandle | WellKnownDirectory;\n}\n\n/**\n * File picker options\n * @public\n */\nexport interface ShowOpenFilePickerOptions {\n  multiple?: boolean;\n  excludeAcceptAllOption?: boolean;\n  id?: string;\n  startIn?: FileSystemHandle | WellKnownDirectory;\n  types?: FilePickerAcceptType[];\n}\n\n/**\n * Save file picker options\n * @public\n */\nexport interface ShowSaveFilePickerOptions {\n  excludeAcceptAllOption?: boolean;\n  id?: string;\n  startIn?: FileSystemHandle | WellKnownDirectory;\n  suggestedName?: string;\n  types?: FilePickerAcceptType[];\n}\n\n/**\n * File picker accept type\n * @public\n */\nexport interface FilePickerAcceptType {\n  description?: string;\n  accept: Record<string, string | string[]>;\n}\n\n/**\n * Well-known directory type\n * @public\n */\nexport type WellKnownDirectory = 'desktop' | 'documents' | 'downloads' | 'music' | 'pictures' | 'videos';\n\n/**\n * Type guard to check if the browser supports the File System Access API\n * @param window - The window object to check\n * @returns True if the window supports File System Access API\n * @public\n */\nexport function supportsFileSystemAccess(window: Window): window is WindowWithFsAccess {\n  return 'showOpenFilePicker' in window && 'showSaveFilePicker' in window && 'showDirectoryPicker' in window;\n}\n\n/**\n * Type guard to check if a FileSystemHandle is a file handle\n * @param handle - The handle to check\n * @returns True if the handle is a FileSystemFileHandle\n * @public\n */\nexport function isFileHandle(handle: FileSystemHandle): handle is FileSystemFileHandle {\n  return handle.kind === 'file';\n}\n\n/**\n * Type guard to check if a FileSystemHandle is a directory handle\n * @param handle - The handle to check\n * @returns True if the handle is a FileSystemDirectoryHandle\n * @public\n */\nexport function isDirectoryHandle(handle: FileSystemHandle): handle is FileSystemDirectoryHandle {\n  return handle.kind === 'directory';\n}\n\n/**\n * Safely access showOpenFilePicker with proper type checking\n * @param window - The window object\n * @param options - Options for the file picker\n * @returns Promise with file handles or null if not supported\n * @public\n */\nexport async function safeShowOpenFilePicker(\n  window: Window,\n  options?: ShowOpenFilePickerOptions\n): Promise<FileSystemFileHandle[] | null> {\n  if (supportsFileSystemAccess(window)) {\n    try {\n      return await window.showOpenFilePicker(options);\n    } catch (error) {\n      if (error instanceof DOMException && error.name === 'AbortError') {\n        return null;\n      }\n      throw error;\n    }\n  }\n  return null;\n}\n\n/**\n * Safely access showSaveFilePicker with proper type checking\n * @param window - The window object\n * @param options - Options for the file picker\n * @returns Promise with file handle or null if not supported\n * @public\n */\nexport async function safeShowSaveFilePicker(\n  window: Window,\n  options?: ShowSaveFilePickerOptions\n): Promise<FileSystemFileHandle | null> {\n  if (supportsFileSystemAccess(window)) {\n    try {\n      return await window.showSaveFilePicker(options);\n    } catch (error) {\n      if (error instanceof DOMException && error.name === 'AbortError') {\n        return null;\n      }\n      throw error;\n    }\n  }\n  return null;\n}\n\n/**\n * Safely access showDirectoryPicker with proper type checking\n * @param window - The window object\n * @param options - Options for the directory picker\n * @returns Promise with directory handle or null if not supported\n * @public\n */\nexport async function safeShowDirectoryPicker(\n  window: Window,\n  options?: ShowDirectoryPickerOptions\n): Promise<FileSystemDirectoryHandle | null> {\n  if (supportsFileSystemAccess(window)) {\n    try {\n      return await window.showDirectoryPicker(options);\n    } catch (error) {\n      if (error instanceof DOMException && error.name === 'AbortError') {\n        return null;\n      }\n      throw error;\n    }\n  }\n  return null;\n}\n\n/**\n * Export data as JSON file using legacy blob download method.\n * Creates a temporary download link and triggers file download.\n * @param data - Data to export as JSON\n * @param filename - Name for the downloaded file\n * @public\n */\nexport function exportAsJson(data: unknown, filename: string): void {\n  const json = JSON.stringify(data, null, 2);\n  const blob = new Blob([json], { type: 'application/json' });\n  const url = URL.createObjectURL(blob);\n\n  const a = document.createElement('a');\n  a.href = url;\n  a.download = filename;\n  document.body.appendChild(a);\n  a.click();\n  document.body.removeChild(a);\n  URL.revokeObjectURL(url);\n}\n\n/**\n * Export data using File System Access API with fallback to blob download.\n * @param data - Data to export as JSON\n * @param suggestedName - Suggested filename for the save dialog\n * @param description - Description for file type filter (default: 'JSON files')\n * @param window - Window object for API access (default: globalThis.window)\n * @returns Promise resolving to true if saved via File System Access API, false if fallback used\n * @public\n */\nexport async function exportUsingFileSystemAPI(\n  data: unknown,\n  suggestedName: string,\n  description: string = 'JSON files',\n  window: Window = globalThis.window\n): Promise<boolean> {\n  if (!supportsFileSystemAccess(window)) {\n    // Fallback to blob download\n    exportAsJson(data, suggestedName);\n    return false;\n  }\n\n  try {\n    const fileHandle = await safeShowSaveFilePicker(window, {\n      suggestedName,\n      types: [\n        {\n          description,\n          accept: {\n            'application/json': ['.json']\n          }\n        }\n      ]\n    });\n\n    if (!fileHandle) {\n      // User cancelled - fallback to blob download\n      exportAsJson(data, suggestedName);\n      return false;\n    }\n\n    const json = JSON.stringify(data, null, 2);\n    const writable = await fileHandle.createWritable();\n    await writable.write(json);\n    await writable.close();\n\n    return true;\n  } catch (error) {\n    // Handle errors by falling back to blob download\n    if ((error as Error).name === 'AbortError') {\n      // User cancelled - fallback\n      exportAsJson(data, suggestedName);\n      return false;\n    }\n    // Other errors - re-throw as they indicate a real problem\n    throw error;\n  }\n}\n"]}

package/dist/packlets/file-tree/directoryHandleStore.js

@@ -0,0 +1,124 @@
+// 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.
+/**
+ * Persistent storage for FileSystemDirectoryHandle objects using IndexedDB.
+ * Allows directory handles to survive page reloads without re-prompting the user.
+ * @packageDocumentation
+ */
+import { fail, succeed } from '@fgv/ts-utils';
+import { createStore, del, get, keys, set } from 'idb-keyval';
+/**
+ * Default IndexedDB database name for directory handles.
+ * @public
+ */
+export const DEFAULT_DIRECTORY_HANDLE_DB = 'chocolate-lab-storage';
+/**
+ * Default IndexedDB store name for directory handles.
+ * @public
+ */
+export const DEFAULT_DIRECTORY_HANDLE_STORE = 'directory-handles';
+/**
+ * Manages persistence of {@link FileSystemDirectoryHandle} objects in IndexedDB.
+ * Keyed by a label (typically the directory name).
+ * @public
+ */
+export class DirectoryHandleStore {
+    constructor(dbName = DEFAULT_DIRECTORY_HANDLE_DB, storeName = DEFAULT_DIRECTORY_HANDLE_STORE) {
+        this._store = createStore(dbName, storeName);
+    }
+    /**
+     * Saves a directory handle to IndexedDB under the given label.
+     * @param label - Key to store the handle under (typically dirHandle.name)
+     * @param handle - The FileSystemDirectoryHandle to persist
+     * @returns Success or Failure
+     */
+    async save(label, handle) {
+        try {
+            await set(label, handle, this._store);
+            return succeed(undefined);
+        }
+        catch (e) {
+            return fail(`DirectoryHandleStore.save "${label}": ${String(e)}`);
+        }
+    }
+    /**
+     * Retrieves a directory handle by label.
+     * @param label - Key to look up
+     * @returns Success with handle (or undefined if not found), or Failure on error
+     */
+    async load(label) {
+        try {
+            const handle = await get(label, this._store);
+            return succeed(handle);
+        }
+        catch (e) {
+            return fail(`DirectoryHandleStore.load "${label}": ${String(e)}`);
+        }
+    }
+    /**
+     * Removes a directory handle from IndexedDB.
+     * @param label - Key to remove
+     * @returns Success or Failure
+     */
+    async remove(label) {
+        try {
+            await del(label, this._store);
+            return succeed(undefined);
+        }
+        catch (e) {
+            return fail(`DirectoryHandleStore.remove "${label}": ${String(e)}`);
+        }
+    }
+    /**
+     * Returns all stored labels (keys).
+     * @returns Success with array of labels, or Failure
+     */
+    async getAllLabels() {
+        try {
+            const allKeys = await keys(this._store);
+            return succeed(allKeys);
+        }
+        catch (e) {
+            return fail(`DirectoryHandleStore.getAllLabels: ${String(e)}`);
+        }
+    }
+    /**
+     * Returns all stored handles as label/handle pairs.
+     * @returns Success with array of entries, or Failure
+     */
+    async getAll() {
+        const labelsResult = await this.getAllLabels();
+        if (labelsResult.isFailure()) {
+            return fail(labelsResult.message);
+        }
+        const entries = [];
+        for (const label of labelsResult.value) {
+            const handleResult = await this.load(label);
+            if (handleResult.isFailure()) {
+                return fail(handleResult.message);
+            }
+            if (handleResult.value !== undefined) {
+                entries.push({ label, handle: handleResult.value });
+            }
+        }
+        return succeed(entries);
+    }
+}
+//# sourceMappingURL=directoryHandleStore.js.map

package/dist/packlets/file-tree/directoryHandleStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directoryHandleStore.js","sourceRoot":"","sources":["../../../src/packlets/file-tree/directoryHandleStore.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Persistent storage for FileSystemDirectoryHandle objects using IndexedDB.\n * Allows directory handles to survive page reloads without re-prompting the user.\n * @packageDocumentation\n */\n\nimport { fail, Result, succeed } from '@fgv/ts-utils';\nimport { createStore, del, get, keys, set } from 'idb-keyval';\nimport { FileSystemDirectoryHandle } from '../file-api-types';\n\n/**\n * Default IndexedDB database name for directory handles.\n * @public\n */\nexport const DEFAULT_DIRECTORY_HANDLE_DB = 'chocolate-lab-storage';\n\n/**\n * Default IndexedDB store name for directory handles.\n * @public\n */\nexport const DEFAULT_DIRECTORY_HANDLE_STORE = 'directory-handles';\n\n/**\n * Manages persistence of {@link FileSystemDirectoryHandle} objects in IndexedDB.\n * Keyed by a label (typically the directory name).\n * @public\n */\nexport class DirectoryHandleStore {\n  private readonly _store: ReturnType<typeof createStore>;\n\n  public constructor(\n    dbName: string = DEFAULT_DIRECTORY_HANDLE_DB,\n    storeName: string = DEFAULT_DIRECTORY_HANDLE_STORE\n  ) {\n    this._store = createStore(dbName, storeName);\n  }\n\n  /**\n   * Saves a directory handle to IndexedDB under the given label.\n   * @param label - Key to store the handle under (typically dirHandle.name)\n   * @param handle - The FileSystemDirectoryHandle to persist\n   * @returns Success or Failure\n   */\n  public async save(label: string, handle: FileSystemDirectoryHandle): Promise<Result<void>> {\n    try {\n      await set(label, handle, this._store);\n      return succeed(undefined);\n    } catch (e) {\n      return fail(`DirectoryHandleStore.save \"${label}\": ${String(e)}`);\n    }\n  }\n\n  /**\n   * Retrieves a directory handle by label.\n   * @param label - Key to look up\n   * @returns Success with handle (or undefined if not found), or Failure on error\n   */\n  public async load(label: string): Promise<Result<FileSystemDirectoryHandle | undefined>> {\n    try {\n      const handle = await get<FileSystemDirectoryHandle>(label, this._store);\n      return succeed(handle);\n    } catch (e) {\n      return fail(`DirectoryHandleStore.load \"${label}\": ${String(e)}`);\n    }\n  }\n\n  /**\n   * Removes a directory handle from IndexedDB.\n   * @param label - Key to remove\n   * @returns Success or Failure\n   */\n  public async remove(label: string): Promise<Result<void>> {\n    try {\n      await del(label, this._store);\n      return succeed(undefined);\n    } catch (e) {\n      return fail(`DirectoryHandleStore.remove \"${label}\": ${String(e)}`);\n    }\n  }\n\n  /**\n   * Returns all stored labels (keys).\n   * @returns Success with array of labels, or Failure\n   */\n  public async getAllLabels(): Promise<Result<string[]>> {\n    try {\n      const allKeys = await keys<string>(this._store);\n      return succeed(allKeys);\n    } catch (e) {\n      return fail(`DirectoryHandleStore.getAllLabels: ${String(e)}`);\n    }\n  }\n\n  /**\n   * Returns all stored handles as label/handle pairs.\n   * @returns Success with array of entries, or Failure\n   */\n  public async getAll(): Promise<Result<Array<{ label: string; handle: FileSystemDirectoryHandle }>>> {\n    const labelsResult = await this.getAllLabels();\n    if (labelsResult.isFailure()) {\n      return fail(labelsResult.message);\n    }\n\n    const entries: Array<{ label: string; handle: FileSystemDirectoryHandle }> = [];\n    for (const label of labelsResult.value) {\n      const handleResult = await this.load(label);\n      if (handleResult.isFailure()) {\n        return fail(handleResult.message);\n      }\n      if (handleResult.value !== undefined) {\n        entries.push({ label, handle: handleResult.value });\n      }\n    }\n    return succeed(entries);\n  }\n}\n"]}