wgblas 2.0.0 → 2.2.0

package/index.d.mts

@@ -3,23 +3,34 @@
  */
 export { GpuVector } from "./src/classes/GpuVector.mjs";
 export { GpuMatrix } from "./src/classes/GpuMatrix.mjs";
+export { Complex32, Complex32Array } from "./src/classes/Complex32.mjs";
+export { Complex64, Complex64Array } from "./src/classes/Complex64.mjs";
 export {
   randomFloat32Array,
   randomFloat64Array,
   randomTriangularFloat32Array,
 } from "./src/random/random.mjs";
 export { sscal } from "./src/sscal/sscal.mjs";
+export { cscal } from "./src/cscal/cscal.mjs";
+export { dscal } from "./src/dscal/dscal.mjs";
 export { sswap } from "./src/sswap/sswap.mjs";
+export { dswap } from "./src/dswap/dswap.mjs";
 export { saxpy } from "./src/saxpy/saxpy.mjs";
+export { daxpy } from "./src/daxpy/daxpy.mjs";
 export { scopy } from "./src/scopy/scopy.mjs";
+export { dcopy } from "./src/dcopy/dcopy.mjs";
 export { sdot } from "./src/sdot/sdot.mjs";
 export { sasum } from "./src/sasum/sasum.mjs";
 export { dasum } from "./src/dasum/dasum.mjs";
+export { ddot } from "./src/ddot/ddot.mjs";
 export { snrm2 } from "./src/snrm2/snrm2.mjs";
+export { dnrm2 } from "./src/dnrm2/dnrm2.mjs";
 export { isamax } from "./src/isamax/isamax.mjs";
 export { idamax } from "./src/idamax/idamax.mjs";
 export { srot } from "./src/srot/srot.mjs";
+export { drot } from "./src/drot/drot.mjs";
 export { srotm } from "./src/srotm/srotm.mjs";
+export { drotm } from "./src/drotm/drotm.mjs";
 export { sgemv } from "./src/sgemv/sgemv.mjs";
 export { ssymv } from "./src/ssymv/ssymv.mjs";
 export { strmv } from "./src/strmv/strmv.mjs";
@@ -38,43 +49,37 @@ export { strsm } from "./src/strsm/strsm.mjs";
 /**
  * Initializes the WebGPU device.
  *
+ * Devices are cached per option set: the same options return the same device,
+ * different options a separate one — so one process can drive several GPUs
+ * (`"high-performance"` and `"low-power"` typically resolve to the discrete and
+ * integrated adapters). Each routine dispatches to the device you pass it; GPU
+ * buffers cannot cross devices, so a `GpuVector`/`GpuMatrix` from one is
+ * rejected by another. {@link cleanup} releases them all.
+ *
  * @param options.powerPreference - GPU power preference (default: `"high-performance"`).
  *   This is a hint to the browser: on dual-GPU systems, `"high-performance"` typically favors the discrete GPU
  *   and `"low-power"` favors the integrated one.
  *   See [MDN: GPU.requestAdapter()](https://developer.mozilla.org/en-US/docs/Web/API/GPU/requestAdapter).
- * @param options.benchmark - enable GPU timestamp queries; BLAS functions return `{ result, gpuTimeMs }` (default: `false`)
+ * @param options.benchmark - enable GPU timestamp queries; BLAS functions then also return `gpuTimeMs`
+ *   alongside their normal result (e.g. sscal returns `{ x, gpuTimeMs }`, saxpy returns `{ y, gpuTimeMs }`) —
+ *   see each routine's own docs for its exact return shape (default: `false`)
  * @param options.dumpShaders - Node-only. Forwards Dawn's `dump_shaders` debug toggle, printing
  *   each pipeline's WGSL and compiled backend IR (SPIR-V/Vulkan, MSL/Metal, or HLSL/D3D12,
  *   whichever Dawn picked) to stderr as it compiles. A Dawn passthrough, not a wgblas format —
  *   no effect in the browser, which gives pages no API to request compiled shader IR (default: `false`)
  *
- * @example Default (high-performance GPU)
- * ```js
- * import { init, gpuName } from "wgblas";
- * await init();
- * const { description, device } = gpuName();
- * console.log("description:", description, "device:", device);
- * ```
+ * **Default (high-performance GPU):**
+ * {@includeCode examples/init/init.js}
+ *
+ * **Low-power (integrated GPU):**
+ * {@includeCode examples/init-low-power/init-low-power.js}
+ *
+ * **Benchmark mode:**
+ * {@includeCode examples/init-benchmark/init-benchmark.js}
  *
- * @example Low-power (integrated GPU)
- * ```js
- * import { init, gpuName } from "wgblas";
- * await init({ powerPreference: "low-power" });
- * const { description, device } = gpuName();
- * console.log("description:", description, "device:", device);
- * ```
+ * **Two GPUs at once:**
+ * {@includeCode examples/init-two-gpus/init-two-gpus.js}
  *
- * @example Benchmark mode
- * ```js
- * import { init, sscal } from "wgblas";
- * const device = await init({ benchmark: true });
- * const n = 5;
- * const alpha = 2.0;
- * const x = new Float32Array([1, 2, 3, 4, 5]);
- * const { result, gpuTimeMs } = await sscal(device, n, alpha, x, 1);
- * console.log(`Result: [${Array.from(result).join(", ")}]`);
- * console.log(`GPU time: ${gpuTimeMs.toFixed(3)} ms`);
- * ```
  * @see [Source code: init.mjs](https://github.com/manit2004/wgblas/blob/main/src/init.mjs#L18-L54)
  * @category Core
  */
@@ -85,33 +90,33 @@ export declare function init(options?: {
 }): Promise<GPUDevice>;
 
 /**
- * Destroys the WebGPU device, releases the adapter, resets benchmark state, and fires all internal
- * cleanup callbacks (e.g. releasing cached GPU pipelines and buffers). Call when done (required in Node.js to prevent crash on exit).
+ * Destroys devices created by {@link init} and releases their cached pipelines and buffers.
+ * Call when done (required in Node.js to prevent crash on exit).
  *
- * @example
- * ```js
- * import { init, cleanup, gpuName } from "wgblas";
+ * With no argument, releases every device at once. Pass a device to release
+ * just that one and leave the others usable — handy when driving several GPUs.
+ * Unknown or already-released devices are ignored, so this is safe to call
+ * more than once.
  *
- * await init();
- * console.log("GPU:", gpuName().description);
- * if (typeof process !== "undefined") cleanup(); // Node.js only — browser cleanup is automatic
- * ```
+ * @param device - the device to release; omit to release all of them.
+ *
+ * {@includeCode examples/cleanup/cleanup.js}
  * @see [Source code: init.mjs](https://github.com/manit2004/wgblas/blob/main/src/init.mjs#L56-L65)
  * @category Core
  */
-export declare function cleanup(): void;
+export declare function cleanup(device?: GPUDevice): void;
 
 /**
  * Returns the GPU device name from the WebGPU adapter info. Must be called after `init()`.
  *
- * @example
- * ```js
- * import { init, gpuName } from "wgblas";
- * await init();
- * const { description, device } = gpuName();
- * console.log("description:", description, "device:", device);
- * ```
+ * @param device - which device to report on; defaults to the one from the first
+ *   `init()` call. Pass it explicitly when driving more than one GPU.
+ *
+ * {@includeCode examples/init/init.js}
  * @see [Source code: init.mjs](https://github.com/manit2004/wgblas/blob/main/src/init.mjs#L81-L87)
  * @category Core
  */
-export declare function gpuName(): { description: string; device: string };
+export declare function gpuName(device?: GPUDevice): {
+  description: string;
+  device: string;
+};

package/index.mjs

@@ -1,23 +1,34 @@
 export { init, cleanup, gpuName } from "./src/init.mjs";
 export { GpuVector } from "./src/classes/GpuVector.mjs";
 export { GpuMatrix } from "./src/classes/GpuMatrix.mjs";
+export { Complex32, Complex32Array } from "./src/classes/Complex32.mjs";
+export { Complex64, Complex64Array } from "./src/classes/Complex64.mjs";
 export {
   randomFloat32Array,
   randomFloat64Array,
   randomTriangularFloat32Array,
 } from "./src/random/random.mjs";
 export { sscal } from "./src/sscal/sscal.mjs";
+export { cscal } from "./src/cscal/cscal.mjs";
+export { dscal } from "./src/dscal/dscal.mjs";
 export { sswap } from "./src/sswap/sswap.mjs";
+export { dswap } from "./src/dswap/dswap.mjs";
 export { saxpy } from "./src/saxpy/saxpy.mjs";
+export { daxpy } from "./src/daxpy/daxpy.mjs";
 export { scopy } from "./src/scopy/scopy.mjs";
+export { dcopy } from "./src/dcopy/dcopy.mjs";
 export { sdot } from "./src/sdot/sdot.mjs";
 export { sasum } from "./src/sasum/sasum.mjs";
 export { dasum } from "./src/dasum/dasum.mjs";
+export { ddot } from "./src/ddot/ddot.mjs";
 export { snrm2 } from "./src/snrm2/snrm2.mjs";
+export { dnrm2 } from "./src/dnrm2/dnrm2.mjs";
 export { isamax } from "./src/isamax/isamax.mjs";
 export { idamax } from "./src/idamax/idamax.mjs";
 export { srot } from "./src/srot/srot.mjs";
+export { drot } from "./src/drot/drot.mjs";
 export { srotm } from "./src/srotm/srotm.mjs";
+export { drotm } from "./src/drotm/drotm.mjs";
 export { sgemv } from "./src/sgemv/sgemv.mjs";
 export { ssymv } from "./src/ssymv/ssymv.mjs";
 export { strmv } from "./src/strmv/strmv.mjs";

package/package.json

@@ -1,131 +1,175 @@
 {
   "name": "wgblas",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "BLAS on WebGPU",
   "type": "module",
   "main": "index.mjs",
   "types": "./index.d.mts",
   "exports": {
     ".": {
-      "import": "./index.mjs",
-      "types": "./index.d.mts"
+      "types": "./index.d.mts",
+      "import": "./index.mjs"
     },
     "./browser": "./dist/wgblas.browser.js",
     "./classes/GpuVector": {
-      "import": "./src/classes/GpuVector.mjs",
-      "types": "./src/classes/GpuVector.d.mts"
+      "types": "./src/classes/GpuVector.d.mts",
+      "import": "./src/classes/GpuVector.mjs"
     },
     "./classes/GpuMatrix": {
-      "import": "./src/classes/GpuMatrix.mjs",
-      "types": "./src/classes/GpuMatrix.d.mts"
+      "types": "./src/classes/GpuMatrix.d.mts",
+      "import": "./src/classes/GpuMatrix.mjs"
+    },
+    "./classes/Complex32": {
+      "types": "./src/classes/Complex32.d.mts",
+      "import": "./src/classes/Complex32.mjs"
+    },
+    "./classes/Complex64": {
+      "types": "./src/classes/Complex64.d.mts",
+      "import": "./src/classes/Complex64.mjs"
     },
     "./random": {
-      "import": "./src/random/random.mjs",
-      "types": "./src/random/random.d.mts"
+      "types": "./src/random/random.d.mts",
+      "import": "./src/random/random.mjs"
     },
     "./sscal": {
-      "import": "./src/sscal/sscal.mjs",
-      "types": "./src/sscal/sscal.d.mts"
+      "types": "./src/sscal/sscal.d.mts",
+      "import": "./src/sscal/sscal.mjs"
+    },
+    "./cscal": {
+      "types": "./src/cscal/cscal.d.mts",
+      "import": "./src/cscal/cscal.mjs"
+    },
+    "./dscal": {
+      "types": "./src/dscal/dscal.d.mts",
+      "import": "./src/dscal/dscal.mjs"
     },
     "./sswap": {
-      "import": "./src/sswap/sswap.mjs",
-      "types": "./src/sswap/sswap.d.mts"
+      "types": "./src/sswap/sswap.d.mts",
+      "import": "./src/sswap/sswap.mjs"
+    },
+    "./dswap": {
+      "types": "./src/dswap/dswap.d.mts",
+      "import": "./src/dswap/dswap.mjs"
     },
     "./saxpy": {
-      "import": "./src/saxpy/saxpy.mjs",
-      "types": "./src/saxpy/saxpy.d.mts"
+      "types": "./src/saxpy/saxpy.d.mts",
+      "import": "./src/saxpy/saxpy.mjs"
+    },
+    "./daxpy": {
+      "types": "./src/daxpy/daxpy.d.mts",
+      "import": "./src/daxpy/daxpy.mjs"
     },
     "./scopy": {
-      "import": "./src/scopy/scopy.mjs",
-      "types": "./src/scopy/scopy.d.mts"
+      "types": "./src/scopy/scopy.d.mts",
+      "import": "./src/scopy/scopy.mjs"
+    },
+    "./dcopy": {
+      "types": "./src/dcopy/dcopy.d.mts",
+      "import": "./src/dcopy/dcopy.mjs"
     },
     "./sdot": {
-      "import": "./src/sdot/sdot.mjs",
-      "types": "./src/sdot/sdot.d.mts"
+      "types": "./src/sdot/sdot.d.mts",
+      "import": "./src/sdot/sdot.mjs"
     },
     "./sasum": {
-      "import": "./src/sasum/sasum.mjs",
-      "types": "./src/sasum/sasum.d.mts"
+      "types": "./src/sasum/sasum.d.mts",
+      "import": "./src/sasum/sasum.mjs"
     },
     "./dasum": {
-      "import": "./src/dasum/dasum.mjs",
-      "types": "./src/dasum/dasum.d.mts"
+      "types": "./src/dasum/dasum.d.mts",
+      "import": "./src/dasum/dasum.mjs"
+    },
+    "./ddot": {
+      "types": "./src/ddot/ddot.d.mts",
+      "import": "./src/ddot/ddot.mjs"
     },
     "./snrm2": {
-      "import": "./src/snrm2/snrm2.mjs",
-      "types": "./src/snrm2/snrm2.d.mts"
+      "types": "./src/snrm2/snrm2.d.mts",
+      "import": "./src/snrm2/snrm2.mjs"
+    },
+    "./dnrm2": {
+      "types": "./src/dnrm2/dnrm2.d.mts",
+      "import": "./src/dnrm2/dnrm2.mjs"
     },
     "./isamax": {
-      "import": "./src/isamax/isamax.mjs",
-      "types": "./src/isamax/isamax.d.mts"
+      "types": "./src/isamax/isamax.d.mts",
+      "import": "./src/isamax/isamax.mjs"
     },
     "./idamax": {
-      "import": "./src/idamax/idamax.mjs",
-      "types": "./src/idamax/idamax.d.mts"
+      "types": "./src/idamax/idamax.d.mts",
+      "import": "./src/idamax/idamax.mjs"
     },
     "./srot": {
-      "import": "./src/srot/srot.mjs",
-      "types": "./src/srot/srot.d.mts"
+      "types": "./src/srot/srot.d.mts",
+      "import": "./src/srot/srot.mjs"
+    },
+    "./drot": {
+      "types": "./src/drot/drot.d.mts",
+      "import": "./src/drot/drot.mjs"
     },
     "./srotm": {
-      "import": "./src/srotm/srotm.mjs",
-      "types": "./src/srotm/srotm.d.mts"
+      "types": "./src/srotm/srotm.d.mts",
+      "import": "./src/srotm/srotm.mjs"
+    },
+    "./drotm": {
+      "types": "./src/drotm/drotm.d.mts",
+      "import": "./src/drotm/drotm.mjs"
     },
     "./sgemv": {
-      "import": "./src/sgemv/sgemv.mjs",
-      "types": "./src/sgemv/sgemv.d.mts"
+      "types": "./src/sgemv/sgemv.d.mts",
+      "import": "./src/sgemv/sgemv.mjs"
     },
     "./ssymv": {
-      "import": "./src/ssymv/ssymv.mjs",
-      "types": "./src/ssymv/ssymv.d.mts"
+      "types": "./src/ssymv/ssymv.d.mts",
+      "import": "./src/ssymv/ssymv.mjs"
     },
     "./strmv": {
-      "import": "./src/strmv/strmv.mjs",
-      "types": "./src/strmv/strmv.d.mts"
+      "types": "./src/strmv/strmv.d.mts",
+      "import": "./src/strmv/strmv.mjs"
     },
     "./strsv": {
-      "import": "./src/strsv/strsv.mjs",
-      "types": "./src/strsv/strsv.d.mts"
+      "types": "./src/strsv/strsv.d.mts",
+      "import": "./src/strsv/strsv.mjs"
     },
     "./sger": {
-      "import": "./src/sger/sger.mjs",
-      "types": "./src/sger/sger.d.mts"
+      "types": "./src/sger/sger.d.mts",
+      "import": "./src/sger/sger.mjs"
     },
     "./ssyr": {
-      "import": "./src/ssyr/ssyr.mjs",
-      "types": "./src/ssyr/ssyr.d.mts"
+      "types": "./src/ssyr/ssyr.d.mts",
+      "import": "./src/ssyr/ssyr.mjs"
     },
     "./ssyr2": {
-      "import": "./src/ssyr2/ssyr2.mjs",
-      "types": "./src/ssyr2/ssyr2.d.mts"
+      "types": "./src/ssyr2/ssyr2.d.mts",
+      "import": "./src/ssyr2/ssyr2.mjs"
     },
     "./sgemm": {
-      "import": "./src/sgemm/sgemm.mjs",
-      "types": "./src/sgemm/sgemm.d.mts"
+      "types": "./src/sgemm/sgemm.d.mts",
+      "import": "./src/sgemm/sgemm.mjs"
     },
     "./sgemmtr": {
-      "import": "./src/sgemmtr/sgemmtr.mjs",
-      "types": "./src/sgemmtr/sgemmtr.d.mts"
+      "types": "./src/sgemmtr/sgemmtr.d.mts",
+      "import": "./src/sgemmtr/sgemmtr.mjs"
     },
     "./ssyrk": {
-      "import": "./src/ssyrk/ssyrk.mjs",
-      "types": "./src/ssyrk/ssyrk.d.mts"
+      "types": "./src/ssyrk/ssyrk.d.mts",
+      "import": "./src/ssyrk/ssyrk.mjs"
     },
     "./ssyr2k": {
-      "import": "./src/ssyr2k/ssyr2k.mjs",
-      "types": "./src/ssyr2k/ssyr2k.d.mts"
+      "types": "./src/ssyr2k/ssyr2k.d.mts",
+      "import": "./src/ssyr2k/ssyr2k.mjs"
     },
     "./ssymm": {
-      "import": "./src/ssymm/ssymm.mjs",
-      "types": "./src/ssymm/ssymm.d.mts"
+      "types": "./src/ssymm/ssymm.d.mts",
+      "import": "./src/ssymm/ssymm.mjs"
     },
     "./strmm": {
-      "import": "./src/strmm/strmm.mjs",
-      "types": "./src/strmm/strmm.d.mts"
+      "types": "./src/strmm/strmm.d.mts",
+      "import": "./src/strmm/strmm.mjs"
     },
     "./strsm": {
-      "import": "./src/strsm/strsm.mjs",
-      "types": "./src/strsm/strsm.d.mts"
+      "types": "./src/strsm/strsm.d.mts",
+      "import": "./src/strsm/strsm.mjs"
     }
   },
   "files": [
@@ -179,7 +223,18 @@
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@eslint/js": "^10.0.1",
+    "@size-limit/file": "^13.0.3",
+    "@stdlib/array-complex64": "^0.3.2",
+    "@stdlib/blas-base-cscal": "^0.1.1",
     "@stdlib/blas-base-dasum": "^0.4.1",
+    "@stdlib/blas-base-daxpy": "^0.4.1",
+    "@stdlib/blas-base-dcopy": "^0.4.1",
+    "@stdlib/blas-base-ddot": "^0.4.1",
+    "@stdlib/blas-base-dnrm2": "^0.4.1",
+    "@stdlib/blas-base-drot": "^0.1.1",
+    "@stdlib/blas-base-drotm": "^0.2.1",
+    "@stdlib/blas-base-dscal": "^0.4.1",
+    "@stdlib/blas-base-dswap": "^0.4.1",
     "@stdlib/blas-base-idamax": "^0.1.1",
     "@stdlib/blas-base-isamax": "^0.1.1",
     "@stdlib/blas-base-sasum": "^0.3.1",
@@ -199,8 +254,10 @@
     "@stdlib/blas-base-ssyr2": "^0.1.1",
     "@stdlib/blas-base-strmv": "^0.1.0",
     "@stdlib/blas-base-strsv": "^0.1.1",
+    "@stdlib/complex-float32-ctor": "^0.1.1",
     "@stdlib/random-array-uniform": "^0.2.2",
     "@stdlib/random-base-uniform": "^0.2.3",
+    "c8": "^12.0.0",
     "esbuild": "^0.28.1",
     "eslint": "^10.6.0",
     "fast-check": "^4.8.0",
@@ -208,7 +265,10 @@
     "husky": "^9.1.7",
     "lint-staged": "^17.0.8",
     "prettier": "^3.9.4",
+    "publint": "^0.3.24",
+    "size-limit": "^13.0.3",
     "typedoc": "^0.28.19",
+    "typedoc-plugin-katex": "^0.1.2",
     "typescript": "^6.0.3",
     "vite": "^8.0.16"
   },
@@ -216,12 +276,22 @@
     "prepare": "husky",
     "build:browser": "node scripts/build-browser.mjs",
     "docs": "npx typedoc && npm run build:browser",
-    "prepublishOnly": "npm run build:browser"
+    "prepublishOnly": "npm run build:browser",
+    "coverage": "c8 --reporter=text --reporter=html node --test $(find tests \\( -name 'test.*.js' -o -name 'gpustorage.*.js' \\))",
+    "cpd": "jscpd src",
+    "size": "npm run build:browser && size-limit"
   },
   "lint-staged": {
     "*.{js,mjs,cjs}": [
       "prettier --write",
       "eslint"
     ]
-  }
+  },
+  "size-limit": [
+    {
+      "name": "browser bundle (brotli)",
+      "path": "dist/wgblas.browser.js",
+      "limit": "50 KB"
+    }
+  ]
 }

package/src/classes/Complex32.d.mts

@@ -0,0 +1,43 @@
+/**
+ * A single 32-bit (f32) complex number: a real and an imaginary component.
+ * JavaScript has no native complex number type, so this is the value type
+ * every complex routine in this library builds on.
+ *
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/classes/Complex32.mjs#L8">Source code: Complex32.mjs (L8)</a>
+ * @category Classes
+ */
+export declare class Complex32 {
+  /**
+   * @param re - real component, rounded to the nearest f32
+   * @param im - imaginary component, rounded to the nearest f32
+   *
+   * {@includeCode ../../examples/complex32/complex32.js}
+   */
+  constructor(re: number, im: number);
+
+  /** Real component (f32-rounded via `Math.fround`). */
+  re: number;
+
+  /** Imaginary component (f32-rounded via `Math.fround`). */
+  im: number;
+}
+
+/**
+ * An array of Complex32 values — array-of-structs, each element its own
+ * independent Complex32 instance (as opposed to a struct-of-arrays layout
+ * with separate re/im buffers). Extends the native Array, so indexing
+ * (`arr[i]`), `.length`, iteration, `.map`, etc. all work as expected.
+ *
+ * @see <a href="https://github.com/manit2004/wgblas/blob/main/src/classes/Complex32.mjs#L38">Source code: Complex32.mjs (L38)</a>
+ * @category Classes
+ */
+export declare class Complex32Array extends Array<Complex32> {
+  /**
+   * @param arg - a length (fills with that many zero-valued Complex32
+   *   entries), a flat interleaved `[re, im, re, im, ...]` list of numbers,
+   *   or an iterable of existing Complex32 instances to copy
+   *
+   * {@includeCode ../../examples/complex32array/complex32array.js}
+   */
+  constructor(arg?: number | Iterable<number> | Iterable<Complex32>);
+}

package/src/classes/Complex32.mjs

@@ -0,0 +1,82 @@
+/** @module devdocs/classes/Complex32 */
+
+/**
+ * A single 32-bit (f32) complex number: a real and an imaginary component.
+ * JavaScript has no native complex number type, so this is the value type
+ * every complex routine in this library builds on.
+ */
+export class Complex32 {
+  /**
+   * @param {number} re - real component, rounded to the nearest f32 (same
+   *   `Math.fround` truncation splitDoubleDouble uses for f64 emulation) —
+   *   a plain JS number is an f64, and "32" in Complex32 means each
+   *   component is genuinely f32-precision, not just f64 stored in an
+   *   f32-sized slot
+   * @param {number} im - imaginary component, rounded to the nearest f32
+   */
+  constructor(re, im) {
+    this.re = Math.fround(re);
+    this.im = Math.fround(im);
+  }
+}
+
+/**
+ * An array of Complex32 values — array-of-structs, each element its own
+ * independent Complex32 instance (as opposed to a struct-of-arrays layout
+ * with separate re/im buffers). Extends the native Array so indexing
+ * (`arr[i]`), `.length`, iteration, `.map`, etc. all work as expected.
+ *
+ * Mirrors @stdlib/array-complex64's constructor overloads (minus the
+ * ArrayBuffer-view form, which needs a flat backing buffer — incompatible
+ * with storing genuine Complex32 instances one per slot):
+ *
+ *   new Complex32Array()                 // empty
+ *   new Complex32Array(length)           // length zero-valued entries
+ *   new Complex32Array([1, 5, 3, 8])     // flat [re, im, re, im, ...] pairs
+ *   new Complex32Array([z1, z2])         // copies existing Complex32 instances
+ */
+export class Complex32Array extends Array {
+  /**
+   * @param {number|Iterable<number>|Iterable<Complex32>} [arg] - a length,
+   *   a flat interleaved [re, im, ...] list of numbers, or an iterable of
+   *   existing Complex32 instances
+   */
+  constructor(arg) {
+    if (arg === undefined) {
+      super();
+      return;
+    }
+    if (typeof arg === "number") {
+      super(arg);
+      for (let i = 0; i < arg; i++) this[i] = new Complex32(0, 0);
+      return;
+    }
+
+    const items = Array.from(arg);
+    super();
+    if (items.length === 0) return;
+
+    if (items[0] instanceof Complex32) {
+      for (const z of items) {
+        if (!(z instanceof Complex32))
+          throw new Error(
+            "Complex32Array expects every element to be a Complex32.",
+          );
+        this.push(z);
+      }
+      return;
+    }
+
+    if (items.length % 2 !== 0)
+      throw new Error(
+        "Complex32Array expects an even number of interleaved [re, im, ...] values.",
+      );
+    for (let i = 0; i < items.length; i += 2) {
+      if (typeof items[i] !== "number" || typeof items[i + 1] !== "number")
+        throw new Error(
+          "Complex32Array expects interleaved [re, im, ...] values to be numbers.",
+        );
+      this.push(new Complex32(items[i], items[i + 1]));
+    }
+  }
+}