@tumaet/apollon 4.8.0 → 5.0.0

package/README.md

@@ -23,24 +23,17 @@ Apollon is the modeling editor behind [Artemis](https://artemis.tum.de/), TUM's
 - **Framework-agnostic**: one imperative API for Angular, Vue, Svelte, and vanilla JS, plus a React component, hooks, and provider.
 - **Real-time collaboration**: opt-in multi-user editing over [Yjs](https://yjs.dev/), with any transport you like (WebSocket, WebRTC, BroadcastChannel).
 - **Export**: SVG and JSON are built in. Generate PNG and PDF from the SVG (see [Export](#export)).
+- **Canvas overlays**: inject your own toolbars, banners, and rails into the editor canvas, collision-free with built-in chrome — `<ApollonControl>` (React) or `addControl` / `getRegionElement` (any framework). See [Overlay controls](https://ls1intum.github.io/Apollon/library/api/overlay-controls).
 - **Assessment mode**: attach scores and feedback to elements. This is the grading workflow Artemis uses.
 - **TypeScript**: type definitions are included.
 
 ## Install
 
-The package ships two builds with the same API. Pick one based on whether your host already uses React:
-
-| Import                        | React / MUI / emotion / xyflow | Size (min / gzip) | Use when                                                                                                |
-| ----------------------------- | ------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------- |
-| `@tumaet/apollon` _(default)_ | **bundled**                    | ~2.4 MB / ~540 KB | Your host is Angular, Vue, Svelte, or vanilla JS. No peer deps to install.                              |
-| `@tumaet/apollon/react`       | **peer deps** (shared)         | ~875 KB / ~170 KB | Your host is React 18.3 and should share its React and MUI with the editor instead of duplicating them. |
-
-Sizes are the published entry chunks. Gzip is the transfer size. The `/react` number excludes the peers your app already ships.
-
-### Standalone build (any framework, no peer deps)
-
 ```sh
-npm install @tumaet/apollon
+npm install @tumaet/apollon \
+  react react-dom \
+  @xyflow/react \
+  yjs y-protocols
 ```
 
 ```ts
@@ -48,35 +41,29 @@ import { ApollonEditor } from "@tumaet/apollon"
 import "@tumaet/apollon/style.css"
 ```
 
-React, MUI, emotion, and xyflow are bundled in. Nothing else to install.
+Apollon ships **one** build with every runtime dependency left external — the React family (`react`, `react-dom`, `@xyflow/react`), the CRDT singletons (`yjs`, `y-protocols`), and Apollon's own UI deps (`@base-ui/react`, `lucide-react`, `@dnd-kit`, `zustand`, `@chenglou/pretext`), which arrive transitively when you install 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 the real packages they are — never a copy inlined invisibly into one chunk. This works from any framework with a bundler (Angular, Vue, Svelte, React).
 
-### React build (share your host's React)
+These are the peers you install explicitly:
 
-```sh
-npm install @tumaet/apollon \
-  react react-dom \
-  @emotion/react @emotion/styled @mui/material @xyflow/react
-```
+| Peer            | Range     | Powers                                                |
+| --------------- | --------- | ----------------------------------------------------- |
+| `react`         | `^19.0.0` | the editor's rendering                                |
+| `react-dom`     | `^19.0.0` | the editor's rendering                                |
+| `@xyflow/react` | `^12.9.0` | the diagram canvas                                    |
+| `yjs`           | `^13.6.0` | the document model, undo/redo, and live collaboration |
+| `y-protocols`   | `^1.0.6`  | collaboration sync/awareness                          |
 
-```tsx
-import { Apollon } from "@tumaet/apollon/react"
-import "@tumaet/apollon/style.css"
-```
+Most package managers install missing peers automatically; the explicit command above is listed for clarity. Keeping these external means a host that already uses React or Yjs shares a single instance with the editor instead of loading a private, possibly mismatched copy — no duplicate payload, and no "Invalid hook call" or cross-instance-document errors.
 
-| Peer            | Range     |     | Peer              | Range      |
-| --------------- | --------- | --- | ----------------- | ---------- |
-| `react`         | `^18.3.0` |     | `@mui/material`   | `^6.4.0`   |
-| `react-dom`     | `^18.3.0` |     | `@emotion/react`  | `^11.11.0` |
-| `@xyflow/react` | `^12.3.0` |     | `@emotion/styled` | `^11.11.0` |
+### Non-React hosts (Angular, Vue, Svelte, vanilla)
 
-## Which build do I use?
+The API is imperative — `new ApollonEditor(container, options)` — and the editor renders its own React tree inside the container, so your own code never imports or touches React. You still install the React peers (the editor uses them internally), but Apollon is the only thing on the page that does.
 
-It comes down to whether your host already runs React:
+### React hosts
 
-- **Not a React app?** Use the default `@tumaet/apollon`. It bundles its own React, so there is nothing extra to install or configure.
-- **A React app?** Use `@tumaet/apollon/react` and install the peers above. The default build bundles its own React, so in a React app you would load two copies. That causes "Invalid hook call" errors and a larger bundle. The `/react` subpath leaves React, MUI, emotion, and xyflow external so the editor shares the copies your app already has. It is also the only entry that exports the `<Apollon>` component, hooks, and provider.
+Import the `<Apollon>` component, hooks, and provider from the same entry: `import { Apollon } from "@tumaet/apollon"`. They render on the React you already have. Because the package is side-effect-free except for CSS, non-React hosts tree-shake the component and hooks out automatically.
 
-> **⚠️ Give the container an explicit, non-zero height** (`600px`, `80vh`, or a sized flex/grid child), whichever build you use. The canvas sizes itself to its parent, so with no resolvable height it collapses to zero pixels and renders blank. This is the most common embedding mistake. See [Troubleshooting](https://ls1intum.github.io/Apollon/library/troubleshooting).
+> **⚠️ Give the container an explicit, non-zero height** (`600px`, `80vh`, or a sized flex/grid child). The canvas sizes itself to its parent, so with no resolvable height it collapses to zero pixels and renders blank. This is the most common embedding mistake. See [Troubleshooting](https://ls1intum.github.io/Apollon/library/troubleshooting).
 
 ## Quick start
 
@@ -107,10 +94,10 @@ The editor is client-only. In SSR frameworks (Next.js, Remix, SvelteKit, Nuxt),
 
 ### React
 
-Render the `<Apollon>` component from the `@tumaet/apollon/react` subpath. It owns the editor's lifecycle: it constructs on mount and destroys on unmount.
+Render the `<Apollon>` component from `@tumaet/apollon`. It owns the editor's lifecycle: it constructs on mount and destroys on unmount.
 
 ```tsx
-import { Apollon } from "@tumaet/apollon/react"
+import { Apollon } from "@tumaet/apollon"
 import type { UMLModel } from "@tumaet/apollon"
 import "@tumaet/apollon/style.css"
 
@@ -134,7 +121,7 @@ Reach the instance through `ref`, the `onMount(editor)` callback, or the `useApo
 
 ### Angular (17.3+ signal-based)
 
-```ts
+```ts no-check
 import {
   Component,
   DestroyRef,
@@ -177,12 +164,14 @@ export class DiagramEditorComponent {
 
 ### Vanilla JS / CDN
 
+`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.)
+
 ```html
-<link rel="stylesheet" href="https://esm.sh/@tumaet/apollon@4.8.0/style.css" />
+<link rel="stylesheet" href="https://esm.sh/@tumaet/apollon@5.0.0/style.css" />
 <div id="apollon" style="width: 100%; height: 600px"></div>
 
 <script type="module">
-  import { ApollonEditor } from "https://esm.sh/@tumaet/apollon@4.8.0"
+  import { ApollonEditor } from "https://esm.sh/@tumaet/apollon@5.0.0"
 
   const saved = localStorage.getItem("diagram")
   const editor = new ApollonEditor(document.getElementById("apollon"), {
@@ -205,7 +194,7 @@ Class, Object, Activity, Use Case, Communication, Component, Deployment, Petri N
 
 Collaboration is opt-in and transport-agnostic. Set `collaborationEnabled: true`, then wire up your transport:
 
-```ts
+```ts no-check
 const editor = new ApollonEditor(container, { collaborationEnabled: true })
 
 // Outbound: the editor calls back when it has bytes to send.
@@ -217,7 +206,7 @@ transport.onMessage((base64) => editor.receiveBroadcastedMessage(base64))
 
 To let the library render participant presence, live cursors, and remote node/edge selection highlights, pass the optional `collaboration` UI config:
 
-```ts
+```ts no-check
 const editor = new ApollonEditor(container, {
   collaborationEnabled: true,
   collaboration: {
@@ -234,7 +223,7 @@ Any Yjs-compatible transport works: `y-websocket`, `y-webrtc`, BroadcastChannel,
 - **SVG**: `await editor.exportAsSVG(options)` resolves to `{ svg, clip }`. `svgMode: "web"` (the default) keeps CSS variables for theme-adaptive output; `"compat"` inlines them for PDF and Inkscape.
 - **JSON**: `editor.model` returns the `UMLModel`, and assigning it back is round-trip safe. Use `importDiagram(json)` to normalize older v2/v3 models first.
 - **Headless**: `ApollonEditor.exportModelAsSvg(model, options)` renders a model without a mounted editor.
-- **PNG / PDF**: not built in. Generate them from the exported SVG. The standalone webapp and server in this repo do this with `@resvg/resvg-js` (PNG) and `pdfmake` (PDF).
+- **PNG / PDF**: not built in, but the library ships `svgToPng` / `svgToPdf` renderers under [`@tumaet/apollon/export`](https://ls1intum.github.io/Apollon/library/api/export) (PNG via `@resvg/resvg-wasm`, PDF via `svg2pdf.js` + `jspdf`, installed as optional peers). The standalone server in this repo renders server-side instead, with `@napi-rs/canvas` (PNG) and `pdfmake` (PDF).
 
 See [Export](https://ls1intum.github.io/Apollon/library/api/export) for the full `ExportOptions`.