@thednp/dommatrix 3.0.6 → 3.1.0

package/AGENTS.md

@@ -29,6 +29,8 @@ pnpm lint:ts        # deno lint src
 pnpm check:ts       # tsc --noEmit
 pnpm fix:ts         # deno lint src --fix
 pnpm format         # deno fmt src
+pnpm bench          # vitest browser bench vs test/fixtures/index-3.0.x.ts (no coverage)
+pnpm bench:native   # vitest browser bench vs native DOMMatrix (no coverage)
 ```
 
 Always run `pnpm lint` and `pnpm test` after making changes.
@@ -38,8 +40,11 @@ Deno equivalents: `deno task test`, `deno task lint`, `deno task check`, `deno t
 ## Project Structure
 
 - `src/index.ts` — the entire library (single file, ~1200 lines). The `CSSMatrix` class plus module-level helper functions (`Translate`, `Rotate`, `fromString`, etc.). Heavily documented with JSDoc.
+- `test/fixtures/index-3.0.x.ts` — snapshot of the pre-3.1.0 implementation used as the benchmark baseline by `test/dommatrix.bench.test.ts`. Excluded from coverage (see `vitest.config.mts`) and from JSR publish (only the `publish.include` files ship). Included in the `tsconfig.json` `include` so `pnpm check:ts` covers it.
 - `src/types.ts` — exported types (`JSONMatrix`, `Matrix`, `Matrix3d`, `PointTuple`)
 - `test/dommatrix.test.ts` — the full test suite (Vitest, browser mode)
+- `test/dommatrix.bench.test.ts` — benchmark vs the `test/fixtures/index-3.0.x.ts` snapshot: parity suite (every op must match the backup within `1e-9`, runs in `pnpm test` and gates CI) + interleaved perf suite (auto-skipped under coverage)
+- `test/native.bench.test.ts` — benchmark vs native `DOMMatrix`: parity suite (21 ops at `1e-9`, runs in `pnpm test`) + interleaved perf suite
 - `test/fixtures/` — test helpers and sample data
 - `docs/` — GitHub Pages demo; `docs/dommatrix.js` is a build artifact copied from `dist/`
 - `dist/` — build output, committed to the repo; regenerate with `pnpm build`, never edit by hand
@@ -83,5 +88,9 @@ Note: `prepublishOnly` runs `pnpm up --latest` (updates all deps), `pnpm format`
 - The old `vite.config.ts` was replaced by `tsdown.config.mts` in 3.0.5 — `tsdown.config.mts` relies on: object-form `entry` for the chunk name (`dommatrix`), an `outputOptions` override for UMD (it must spread defaults, otherwise `sourcemap` is silently dropped), and `outExtensions` to keep the `.d.ts` filename. The `.mts` extension (not `.ts`) prevents Node's `MODULE_TYPELESS_PACKAGE_JSON` ESM-reparse warning — `package.json` deliberately has no `"type": "module"` because that would break Node `require()` of the UMD `dist/dommatrix.js`
 - With `deno.json` present, `deno lint` enforces `verbatim-module-syntax` — type-only imports (like `import type CSSMatrix from "."` in `src/types.ts`) must use `import type`
 - Vitest runs only in browser mode; any Node-only concern (globals, `require()`, `process`) needs the stubbed-global test pattern
+- **Browser `console.table` is NOT forwarded to the terminal** — both bench suites accumulate rows on `globalThis` (`__CSSMATRIX_BENCH__`, `__CSSMATRIX_NATIVE_BENCH__`, inspectable in `pnpm test-ui` devtools) and print a pad-aligned `console.log` table in `afterAll`. `console.log` in `afterAll` does forward.
+- **Bench measurements must run without coverage**: istanbul instruments `src/index.ts` but not `test/fixtures/index-3.0.x.ts`, so under coverage the current file measures 30-60% slower than an identical backup. The suites skip timing at runtime when `typeof globalThis["__VITEST_COVERAGE__"] === "object"` (the key only appears after instrumented code executes) — parity assertions still run in `pnpm test`.
+- **Interleaved sampling**: `bench(a, b, iterations)` warms up both implementations, then takes 2 alternating samples each and reports medians. Sequential per-implementation measurement biases toward the first implementation (~20-30%) because the second's allocations raise GC pressure. Identical files must measure ~0.92-1.09x.
+- Native DOMMatrix quirks that shaped `test/native.bench.test.ts`: Chrome lacks `DOMMatrix.fromArray` (use `DOMMatrix.fromMatrix(values)`); native has no `skew()`/`skewSelf()` (only `skewX`/`skewY`); `rotateAxisAngle(x, y, z, angle)` takes the angle last; `DOMPoint` exposes `x/y/z/w` as prototype getters so `Object.keys()` is empty — extract values into a plain object before comparing; the bench test needs a long timeout (120s) because 22 interleaved cases take ~15s.
 - `rotateAxisAngle`/`rotateAxisAngleSelf` throw only when any of the 4 values is non-finite; zero-length vector returns a copy (or `this` for the `Self` variant)
 - `deno lint` runs on `src/` only — the `tsconfig.json` `include` is `["src/*"]`, `noEmit: true`

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.0] - 2026-08-04
+
+### Added
+
+- A benchmark suite in `test/dommatrix.bench.test.ts` comparing the current implementation against a `test/fixtures/index-3.0.x.ts` snapshot of the previous release: a parity suite (every operation must produce output identical to the backup, within `1e-9`) and a performance suite with interleaved, median-of-2 sampling per operation. Measurements are skipped automatically under coverage (istanbul instrumentation distorts timings); run `pnpm bench`.
+- A native comparison suite in `test/native.bench.test.ts` comparing the current implementation against the browser's native `DOMMatrix`: parity at `1e-9` for 21 operations plus interleaved performance measurements; run `pnpm bench:native`.
+- `pnpm bench` and `pnpm bench:native` scripts. Both suites store their result tables on `globalThis.__CSSMATRIX_BENCH__` / `__CSSMATRIX_NATIVE_BENCH__` for inspection in `pnpm test-ui` devtools, and print a combined table to the terminal (browser `console.table` output is not forwarded by Vitest).
+
+### Changed
+
+- Major performance rework of the internal hot paths, all parity-verified against the previous release and against native `DOMMatrix`:
+  - `new CSSMatrix(init)` now fast-paths string / array / typed-array / object initializers instead of round-tripping through `setMatrixValue()`, and construction is funneled through a new internal `fromValues()` factory that writes all 22 aliases in one pass (a single hidden class keeps the constructor monomorphic).
+  - `CSSMatrix.fromString()` parses transform lists with a single regex iteration instead of split/filter/forEach, with equivalent strict validation of non-transform garbage.
+  - `CSSMatrix.fromArray()` and `CSSMatrix.fromMatrix()` validate and destructure input directly, no intermediate `Array` copy.
+  - `multiply()`/`multiplySelf()` share a new `multiplyInto()` kernel with a single 64-multiplication pass; `multiplySelf()` writes into `this` instead of allocating and spreading a result object.
+  - `translate()`, `translateSelf()`, `scale()`, `scaleSelf()`, `skew()`, `skewSelf()` (plus `skewX()`/`skewY()` delegating to `skew()`) use specialized pre-multiply math instead of general matrix multiplication.
+  - `toJSON()` builds the result object with explicit property writes instead of spreading `this`; `toFloat32Array()`/`toFloat64Array()` build typed arrays directly, skipping the intermediate `toArray()` allocation.
+- Measured performance deltas (vs `3.0.7` snapshot, Chromium, `pnpm bench`; ops/s ratios are noise-floor-corrected via interleaved sampling): `multiplySelf` ~17–18x, `scale` ~13x, `skew` ~6–14x, `translate` ~6.5–13x, `multiply` ~7x, `fromMatrix` ~7–7.6x, `rotate` ~5–5.6x, `rotateAxisAngle` ~4.1–4.5x, `toJSON` ~9.7–10.1x, `new CSSMatrix(transform list)` ~1.9–2.4x; unchanged code paths (`new CSSMatrix()`, `fromArray`, `transformPoint`, `toString`, `is2D`/`isIdentity`) measure ~0.96–1.1x.
+- vs native `DOMMatrix` (`pnpm bench:native`, Chromium): the shim is faster on construction and mutation-heavy operations (e.g. `multiplySelf` ~48x, `translateSelf` ~28x, `scaleSelf` ~36x, `multiply` ~4x — largely native's Web IDL per-property access and `toJSON()` overhead), while native wins the pure-compute cases: `transformPoint` ~0.36x and `toString` ~0.84x (shim/native ratios); `toFloat32Array` is at parity.
+
+### Fixed
+
+- `CSSMatrix.toArray()` remained coverage-uncovered after the typed-array paths stopped using it; the `is2D` branch is now exercised by tests again (coverage back to 100%).
+
+[3.1.0]: https://github.com/thednp/dommatrix/releases/tag/3.1.0
+
 ## [3.0.6] - 2026-08-04
 - The `README.md` now documents installing from JSR (`jsr add @thednp/dommatrix`).
 

package/README.md

@@ -17,6 +17,7 @@ A TypeScript sourced [DOMMatrix](https://developer.mozilla.org/en-US/docs/Web/AP
 - [Quick Start](#quick-start)
 - [API Reference](#api-reference)
 - [CSSMatrix vs native DOMMatrix](#cssmatrix-vs-native-dommatrix)
+- [Benchmarks](#benchmarks)
 - [Alternatives](#alternatives)
 - [History](#history)
 - [Thanks](#thanks)
@@ -194,6 +195,79 @@ The shim mirrors the native **DOMMatrix** API surface closely — the same `m11`
 
 Methods of the `DOMMatrixReadOnly` prototype that are not part of this shim: `flipX()`, `flipY()`, `inverse()` and `rotateFromVector()` (`transpose()` is not part of the native interface either). Everything else — `translate*`, `rotate*`, `rotateAxisAngle*`, `scale*`, `skew*`, `multiply*`, `toString()`, `toFloat(32/64)Array()`, `transformPoint()` — is implemented with behavior verified against the native interface by the test suite.
 
+## Benchmarks
+
+Two benchmark suites run headless Chromium via Vitest and gate CI with **parity assertions** (output must be identical within `1e-9`), while the timings are reported only:
+
+- `pnpm bench` — `test/dommatrix.bench.test.ts`, current implementation vs a `test/fixtures/index-3.0.x.ts` snapshot of the previous release (22 operations)
+- `pnpm bench:native` — `test/native.bench.test.ts`, current implementation vs the browser's native `DOMMatrix` (22 operations, 21 parity-checked)
+
+Measurements are skipped under coverage (istanbul instrumentation distorts timings) and use interleaved sampling — both implementations are alternated per sample and medians are reported, so the ratios are noise-floor-corrected (identical files measure ~0.92–1.09x). Results are also stored on `globalThis.__CSSMATRIX_BENCH__` / `__CSSMATRIX_NATIVE_BENCH__` for inspection in `pnpm test-ui` devtools, since browser `console.table` output is not forwarded to the terminal.
+
+The tables below report the median of two interleaved runs on headless Chromium (Playwright 1217), 2026-08-04. Ratios above 1 mean the shim is faster.
+
+### vs 3.0.x (previous release)
+
+Ratio = 3.1.x ops/s ÷ 3.0.x ops/s.
+
+**Large wins (6.9–104x)** — the hot paths that were specialized:
+
+| Operation | Ratio | Operation | Ratio |
+| --- | --- | --- | --- |
+| `skewSelf` | ~104x | `scaleSelf` | ~61x |
+| `translateSelf` | ~49x | `multiplySelf` | ~18x |
+| `scale` | ~14x | `skew` | ~13x |
+| `translate` | ~13x | `toJSON` | ~9.7x |
+| `fromMatrix` | ~7.3x | `multiply` | ~6.9x |
+
+**Moderate wins (2.2–5.2x)**:
+
+| Operation | Ratio | Operation | Ratio |
+| --- | --- | --- | --- |
+| `rotate` | ~5.2x | `rotateSelf` | ~4.7x |
+| `rotateAxisAngle` | ~4.1x | `new CSSMatrix(transform list)` | ~2.2x |
+
+**Mild wins (1.2–1.4x)**:
+
+| Operation | Ratio |
+| --- | --- |
+| `new CSSMatrix(matrix 2D)` | ~1.3x |
+| `new CSSMatrix(matrix3d)` | ~1.2x |
+
+**At parity (~1.0x)** — unchanged code paths, no regression:
+
+`new CSSMatrix()`, `fromArray`, `transformPoint`, `toString`, `toFloat32Array`, `is2D` + `isIdentity` (~1.0–1.1x).
+
+### vs native `DOMMatrix`
+
+Ratio = shim ops/s ÷ native ops/s.
+
+**Shim faster** (1.8–150x):
+
+| Operation | Ratio | Operation | Ratio |
+| --- | --- | --- | --- |
+| `new Matrix()` | ~150x¹ | `multiplySelf` | ~48x |
+| `scaleSelf` | ~35x | `skewXSelf` | ~35x |
+| `translateSelf` | ~31x | `rotateAxisAngle` | ~10x |
+| `rotateSelf` | ~8.3x | static from values | ~7.0x |
+| `multiply` | ~4.0x | `translate` | ~4.0x |
+| `scale` | ~4.0x | `fromMatrix` | ~3.8x |
+| `skewX` | ~3.7x | `rotate` | ~3.4x |
+| `new Matrix(matrix 2D)` | ~2.7x | `toJSON` | ~2.0x |
+| `new Matrix(matrix3d)` | ~1.95x | `new Matrix(transform list)` | ~1.9x |
+| `is2D` + `isIdentity` | ~1.8x | `toFloat32Array` | ~1.0x |
+
+¹ measured as construct + `toJSON()`; native's `toJSON()` is a slow JS↔C++ bridge that dominates this row.
+
+**Native faster** (the pure-compute cases):
+
+| Operation | Ratio |
+| --- | --- |
+| `transformPoint` | ~0.36x (native ~2.8x faster) |
+| `toString` | ~0.82x (native ~1.2x faster) |
+
+The shim wins construction and mutation-heavy operations because V8 fully optimizes the plain-JS hot paths, while native `DOMMatrix` pays a C++ call per property access. Native C++ wins where the operation itself is the whole cost: point transforms and serialization.
+
 ## Alternatives
 
 DOMMatrix shim is meant to be a light pocket tool for many things like [svg-path-commander](http://thednp.github.io/svg-path-commander). For a complete polyfill that fills in the missing `DOMMatrixReadOnly` methods (`inverse()`, `flipX()`, `flipY()`, ...), you might want to also consider [geometry-interfaces](https://github.com/trusktr/geometry-interfaces) and [geometry-polyfill](https://github.com/jarek-foksa/geometry-polyfill).
@@ -204,6 +278,7 @@ DOMMatrix shim is meant to be a light pocket tool for many things like [svg-path
 
 - **changed** how the constructor determines if the matrix is 2D, based on a [more accurate method](https://github.com/jsidea/jsidea/blob/2b4486c131d5cca2334293936fa13454b34fcdef/ts/jsidea/geom/Matrix3D.ts#L788) which is actually checking the designated values of the 3D space; in contrast, the old *CSSMatrix* constructor sets the `afine` property at initialization only and based on the number of arguments or the type of the input CSS transform syntax;
 - **fixed** the `translate()`, `scale()` and `rotate()` instance methods to work with one axis transformation, also inline with **DOMMatrix**;
+- **added** the `*Self` instance methods — `translateSelf()`, `scaleSelf()`, `rotateSelf()`, `rotateAxisAngleSelf()`, `skewXSelf()`, `skewYSelf()`, `skewSelf()` and `multiplySelf()` — the mutating counterparts of the immutable methods above, inline with the native **DOMMatrix** API;
 - **changed** `toString()` instance method to utilize the new method `toArray()` described below;
 - **changed** `setMatrixValue()` instance method to do all the heavy duty work with parameters;
 - **added** `is2D` (*getter*) property;