@thednp/dommatrix 3.0.6 → 3.1.1

package/AGENTS.md

@@ -29,6 +29,9 @@ 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)
+pnpm bench:docs     # run both bench suites (2x), write test/fixtures/bench-results.json, regenerate the BENCHMARK.md tables and the README ## Benchmarks summary
 ```
 
 Always run `pnpm lint` and `pnpm test` after making changes.
@@ -38,9 +41,15 @@ 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/fixtures/` — test helpers and sample data
+- `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 (22 ops at `1e-9`, runs in `pnpm test`) + interleaved perf suite
+- `test/fixtures/bench-results.json` — last measured results, written by `scripts/update-benchmark.js`; single source of truth for the `BENCHMARK.md` tables and the README `## Benchmarks` summary
+- `scripts/update-benchmark.js` — runs both bench suites (2x, ~1 min), parses the `afterAll` tables from vitest stdout, writes the fixture, rewrites the two table blocks of `BENCHMARK.md` (between the `<!-- b1 -->`/`<!-- /b1 -->` and `<!-- b2 -->`/`<!-- /b2 -->` markers, plus the `<!-- b-updated -->` date stamp) and regenerates the README `## Benchmarks` summary
+- `BENCHMARK.md` — the full benchmark report (static methodology intro, `<!-- b1 -->`/`<!-- b2 -->`-marked table blocks, static conclusion); only the marked blocks are regenerated by `pnpm bench:docs`
+- `test/fixtures/` — test helpers, sample data, and the bench-results fixture
 - `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
 - `experiments/` — archived Cypress experiments (not part of the build)
@@ -72,7 +81,7 @@ Deno equivalents: `deno task test`, `deno task lint`, `deno task check`, `deno t
 1. Bump `version` in `package.json` **and** in `deno.json`
 2. Add an entry to `CHANGELOG.md` (Keep a Changelog style, date-stamped)
 3. Run `pnpm build && pnpm lint && pnpm test` and `deno publish --dry-run --allow-dirty`
-4. Commit, then tag with the **bare version number** (no `v` prefix — existing tags are `1.0.0` ... `3.0.4`)
+4. Commit, then tag with the **bare version number** (no `v` prefix — existing tags are `1.0.0` ... `3.1.0`)
 
 The GitHub Actions `publish.yml` workflow publishes to both npm and JSR on GitHub Release (JSR via OIDC when enabled on the scope, otherwise the `JSR_TOKEN` secret).
 
@@ -83,5 +92,10 @@ 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 (but only with the verbose reporter — see next bullet).
+- **The `BENCHMARK.md` tables are generated** by `pnpm bench:docs` (`scripts/update-benchmark.js`) from `test/fixtures/bench-results.json` — do not hand-edit the blocks between the `<!-- b1 -->`/`<!-- /b1 -->` and `<!-- b2 -->`/`<!-- /b2 -->` markers (the tables and their interpretation only), nor the `<!-- b-updated -->`/`<!-- /b-updated -->` date stamp; the intro and the closing conclusion are otherwise static. The script also regenerates the short README `## Benchmarks` summary — a "X–Yx faster" report with a last-updated line, linking to `BENCHMARK.md` — by writing between the `<!-- b-summary -->`/`<!-- /b-summary -->` markers of the section bounded by the `## Benchmarks` and `## Demo` headings (the script fails if that boundary is not found). It spawns vitest with `--reporter=verbose` (the default reporter does not forward browser `console.log`), parses the two `afterAll` tables from stdout, runs each suite twice and reports medians. Grouping thresholds: vs-3.0.x buckets at 6x / 2x / 1.12x (ratio >= 6 “Large”, >= 2 “Moderate”, >= 1.12 “Mild”, else “At parity”); native is split three-way at ±5% (the measured noise floor).
+- **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 23 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,49 @@ 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.1] - 2026-08-05
+
+### Added
+
+- `pnpm bench:docs` (`scripts/update-benchmark.js`): runs both bench suites twice, parses the printed tables, writes `test/fixtures/bench-results.json`, and regenerates the `BENCHMARK.md` tables and the README `## Benchmarks` summary from it — no more hand-transcribing benchmark numbers.
+
+### Changed
+
+- The full benchmark report moved out of the README into a dedicated `BENCHMARK.md` (static methodology intro and conclusion, with the two result tables wrapped in `<!-- b1 -->` / `<!-- /b1 -->` and `<!-- b2 -->` / `<!-- /b2 -->` markers). The README `## Benchmarks` section is now a short summary — a one-line "X–Yx faster than the previous release / than native" range plus a link to `BENCHMARK.md` — so it keeps the attention on the big picture instead of the per-operation numbers.
+- `setMatrixValue()` now **mutates the matrix in place and returns `this`**, matching the native `DOMMatrix.setMatrixValue()` (previously it returned a new matrix and left the original untouched). The `fromArray()` / `fromMatrix()` value writers now accept an optional target instance, so the array / object paths of `setMatrixValue()` write straight into the existing instance instead of allocating a new one. Both benchmark suites gained `setMatrixValue()` operations to cover the new path: array and transform-list inputs against the 3.0.x snapshot, and a parity-checked transform-list case against native (the native parity suite now covers 22 operations).
+
+### Fixed
+
+- The native benchmark's `transformPoint` case measured asymmetric work: the shim side constructed the matrix from a transform string on every iteration while the native side reused a pre-built `DOMMatrix`. Both sides now pre-build the matrix, and the corrected measurement is ~11x shim-faster on `transformPoint` (previously reported as ~0.36x native-faster, see the 3.1.0 entry above); `test/fixtures/bench-results.json`, the `BENCHMARK.md` tables and the README `## Benchmarks` summary were regenerated with `pnpm bench:docs`.
+
+[3.1.1]: https://github.com/thednp/dommatrix/releases/tag/3.1.1
+
+## [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 the `3.0.x` 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) and on point transforms (`transformPoint` ~11x), while native wins only the serialization case: `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

@@ -12,6 +12,7 @@ A TypeScript sourced [DOMMatrix](https://developer.mozilla.org/en-US/docs/Web/AP
 ## Table of Contents
 
 - [Features](#features)
+- [Benchmarks](#benchmarks)
 - [Demo](#demo)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
@@ -32,6 +33,18 @@ A TypeScript sourced [DOMMatrix](https://developer.mozilla.org/en-US/docs/Web/AP
 - **TypeScript** — bundled type definitions, including the `Matrix`, `Matrix3d`, `JSONMatrix` and `PointTuple` types
 - **Verified against native** — every method is tested side-by-side with the native `DOMMatrix` in real browsers, with **100% test coverage**
 
+## Benchmarks
+
+<!-- b-summary -->
+
+`CSSMatrix` is **1.2x–91x faster** than the previous 3.0.x release series and **1.8x–162x faster** than the native `DOMMatrix` — except `toString()`, which native does ~1.2x faster.
+
+Every operation's result matches the previous release series and the native `DOMMatrix` to within `1e-9` (output is indistinguishable at the 9th decimal place). Full methodology, per-operation results and interpretation: [BENCHMARK](BENCHMARK.md).
+
+Last updated: **2026-08-05**.
+
+<!-- /b-summary -->
+
 ## Demo
 
 See DOMMatrix shim in action, [click me](https://thednp.github.io/dommatrix) and start transforming.
@@ -151,7 +164,7 @@ For the complete JavaScript API, check the [JavaScript API](https://github.com/t
 
 | Method | Description |
 | --- | --- |
-| `setMatrixValue(init)` | Returns a new matrix from the given string / array / object |
+| `setMatrixValue(init)` | Replaces the matrix values from the given string / array / object, mutates in place and returns `this` |
 | `translate(x, y?, z?)` / `translateSelf(x, y?, z?)` | Applies a translation (CSS `translate3d()`) |
 | `rotate(rx?, ry?, rz?)` / `rotateSelf(rx?, ry?, rz?)` | Applies a rotation; a single value rotates about the z-axis (CSS `rotate()`) |
 | `rotateAxisAngle(x, y, z, angle)` / `rotateAxisAngleSelf(...)` | Applies a rotation about a vector (CSS `rotate3d()`) |
@@ -187,7 +200,7 @@ The shim mirrors the native **DOMMatrix** API surface closely — the same `m11`
 | `transformOrigin` argument | Not supported | Supported (`new DOMMatrix(init, transformOrigin)`) |
 | `is2D` / `isIdentity` | Computed getters — always reflect the current values | `is2D` is a flag fixed at construction and can report stale results (e.g. after `rotateAxisAngle()`) |
 | `transformPoint()` | Accepts a `DOMPoint` **or** a plain `{ x, y, z, w }` tuple; returns the same type it received | Accepts `DOMPointInit`, always returns a `DOMPoint` |
-| `setMatrixValue()` | Returns a **new** matrix, the original is left unchanged | Mutates the matrix in place and returns `this` |
+| `setMatrixValue()` | Mutates in place and returns `this`; accepts any of the shim's input types (string, array / typed array, `DOMMatrix`, plain object) | Mutates in place and returns `this`; accepts `DOMMatrixInit` only |
 | `toArray()` | Plain `Array` of 6/16 values, alongside `toFloat32Array()` / `toFloat64Array()` | `toFloat32Array()` / `toFloat64Array()` only |
 | `toJSON()` | `{ a-f, m11-m44, is2D, isIdentity }` | Same shape |
 | TypeScript | Ships bundled type definitions, zero runtime dependencies | WebIDL-generated typings |
@@ -204,6 +217,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;