feat(library)!: consolidate @tumaet/apollon to a single entry with required peers (#785)

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/library-theming-api.md

@@ -5,7 +5,7 @@
 Adds a public theming API for embedding hosts. You can now theme the editor with a typed helper instead of hand-writing CSS variables: `createApollonTheme()` maps a structured `ApollonTheme` (primary, background, grid, etc.) to the underlying `--apollon-*` custom properties, and `<Apollon>` accepts optional `theme` and `dataTheme` props (also available as `ApollonOptions` fields) that are applied to the editor mount node.
 
 ```ts
-import { Apollon, createApollonTheme } from "@tumaet/apollon/react"
+import { Apollon, createApollonTheme } from "@tumaet/apollon"
 
 <Apollon theme={createApollonTheme({ primary: "#6d28d9", background: "#0b0b0c" })} dataTheme="dark" />
 ```

.changeset/single-external-entry.md

@@ -0,0 +1,15 @@
+---
+"@tumaet/apollon": major
+---
+
+Everything ships from one entry now: `@tumaet/apollon` exports the `<Apollon>` React component, the hooks, the provider, and the imperative `ApollonEditor` API together, with every dependency external. `react`, `react-dom`, and `@xyflow/react` are required peers alongside `yjs` / `y-protocols`, so your app and the editor share a single copy of each — no duplicate React, and your bundle analyzer / SBOM sees the real packages instead of a copy inlined into one chunk.
+
+If you imported from the `/react` or `/external` subpaths, switch to `@tumaet/apollon`:
+
+- `@tumaet/apollon/external` → `@tumaet/apollon` — same `ApollonEditor` API, just drop the subpath.
+- `@tumaet/apollon/react` → `@tumaet/apollon` — the component, hooks, and provider are on the main entry.
+- Install the peers if you haven't: `react react-dom @xyflow/react` (npm 7+ auto-installs them; pnpm/yarn users add them explicitly).
+- The main entry is a client module (`"use client"`) — import it from client components, not React Server Components.
+- `@tumaet/apollon/internals` and `@tumaet/apollon/export` are unchanged.
+
+See the [Upgrading guide](https://ls1intum.github.io/Apollon/library/upgrading) for the full walkthrough.

.github/pull_request_template.md

@@ -29,5 +29,6 @@ Write "n/a — no Changesets-tracked package changed" if this PR doesn't touch @
 - [ ] Added a changeset whose summary is written in the user's voice (`pnpm changeset`, [how](https://ls1intum.github.io/Apollon/contributor/development/release-notes/)) — or this PR doesn't touch a Changesets-tracked package (`@tumaet/apollon`, `@tumaet/webapp`, `@tumaet/server`)
 - [ ] PR title's Conventional Commit type (`feat`/`fix`/…) matches the kind of change — it groups the release note
 - [ ] Tests added or updated
+- [ ] Ran `pnpm lint && pnpm format:check && pnpm build && pnpm test` locally — green
 - [ ] Documentation updated (if applicable)
 - [ ] Screenshots or screencasts attached (if a UI change)

.github/workflows/pr-health-checks.yml

@@ -38,6 +38,8 @@ jobs:
               - 'library/**'
               - 'standalone/**'
               - 'vscode-extension/**'
+              - 'docs/**'
+              - 'scripts/**'
               - 'package.json'
               - 'pnpm-lock.yaml'
               - 'pnpm-workspace.yaml'
@@ -138,9 +140,22 @@ jobs:
         # needs `library/dist/` to exist — keep this step after build.
         run: pnpm --filter @tumaet/apollon-docs run typecheck
 
+      - name: Typecheck doc code examples
+        # Compiles the ```ts / ```tsx examples in library/README.md,
+        # library/THEMING.md and docs/library/** against the real
+        # @tumaet/apollon types — fails if the public API drifts from the
+        # docs. Resolves through docs/node_modules → library/dist, so it must
+        # run after the build above.
+        run: pnpm run check:doc-snippets
+
       - name: Run unit tests
         run: pnpm run test
 
+      - name: Typecheck @tumaet/ui (incl. stories)
+        # The declaration build excludes stories/tests (they are not public API),
+        # so type-check the full source here to keep stories type-safe.
+        run: pnpm --filter @tumaet/ui run typecheck
+
       - name: Run shared-ui unit tests
         # The @tumaet/ui component suite (Base UI primitives + a11y behaviour).
         run: pnpm --filter @tumaet/ui run test
@@ -339,10 +354,10 @@ jobs:
         run: |
           node --input-type=module -e '
             const root = import.meta.resolve("@tumaet/apollon");
-            const react = import.meta.resolve("@tumaet/apollon/react");
             const internals = import.meta.resolve("@tumaet/apollon/internals");
+            const exportEntry = import.meta.resolve("@tumaet/apollon/export");
             const css = import.meta.resolve("@tumaet/apollon/style.css");
-            console.log({ root, react, internals, css });
+            console.log({ root, internals, exportEntry, css });
           '
 
       - name: Lint published package shape (publint)
@@ -355,10 +370,8 @@ jobs:
       # decompressed buffer on each chunk callback instead of accumulating.
       # Any tarball that decompresses across multiple fflate chunks (ours
       # is ~750 KB → 3 chunks) crashes with `Cannot read properties of
-      # undefined (reading 'filename')`. The standalone subpath
-      # deliberately bundles peers (~2.4 MB) so the tarball is over
-      # threshold by design. `publint` above plus the `import.meta.resolve`
-      # exports-map check below cover the same ground.
+      # undefined (reading 'filename')`. `publint` above plus the
+      # `import.meta.resolve` exports-map check below cover the same ground.
       - name: Enforce bundle-size budget
         working-directory: library
         # Budgets in library/package.json#size-limit. Fails on regression

.gitignore

@@ -76,3 +76,6 @@ docs/build/
 
 # Stray pnpm store if pnpm is run outside the workspace root
 .pnpm-store/
+
+# Temp dir used by scripts/check-doc-snippets.mjs (removed on each run)
+docs/.snippet-typecheck/

AGENTS.md

@@ -13,7 +13,7 @@ Conventions for AI coding agents in this repo, the TUM UML diagram editor. Follo
 
 A pnpm + Vite monorepo (the server compiles with `tsc`, not Vite).
 
-- **`library/`** — `@tumaet/apollon`, the embeddable React editor, published to npm. Native HTML + Base UI primitives (`@base-ui-components/react`) styled via `--apollon-*` CSS variables; `lucide-react` icons; Yjs collaboration — the live-cursor/presence layer lives here ([`collaboration.md`](docs/library/api/collaboration.md)).
+- **`library/`** — `@tumaet/apollon`, the embeddable React editor, published to npm. Native HTML + Base UI primitives (`@base-ui/react`) styled via `--apollon-*` CSS variables; `lucide-react` icons; Yjs collaboration — the live-cursor/presence layer lives here ([`collaboration.md`](docs/library/api/collaboration.md)).
 - **`standalone/webapp/`** — `@tumaet/webapp` (private). React + Vite + Tailwind; Capacitor for iOS/Android.
 - **`standalone/server/`** — `@tumaet/server` (private). Express + Redis Stack (RedisJSON diagram storage + version history).
 - **`vscode-extension/`** — `apollon-vscode`, with nested `menu/` and `editor/` webview sub-packages.

README.md

@@ -15,13 +15,13 @@ This monorepo contains every piece of the Apollon platform:
 ## Use the library
 
 ```sh
-npm install @tumaet/apollon yjs y-protocols
+npm install @tumaet/apollon react react-dom @xyflow/react yjs y-protocols
 ```
 
-`yjs` and `y-protocols` are required peer dependencies — they power Apollon's
-document model and undo/redo (and live collaboration when enabled), kept
-external so the host owns a single Yjs instance. See the
-[library README](./library/README.md) for the API and the other build entries.
+`react`, `react-dom`, `@xyflow/react`, `yjs`, and `y-protocols` are required
+peer dependencies — the editor renders on the host's single React and Yjs
+instance instead of bundling its own. See the
+[library README](./library/README.md) for the full API and per-framework guides.
 
 ## Run the stack locally
 

docs/contributor/development/scripts.md

@@ -70,8 +70,9 @@ Run a production build locally — assumes `pnpm build` already ran.
 Per-workspace variants (`lint:ui`, `lint:lib`, `lint:server`, `lint:webapp`,
 `lint:vscode`, `lint:docs`, and their `lint:fix:*` counterparts) exist for
 narrower runs.
-`lint:docs` runs `markdownlint-cli2` over the docs Markdown **and** `tsc
---noEmit` on the Docusaurus config + theme.
+`lint:docs` runs `markdownlint-cli2` over the docs Markdown. Type-checking — the
+Docusaurus config/theme (`typecheck`) and the doc code examples
+(`check:doc-snippets`) — runs separately in CI, not as part of `lint`.
 
 ## Test
 
@@ -93,15 +94,41 @@ Playwright visual regression lives in the webapp workspace — see
 
 ## Docs
 
-| Script            | Does                                           |
-| ----------------- | ---------------------------------------------- |
-| `pnpm dev:docs`   | Library build, then the Docusaurus dev server  |
-| `pnpm build:docs` | Library build, then the static Docusaurus site |
+| Script                    | Does                                                   |
+| ------------------------- | ------------------------------------------------------ |
+| `pnpm dev:docs`           | Library build, then the Docusaurus dev server          |
+| `pnpm build:docs`         | Library build, then the static Docusaurus site         |
+| `pnpm check:doc-snippets` | Library build, then type-check the docs' code examples |
 
 The docs site is published at <https://ls1intum.github.io/Apollon/>. The
 Docusaurus build uses `onBrokenLinks: "throw"`, so a bad internal link fails
 `build:docs`.
 
+### Doc code examples are type-checked
+
+`check:doc-snippets` (`scripts/check-doc-snippets.mjs`) compiles every fenced
+`ts`/`tsx` block in `library/README.md`, `library/THEMING.md`, and
+`docs/library/**` against the **real** built `@tumaet/apollon` types, so a public
+API change that breaks a documented example fails CI (`pr-health-checks`) instead
+of shipping rotten docs. Each block is checked as a standalone module, so it must
+carry its own imports.
+
+Mark a block `no-check` in the fence info string to skip it — for bare fragments
+that reference an undeclared `editor`, type-signature illustrations, or
+framework-specific examples (`@angular/core`, `next/dynamic`, the resvg `?url`
+wasm import) that can't compile in isolation:
+
+````md
+```ts no-check
+editor.fitView() // `editor` is illustrative, not declared here
+```
+````
+
+The `no-check` token lives after the language in the info string, which
+Docusaurus, GitHub, and npm all ignore when rendering — readers never see it.
+Prefer making a block self-contained (add the imports) over `no-check` when it's
+a real copy-paste example.
+
 ## Capacitor
 
 Mobile shell scaffolding for the webapp. Run these once per platform; see

docs/contributor/overview.md

@@ -36,7 +36,7 @@ pnpm dev
 ## Pull-request checklist
 
 ```sh
-pnpm run lint        # eslint per workspace + markdownlint + docs typecheck
+pnpm run lint        # eslint per workspace + markdownlint
 pnpm run format:check
 pnpm run build       # library first, then server + webapp concurrently
 pnpm test            # library unit tests

docs/library/api.md

@@ -10,7 +10,7 @@ description: The complete ApollonEditor reference — constructor options, lifec
 into the DOM node you hand it and exposes an imperative API — your host code
 never touches React.
 
-```ts
+```ts no-check
 import { ApollonEditor, UMLDiagramType } from "@tumaet/apollon"
 import "@tumaet/apollon/style.css"
 
@@ -29,11 +29,11 @@ documented below remains the API for non-React hosts and for advanced control.
 
 For React hosts, `<Apollon>` wraps `ApollonEditor` and owns its lifecycle: it
 constructs the editor on mount and destroys it on unmount. Import it from the
-`@tumaet/apollon/react` subpath — see [React](/library/embedding/react) for
+package's main entry, `@tumaet/apollon` — see [React](/library/embedding/react) for
 the full integration story (hooks, provider, ref, controlled-model overlay).
 
 ```tsx
-import { Apollon } from "@tumaet/apollon/react"
+import { Apollon } from "@tumaet/apollon"
 import "@tumaet/apollon/style.css"
 ;<Apollon style={{ height: 600 }} />
 ```
@@ -97,7 +97,7 @@ live value untouched (no reset). Re-key the component to fully reset.
 
 ## Constructor
 
-```ts
+```ts no-check
 new ApollonEditor(element: HTMLElement, options?: ApollonOptions)
 ```
 
@@ -212,7 +212,7 @@ prev/next equality check.
 | `subscribeToCollaboratorChanges(cb)` | `(collaborators: CollaboratorInfo[]) => void`       |
 | `unsubscribe(subscriptionId)`        | `(number) => void`                                  |
 
-```ts
+```ts no-check
 const id = editor.subscribeToModelChange((model) => persist(model))
 // later
 editor.unsubscribe(id)