Raise Node baseline to 22.20

Author: hyfdev

.agents/docs/taffyjs-node-decisions.md

@@ -174,6 +174,16 @@ New public state owners, compatibility layers, retained JavaScript values, callb
 
 ## Decided
 
+### Node runtime baseline
+
+**Ruling:** TaffyJS must use a suitable maintained Node.js baseline rather than preserving Node 22.18 merely because it was the repository's original minimum.
+
+**Limits:** This direction does not itself choose an exact replacement version or change the separately decided native target set. The current baseline belongs in package metadata, build targets, CI, and public support documentation rather than in this ledger.
+
+**Why:** No additional rationale was stated.
+
+**Source:** Yunfei (`@hyfdev`), 2026-08-17; explicitly directed the repository not to preserve Node 22.18 for its own sake and to choose a suitable version.
+
 ### Native distribution targets
 
 **Ruling:** `@taffyjs/node` must provide native packages for the 13 native targets carried by napi-rs's maintained package templates: macOS x64 and arm64; Windows x86, x64, and arm64 MSVC; Linux x64 and arm64 with GNU or musl plus armv7 GNU; Android armv7 and arm64; and FreeBSD x64.

.agents/docs/taffyjs-yoga-decisions.md

@@ -40,15 +40,13 @@ This ledger records only judgments that Yunfei explicitly expressed about `@taff
 
 ### Node runtime and package entries
 
-[VOUCHED @hyfdev 2026-08-15]
-
-**Ruling:** `@taffyjs/yoga` is permanently the Node.js compatibility package built over `@taffyjs/node`; it does not provide a browser or WASM backend. Its supported Node.js version follows `@taffyjs/node`, currently Node.js `>=22.18`. The package is ESM-only and reproduces both Yoga 3.2.1 public entry shapes at `@taffyjs/yoga` and `@taffyjs/yoga/load`.
+**Ruling:** `@taffyjs/yoga` is permanently the Node.js compatibility package built over `@taffyjs/node`; it does not provide a browser or WASM backend. Its supported Node.js version follows `@taffyjs/node`. The package is ESM-only and reproduces both Yoga 3.2.1 public entry shapes at `@taffyjs/yoga` and `@taffyjs/yoga/load`.
 
 **Limits:** The root entry provides the default Yoga facade plus the supported named enums and types; the `/load` entry provides `loadYoga()` plus the corresponding supported named enums and types. Exact unsupported exports remain governed by the compatibility classification. A possible future `@taffyjs/yoga-wasm` would be a separate package and is not promised or designed by this decision. The package-manager alias or dependency-substitution instructions remain to be verified.
 
 **Why:** The implementation is intentionally a JavaScript compatibility layer over the native `@taffyjs/node` backend, while Yoga 3.2.1 itself is ESM and exposes both eager root and asynchronous `/load` entries. Keeping any future WASM backend under a distinct package avoids pretending that one package has interchangeable runtime implementations.
 
-**Source:** Yunfei (`@hyfdev`), 2026-08-15; vouched Node-only support, the inherited Node.js version, ESM-only publication, and both public entries, and explicitly ruled out ever adding browser or WASM support to `@taffyjs/yoga` itself.
+**Source:** Yunfei (`@hyfdev`), 2026-08-15 and 2026-08-17; vouched Node-only support, an inherited Node.js version, ESM-only publication, and both public entries, explicitly ruled out ever adding browser or WASM support to `@taffyjs/yoga` itself, and later directed the repository not to preserve Node 22.18 merely as a historical floor.
 
 ### Bun and Deno platform smoke coverage
 

.agents/docs/taffyjs-yoga-reference.md

@@ -51,7 +51,7 @@ API shape, accepted input, stored getter value, state transition, error behavior
 
 ## Package entries and exports
 
-The decided package is ESM-only, follows @taffyjs/node's supported Node.js version (currently Node.js >=22.18) and alternate-runtime floors and constraints, and mirrors both Yoga entry shapes at @taffyjs/yoga and @taffyjs/yoga/load. It never provides a browser or WASM backend.
+The decided package is ESM-only, follows @taffyjs/node's supported Node.js version (currently Node.js >=22.20) and alternate-runtime floors and constraints, and mirrors both Yoga entry shapes at @taffyjs/yoga and @taffyjs/yoga/load. It never provides a browser or WASM backend.
 
 Yoga 3.2.1 is ESM and publishes two package entries.
 

.agents/docs/taffyjs-yoga-wasm-package.md

@@ -5,7 +5,7 @@
 ## Public contract
 
 - The package is ESM-only and exposes the same root and `/load` shapes, declarations, constants, and Yoga compatibility classifications as `@taffyjs/yoga`.
-- The package supports Node.js `>=22.18`, Bun 1.2+ within major 1, Deno 2.2+ within major 2, and modern bundled browsers within the existing `@taffyjs/wasm` contract. Deno requires no permission flags. It does not claim direct CDN, legacy-browser, workerd, or other edge-runtime support without separate evidence.
+- The package supports Node.js `>=22.20`, Bun 1.2+ within major 1, Deno 2.2+ within major 2, and modern bundled browsers within the existing `@taffyjs/wasm` contract. Deno requires no permission flags. It does not claim direct CDN, legacy-browser, workerd, or other edge-runtime support without separate evidence.
 - Consumers may install it under Yoga's original name with the registry alias `"yoga-layout": "npm:@taffyjs/yoga-wasm@<version>"`; supported application imports remain unchanged.
 - `PositionType.Static` and every other Unsupported capability stay unsupported. Replacing the runtime transport does not create missing Taffy layout semantics.
 

.agents/docs/technology-stack.md

@@ -2,7 +2,9 @@
 
 ## Native bindings and distribution
 
-napi-rs owns the Rust-to-Node boundary, private native declarations, native loader, and target-specific package metadata. It generates an ESM loader, which Vite+ bundles into the ESM public entry without maintaining a custom loader. The pinned napi-rs template deliberately emits bare Node builtin specifiers to retain Node 12 compatibility; TaffyJS targets Node 22.18 or newer, so the repository mechanically normalizes those generated specifiers to the explicit `node:` protocol before formatting and bundling the loader.
+napi-rs owns the Rust-to-Node boundary, private native declarations, native loader, and target-specific package metadata. It generates an ESM loader, which Vite+ bundles into the ESM public entry without maintaining a custom loader. The pinned napi-rs template deliberately emits bare Node builtin specifiers to retain Node 12 compatibility; TaffyJS targets Node 22.20 or newer, so the repository mechanically normalizes those generated specifiers to the explicit `node:` protocol before formatting and bundling the loader.
+
+Node 22.20 is the shared package, build-target, and CI baseline. The locked `@napi-rs/lzma` 1.5.1 tool used by napi-rs cross compilation requires Node `^22.20`, `^24.12`, or `>=25`; selecting the first accepted Node 22 release also retains official [Windows x86 and Linux ARMv7 binaries](https://nodejs.org/download/release/v22.20.0/), which [Node 24 no longer provides](https://nodejs.org/en/blog/migrations/v22-to-v24). This keeps the build toolchain compatible without contradicting the maintained native target set.
 
 The generated ESM loader is a private build input. The authored wrapper imports it privately, and the bundled public entry does not re-export raw native operations.
 
@@ -32,7 +34,7 @@ For `packages/taffyjs-yoga-wasm`, Vite+ builds those same sibling source entries
 
 `tools/api-codegen` owns source generation that must keep Rust and TypeScript API facts aligned. Its first maintained input is `api/numeric-families.json`; `vp run codegen` updates both language outputs. CI runs `vp run check:codegen`, which regenerates and rejects any resulting Git diff.
 
-CI has eight logical jobs. Ubuntu x64 GNU, Windows x64 MSVC, and macOS arm64 each build the native addon and run all Rust, JavaScript, and type tests with Node.js 22.18.0; Ubuntu and Windows then smoke-test the public `@taffyjs/node` and `@taffyjs/yoga` entries with Bun 1.2.0 and Deno 2.2.0. Ubuntu also rejects stale committed package JavaScript and declarations after the build. A distribution matrix separately compiles all twelve non-FreeBSD template targets with napi-rs's maintained recipes and uploads every binary; this intentionally rebuilds Linux x64 GNU through napi-rs's cross toolchain for its distribution compatibility floor and applies the upstream macOS deployment target. A FreeBSD 15 VM builds and uploads the thirteenth native target. These distribution jobs prove compilation and artifact generation; they do not extend the blocking runtime matrix beyond the three full native test jobs. A separate Ubuntu WASIP job installs the Rust target and Playwright Chromium, builds `@taffyjs/wasm`, reruns the complete Node public API suite against it, runs type, package-content, packed-consumer, bundled-consumer, and browser-runtime checks against the generated package, and applies the same Bun 1.2.0 and Deno 2.2.0 smoke checks to the public entry. That job also builds `@taffyjs/yoga-wasm`, reruns the complete maintained Yoga behavior and declaration suites, inspects and installs the packed package with npm and pnpm, exercises both public entries in bundled Chromium, and smoke-tests both entries with Bun 1.2.0 and Deno 2.2.0. Alternate-runtime smoke checks perform one fixed layout rather than copying the complete behavior suite. A Node-only job checks formatting, JavaScript and repository TypeScript including maintained tools through Vite+'s type-aware lint path, the alignment among target declarations and platform package metadata, and generated-source drift. A Rust-only job checks formatting and Clippy. Publication workflows are not configured.
+CI has eight logical jobs. Ubuntu x64 GNU, Windows x64 MSVC, and macOS arm64 each build the native addon and run all Rust, JavaScript, and type tests with Node.js 22.20.0; Ubuntu and Windows then smoke-test the public `@taffyjs/node` and `@taffyjs/yoga` entries with Bun 1.2.0 and Deno 2.2.0. Ubuntu also rejects stale committed package JavaScript and declarations after the build. A distribution matrix separately compiles all twelve non-FreeBSD template targets with napi-rs's maintained recipes and uploads every binary; this intentionally rebuilds Linux x64 GNU through napi-rs's cross toolchain for its distribution compatibility floor and applies the upstream macOS deployment target. A FreeBSD 15 VM builds and uploads the thirteenth native target. These distribution jobs prove compilation and artifact generation; they do not extend the blocking runtime matrix beyond the three full native test jobs. A separate Ubuntu WASIP job installs the Rust target and Playwright Chromium, builds `@taffyjs/wasm`, reruns the complete Node public API suite against it, runs type, package-content, packed-consumer, bundled-consumer, and browser-runtime checks against the generated package, and applies the same Bun 1.2.0 and Deno 2.2.0 smoke checks to the public entry. That job also builds `@taffyjs/yoga-wasm`, reruns the complete maintained Yoga behavior and declaration suites, inspects and installs the packed package with npm and pnpm, exercises both public entries in bundled Chromium, and smoke-tests both entries with Bun 1.2.0 and Deno 2.2.0. Alternate-runtime smoke checks perform one fixed layout rather than copying the complete behavior suite. A Node-only job checks formatting, JavaScript and repository TypeScript including maintained tools through Vite+'s type-aware lint path, the alignment among target declarations and platform package metadata, and generated-source drift. A Rust-only job checks formatting and Clippy. Publication workflows are not configured.
 
 ## Public website
 

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: pnpm/setup@v2
         with:
           version: 11.20.0
-          runtime: node@22.18.0
+          runtime: node@22.20.0
           cache: true
           install: false
       - uses: dtolnay/rust-toolchain@stable
@@ -43,7 +43,7 @@ jobs:
       - uses: pnpm/setup@v2
         with:
           version: 11.20.0
-          runtime: node@22.18.0
+          runtime: node@22.20.0
           cache: true
           install: false
       - uses: dtolnay/rust-toolchain@stable
@@ -67,7 +67,7 @@ jobs:
       - uses: pnpm/setup@v2
         with:
           version: 11.20.0
-          runtime: node@22.18.0
+          runtime: node@22.20.0
           cache: true
           install: false
       - uses: dtolnay/rust-toolchain@stable
@@ -125,7 +125,7 @@ jobs:
       - uses: pnpm/setup@v2
         with:
           version: 11.20.0
-          runtime: node@22.18.0
+          runtime: node@22.20.0
           cache: true
           install: false
       - uses: dtolnay/rust-toolchain@stable
@@ -146,7 +146,7 @@ jobs:
         if: matrix.settings.target == 'i686-pc-windows-msvc'
         uses: actions/setup-node@v7
         with:
-          node-version: 22.18.0
+          node-version: 22.20.0
           architecture: x86
       - name: Build native target
         shell: bash
@@ -210,7 +210,7 @@ jobs:
       - uses: pnpm/setup@v2
         with:
           version: 11.20.0
-          runtime: node@22.18.0
+          runtime: node@22.20.0
           cache: true
           install: false
       - uses: dtolnay/rust-toolchain@stable
@@ -238,7 +238,7 @@ jobs:
       - uses: pnpm/setup@v2
         with:
           version: 11.20.0
-          runtime: node@22.18.0
+          runtime: node@22.20.0
           cache: true
           install: false
       - run: pnpm install --frozen-lockfile

README.md

@@ -28,9 +28,9 @@ npm install @taffyjs/node
 
 ## Runtime compatibility
 
-TaffyJS supports Node.js 22.18+, Bun 1.2+ within the Bun 1 major, and Deno 2.2+ within the Deno 2 major. CI runs the complete test suite on Node.js 22.18.0 and smoke-tests Bun 1.2.0 and Deno 2.2.0 by importing each implemented public package, computing a minimal layout, and verifying the result. Bun and Deno support follows one current major per runtime rather than spanning runtime majors.
+TaffyJS supports Node.js 22.20+, Bun 1.2+ within the Bun 1 major, and Deno 2.2+ within the Deno 2 major. CI runs the complete test suite on Node.js 22.20.0 and smoke-tests Bun 1.2.0 and Deno 2.2.0 by importing each implemented public package, computing a minimal layout, and verifying the result. Bun and Deno support follows one current major per runtime rather than spanning runtime majors.
 
-| Package              | Node.js 22.18+ | Bun 1.2+ | Deno 2.2+                                                                   |
+| Package              | Node.js 22.20+ | Bun 1.2+ | Deno 2.2+                                                                   |
 | -------------------- | -------------- | -------- | --------------------------------------------------------------------------- |
 | `@taffyjs/node`      | ✅             | ✅       | ✅ (local `node_modules`; `--allow-env`, `--allow-read`, and `--allow-ffi`) |
 | `@taffyjs/wasm`      | ✅             | ✅       | ✅ (without permission flags)                                               |

apps/website/guide/getting-started.md

@@ -14,7 +14,7 @@ Install `@taffyjs/node` with npm:
 npm install @taffyjs/node
 ```
 
-`@taffyjs/node` requires Node.js 22.18 or newer.
+`@taffyjs/node` requires Node.js 22.20 or newer.
 
 ## Start from CSS
 

apps/website/node/index.md

@@ -8,7 +8,7 @@ Read the [Design Philosophy](./design-philosophy.md) to understand why the API f
 
 ## Runtime support
 
-The package requires Node.js 22.18.0 or newer. Its native package metadata and distribution build matrix cover these targets:
+The package requires Node.js 22.20.0 or newer. Its native package metadata and distribution build matrix cover these targets:
 
 | Operating system | Architecture | Native target                   |
 | ---------------- | ------------ | ------------------------------- |

apps/website/wasm/index.md

@@ -32,7 +32,7 @@ The [Guide](../guide/getting-started.md) and [`TaffyTree` reference](../node/nod
 
 | Environment | Support                                                                                       |
 | ----------- | --------------------------------------------------------------------------------------------- |
-| Node.js     | Node.js 22.18 or newer                                                                        |
+| Node.js     | Node.js 22.20 or newer                                                                        |
 | Bun         | Version 1.2 or newer within the Bun 1 major                                                   |
 | Deno        | Version 2.2 or newer within the Deno 2 major, without permission flags                        |
 | Browser     | Applications built with a bundler that supports package export conditions and top-level await |