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

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "@fgv/ts-web-extras",
-  "version": "5.0.2",
+  "version": "5.1.0-1",
   "description": "Browser-compatible utilities and FileTree implementations",
   "main": "lib/index.js",
   "types": "dist/ts-web-extras.d.ts",
+  "scripts": {
+    "build": "heft test --clean",
+    "clean": "heft clean",
+    "test": "heft test --clean",
+    "build-docs": "typedoc --options ./config/typedoc.json",
+    "build-all": "rushx build; rushx build-docs",
+    "test-handles": "jest --runInBand --detectOpenHandles",
+    "clean-jest": "jest --clear-cache",
+    "coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "fixlint": "eslint src --ext .ts --fix"
+  },
   "sideEffects": false,
   "keywords": [
     "browser",
@@ -19,41 +31,45 @@
   },
   "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-web-extras#readme",
   "devDependencies": {
-    "@microsoft/api-documenter": "^7.27.3",
-    "@microsoft/api-extractor": "^7.53.3",
+    "@fgv/heft-dual-rig": "workspace:*",
+    "@fgv/ts-extras": "workspace:*",
+    "@fgv/ts-utils": "workspace:*",
+    "@fgv/ts-json-base": "workspace:*",
+    "@fgv/ts-utils-jest": "workspace:*",
+    "@microsoft/api-documenter": "^7.28.2",
+    "@microsoft/api-extractor": "^7.55.2",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.14.9",
-    "@typescript-eslint/eslint-plugin": "^8.46.2",
-    "@typescript-eslint/parser": "^8.46.2",
-    "eslint": "^9.39.0",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^7.2.1",
     "jest": "^29.7.0",
     "jest-extended": "^4.0.2",
-    "rimraf": "^6.1.0",
-    "ts-jest": "^29.4.5",
+    "rimraf": "^6.1.2",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "typescript": "5.9.3",
     "eslint-plugin-n": "^17.23.1",
-    "@rushstack/eslint-config": "4.5.3",
-    "@rushstack/heft": "1.1.3",
-    "@rushstack/heft-jest-plugin": "1.1.3",
-    "@rushstack/heft-node-rig": "2.11.4",
+    "@rushstack/eslint-config": "4.6.4",
+    "@rushstack/heft": "1.2.6",
+    "@rushstack/heft-jest-plugin": "1.2.6",
+    "@rushstack/heft-node-rig": "2.11.26",
     "@types/heft-jest": "1.0.6",
-    "eslint-plugin-tsdoc": "~0.4.0",
+    "eslint-plugin-tsdoc": "~0.5.2",
     "@rushstack/eslint-patch": "1.14.1",
-    "@types/react": "~19.2.2",
-    "@fgv/heft-dual-rig": "0.1.0",
-    "@fgv/ts-utils": "5.0.2",
-    "@fgv/ts-json-base": "5.0.2",
-    "@fgv/ts-utils-jest": "5.0.2"
+    "@types/react": "~19.2.8",
+    "typedoc": "~0.28.16",
+    "typedoc-plugin-markdown": "~4.9.0"
   },
   "peerDependencies": {
+    "@fgv/ts-extras": "workspace:*",
+    "@fgv/ts-utils": "workspace:*",
+    "@fgv/ts-json-base": "workspace:*",
     "react": ">=18 <20",
-    "react-dom": ">=18 <20",
-    "@fgv/ts-json-base": "5.0.2",
-    "@fgv/ts-utils": "5.0.2"
+    "react-dom": ">=18 <20"
   },
   "exports": {
     ".": {
@@ -70,18 +86,9 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ErikFortune/fgv.git"
+    "url": "git+https://github.com/ErikFortune/fgv.git"
   },
-  "scripts": {
-    "build": "heft test --clean",
-    "clean": "heft clean",
-    "test": "heft test --clean",
-    "build-docs": "api-documenter markdown --input-folder ./temp --output-folder docs",
-    "build-all": "rushx build; rushx build-docs",
-    "test-handles": "jest --runInBand --detectOpenHandles",
-    "clean-jest": "jest --clear-cache",
-    "coverage": "jest --coverage",
-    "lint": "eslint src --ext .ts",
-    "fixlint": "eslint src --ext .ts --fix"
+  "dependencies": {
+    "idb-keyval": "^6.2.2"
   }
-}
+}

package/rush-logs/ts-web-extras.build.cache.log

@@ -1 +0,0 @@
-Project does not have a rush-project.json configuration file, or one provided by a rig, so it does not support caching.

package/rush-logs/ts-web-extras.build.error.log

@@ -0,0 +1,18 @@
+(node:72593) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72591) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72598) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72594) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72597) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72590) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72596) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72592) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72595) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)

package/rush-logs/ts-web-extras.build.log

@@ -1,42 +1,75 @@
 Invoking: heft test --clean 
  ---- build started ---- 
+[build:clean] Deleted 0 files and 3 folders
 [build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
 [build:typescript] Using TypeScript version 5.9.3
-[build:api-extractor] Using API Extractor version 7.54.0
+[build:api-extractor] Using API Extractor version 7.57.6
 [build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
 [build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
- ---- build finished (22.824s) ---- 
+ ---- build finished (3.991s) ---- 
  ---- test started ---- 
+[test:clean] Deleted 0 files and 1 folder
 [test:jest] Using Jest version 29.5.0
 [test:jest] 
-[test:jest] Run start. 5 test suites
+[test:jest] Run start. 9 test suites
 [test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
+[test:jest] START lib/test/unit/httpTreeAccessors.test.js
+[test:jest] START lib/test/unit/localStorageTreeAccessors.test.js
+[test:jest] START lib/test/unit/fileSystemAccessTreeAccessors.test.js
 [test:jest] START lib/test/unit/fileTreeHelpers.test.js
 [test:jest] START lib/test/unit/fileApiTypes.test.js
 [test:jest] START lib/test/unit/urlParams.test.js
-[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 2.655s, 35 passed, 0 failed)
+[test:jest] START lib/test/unit/directoryHandleStore.test.js
 [test:jest] START lib/test/unit/browserHashProvider.test.js
-[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 2.813s, 33 passed, 0 failed)
-[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 2.987s, 63 passed, 0 failed)
-[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 1.119s, 60 passed, 0 failed)
-[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 1.312s, 15 passed, 0 failed)
+(node:72593) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72591) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72598) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/httpTreeAccessors.test.js (duration: 0.858s, 52 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 0.900s, 44 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 0.969s, 15 passed, 0 failed)
+(node:72594) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 0.968s, 35 passed, 0 failed)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 0.948s, 19 passed, 0 failed)
+(node:72597) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72590) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72596) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:72592) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 0.916s, 60 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 0.987s, 65 passed, 0 failed)
+[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 0.974s, 44 passed, 0 failed)
+(node:72595) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 0.933s, 36 passed, 0 failed)
 [test:jest] 
 [test:jest] Tests finished:
-[test:jest]   Successes: 206
+[test:jest]   Successes: 370
 [test:jest]   Failures: 0
-[test:jest]   Total: 207
---------------------------|---------|----------|---------|---------|-------------------
-File                      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
---------------------------|---------|----------|---------|---------|-------------------
-All files                 |     100 |      100 |     100 |     100 |                   
- crypto                   |     100 |      100 |     100 |     100 |                   
-  browserHashProvider.ts  |     100 |      100 |     100 |     100 |                   
- file-tree                |     100 |      100 |     100 |     100 |                   
-  fileApiTreeAccessors.ts |     100 |      100 |     100 |     100 |                   
- helpers                  |     100 |      100 |     100 |     100 |                   
-  fileTreeHelpers.ts      |     100 |      100 |     100 |     100 |                   
- url-utils                |     100 |      100 |     100 |     100 |                   
-  urlParams.ts            |     100 |      100 |     100 |     100 |                   
---------------------------|---------|----------|---------|---------|-------------------
- ---- test finished (7.278s) ---- 
--------------------- Finished (30.108s) --------------------
+[test:jest]   Total: 371
+-----------------------------------|---------|----------|---------|---------|-------------------
+File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
+-----------------------------------|---------|----------|---------|---------|-------------------
+All files                          |     100 |      100 |     100 |     100 |                   
+ crypto-utils                      |     100 |      100 |     100 |     100 |                   
+  browserCryptoProvider.ts         |     100 |      100 |     100 |     100 |                   
+  browserHashProvider.ts           |     100 |      100 |     100 |     100 |                   
+ file-tree                         |     100 |      100 |     100 |     100 |                   
+  directoryHandleStore.ts          |     100 |      100 |     100 |     100 |                   
+  fileApiTreeAccessors.ts          |     100 |      100 |     100 |     100 |                   
+  fileSystemAccessTreeAccessors.ts |     100 |      100 |     100 |     100 |                   
+  httpTreeAccessors.ts             |     100 |      100 |     100 |     100 |                   
+  localStorageTreeAccessors.ts     |     100 |      100 |     100 |     100 |                   
+ helpers                           |     100 |      100 |     100 |     100 |                   
+  fileTreeHelpers.ts               |     100 |      100 |     100 |     100 |                   
+ url-utils                         |     100 |      100 |     100 |     100 |                   
+  urlParams.ts                     |     100 |      100 |     100 |     100 |                   
+-----------------------------------|---------|----------|---------|---------|-------------------
+ ---- test finished (2.336s) ---- 
+-------------------- Finished (6.331s) --------------------

package/rush-logs/ts-web-extras.test.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "test" command, so caching has been disabled.

package/rush-logs/ts-web-extras.test.error.log

@@ -0,0 +1,16 @@
+(node:35708) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35707) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35710) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35711) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35705) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35709) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35712) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35706) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)

package/rush-logs/ts-web-extras.test.log

@@ -0,0 +1,70 @@
+Invoking: heft test --clean 
+ ---- build started ---- 
+[build:clean] Deleted 0 files and 3 folders
+[build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
+[build:typescript] Using TypeScript version 5.9.3
+[build:api-extractor] Using API Extractor version 7.55.2
+[build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
+[build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
+ ---- build finished (2.899s) ---- 
+ ---- test started ---- 
+[test:clean] Deleted 0 files and 1 folder
+[test:jest] Using Jest version 29.5.0
+[test:jest] 
+[test:jest] Run start. 8 test suites
+[test:jest] START lib/test/unit/fileApiTreeAccessors.test.js
+[test:jest] START lib/test/unit/fileTreeHelpers.test.js
+[test:jest] START lib/test/unit/fileSystemAccessTreeAccessors.test.js
+[test:jest] START lib/test/unit/localStorageTreeAccessors.test.js
+[test:jest] START lib/test/unit/fileApiTypes.test.js
+[test:jest] START lib/test/unit/urlParams.test.js
+[test:jest] START lib/test/unit/directoryHandleStore.test.js
+[test:jest] START lib/test/unit/browserHashProvider.test.js
+(node:35708) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/localStorageTreeAccessors.test.js (duration: 0.633s, 33 passed, 0 failed)
+(node:35707) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35710) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35711) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/directoryHandleStore.test.js (duration: 0.656s, 19 passed, 0 failed)
+[test:jest] PASS lib/test/unit/urlParams.test.js (duration: 0.661s, 60 passed, 0 failed)
+(node:35705) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileApiTreeAccessors.test.js (duration: 0.660s, 63 passed, 0 failed)
+(node:35709) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileApiTypes.test.js (duration: 0.676s, 36 passed, 0 failed)
+(node:35712) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+(node:35706) [DEP0040] DeprecationWarning: The `punycode` module is deprecated. Please use a userland alternative instead.
+(Use `node --trace-deprecation ...` to show where the warning was created)
+[test:jest] PASS lib/test/unit/fileTreeHelpers.test.js (duration: 0.713s, 35 passed, 0 failed)
+[test:jest] PASS lib/test/unit/fileSystemAccessTreeAccessors.test.js (duration: 0.719s, 38 passed, 0 failed)
+[test:jest] PASS lib/test/unit/browserHashProvider.test.js (duration: 0.723s, 15 passed, 0 failed)
+[test:jest] 
+[test:jest] Tests finished:
+[test:jest]   Successes: 299
+[test:jest]   Failures: 0
+[test:jest]   Total: 300
+-----------------------------------|---------|----------|---------|---------|------------------------------------
+File                               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s                  
+-----------------------------------|---------|----------|---------|---------|------------------------------------
+All files                          |     100 |    95.68 |     100 |     100 |                                    
+ crypto-utils                      |     100 |      100 |     100 |     100 |                                    
+  browserCryptoProvider.ts         |     100 |      100 |     100 |     100 |                                    
+  browserHashProvider.ts           |     100 |      100 |     100 |     100 |                                    
+ file-tree                         |     100 |     94.9 |     100 |     100 |                                    
+  directoryHandleStore.ts          |     100 |      100 |     100 |     100 |                                    
+  fileApiTreeAccessors.ts          |     100 |      100 |     100 |     100 |                                    
+  fileSystemAccessTreeAccessors.ts |     100 |    93.06 |     100 |     100 | 90,152,160,169,176                 
+  localStorageTreeAccessors.ts     |     100 |     88.6 |     100 |     100 | 92,107,163-164,196-197,210,245-249 
+ helpers                           |     100 |      100 |     100 |     100 |                                    
+  fileTreeHelpers.ts               |     100 |      100 |     100 |     100 |                                    
+ url-utils                         |     100 |      100 |     100 |     100 |                                    
+  urlParams.ts                     |     100 |      100 |     100 |     100 |                                    
+-----------------------------------|---------|----------|---------|---------|------------------------------------
+ ---- test finished (1.675s) ---- 
+-------------------- Finished (4.577s) --------------------

package/src/index.ts

@@ -31,8 +31,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';

package/src/packlets/crypto-utils/browserCryptoProvider.ts

@@ -0,0 +1,311 @@
+// 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, Result, Success } from '@fgv/ts-utils';
+import { CryptoUtils } from '@fgv/ts-extras';
+
+type ICryptoProvider = CryptoUtils.ICryptoProvider;
+type IEncryptionResult = CryptoUtils.IEncryptionResult;
+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: Uint8Array): ArrayBuffer {
+  // 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 implements ICryptoProvider {
+  private readonly _crypto: Crypto;
+
+  /**
+   * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
+   * @param cryptoApi - Optional Crypto instance (defaults to globalThis.crypto)
+   */
+  public constructor(cryptoApi?: Crypto) {
+    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.
+   */
+  public async encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>> {
+    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.
+   */
+  public async decrypt(
+    encryptedData: Uint8Array,
+    key: Uint8Array,
+    iv: Uint8Array,
+    authTag: Uint8Array
+  ): Promise<Result<string>> {
+    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
+   */
+  public async generateKey(): Promise<Result<Uint8Array>> {
+    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
+   */
+  public async deriveKey(
+    password: string,
+    salt: Uint8Array,
+    iterations: number
+  ): Promise<Result<Uint8Array>> {
+    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
+   */
+  public generateRandomBytes(length: number): Result<Uint8Array> {
+    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
+   */
+  public toBase64(data: Uint8Array): string {
+    // 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
+   */
+  public fromBase64(base64: string): Result<Uint8Array> {
+    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(): Result<BrowserCryptoProvider> {
+  return captureResult(() => new BrowserCryptoProvider());
+}
+/* c8 ignore stop */

package/src/packlets/{crypto → crypto-utils}/index.ts

@@ -26,3 +26,4 @@
  */
 
 export * from './browserHashProvider';
+export * from './browserCryptoProvider';