@thednp/dommatrix 3.1.0 → 3.1.1

package/AGENTS.md

@@ -31,6 +31,7 @@ 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.
@@ -44,8 +45,11 @@ Deno equivalents: `deno task test`, `deno task lint`, `deno task check`, `deno t
 - `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
+- `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)
@@ -77,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).
 
@@ -88,9 +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.
+- **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 22 interleaved cases take ~15s.
+- 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,23 @@ 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
@@ -22,8 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `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.
+- 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
 

package/README.md

@@ -12,12 +12,12 @@ 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)
 - [API Reference](#api-reference)
 - [CSSMatrix vs native DOMMatrix](#cssmatrix-vs-native-dommatrix)
-- [Benchmarks](#benchmarks)
 - [Alternatives](#alternatives)
 - [History](#history)
 - [Thanks](#thanks)
@@ -33,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.
@@ -152,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()`) |
@@ -188,86 +200,13 @@ 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 |
 
 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).

package/dist/dommatrix.cjs

@@ -42,17 +42,68 @@ const isCompatibleObject = (object) => {
 * the result is a 3D matrix. Otherwise, a TypeError exception is thrown.
 *
 * @param array an `Array` to feed values from.
+* @param target an optional matrix instance to write the values into; when omitted
+* a new matrix is returned. Used internally by `setMatrixValue` to mutate in place.
 * @return the resulted matrix.
 */
-const fromArray = (array) => {
+const fromArray = (array, target) => {
 	if (!isCompatibleArray(array)) throw TypeError(`CSSMatrix: "${Array.from(array).join(",")}" must be an array with 6/16 numbers.`);
 	// istanbul ignore else @preserve
 	if (array.length === 16) {
 		const [m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44] = array;
-		return fromValues(m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44);
+		return writeValues(target ?? new CSSMatrix(), m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44);
 	}
 	const [M11, M12, M21, M22, M41, M42] = array;
-	return fromValues(M11, M12, 0, 0, M21, M22, 0, 0, 0, 0, 1, 0, M41, M42, 0, 1);
+	return writeValues(target ?? new CSSMatrix(), M11, M12, 0, 0, M21, M22, 0, 0, 0, 0, 1, 0, M41, M42, 0, 1);
+};
+/**
+* Internal helper that writes the 16 values of a matrix into a given `CSSMatrix`
+* instance. This is the single place where all 22 aliases (`a`-`f` and `m11`-`m44`)
+* are written, so every write path keeps the instance monomorphic.
+*
+* @param target the matrix instance to write the values into.
+* @param m11 the `m11` value.
+* @param m12 the `m12` value.
+* @param m13 the `m13` value.
+* @param m14 the `m14` value.
+* @param m21 the `m21` value.
+* @param m22 the `m22` value.
+* @param m23 the `m23` value.
+* @param m24 the `m24` value.
+* @param m31 the `m31` value.
+* @param m32 the `m32` value.
+* @param m33 the `m33` value.
+* @param m34 the `m34` value.
+* @param m41 the `m41` value.
+* @param m42 the `m42` value.
+* @param m43 the `m43` value.
+* @param m44 the `m44` value.
+* @return the target matrix.
+*/
+const writeValues = (target, m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44) => {
+	target.m11 = m11;
+	target.a = m11;
+	target.m21 = m21;
+	target.c = m21;
+	target.m31 = m31;
+	target.m41 = m41;
+	target.e = m41;
+	target.m12 = m12;
+	target.b = m12;
+	target.m22 = m22;
+	target.d = m22;
+	target.m32 = m32;
+	target.m42 = m42;
+	target.f = m42;
+	target.m13 = m13;
+	target.m23 = m23;
+	target.m33 = m33;
+	target.m43 = m43;
+	target.m14 = m14;
+	target.m24 = m24;
+	target.m34 = m34;
+	target.m44 = m44;
+	return target;
 };
 /**
 * Creates a new mutable `CSSMatrix` instance given the 16 values of the matrix.
@@ -78,40 +129,19 @@ const fromArray = (array) => {
 * @return the resulted matrix.
 */
 const fromValues = (m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44) => {
-	const m = new CSSMatrix();
-	m.m11 = m11;
-	m.a = m11;
-	m.m21 = m21;
-	m.c = m21;
-	m.m31 = m31;
-	m.m41 = m41;
-	m.e = m41;
-	m.m12 = m12;
-	m.b = m12;
-	m.m22 = m22;
-	m.d = m22;
-	m.m32 = m32;
-	m.m42 = m42;
-	m.f = m42;
-	m.m13 = m13;
-	m.m23 = m23;
-	m.m33 = m33;
-	m.m43 = m43;
-	m.m14 = m14;
-	m.m24 = m24;
-	m.m34 = m34;
-	m.m44 = m44;
-	return m;
+	return writeValues(new CSSMatrix(), m11, m12, m13, m14, m21, m22, m23, m24, m31, m32, m33, m34, m41, m42, m43, m44);
 };
 /**
 * Creates a new mutable `CSSMatrix` instance given an existing matrix or a
 * `DOMMatrix` instance which provides the values for its properties.
 *
 * @param m the source matrix to feed values from.
+* @param target an optional matrix instance to write the values into; when omitted
+* a new matrix is returned. Used internally by `setMatrixValue` to mutate in place.
 * @return the resulted matrix.
 */
-const fromMatrix = (m) => {
-	if (isCompatibleObject(m)) return fromValues(m.m11, m.m12, m.m13, m.m14, m.m21, m.m22, m.m23, m.m24, m.m31, m.m32, m.m33, m.m34, m.m41, m.m42, m.m43, m.m44);
+const fromMatrix = (m, target) => {
+	if (isCompatibleObject(m)) return writeValues(target ?? new CSSMatrix(), m.m11, m.m12, m.m13, m.m14, m.m21, m.m22, m.m23, m.m24, m.m31, m.m32, m.m33, m.m34, m.m41, m.m42, m.m43, m.m44);
 	throw TypeError(`CSSMatrix: "${JSON.stringify(m)}" is not a DOMMatrix / CSSMatrix / JSON compatible object.`);
 };
 /**
@@ -576,13 +606,19 @@ var CSSMatrix = class {
 	* This method expects valid *matrix()* / *matrix3d()* string values, as well
 	* as other transform functions like *translateX(10px)*.
 	*
+	* The matrix is mutated in place (the same instance is returned), matching
+	* the behavior of the native `DOMMatrix.setMatrixValue()`.
+	*
 	* @param source
-	* @return the matrix instance
+	* @return the current matrix instance
 	*/
 	setMatrixValue(source) {
-		if (typeof source === "string" && source.length && source !== "none") return fromString(source);
-		if (Array.isArray(source) || source instanceof Float64Array || source instanceof Float32Array) return fromArray(source);
-		if (typeof source === "object") return fromMatrix(source);
+		if (typeof source === "string" && source.length && source !== "none") {
+			const m = fromString(source);
+			return writeValues(this, m.m11, m.m12, m.m13, m.m14, m.m21, m.m22, m.m23, m.m24, m.m31, m.m32, m.m33, m.m34, m.m41, m.m42, m.m43, m.m44);
+		}
+		if (Array.isArray(source) || source instanceof Float64Array || source instanceof Float32Array) return fromArray(source, this);
+		if (typeof source === "object") return fromMatrix(source, this);
 		return this;
 	}
 	/**