Support Node 22 and pnpm 10

Author: Doppp

.github/workflows/compatibility.yml

@@ -0,0 +1,37 @@
+name: Toolchain compatibility
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Node ${{ matrix.node }} / pnpm ${{ matrix.pnpm }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - node: 22.22.2
+            pnpm: 10.26.0
+          - node: 24.18.0
+            pnpm: 11.15.1
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/action-setup@v6
+        with:
+          version: ${{ matrix.pnpm }}
+          run_install: false
+      - uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node }}
+          cache: pnpm
+      - run: pnpm --version
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - run: pnpm build

AGENTS.md

@@ -24,7 +24,9 @@ When requirements conflict, follow `docs/PRD.md`, then document the conflict and
 - Do not add accounts, databases, analytics, audio, hosted application services, or a visual authoring system. A static GitHub Pages landing site is required.
 - Do not replace plain Markdown with MDX.
 - Do not add custom Markdown directives beyond `explorable` and `exercise`.
-- Preserve TypeScript 7, Node.js 24 LTS, and pnpm 11 unless a verified incompatibility requires an ADR.
+- Preserve TypeScript 7, the default Node.js 24 LTS/pnpm 11 toolchain, and the
+  tested Node.js 22/pnpm 10 compatibility floor unless a verified
+  incompatibility requires an ADR.
 - Keep course code out of the main runtime document context.
 - Keep Codex and Claude Code Desktop support as thin adapters over the same host-neutral course format.
 - Treat sandboxing, accessibility, validation, and clean-checkout reproducibility as required features.

CODEX_BUILD_PROMPT.md

@@ -75,8 +75,8 @@ The completed repository must let a learner:
 Follow these unless the PRD explicitly says otherwise:
 
 - TypeScript 7.0
-- Node.js 24 LTS
-- pnpm 11
+- Node.js 24 LTS by default; support Node.js 22.22.2+ within the 22.x line
+- pnpm 11 by default; support pnpm 10.26.0+
 - Plain Markdown, not MDX
 - React for the runtime shell only
 - Vite for development and bundling

CONTRIBUTING.md

@@ -5,7 +5,8 @@ Thank you for improving `explorables`. By participating, follow the
 
 ## Local setup
 
-Use Node.js 24 LTS and pnpm 11:
+Use Node.js 22.22.2+ (22.x) or 24.15.0+ (24.x), with pnpm 10.26.0+ (10.x) or
+pnpm 11. Node.js 24 and pnpm 11 remain the default toolchain:
 
 ```bash
 pnpm install --frozen-lockfile

README.md

@@ -30,12 +30,13 @@ Install and launch explorables from https://github.com/Doppp/explorables.
 Create a new `explorables` folder in my Documents folder. If that folder
 already exists, do not overwrite it; ask me what to do. Clone the repository
 using HTTPS, read its `AGENTS.md`, and follow its instructions. Check for
-Node.js 24 and pnpm 11, but ask before installing or changing system software.
-Install the locked dependencies with `pnpm install --frozen-lockfile`, run
-`pnpm course`, and open the printed local course library. Help me choose a
-course, then read that course's `AGENTS.md` and follow its tutoring policy. Ask
-me to predict, let me attempt exercises, run tests, and give the smallest useful
-hint before showing more.
+Node.js 22.22.2 or newer in the 22.x line, or Node.js 24.15.0 or newer in the
+24.x line, and pnpm 10.26.0+ (10.x) or pnpm 11, but ask before installing or
+changing system software. Install the locked dependencies with
+`pnpm install --frozen-lockfile`, run `pnpm course`, and open the printed local
+course library. Help me choose a course, then read that course's `AGENTS.md` and
+follow its tutoring policy. Ask me to predict, let me attempt exercises, run
+tests, and give the smallest useful hint before showing more.
 ```
 
 Codex will ask for permission before running some commands or accessing a
@@ -50,7 +51,10 @@ server, or explorables account is required.
 
 ## Manual quick start
 
-Requirements: Node.js 24 LTS and pnpm 11.
+Requirements: Node.js 22.22.2+ (22.x) or 24.15.0+ (24.x), and pnpm 10.26.0+
+(10.x) or pnpm 11.
+Node.js 24 with pnpm 11 remains the default development and deployment
+toolchain.
 
 ```bash
 git clone https://github.com/Doppp/explorables.git

docs/PRD.md

@@ -1026,7 +1026,8 @@ Explorable dependencies are bundled before loading into the iframe. Runtime impo
 
 ## 11.4 Dependency security
 
-The reference implementation uses pnpm 11 with a committed lockfile.
+The reference implementation defaults to pnpm 11 with a committed lockfile and
+maintains backward compatibility with pnpm 10.26.0 and newer 10.x releases.
 
 Course dependencies must:
 
@@ -1213,8 +1214,8 @@ or hidden assessment data.
 | Area | Choice |
 |---|---|
 | Language | TypeScript 7.0 |
-| Runtime | Node.js 24 LTS |
-| Package manager | pnpm 11 |
+| Runtime | Node.js 24 LTS default; Node.js 22.22.2+ compatible |
+| Package manager | pnpm 11 default; pnpm 10.26.0+ compatible |
 | Monorepo | pnpm workspaces |
 | Dev server and bundling | Vite |
 | Runtime UI shell | React |
@@ -1269,7 +1270,10 @@ The project should not depend on custom TypeScript language-service plugins in v
 
 ## 14.4 Node.js policy
 
-Use Node.js 24 LTS for production and CI.
+Use Node.js 24 LTS as the default for production and deployment CI. Also test
+and support Node.js 22 from 22.22.2 onward while that release line remains LTS.
+The lower bound follows the strictest dependency in the committed lockfile;
+older Node.js 22 releases are not supported.
 
 A `.node-version` file should pin the supported major version:
 
@@ -1279,7 +1283,9 @@ A `.node-version` file should pin the supported major version:
 
 ## 14.5 Package manager policy
 
-Use pnpm 11 because it provides:
+Use pnpm 11 by default and keep the committed lockfile installable with pnpm
+10.26.0 and newer 10.x releases. The pnpm 10 lower bound is the first release
+with the workspace's `allowBuilds` setting. Both supported majors provide:
 
 - Strong workspace support
 - Reproducible lockfiles

docs/course-roadmap.md

@@ -284,8 +284,9 @@ versioned educational contract.
   prompt, text alternative, and primary-source references where applicable.
 - All required work runs locally without accounts, APIs, GPUs, or weight
   downloads.
-- Every course validates, tests, and builds from a clean checkout under Node 24
-  and pnpm 11.
+- Every course validates, tests, and builds from a clean checkout under the
+  default Node.js 24/pnpm 11 toolchain and the supported Node.js 22/pnpm 10
+  compatibility floor.
 - Codex and Claude Code Desktop tutor every course through the same
   host-neutral format.
 - Learner evidence shows that transitions from foundation to shared core to a

docs/decisions/0006-node-pnpm-backward-compatibility.md

@@ -0,0 +1,56 @@
+# ADR 0006: Node.js and pnpm backward compatibility
+
+Status: accepted
+Date: 15 August 2026
+
+## Context
+
+The original implementation treated Node.js 24 and pnpm 11 as exclusive
+versions. That made the initial clean-checkout target unambiguous, but it also
+rejected maintained installations that the current toolchain can support.
+Node.js 22 remains an LTS release, and pnpm documents both majors 10 and 11 as
+compatible with Node.js 22 and 24.
+
+The committed dependency graph prevents a broader Node.js claim. In
+particular, `jsdom@30.0.1` requires Node.js 22.22.2 or Node.js 24.15.0 at
+minimum. Node.js 20 is end-of-life and is not a support target. The pnpm 9.0
+lockfile format can be installed by pnpm 10 and 11.
+
+## Decision
+
+Keep Node.js 24 and pnpm 11 as the default development and GitHub Pages
+deployment toolchain. Support these additional backward-compatible boundaries:
+
+- Node.js 22 from 22.22.2 through the end of the 22.x line;
+- pnpm 10.26.0 and newer 10.x releases, as well as pnpm 11.x. pnpm 10.26.0 is
+  the first release with the workspace's `allowBuilds` setting.
+
+The root `engines` field enforces those ranges. The former exact
+`packageManager` field is removed because pnpm uses it to download and execute
+pnpm 11 even when the user explicitly invokes pnpm 10; retaining it would make
+pnpm 10 support nominal rather than real. GitHub Actions continues to pin pnpm
+11.15.1 as the default. Compatibility CI installs the frozen lockfile and runs
+the full check and build suite at the oldest supported Node major/pnpm major
+pairing and the default pairing.
+
+Support follows maintained Node.js LTS lines and is not extended to Node.js 20
+or odd-numbered, end-of-life releases. A dependency upgrade that raises the
+minimum patch version must update the engine range, CI matrix, documentation,
+and this decision's consequences together.
+
+## Consequences
+
+- Learners and contributors can use maintained Node.js 22 environments and
+  pnpm 10 without bypassing engine checks.
+- Node.js 24/pnpm 11 remains the single default, avoiding ambiguous setup
+  instructions and deployment drift.
+- Backward compatibility is an exercised contract rather than an untested
+  semver declaration.
+- The supported Node.js 22 window ends when upstream Node.js support ends or a
+  verified required dependency makes it infeasible; either change requires a
+  new ADR.
+
+## References
+
+- https://nodejs.org/en/about/previous-releases
+- https://pnpm.io/installation#compatibility

docs/deployment.md

@@ -12,10 +12,12 @@ deployment branch.
 
 ## GitHub Pages
 
-`.github/workflows/pages.yml` installs the pinned Node 24 and pnpm 11 versions
-from the lockfile, validates and tests the repository, builds `apps/site`,
-uploads its static output, and deploys through the `github-pages` environment.
-It runs on pushes to `master` and manual dispatch.
+`.github/workflows/pages.yml` installs the default pinned Node 24 and pnpm 11
+versions from the lockfile, validates and tests the repository, builds
+`apps/site`, uploads its static output, and deploys through the `github-pages`
+environment. It runs on pushes to `master` and manual dispatch. A separate
+compatibility workflow verifies the same frozen lockfile under the supported
+Node.js 22/pnpm 10 and Node.js 24/pnpm 11 boundaries.
 
 Repository Pages settings must use GitHub Actions as the build type. The REST
 equivalent after the workflow exists is:

docs/implementation-plan.md

@@ -9,7 +9,8 @@ is committed and pushed to `master` after its checks pass.
 - Local-first course folders; no accounts, database, analytics, backend, audio,
   hosted execution, catalogue service, or LMS features.
 - Plain Markdown with only `explorable` and `exercise` directives.
-- Node.js 24 LTS, pnpm 11, TypeScript 7, React/Vite, unified/remark/rehype,
+- Node.js 24 LTS and pnpm 11 by default, with Node.js 22.22.2+ and pnpm 10.26.0+
+  compatibility; TypeScript 7, React/Vite, unified/remark/rehype,
   Zod, Biome, Vitest, Playwright, and axe-core.
 - Course JavaScript runs only in sandboxed iframes with network access denied.
 - `AGENTS.md` is canonical; `CLAUDE.md` and `.claude/launch.json` are thin
@@ -99,7 +100,8 @@ Deliverables:
 
 Final verification:
 
-1. Install using the committed lockfile under Node 24 and pnpm 11.
+1. Install using the committed lockfile under the default Node 24/pnpm 11
+   toolchain and the Node 22/pnpm 10 compatibility floor.
 2. Run formatting/lint, typecheck, unit, integration, browser, accessibility,
    validator, all-package build, site build/test, and both example validations.
 3. Scaffold and verify a course in a temporary directory.
@@ -161,5 +163,19 @@ Deliverables:
 
 Exit check: collection and standalone validation/build pass; browser tests
 cover selection, planned states, deep links, guidance, sandboxing, narrow
-layout, and axe; the full repository check and build pass under Node 24 and
-pnpm 11.
+layout, and axe; the full repository check and build pass under the default
+Node 24/pnpm 11 toolchain and the Node 22/pnpm 10 compatibility floor.
+
+## Milestone 9 — supported toolchain compatibility
+
+Deliverables:
+
+- Keep Node.js 24 and pnpm 11 as the default development and deployment
+  toolchain.
+- Accept Node.js 22.22.2+ within the 22.x LTS line and pnpm 10.26.0+.
+- Verify frozen installs, checks, and builds at both compatibility boundaries in
+  GitHub Actions.
+- Document the support window and dependency-derived minimum versions.
+
+Exit check: the frozen lockfile installs and the full check/build suite passes
+under Node.js 22 with pnpm 10 and Node.js 24 with pnpm 11.