Merge remote-tracking branch 'origin/main' into feat/issue-757-migrate-mui-to-shadcn

# Conflicts:
#	docs/library/embedding/install.md
#	docs/library/overview.md
#	docs/library/quickstart.md
#	library/package.json
#	library/vite.config.ts
#	pnpm-lock.yaml

Author: FelixTJDietrich

.changeset/externalize-yjs-peer-dependency.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/apollon": minor
+---
+
+Two packaging improvements for embedding hosts. First, `yjs` and `y-protocols` are now required peer dependencies instead of being bundled, so your app and Apollon share a single Yjs instance — no duplicate payload and no cross-instance document errors. Second, a new `@tumaet/apollon/external` entry exposes the same imperative `ApollonEditor` API as the default entry but leaves **every** dependency external (React, xyflow, Base UI, lucide, @dnd-kit, zustand, uuid, @chenglou/pretext, …) — so a bundler host of any framework resolves and de-duplicates each one from its own `node_modules` and gets full supply-chain / SBOM visibility, instead of a copy inlined invisibly into the bundle. The default `@tumaet/apollon` (self-contained) and `@tumaet/apollon/react` entries are unchanged. Action required only if you adopt the new entry or the Yjs peer: install the corresponding peers (most package managers do this automatically).

README.md

@@ -15,10 +15,13 @@ This monorepo contains every piece of the Apollon platform:
 ## Use the library
 
 ```sh
-npm install @tumaet/apollon
+npm install @tumaet/apollon yjs y-protocols
 ```
 
-See the [library README](./library/README.md) for the API.
+`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.
 
 ## Run the stack locally
 
@@ -52,7 +55,7 @@ To preview the documentation site instead, run `pnpm dev:docs` from the repo roo
 | ------------- | -------------------------------------------------------------------- |
 | Library       | React, TypeScript, React Flow (`@xyflow/react`), Yjs, Zustand, Vite  |
 | Server        | Express 5, Redis (RedisJSON), WebSocket relay                        |
-| Webapp        | React, TypeScript, Vite, MUI, Tailwind                               |
+| Webapp        | React, TypeScript, Vite, shadcn-style UI (Base UI), Tailwind         |
 | Storage       | Redis with RedisJSON (diagrams expire after 120 days via native TTL) |
 | Reverse proxy | Traefik v3 (production)                                              |
 

docs/library/embedding/angular.md

@@ -7,8 +7,8 @@ description: Embed Apollon in an Angular host using the default standalone bundl
 # Angular
 
 Use the **standalone subpath** (`@tumaet/apollon`). Angular hosts get the
-editor with **zero peer deps** to install — React is bundled inside the
-tarball.
+editor with React bundled inside the tarball; the only peers to install are
+`yjs` and `y-protocols` (`npm install @tumaet/apollon yjs y-protocols`).
 
 ```ts
 import {

docs/library/embedding/install.md

@@ -6,23 +6,32 @@ description: Install @tumaet/apollon — pick the standalone or /react subpath.
 
 # Install
 
+`yjs` and `y-protocols` are required peer dependencies of **every** build — they
+power Apollon's document model and undo/redo (and live collaboration when
+enabled), so the editor needs them whether or not you collaborate. Keeping them
+external lets a host that already uses Yjs share a single instance instead of a
+private, possibly mismatched copy. Most package managers install missing peers
+automatically.
+
 ## Standalone build (any framework)
 
 ```sh
-npm install @tumaet/apollon
+npm install @tumaet/apollon yjs y-protocols
 ```
 
 ```ts
 import { ApollonEditor } from "@tumaet/apollon"
 import "@tumaet/apollon/style.css"
 ```
 
-No further installs — React and xyflow are bundled inside the library tarball.
+React, Base UI, lucide, and xyflow are bundled inside the library tarball; only
+`yjs` and `y-protocols` are peers you provide.
 
 ## Peer-dependency build (React hosts)
 
 ```sh
 npm install @tumaet/apollon \
+  yjs y-protocols \
   react react-dom \
   @xyflow/react
 ```
@@ -32,16 +41,45 @@ import { ApollonEditor } from "@tumaet/apollon/react"
 import "@tumaet/apollon/style.css"
 ```
 
+`yjs` and `y-protocols` are required for every build; the React and xyflow peers
+below are needed by the `/react` and `/external` builds.
+
 | Peer            | Range     |
 | --------------- | --------- |
-| `react`         | `^18.3.0` |
-| `react-dom`     | `^18.3.0` |
-| `@xyflow/react` | `^12.3.0` |
+| `yjs`           | `^13.6.0` |
+| `y-protocols`   | `^1.0.6`  |
+| `react`         | `^19.0.0` |
+| `react-dom`     | `^19.0.0` |
+| `@xyflow/react` | `^12.9.0` |
 
 The `/react` subpath keeps your final bundle from shipping a second copy of
 React. It is also the entry that exports the `<Apollon>` React component — the
 recommended way to embed in React. See [React](/library/embedding/react).
 
+## Fully external build (any bundler host)
+
+```sh
+npm install @tumaet/apollon \
+  yjs y-protocols \
+  react react-dom \
+  @xyflow/react
+```
+
+```ts
+import { ApollonEditor } from "@tumaet/apollon/external"
+import "@tumaet/apollon/style.css"
+```
+
+Same imperative `ApollonEditor` API as the default entry, but **every**
+dependency is external — the React family above _and_ Apollon's own runtime
+deps (`@base-ui/react`, `lucide-react`, `@dnd-kit`, `zustand`, `uuid`,
+`@chenglou/pretext`), which arrive transitively with the package. Your bundler
+resolves and de-duplicates each one against your app's `node_modules`, and your
+bundle analyzer / SBOM tooling sees them as real packages instead of code
+inlined invisibly into one chunk. Use it from any framework with a bundler,
+including non-React ones (the editor still runs on the React you provide
+internally; your own code never touches it).
+
 ## Type definitions
 
-Types ship with the package (`dist/index.d.ts`) and are identical for both subpaths. Requires TypeScript 5.0+ with `moduleResolution: "bundler" | "node16" | "nodenext"`.
+Types ship with the package (`dist/index.d.ts`) and are identical for every subpath. Requires TypeScript 5.0+ with `moduleResolution: "bundler" | "node16" | "nodenext"`.

docs/library/embedding/vanilla.md

@@ -9,6 +9,11 @@ description: Drop Apollon into a plain HTML page with one script tag.
 The standalone subpath works as a single ESM module loaded directly from a
 CDN. No build step, no bundler.
 
+`yjs` and `y-protocols` are required peers, but on the CDN path esm.sh resolves
+and serves them from the import URL automatically — there is nothing extra to
+load. (With a bundler you install the peers yourself — see
+[Install](/library/embedding/install).)
+
 ```html
 <link rel="stylesheet" href="https://esm.sh/@tumaet/apollon@4.8.0/style.css" />
 <div id="apollon" style="width: 100%; height: 600px"></div>

docs/library/overview.md

@@ -14,14 +14,15 @@ Apollon ships as an npm library that any framework can embed. The public API is
 
 13 UML and modeling diagram types · SVG/PNG/PDF/JSON export · optional real-time collaboration via Yjs · injectable [canvas overlay controls](/library/api/overlay-controls).
 
-## Two builds, one API
+## Three builds, one API
 
-| Subpath                       | React / xyflow | Bundle  | When to use                                                                                                                                                                          |
-| ----------------------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@tumaet/apollon` _(default)_ | bundled        | ~2.4 MB | Any framework that doesn't already have React installed — Angular (the primary use case for [Artemis](https://artemis.tum.de/)), Vue, Svelte, vanilla JS. Zero peer deps to install. |
-| `@tumaet/apollon/react`       | externalized   | ~875 KB | React 18.3 hosts that want to share their React instance with the editor and dedupe the bundle.                                                                                      |
+| Subpath                       | Dependencies             | When to use                                                                                                                                                                                                        |
+| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@tumaet/apollon` _(default)_ | all bundled (except Yjs) | No bundler — vanilla JS, a `<script>` tag, or a CDN. Also any framework without React installed: Angular ([Artemis](https://artemis.tum.de/)), Vue, Svelte. Self-contained; only `yjs` + `y-protocols` to install. |
+| `@tumaet/apollon/react`       | React family external    | A React 19 host that shares its own React instance with the editor and wants the `<Apollon>` component.                                                                                                            |
+| `@tumaet/apollon/external`    | everything external      | A bundler host of any framework — Angular, Vue, Svelte, React — that wants one shared, fully auditable copy of every dependency.                                                                                   |
 
-`peerDependenciesMeta.optional` covers all peers — `npm install @tumaet/apollon` never warns about missing React.
+`peerDependenciesMeta.optional` covers the React-family peers (`react`, `react-dom`, `@xyflow/react`), so `npm install @tumaet/apollon` never warns about missing React. `yjs` and `y-protocols` are required peers of all builds — they power Apollon's document model and undo/redo (and live collaboration when enabled), so the editor needs them either way, and keeping them external lets a host that already uses Yjs own a single instance. Most package managers add them automatically. The `/external` entry additionally externalizes Apollon's own runtime deps (`@base-ui/react`, `lucide-react`, `@dnd-kit`, `zustand`, `uuid`, `@chenglou/pretext`), which install transitively with the package.
 
 ## What's next
 

docs/library/quickstart.md

@@ -13,12 +13,15 @@ idiomatic version — but the two steps below are all Apollon needs.
 ## 1. Install
 
 ```sh
-npm install @tumaet/apollon
+npm install @tumaet/apollon yjs y-protocols
 ```
 
-This is the standalone build: React and xyflow are bundled inside the tarball,
-so there are no peer dependencies to install. React hosts
-should instead use the `/react` subpath — see [Install](/library/embedding/install).
+This is the standalone build: React, Base UI, lucide, and xyflow are bundled
+inside the tarball; `yjs` and `y-protocols` are the only peers you install. They
+power Apollon's document model and undo/redo (and live collaboration when
+enabled), kept external so a host that already uses Yjs shares one instance.
+React hosts should instead use the `/react` subpath — see
+[Install](/library/embedding/install).
 
 :::danger The editor MUST have an explicit height
 Apollon renders onto a React Flow canvas, which sizes itself to its parent. If

docs/src/pages/index.tsx

@@ -75,6 +75,7 @@ const VANILLA_SNIPPET = `<link
 <div id="apollon" style="width: 100%; height: 600px"></div>
 
 <script type="module">
+  // esm.sh serves Apollon's required yjs/y-protocols peers automatically.
   import { ApollonEditor } from "https://esm.sh/@tumaet/apollon@4.8.0"
 
   const saved = localStorage.getItem("diagram")
@@ -111,7 +112,9 @@ function Hero() {
           </Link>
         </div>
         <div className={styles.install}>
-          <CodeBlock language="bash">npm install @tumaet/apollon</CodeBlock>
+          <CodeBlock language="bash">
+            npm install @tumaet/apollon yjs y-protocols
+          </CodeBlock>
         </div>
       </div>
     </header>
@@ -174,7 +177,7 @@ function LiveDemo() {
               >
                 {() => {
                   // Lazy-require: BrowserOnly only runs this on the client,
-                  // so the editor's emotion/MUI/xyflow imports stay out of
+                  // so the editor's Base UI / xyflow imports stay out of
                   // Docusaurus's SSR bundle.
                   const ApollonEmbed =
                     require("../components/ApollonEmbed").default
@@ -224,8 +227,9 @@ const WAYS: LinkCard[] = [
     body: (
       <>
         <code>@tumaet/apollon</code> on npm. Framework-agnostic by default;
-        Angular hosts install <strong>zero peer deps</strong>. A{" "}
-        <code>/react</code> subpath dedupes React when the host already has it.
+        Angular hosts install just <code>yjs</code> + <code>y-protocols</code>.
+        A <code>/react</code> subpath dedupes React when the host already has
+        it.
       </>
     ),
     to: "/library/",

docs/user/overview.md

@@ -54,7 +54,7 @@ versioned and reviewed like any other source.
 you need UML modeling inside an existing application.
 
 ```sh
-npm install @tumaet/apollon
+npm install @tumaet/apollon yjs y-protocols
 ```
 
 | You want to...                                  | Use this           |