feat: monorepo modernization — pnpm 11 + Node 24, Docusaurus docs, React <Apollon> API, VS Code rewrite

[FelixTJDietrich]

Summary

This branch does three things that ship independently of each other:

1. Modernises the monorepo plumbing — pnpm 11.1.3 + Node 24.15.0 LTS, Vite everywhere, server CJS → ESM. One lockfile. No more webpack, no more Parcel, no more CJS/ESM coexistence dance.
2. Adds a real React API to the library — a <Apollon> component plus ApollonProvider, useApollonEditor, useApollonEditorOrThrow, useApollonSubscription. React-19-style onMount cleanup return, "use client" directive that actually survives the bundle. Webapp + VS Code editor migrated; zero new ApollonEditor(...) in repo outside the library itself.
3. Replaces the static Sphinx docs with a Docusaurus 3.10 site — Library / User / Contributor sidebars, a live in-browser editor on the landing page, deployed to GitHub Pages by a new docs.yml workflow on every push to main.

The library is dual-build by design: the default subpath (@tumaet/apollon) bundles React + MUI + emotion + xyflow so non-React hosts (Angular/Artemis is the primary consumer) install with zero peer deps. The /react subpath externalises them so React hosts can dedupe. Both subpaths share the same stylesheet via ./style.css.

Why this PR is large

The original scope was "pnpm + Node 24". Mid-review, two things became unavoidable:

• The library shipped as React-only mid-PR (commit c79683e8), which would have broken Artemis (Angular). That got reverted (c64d88b2); the dual-build is now part of the same PR because reverting it cleanly required tooling that didn't exist on main.
• The docs were Sphinx + ReadTheDocs and the requirements.txt/Makefile/bin/plantuml.jar machinery had to go anyway. Once Sphinx was out, Docusaurus and the React API were the natural place to land — and they reuse the same pnpm workspace plumbing this PR introduces.

Splitting into three PRs would have meant main ships in an awkward in-between state for two of the three weeks.

What changed, by concern

Build & toolchain

	Before	After
Package manager	npm	pnpm 11.1.3 (Corepack-verifiable SHA512 pin in packageManager)
Node	22	24.15.0 (.nvmrc, engines, Dockerfiles, all CI runners)
Bundlers	webpack + Parcel + Vite	Vite only (server: tsc)
Module system	mixed CJS / ESM	ESM end-to-end (server "type": "module", NodeNext, verbatimModuleSyntax)
Lockfiles	3 × package-lock.json	1 × pnpm-lock.yaml

The server migration alone is 22 source files / 76 import specifiers gaining .js suffixes plus a static import { ApollonEditor, importDiagram, ... } from "@tumaet/apollon" replacing the cargo-cult loadApollonModule = () => import(...) lazy wrapper. Express 5's automatic async-handler propagation lets routes/conversion.ts and middleware/validate.ts drop their try/catch ceremonies.

Library — public API

import { Apollon } from "@tumaet/apollon/react"
import "@tumaet/apollon/style.css"

<Apollon
  style={{ height: 600 }}
  defaultModel={savedDiagram}
  readonly={isReadonly}        // reactive
  onMount={(editor) => {        // React-19 cleanup-return idiom
    const id = editor.subscribeToModelChange(persist)
    return () => editor.unsubscribe(id)
  }}
/>

Props split into initial-only (snapshotted at mount; re-key to rebuild) and reactive (applied through the matching editor.setX(...) when the prop changes). The split is documented in source JSDoc, in /library/api, and in /library/embedding/react — and verified by a small Apollon.test.tsx that asserts the contract three ways (constructor argument shape, ref forwarding, reactive-setter dispatch).

Imperative ApollonEditor is unchanged for non-React hosts. The constructor still takes (element, options?); the standalone subpath still re-exports the full surface.

"use client" actually works. Rollup strips source-level directives during bundling; verified that the previous bundle started with var f0 = …, not "use client";. Re-added via Rollup output.banner on the peer pass only. head -1 dist/react/react.js now prints "use client"; — Next.js App Router consumers don't need a wrapper.

Library — bundle shape

Subpath	Peers	Bundle
@tumaet/apollon (default)	bundled	~2.4 MB
@tumaet/apollon/react	externalised	~875 KB raw / ~100 kB brotli
@tumaet/apollon/internals	(unstable; host integration tests)	~1 KB + reused yjs chunk
@tumaet/apollon/style.css	—	21 KB

peerDependenciesMeta.optional marks all six peers optional, so npm install @tumaet/apollon never warns about missing React/MUI/etc. — even though the default subpath inlines them.

VS Code extension

	Before	After
Extension main bundle	18.2 KB (webpack, 940 ms)	8.2 KB (Vite, 87 ms)
Menu webview	~360 KB (sunset UI toolkit)	146 KB (native HTML + VS Code CSS vars)
Editor webview theme	locked to setTheme("light")	follows VS Code's auto-applied light/dark/high-contrast
Deprecated runtime deps	4	0
Release pipeline	manual vsce from a laptop	GitHub Actions, environment-gated, sigstore-attested, dual-registry (Marketplace + Open VSX)

Dropped: @vscode/webview-ui-toolkit (Microsoft sunset 2026-01-06), styled-components, uuid, @vscode/codicons. Replacement is native HTML elements styled via var(--vscode-*) per Microsoft's post-deprecation guidance. The editor webview imports from @tumaet/apollon/react to share its React copy with the host webview.

Docs

Static Sphinx site → Docusaurus 3.10 at https://ls1intum.github.io/Apollon/. Three sidebars (Library / User / Contributor), live in-browser editor on the landing page (docs/src/components/ApollonEmbed), Diátaxis-shaped Library section, deployed by .github/workflows/docs.yml on every main push. onBrokenLinks: throw and onBrokenAnchors: throw keep cross-refs honest.

Monorepo hygiene

• pnpm catalogs for shared version pins (pnpm-workspace.yaml).
• Override floors tightened to the minimum fixed version per CVE (no more mass major-bumps).
• HEALTHCHECK in both Dockerfiles; digest-pinned base images.
• SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, .editorconfig, .gitattributes added.
• Renovate gains helpers:pinGitHubActionDigests so SHA pins don't rot.
• All third-party GitHub Actions are SHA-pinned with version comments.
• release-library.yml hardened against pnpm 11's varying pnpm pack --json output shape (pnpm/pnpm#10200).

Required GitHub setup before the first VS Code Marketplace release

release-vscode-extension.yml is gated on a vscode-marketplace Environment that doesn't exist on this repo yet — the workflow will hang on approval until it's created:

1. Settings → Environments → New environment → name vscode-marketplace
2. Deployment branches: "Selected branches and tags" → add main
3. Required reviewers: add the release maintainer; turn on Prevent self-review
4. Environment secrets:
   • VSCE_PAT — Azure DevOps PAT, scope Marketplace → Manage, 1-year max lifetime
   • OVSX_PAT — Open VSX PAT. The tumaet namespace must exist on open-vsx.org first; any namespace member can create it once with ovsx create-namespace tumaet -p <PAT>
5. Delete any pre-existing repo-level VSCE_PAT / OVSX_PAT — repo secrets bypass the environment's deployment-branch and reviewer controls.

Full checklist also at docs/contributor/deployment/npm-publishing.md.

How to review

The PR is large by line count but the architecture is small — three orthogonal concerns that don't touch each other much. Pick the angle that matches your expertise:

If you maintain the library

Focus on library/lib/components/react/ (~330 lines net new) and the dual-build in library/vite.config.ts. The questions worth answering:

1. Is the initial-only vs reactive prop split right? Apollon.tsx JSDoc lists which is which. Passing undefined to a reactive prop leaves the live value alone — re-key to fully reset.
2. Does onMount's cleanup-return ordering make sense? consumer cleanup → editor.destroy() → null the ref. The comment in Apollon.tsx explains why; the test Apollon.test.tsx pins it.
3. Is the "use client" banner the right escape hatch? Rollup strips the source directive. The vite.config.ts comment + head -1 dist/react/react.js should answer it.
4. Does the dual-build genuinely keep React out of the standalone subpath? Smoke test below.

If you maintain the standalone server / webapp / VS Code extension

The webapp + VS Code editor are migrated from imperative new ApollonEditor(...) to <Apollon>. grep -rn "new ApollonEditor" --include="*.tsx" outside library/ should return zero hits. ApollonWithConnection.tsx is the most complex consumer (collab cursors, version preview, autosave, WS) — focus there.

Server: 22 files gain .js import suffixes. The substantive changes are in conversion-service.ts (static import replacing lazy wrapper) and the Express-5 async-handler simplifications in routes/conversion.ts + middleware/validate.ts.

VS Code: editor/src/App.tsx now renders <Apollon> with a key={loadVersion} for "loadDiagram" remounts; the hand-rolled ApollonEditorContext/ApollonEditorComponent (which duplicated the library's ApollonProvider/useApollonEditor) is deleted.

If you maintain CI / deployment

Three new workflow files: docs.yml (GitHub Pages publish), release-vscode-extension.yml (sigstore + dual-registry), and the new library-node22-compat job in pr-health-checks.yml (the library still advertises engines.node: ">=22.0.0" for downstream consumers even though the monorepo is on 24).

The vscode-marketplace environment setup above is the only blocking action required.

If you're reviewing docs

The Library section follows Diátaxis: Quickstart (tutorial) → Embedding (how-to) → API (reference) → Troubleshooting (explanation/diagnosis). The API page is canonical: embedding pages link there for prop tables instead of duplicating. onBrokenLinks: throw in docusaurus.config.ts means the production build is a transitive link-check.

Steps for testing

# 1. Fresh install — expect a single pnpm-lock.yaml, zero ignored-build-script warnings,
#    no leftover package-lock.json files anywhere.
nvm install && nvm use
npm install -g pnpm@11.1.3
pnpm install

# 2. Build everything
pnpm build          # library + server + webapp (library first; tsc -b enforces order)
pnpm build:vscode   # extension + 2 webviews
pnpm build:docs     # library + Docusaurus site (onBrokenLinks: throw)

# 3. Lint + tests
pnpm lint           # ESLint per workspace + markdownlint (docs)
pnpm test           # 760 library unit tests
pnpm test:e2e       # Playwright

# 4. Verify the "use client" directive survives the bundle — this is the
#    headline correctness check for Next.js App Router consumers
head -1 library/dist/react/react.js          # → "use client";

# 5. Smoke-test both library subpaths in isolation
node --input-type=module -e \
  'import("./library/dist/index.js").then(m => console.log("standalone:", Object.keys(m).length, "exports"))'
node --input-type=module -e \
  'import("./library/dist/react/react.js").then(m => console.log("/react:", Object.keys(m).length, "exports"))'

The standalone resolves with no peer deps installed (Artemis case). The /react subpath resolves only when react, react-dom, @mui/material, @emotion/{react,styled}, and @xyflow/react are present. Both share the same ./style.css export.

Out of scope (deliberately deferred)

What	Why deferred	Tracked where
Library version bump from 4.4.0	version-bump.yml handles release bumps post-merge	Existing workflow
arethetypeswrong CI gate	Dropped in bb72249b — fflate streaming bug prevents tarball extraction on our shape; publint + exports-map check still cover it	Re-add when fflate lands a fix
React 19 in peer range	Reviewer-confirmed Round 6: narrow to ^18.3.0 matches reality. Widening requires a ref-type refactor (anchorRef: RefObject<SVGSVGElement | null> plus call-site adjustments where the SVG ref crosses SVGForeignObjectElement boundaries)	Follow-up PR
MUI emotion CSP 'unsafe-inline' in VS Code webviews	Needs a library cspNonce option threaded into emotion's createCache	emotion-js/emotion#403
Server unit-test isolation flake (tryAutoVersion races flushDb)	Pre-existing on main — verified by baseline	Unchanged scope
Mobile (iOS / Android) build pipeline	Capacitor dep cleanup is in scope; native builds are untouched	Future PR
export * barrel from lib/index.tsx still leaks ~33 unused identifiers (caught by knip)	Cutting them is SemVer-major	Next release bump

Screenshots

No UI changes inside Apollon itself. The VS Code editor webview now follows VS Code's theme automatically (light/dark/high-contrast); it used to be locked to light. The Docusaurus site is the new public-facing surface — landing page at docs/src/pages/index.tsx, hosted at https://ls1intum.github.io/Apollon/ after merge.

Checklist

• No linked issue — foundational migration, not a tracked feature
• Library version unchanged (4.4.0, matches main) — release bump handled by version-bump.yml post-merge
• Dual-build preserved: Angular hosts (Artemis primary) install with zero peer deps; React hosts opt into /react
• "use client"; directive present at byte 0 of dist/react/react.js (the previous bundle was silently missing it)
• Docusaurus build clean (onBrokenLinks: throw, onBrokenAnchors: throw)
• All required CI workflows green on the latest push

[Claudia-Anthropica]

@FelixTJDietrich Big, well-structured migration — pnpm wiring, CHANGELOG, README, security overrides, SHA-pinned actions/images, the OVSX checksum-verify retry, and the Node-22 compat job for the library all look great. Two things worth syncing on before merge: the PR description still describes the original dual-build design (@tumaet/apollon/react + optional peers) that was pivoted away from in c79683e8 refactor(library)!: single bundle with mandatory peers, v5.0.0 — the CHANGELOG/README are correct, but anyone reading the PR description thinks default behavior is unchanged when it's actually breaking for non-React consumers. Codacy also flagged 22 stylelint notices in the new webview CSS (color-hex-length, rule-empty-line-before, no-descending-specificity) plus 3 false-positive Dockerfile warnings (your images ARE SHA-pinned — that's stricter than tag-pinning, Codacy just doesn't recognize the digest syntax). Inline comments below.

[Claudia-Anthropica]

@FelixTJDietrich Re-reviewed the React-migration commits since my last pass and the new code is in great shape — the <Apollon> component (snapshot-vs-reactive prop split, re-key-to-remount, the onMount cleanup ordering) and the migration of ApollonLocal / ApollonPlayground / ApollonWithConnection and the VS Code editor onto it all look correct. The one thing still blocking is CI: lint-and-format-check is red because the docs typecheck still runs before the library build, so @tumaet/apollon/react (now imported in ApollonEmbed) can't resolve — same root cause as the open docs/package.json thread where lint:md && typecheck regrew. Drop typecheck from the concurrent docs lint (or sequence it after the build) and this is good to go.

[Claudia-Anthropica]

@FelixTJDietrich The "use client" banner fix (Rollup strips the source directive, so re-adding it via the peer build's output banner is the right call), the destroy() logging, and the comment/test trims all look fine — and I checked that the defaultType drop in the playground is safe since the editor falls back to model.type. One real regression though: the bloat-cut in ApollonWithConnection removed the readonly restore on preview exit, so the canvas gets stuck read-only after exiting a version preview — details inline. CI is also still red on the same docs typecheck build-order issue from the open docs/package.json thread (@tumaet/apollon/react can't resolve before the library builds).

[Claudia-Anthropica]

@FelixTJDietrich All three threads from last round are properly addressed — docs lint is back to lint:md (CI green again), setReadonly(baseReadonly) is restored on preview exit with a clear comment, and the peer range is honestly back to ^18.3.0. Nice work. One new thing slipped into the "fix factual drift" pass: the README/overview bundle footnote claims Yjs is lazy-loaded only under collaborationEnabled, but it's eagerly loaded for every editor. Worth correcting before this hits npm since the README is the package's front page — details inline.

[Claudia-Anthropica]

@FelixTJDietrich The bundle-table fix is correct — Yjs really does load eagerly (static import * as Y from "yjs" across lib/, unconditional new Y.Doc() + new YjsSync(...) in the constructor, no dynamic import() in lib/), so collapsing the split-with-footnote into one honest ~2.4 MB total in both README and overview is the right call. That clears the last open thread on my side and the rest of the PR is unchanged from prior rounds. Approving.

[tamang29]

LGTM!
Tested standalone application, capacitor and vs-code extension.
Everything working as expected ✅