docs: add editor hero, live-demo link, social card, and "Why Apollon"

.changeset/proud-donkeys-shine.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/apollon": patch
+---
+
+Add an editor screenshot to the npm README so the package page shows the product, not just badges. The image is generated from the live editor by the `readme-assets` Playwright project and hosted from the repository.

.github/workflows/update-visual-baselines.yml

@@ -63,10 +63,13 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           # Scope strictly to generated snapshot PNGs so a render bug can't
           # smuggle other tree changes back onto the branch. The how-to-use modal
-          # assets are regenerated by the same run (howto-assets project) but land
-          # under assets/images/, not a *-snapshots dir, so stage them explicitly.
+          # assets and the README/social-card assets are regenerated by the same
+          # run (howto-assets + readme-assets projects) but land outside the
+          # *-snapshots dirs, so stage them explicitly.
           git add 'standalone/webapp/tests/**/*-snapshots/*.png' \
-            'standalone/webapp/assets/images/how-to-use-*.png'
+            'standalone/webapp/assets/images/how-to-use-*.png' \
+            'docs/static/img/apollon-editor-*.png' \
+            'docs/static/img/apollon-social-card.png'
           if git diff --cached --quiet; then
             echo "Baselines already match — nothing to commit." >> "$GITHUB_STEP_SUMMARY"
             exit 0

README.md

@@ -1,9 +1,33 @@
+<div align="center">
+
 # Apollon
 
 [![npm version](https://img.shields.io/npm/v/@tumaet/apollon)](https://www.npmjs.com/package/@tumaet/apollon)
+[![npm downloads](https://img.shields.io/npm/dm/@tumaet/apollon)](https://www.npmjs.com/package/@tumaet/apollon)
 [![npm license](https://img.shields.io/npm/l/@tumaet/apollon)](./LICENSE)
 
-Apollon is an open-source UML modeling editor for the web. Draw 13 UML and modeling diagram types (class, component, activity, BPMN, SFC, and more) in the browser, collaborate in real time, and export to SVG, PNG, PDF, or JSON.
+**Open-source UML modeling editor for the web.** Draw 13 UML and modeling diagram types (class, component, activity, BPMN, SFC, and more) in the browser, collaborate in real time, and export to SVG, PNG, PDF, PPTX, or JSON.
+
+[**▶ Try the live demo**](https://apollon.aet.cit.tum.de) · [Documentation](https://ls1intum.github.io/Apollon/) · [npm package](https://www.npmjs.com/package/@tumaet/apollon) · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=aet-tum.apollon-extension)
+
+<a href="https://apollon.aet.cit.tum.de">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/static/img/apollon-editor-dark.png" />
+    <img src="docs/static/img/apollon-editor-light.png" alt="The Apollon editor showing a UML class diagram, with the element palette on the left and the app chrome on top" />
+  </picture>
+</a>
+
+</div>
+
+## Why Apollon
+
+- **Made for learning and teaching.** Apollon powers the UML modeling exercises and grading workflows in [Artemis](https://artemis.tum.de/), TUM's interactive learning platform, and holds up in large university courses — but it is a general-purpose editor that works just as well outside the classroom.
+- **Embeddable first.** The editor is an npm library with an imperative API (plus a React component); the standalone web app and the VS Code extension in this repo are built on top of it. If you need diagramming inside your own product, you embed the exact editor you see in the demo.
+- **Framework-agnostic.** One API works from Angular, Vue, Svelte, vanilla JS, or React.
+- **Real-time collaboration built in.** Opt-in multi-user editing over [Yjs](https://yjs.dev/), with any transport you like.
+- **MIT-licensed and self-hostable.** No account, no cloud dependency — run the whole stack yourself.
+
+## What's in this repo
 
 This monorepo contains every piece of the Apollon platform:
 

docs/contributor/development/visual-tests.md

@@ -41,6 +41,22 @@ cd standalone/webapp
 pnpm exec playwright test tests/visual/svg-export --update-snapshots
 ```
 
+## Generated UI assets
+
+Two Playwright projects double as asset generators — their baselines **are** the shipped files, so the images can never drift from the real editor:
+
+- `howto-assets` writes the "How this editor works" modal images to `standalone/webapp/assets/images/`.
+- `readme-assets` writes the README hero screenshots (`apollon-editor-light.png`, `apollon-editor-dark.png`) and the 1280×640 social preview card (`apollon-social-card.png`) to `docs/static/img/`. These are referenced by `README.md`, `library/README.md` (the npm page), and `themeConfig.image` in `docs/docusaurus.config.ts`.
+
+Both regenerate through the same baseline-refresh flows above, or individually:
+
+```sh
+cd standalone/webapp
+pnpm exec playwright test --project readme-assets --update-snapshots
+```
+
+One manual step remains: GitHub has no API for the repository social preview, so after `apollon-social-card.png` changes, a maintainer re-uploads it under **Settings → General → Social preview**.
+
 ## Triage
 
 If `visual-regression-tests` fails on a PR, download the `playwright-report-visual` artifact from the run, open `playwright-report/index.html` locally, and inspect the actual-vs-expected diff before deciding whether to refresh the baseline (intentional UI change — see above) or fix the regression (unintended).

docs/docusaurus.config.ts

@@ -141,9 +141,10 @@ const config: Config = {
   ],
 
   themeConfig: {
-    // Link-unfurl preview image. The logo works; a dedicated 1200×630 card
-    // would render better in social embeds.
-    image: "img/logo.png",
+    // Link-unfurl preview image: the 1280×640 social card generated from the
+    // live editor by the "readme-assets" Playwright project (see
+    // standalone/webapp/tests/visual/readme-assets.visual.spec.ts).
+    image: "img/apollon-social-card.png",
     colorMode: {
       respectPrefersColorScheme: true,
       disableSwitch: false,

docs/src/pages/index.tsx

@@ -100,9 +100,9 @@ function Hero() {
           browser.
         </h1>
         <p className={styles.heroSubtitle}>
-          An open-source UML modeling editor. 13 diagram types, SVG/PNG/PDF/JSON
-          export, real-time collaboration. Use it in the browser, in VS Code, or
-          as an npm library.
+          An open-source UML modeling editor. 13 diagram types,
+          SVG/PNG/PDF/PPTX/JSON export, real-time collaboration. Use it in the
+          browser, in VS Code, or as an npm library.
         </p>
         <div className={styles.buttons}>
           <Link className="button button--primary button--lg" href={HOSTED_URL}>
@@ -286,7 +286,7 @@ const FEATURES = [
   {
     kicker: "Output",
     title: "Export anywhere",
-    body: "SVG, PNG, PDF, and JSON — from a mounted editor or a headless model. Round-trips through JSON without loss.",
+    body: "SVG, PNG, PDF, and JSON — from a mounted editor or a headless model; the web app adds PPTX slides. Round-trips through JSON without loss.",
   },
   {
     kicker: "Collaboration",

docs/user/overview.md

@@ -8,7 +8,7 @@ slug: /
 # Overview
 
 Apollon is an open-source UML and modeling editor for the web. You draw diagrams
-in the browser, collaborate in real time, and export to SVG, PNG, PDF, or JSON.
+in the browser, collaborate in real time, and export to SVG, PNG, PDF, PPTX, or JSON.
 There is nothing to install to get started.
 
 ## What you can draw
@@ -29,8 +29,8 @@ Apollon supports 13 diagram types:
 - BPMN
 - SFC
 
-Any diagram exports to SVG, PNG, PDF, or JSON. JSON round-trips — re-import it to
-keep editing. Real-time collaboration is optional and runs over WebSockets.
+Any diagram exports to SVG, PNG, PDF, PPTX, or JSON. JSON round-trips — re-import
+it to keep editing. Real-time collaboration is optional and runs over WebSockets.
 
 ## Which way to use Apollon
 

library/README.md

@@ -11,6 +11,12 @@
 
 [**▶ Live demo**](https://apollon.aet.cit.tum.de) · [Docs](https://ls1intum.github.io/Apollon/library/) · [API reference](https://ls1intum.github.io/Apollon/library/api) · [Examples](https://ls1intum.github.io/Apollon/library/embedding/react) · [GitHub](https://github.com/ls1intum/Apollon)
 
+<!-- Absolute URL on purpose: this README is rendered on npmjs.com, where
+     repo-relative image paths do not resolve. The PNG is generated from the
+     live editor by the readme-assets Playwright project. -->
+
+[![The Apollon editor showing a UML class diagram, with the element palette on the left](https://raw.githubusercontent.com/ls1intum/Apollon/main/docs/static/img/apollon-editor-light.png)](https://apollon.aet.cit.tum.de)
+
 </div>
 
 ---

standalone/webapp/playwright.config.ts

@@ -41,10 +41,14 @@ export default defineConfig({
     {
       name: "chromium",
       // The perf suite has its own serial, retry-free project below; keep it
-      // out of the parallel functional run. The how-to-use spec is owned by the
-      // dedicated "howto-assets" project (different snapshotPathTemplate), so
-      // exclude it here too.
-      testIgnore: ["**/perf/**", "**/how-to-use.visual.spec.ts"],
+      // out of the parallel functional run. The how-to-use and readme-assets
+      // specs are owned by their dedicated projects (different
+      // snapshotPathTemplates), so exclude them here too.
+      testIgnore: [
+        "**/perf/**",
+        "**/how-to-use.visual.spec.ts",
+        "**/readme-assets.visual.spec.ts",
+      ],
       use: {
         ...devices["Desktop Chrome"],
         viewport: { width: 1280, height: 720 },
@@ -65,6 +69,27 @@ export default defineConfig({
         viewport: { width: 1280, height: 720 },
       },
     },
+    {
+      // Generates the public-facing marketing assets — the README hero
+      // screenshots (light + dark) and the 1280×640 GitHub social preview
+      // card — straight from the live editor, same one-source-of-truth
+      // pattern as howto-assets. Its snapshotPathTemplate writes (and reads,
+      // for the regression diff) the exact PNGs README.md, library/README.md,
+      // and docs/docusaurus.config.ts reference under docs/static/img/.
+      // Regenerate with:
+      //   pnpm exec playwright test --project readme-assets --update-snapshots
+      name: "readme-assets",
+      testMatch: "**/readme-assets.visual.spec.ts",
+      snapshotPathTemplate: "{testDir}/../../../docs/static/img/{arg}{ext}",
+      use: {
+        ...devices["Desktop Chrome"],
+        // Larger viewport + 2× scale so the hero holds up at README width on
+        // high-DPI displays. The social-card test overrides both to hit
+        // GitHub's exact 1280×640 spec.
+        viewport: { width: 1440, height: 810 },
+        deviceScaleFactor: 2,
+      },
+    },
     // Firefox is where the Apollon-in-Artemis exam freeze was observed, so the
     // functional suite should run there too. It's opt-in (PLAYWRIGHT_FIREFOX=1
     // via `pnpm test:e2e:firefox`) so the default run — and CI that only
@@ -74,9 +99,13 @@ export default defineConfig({
       ? [
           {
             name: "firefox",
-            // The how-to-use assets are baselined once, in the pinned chromium
-            // "howto-assets" project; don't regenerate/diff them on firefox.
-            testIgnore: ["**/perf/**", "**/how-to-use.visual.spec.ts"],
+            // The how-to-use and readme assets are baselined once, in their
+            // pinned chromium projects; don't regenerate/diff them on firefox.
+            testIgnore: [
+              "**/perf/**",
+              "**/how-to-use.visual.spec.ts",
+              "**/readme-assets.visual.spec.ts",
+            ],
             use: {
               ...devices["Desktop Firefox"],
               viewport: { width: 1280, height: 720 },