feat: embed Apollon diagrams in GitHub, GitLab, and iframes (#677)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: FelixTJDietrich

.changeset/embed-diagram-svg-iframe.md

@@ -0,0 +1,6 @@
+---
+"@tumaet/server": minor
+"@tumaet/webapp": minor
+---
+
+Embed your diagrams anywhere. Drop one into a README, an issue, a pull request, or any page as a Markdown image — it renders inline as a polished framed card with the diagram, its title, and an "Open in Apollon" button, matches light and dark themes, and updates as you keep editing — or paste a ready-made iframe snippet. The share dialog gains an "Embed" panel with copy-paste code, and embedding needs no sign-in or tokens: the diagram link is the key, exactly like opening it in the editor. Sharing now leads with live collaboration by default, and the dialog uploads a single shared copy whose access (collaborate, edit, or feedback) you can switch without ever creating duplicates. Embedded diagrams stay alive as long as they're viewed, so they won't quietly disappear from a README, and a popular one stays fast no matter how many people open it.

.changeset/server-render-between-anchor-edges.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/server": patch
+---
+
+Server-rendered diagram images and PDFs now include edges that connect to a node's in-between anchor points. Previously such an edge was silently dropped from the export, so a diagram could come out with its boxes but a missing connection.

.changeset/server-render-edge-labels.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/server": patch
+---
+
+Server-rendered diagram images and PDFs now place edge labels on their edge (at the path midpoint) instead of at a fallback point off to the side. Edge-relative decorators (e.g. the SFC transition condition) are positioned the same way.

docs/library/api/conversion-api.md

@@ -80,30 +80,43 @@ curl -X POST http://localhost:8000/api/converter/pdf \
 
 ## Status codes
 
-| Status | When                                                                           |
-| ------ | ------------------------------------------------------------------------------ |
-| `200`  | success — the body is the rendered file                                        |
-| `400`  | no model in the request body                                                   |
-| `413`  | request body exceeds the size limit (`BODY_TOO_LARGE`)                         |
-| `422`  | a node is missing valid geometry, e.g. width/height (`INVALID_PARAMS`)         |
-| `500`  | the worker could not render the model, e.g. an unsupported format (`INTERNAL`) |
-| `503`  | the conversion queue is full — retry with backoff                              |
+| Status | When                                                                            |
+| ------ | ------------------------------------------------------------------------------- |
+| `200`  | success — the body is the rendered file                                         |
+| `400`  | no model in the request body                                                    |
+| `413`  | request body exceeds the size limit (`BODY_TOO_LARGE`)                          |
+| `422`  | a node is missing valid geometry, e.g. width/height (`INVALID_PARAMS`)          |
+| `500`  | the worker could not render the model, e.g. an unsupported format (`INTERNAL`)  |
+| `503`  | the render pipeline is busy / queue full (`RENDERER_BUSY`) — retry with backoff |
 
 Most errors return the server's standard JSON body —
-`{ "error": "<CODE>", "message": "…", "requestId": "…" }`. The two exceptions are
-`400` and `503`, which the converter sends directly as a short
-`{ "error": "<message>" }`.
+`{ "error": "<CODE>", "message": "…", "requestId": "…" }`. A `503` additionally
+carries a `Retry-After` header (and `retryAfterSeconds` in the body) plus
+`Cache-Control: no-store`. The one exception to the standard body is `400` (no
+model), which the converter sends directly as a short `{ "error": "<message>" }`.
 
 ## Limits & tuning
 
-Requests are serialised through a single render worker with a bounded queue, so
-one slow diagram can't exhaust the process. Defaults (override via environment):
-
-| Variable                     | Default           | Meaning                      |
-| ---------------------------- | ----------------- | ---------------------------- |
-| `MAX_SNAPSHOT_BYTES`         | `5242880` (5 MiB) | max request body size        |
-| `CONVERTER_MAX_QUEUE_LENGTH` | `20`              | queued requests before `503` |
-| `CONVERTER_TIMEOUT_MS`       | `30000`           | per-conversion timeout       |
+Renders run on a **self-calibrating worker pool** that sizes itself to the
+machine — no tuning required. The pool grows from one warm worker up to a
+ceiling derived from `min(CPU, memory)` (`availableParallelism − 1`, bounded by
+~60% of system memory ÷ per-worker footprint), reaps idle workers back to one,
+sheds excess load with `503` + `Retry-After`, and recycles workers to bound
+memory. Every value below has a derived default; override only to constrain a
+shared host.
+
+| Variable                             | Default                 | Meaning                                          |
+| ------------------------------------ | ----------------------- | ------------------------------------------------ |
+| `MAX_SNAPSHOT_BYTES`                 | `5242880` (5 MiB)       | max request body size                            |
+| `CONVERTER_POOL_MAX`                 | _calibrated_            | max render workers (`min(cores−1, memBudget)`)   |
+| `CONVERTER_POOL_MIN`                 | `1`                     | always-warm workers                              |
+| `CONVERTER_MAX_QUEUE_LENGTH`         | `8 × poolMax`           | queued requests before `503`                     |
+| `CONVERTER_MAX_QUEUE_WAIT_MS`        | `10000`                 | drop a job that has waited longer (it's a ghost) |
+| `CONVERTER_TIMEOUT_{SVG,PNG,PDF}_MS` | `10000`/`15000`/`30000` | per-format render deadline                       |
+
+The embed surface additionally serves identical revisions from an in-process
+render cache with single-flight, so a fan-out of viewers (e.g. GitHub Camo)
+collapses to one render per save.
 
 ## See also
 

library/lib/edges/labelTypes/EdgeMultipleLabels.tsx

@@ -65,8 +65,16 @@ export const EdgeMultipleLabels = ({
         )}
 
         <text
-          x={pathMiddlePosition.x + group.textOrigin.x + index * group.stackStep.x}
-          y={pathMiddlePosition.y + group.textOrigin.y + index * group.stackStep.y}
+          x={
+            pathMiddlePosition.x +
+            group.textOrigin.x +
+            index * group.stackStep.x
+          }
+          y={
+            pathMiddlePosition.y +
+            group.textOrigin.y +
+            index * group.stackStep.y
+          }
           textAnchor={group.textAnchor}
           dominantBaseline="middle"
           style={{

library/tests/unit/messageLayout.test.ts

@@ -3,8 +3,16 @@ import { computeMessageLayout } from "@/edges/labelTypes/messageLayout"
 import type { MessageData } from "@/edges/EdgeProps"
 import type { IPoint } from "@/edges/Connection"
 
-const fwd = (id: string): MessageData => ({ id, text: "f", direction: "target" })
-const bwd = (id: string): MessageData => ({ id, text: "b", direction: "source" })
+const fwd = (id: string): MessageData => ({
+  id,
+  text: "f",
+  direction: "target",
+})
+const bwd = (id: string): MessageData => ({
+  id,
+  text: "b",
+  direction: "source",
+})
 
 const VERTICAL = { src: { x: 100, y: 0 }, tgt: { x: 100, y: 300 } } // source above
 const HORIZONTAL = { src: { x: 0, y: 50 }, tgt: { x: 300, y: 50 } } // source left
@@ -51,8 +59,18 @@ describe("computeMessageLayout", () => {
   })
 
   it("fixes the label side by orientation, not by which node is the source", () => {
-    const a = computeMessageLayout([fwd("1")], VERTICAL.src, VERTICAL.tgt, false)
-    const b = computeMessageLayout([fwd("1")], VERTICAL.tgt, VERTICAL.src, false)
+    const a = computeMessageLayout(
+      [fwd("1")],
+      VERTICAL.src,
+      VERTICAL.tgt,
+      false
+    )
+    const b = computeMessageLayout(
+      [fwd("1")],
+      VERTICAL.tgt,
+      VERTICAL.src,
+      false
+    )
     expect(Math.sign(a.forward.textOrigin.x)).toBe(
       Math.sign(b.forward.textOrigin.x)
     )

ops/dsms/record-of-processing.md

@@ -106,7 +106,7 @@ No off-host backups of personal data exist. No personal data leaves the EU.
 :::tip Paste-ready — DSMS "Custom Erasure Time"
 
 ```
-- Diagram content (Redis): 120 days from the last write, enforced by a native database TTL.
+- Diagram content (Redis): 120 days from the last access (opening, embedding, or editing the diagram), enforced by a native database TTL that is extended on each access.
 - Live-collaboration data (display name, cursor, selection): held only while the user is connected; dropped from server memory on disconnect.
 - IP address and user-agent: visible to the server only for the duration of an HTTP request; not persistently stored.
 - Operational events about the service (no personal data by design): size-bounded ring buffer, ~250 MB per container.
@@ -119,7 +119,7 @@ No off-host backups of personal data exist. No personal data leaves the EU.
 :::tip Paste-ready — DSMS "Reasoning for the erasure time"
 
 ```
-Diagram data is retained for 120 days from the last edit to support editing across teaching iterations. After 120 days of inactivity, deletion is performed automatically by the Redis engine. Operational events about the service are kept free of personal data by data minimisation at source (Art. 5(1)(c) + Art. 25 GDPR); a time-based retention period under Art. 5(1)(e) GDPR is therefore not required.
+Diagram data is retained for 120 days from the last access (opening, embedding, or editing the diagram) to support editing across teaching iterations and stable embeds in course materials. Each access resets the window; after 120 days of inactivity, deletion is performed automatically by the Redis engine. Operational events about the service are kept free of personal data by data minimisation at source (Art. 5(1)(c) + Art. 25 GDPR); a time-based retention period under Art. 5(1)(e) GDPR is therefore not required.
 ```
 
 :::

standalone/server/src/__tests__/conversion.int.test.ts

@@ -6,6 +6,10 @@ import path from "node:path"
 import { buildApp } from "../http/app.js"
 import { loadConfig } from "../config.js"
 import { getRedis } from "./setup.js"
+import {
+  ConversionResource,
+  QueueFullError,
+} from "../resources/conversion-resource.js"
 
 // Drive the COMPILED worker — the real production artifact. Running it in its
 // own thread keeps the jsdom globals it installs out of this shared test
@@ -141,4 +145,25 @@ describe("POST /api/converter", () => {
       .send({ model: "{ not valid json" })
     expect(res.status).toBe(400)
   })
+
+  it("maps a full queue to a typed 503 RENDERER_BUSY with Retry-After", async () => {
+    const busy = {
+      render: () =>
+        Promise.reject(new QueueFullError("Conversion queue is full")),
+    } as unknown as ConversionResource
+    const redis = await getRedis()
+    const busyApp = buildApp({
+      config: loadConfig(),
+      redis,
+      autoLogging: false,
+      conversionResource: busy,
+    })
+    const res = await request(busyApp)
+      .post("/api/converter/svg")
+      .send({ model: loadModel() })
+    expect(res.status).toBe(503)
+    expect(res.body.error).toBe("RENDERER_BUSY")
+    expect(res.headers["retry-after"]).toBe("2")
+    expect(res.headers["cache-control"]).toBe("no-store")
+  })
 })