fix(library): make embedded editors reliable in host applications

.changeset/free-squids-like.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/webapp": minor
+---
+
+Test embedded-editor overlays and drag interactions directly in the playground with its new fullscreen workspace action.

.changeset/loose-hounds-cry.md

@@ -0,0 +1,6 @@
+---
+"@tumaet/apollon": minor
+---
+
+Embed Apollon reliably in host pages: fullscreen overlays stay visible, scrolling and shortcuts remain host-safe, assessment feedback is easier to open and navigate through `revealAssessment(id)`, host controls gain a labeled chrome action, exports no longer expand the page, and diagram interactions remain aligned, sharp, and responsive.
+Labels now also stay vertically centered in SVG, PNG, and PDF exports exactly as they appear in the editor.

docs/library/api.md

@@ -198,13 +198,14 @@ regions, the `<ApollonControl>` React component, and the "make room" model.
 
 ### Assessment
 
-| Member                              | Type                                                              | Purpose                                                                                                                                                                                                                                                                                                                          |
-| ----------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `addOrUpdateAssessment(assessment)` | `(Assessment) => void`                                            | Attach or update a score/feedback assessment on an element.                                                                                                                                                                                                                                                                      |
-| `setElementHighlights(highlights)`  | `(Map<string, string> \| Record<string, string> \| null) => void` | Paint a translucent highlight overlay over the given element ids (id → CSS color) — e.g. to flag elements missing feedback or carrying suggestions. Host-driven and ephemeral: never written to the model, serialized, or shared with collaborators. Each call replaces the previous set; pass `null` or an empty map to clear.  |
-| `getElementHighlights()`            | `() => Record<string, string>`                                    | The current highlight map (element id → CSS color).                                                                                                                                                                                                                                                                              |
-| `getElementIdsByTag(tag)`           | `(string) => string[]`                                            | Ids of every element carrying the host-defined `tag` — a node, or one of its members (class attribute, method, SFC action row). Exact and case-sensitive apart from surrounding whitespace; `[]` for an unknown or blank tag. Pair with `setElementHighlights` to color a group — see [Element tags](/library/api/element-tags). |
-| `getInteractiveForSerialization()`  | `InteractiveElements \| undefined`                                | Interactive-element flags for inclusion in a saved model.                                                                                                                                                                                                                                                                        |
+| Member                              | Type                                                              | Purpose                                                                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `addOrUpdateAssessment(assessment)` | `(Assessment) => void`                                            | Attach or update a score/feedback assessment on an element.                                                                                                                                                                                                                                                                                                                                  |
+| `setElementHighlights(highlights)`  | `(Map<string, string> \| Record<string, string> \| null) => void` | Ring the given element ids (id → CSS color) — e.g. to flag elements missing feedback or carrying suggestions. Drawn as an outline, never a fill, so an element's own text and its assessment badge stay legible. Host-driven and ephemeral: never written to the model, serialized, or shared with collaborators. Each call replaces the previous set; pass `null` or an empty map to clear. |
+| `revealAssessment(id, options?)`    | `(string \| null, { reveal?: boolean }) => void`                  | Select one element, open its feedback popover, and pan the canvas to it at the current zoom. Lets a host's feedback list drive the canvas — click an entry, the diagram answers where it applies. `null` clears the selection and closes the popover; `{ reveal: false }` skips the pan. The popover only opens in assessment mode.                                                          |
+| `getElementHighlights()`            | `() => Record<string, string>`                                    | The current highlight map (element id → CSS color).                                                                                                                                                                                                                                                                                                                                          |
+| `getElementIdsByTag(tag)`           | `(string) => string[]`                                            | Ids of every element carrying the host-defined `tag` — a node, or one of its members (class attribute, method, SFC action row). Exact and case-sensitive apart from surrounding whitespace; `[]` for an unknown or blank tag. Pair with `setElementHighlights` to color a group — see [Element tags](/library/api/element-tags).                                                             |
+| `getInteractiveForSerialization()`  | `InteractiveElements \| undefined`                                | Interactive-element flags for inclusion in a saved model.                                                                                                                                                                                                                                                                                                                                    |
 
 ## Subscriptions
 
@@ -267,7 +268,11 @@ SVG/PNG/PDF over HTTP via the standalone server.
 
 `Mod` is Ctrl on Windows/Linux and Cmd on macOS; combos marked _view_ work on
 read-only diagrams too. Nothing fires while the user is typing in a field or
-while a dialog or menu is open.
+while a dialog or menu is open. Shortcuts belong to the editor that has focus:
+click or tap the canvas to activate it, then move focus outside the editor to
+return every shortcut to the surrounding page. Pointer-acquired canvas focus is
+released when the pointer leaves, so browser zoom remains available around an
+embedded editor. Keyboard users keep ownership until they move focus normally.
 
 | Combo                          | Action                                   |
 | ------------------------------ | ---------------------------------------- |
@@ -286,17 +291,18 @@ whose keys produce a printable character fails
 [WCAG 2.1.4](https://www.w3.org/WAI/WCAG21/Understanding/character-key-shortcuts)
 unless it can be turned off, remapped, or scoped to focus.
 
-Pass `keyboardShortcuts: false` to keep the editor's hands off every key above —
-for a host that binds them itself, or that mounts more than one editor (they
-listen on `document`, so two would both answer).
+Pass `keyboardShortcuts: false` to keep the editor's hands off every key above
+when the host binds them itself. Multiple editors need no special coordination:
+only the focused editor answers.
 
 `APOLLON_SHORTCUTS` is the list the editor runs, so a host can render a sheet
 that tracks it, or check it before binding a key of its own. Each entry's
 **first** combo is the primary one — a sheet should render only that; the rest
 are aliases (`Mod+Y` redo, layout variants of `Mod+=`). Entries flagged
-`canvasHandled` are React Flow's, not the editor's own handler. `shortcutKeyName`
-turns a combo into the key it names, so a sheet renders "1" rather than the
-`Digit1` code that combo matches on.
+`canvasHandled` are handled directly by React Flow on a focused canvas element,
+not by the editor-root dispatcher. `shortcutKeyName` turns a combo into
+the key it names, so a sheet renders "1" rather than the `Digit1` code that combo
+matches on.
 
 `matchesShortcutCombo`, `isTypingTarget` and `isInsideOverlay` are the
 primitives that handler matches and stands down with, exported so a host's own

docs/library/api/assessment.md

@@ -76,11 +76,49 @@ const all: Record<string, Assessment> = editor.model.assessments
 | `labelColor`       | `string?`                                                                        | CSS color for the label.                              |
 | `correctionStatus` | `{ status: "CORRECT" \| "INCORRECT" \| "NOT_VALIDATED"; description?: string }?` | For automated/suggested feedback review.              |
 
+## Drive the canvas from a feedback list
+
+A host that lists feedback beside the diagram has a problem the list alone
+cannot solve: an entry says _what_ a tutor wrote, never _where_ it applies. The
+reader is left matching text against boxes by eye.
+
+`revealAssessment` closes that loop. It selects the element, opens its feedback
+popover, and pans the canvas to it — keeping the reader's zoom, because the zoom
+is theirs.
+
+```ts
+import { ApollonEditor } from "@tumaet/apollon"
+
+function showFeedbackFor(
+  editor: ApollonEditor,
+  feedback: { elementId: string }
+) {
+  editor.revealAssessment(feedback.elementId)
+}
+
+// Closing the list, or deselecting, puts the canvas back:
+function clearFeedback(editor: ApollonEditor) {
+  editor.revealAssessment(null)
+}
+```
+
+Pass `{ reveal: false }` to select without panning — useful when the element is
+already on screen and moving the canvas would be disorienting.
+
+Pair it with `subscribeToAssessmentSelection` for the other direction, so
+clicking an element marks its entry in the list. Together the two halves explain
+each other instead of sitting side by side.
+
+The popover only opens in `ApollonMode.Assessment`. In assessment **with**
+`readonly` — a student reading a graded diagram — it opens the read-only
+feedback popover; without `readonly`, the tutor's editable one.
+
 ## Highlight elements
 
-`setElementHighlights` tints elements by id with a CSS color — e.g. to mark the
-elements that still need feedback. Use **translucent** colors so the element's
-own text stays readable. Highlights are ephemeral: they are not serialized into
+`setElementHighlights` rings elements by id with a CSS color — e.g. to mark the
+elements that still need feedback. It draws an outline rather than a fill, so use
+**opaque** colors: the element's own content, including its assessment badge,
+stays fully visible underneath. Highlights are ephemeral: they are not serialized into
 the model and not shared over collaboration. Pass `null` or an empty map to clear.
 
 To color a whole **group** of attributes/methods at once — e.g. by a build
@@ -93,8 +131,8 @@ import { ApollonEditor } from "@tumaet/apollon"
 function highlightMissing(editor: ApollonEditor) {
   editor.setElementHighlights(
     new Map([
-      ["node-2", "rgba(0, 123, 255, 0.35)"],
-      ["node-5", "rgba(0, 123, 255, 0.35)"],
+      ["node-2", "#0d6efd"],
+      ["node-5", "#0d6efd"],
     ])
   )
 }

docs/library/api/overlay-controls.md

@@ -273,6 +273,30 @@ function HostRail({ editor }) {
 }
 ```
 
+Host controls can use the same framework-agnostic chrome classes as Apollon's
+built-ins:
+
+```html no-check
+<div
+  class="apollon-glass apollon-chrome-cluster"
+  role="group"
+  aria-label="Editor actions"
+>
+  <button class="apollon-chrome-iconbtn" type="button" aria-label="Undo">
+    <!-- icon -->
+  </button>
+  <button class="apollon-chrome-actionbtn" type="button">
+    <!-- icon -->
+    <span>Fullscreen</span>
+  </button>
+</div>
+```
+
+Use `.apollon-chrome-iconbtn` only when the icon has an unambiguous accessible
+name. Use `.apollon-chrome-actionbtn` when a visible label makes a host action
+clearer. Both use neutral hover/active layers and the same 32px chrome geometry;
+reserve `.apollon-chrome-accent-btn` for a genuine primary action.
+
 `getRegionElement` registers a host control under the reserved id
 `apollon:host:<region>` with `inset: "auto"`, so the diagram makes room for
 whatever you mount. The host mount is pointer-transparent by default so empty

docs/library/theming.md

@@ -156,25 +156,27 @@ drop shadow, and a few state tints. They are **not** on `ApollonTheme` (the type
 surface stays focused on color), but the names are part of the public contract —
 set them directly through `style` or a stylesheet rule.
 
-| CSS variable                         | Used for                                                                             |
-| ------------------------------------ | ------------------------------------------------------------------------------------ |
-| `--apollon-radius-sm`                | Small radius — node hover/selection rings, chips, pills (default `4px`).             |
-| `--apollon-radius-md`                | Control radius — inputs, toggles. Routes through `--apollon-radius` (default `6px`). |
-| `--apollon-radius-lg`                | Panel / popover / menu radius (default `8px`).                                       |
-| `--apollon-shadow`                   | Drop shadow for floating surfaces — menus, popovers, select listboxes.               |
-| `--apollon-interactive-selection`    | Accent ring/fill marking interactive (quiz-pickable) elements (default amber).       |
-| `--apollon-hover-neutral`            | Neutral hover wash for quiet controls, derived off `--apollon-foreground`.           |
-| `--apollon-dropzone-accent`          | Ring/stroke shown on an assessment feedback drop target on hover (default blue).     |
-| `--apollon-dropzone-accent-fill`     | Translucent fill (40% of `--apollon-dropzone-accent`) outlining box/div targets.     |
-| `--apollon-on-collaboration-cursor`  | Ink drawn on a collaborator's colored cursor/avatar (default white).                 |
-| `--apollon-assessment-positive-text` | Glyph/text for a positive (rewarded) score — popover pill AND on-canvas badge.       |
-| `--apollon-assessment-positive-bg`   | Soft tint behind a positive score (popover pill + canvas badge).                     |
-| `--apollon-assessment-negative-text` | Glyph/text for a negative (penalty) score.                                           |
-| `--apollon-assessment-negative-bg`   | Soft tint behind a negative score.                                                   |
-| `--apollon-assessment-zero-text`     | Glyph/text for a zero score.                                                         |
-| `--apollon-assessment-zero-bg`       | Soft tint behind a zero score.                                                       |
-| `--apollon-assessment-ungraded-text` | Text for the "Not graded" pill (popover only — ungraded elements get no badge).      |
-| `--apollon-assessment-ungraded-bg`   | Soft tint behind the "Not graded" pill.                                              |
+| CSS variable                         | Used for                                                                                             |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `--apollon-radius-sm`                | Small radius — node hover/selection rings, chips, pills (default `4px`).                             |
+| `--apollon-radius-md`                | Control radius — inputs, toggles. Routes through `--apollon-radius` (default `6px`).                 |
+| `--apollon-radius-lg`                | Panel / popover / menu radius (default `8px`).                                                       |
+| `--apollon-shadow`                   | Drop shadow for floating surfaces — menus, popovers, select listboxes.                               |
+| `--apollon-interactive-selection`    | Accent ring/fill marking highlighted elements — the picker and assessment (default amber).           |
+| `--apollon-scroll-lock-veil`         | Veil over the canvas while a scroll-locked editor explains the zoom gesture. Darkens in both themes. |
+| `--apollon-scroll-lock-text`         | Ink for that message, paired with the veil above.                                                    |
+| `--apollon-hover-neutral`            | Neutral hover wash for quiet controls, derived off `--apollon-foreground`.                           |
+| `--apollon-dropzone-accent`          | Ring/stroke shown on an assessment feedback drop target on hover (default blue).                     |
+| `--apollon-dropzone-accent-fill`     | Translucent fill (40% of `--apollon-dropzone-accent`) outlining box/div targets.                     |
+| `--apollon-on-collaboration-cursor`  | Ink drawn on a collaborator's colored cursor/avatar (default white).                                 |
+| `--apollon-assessment-positive-text` | Glyph/text for a positive (rewarded) score — popover pill AND on-canvas badge.                       |
+| `--apollon-assessment-positive-bg`   | Soft tint behind a positive score (popover pill + canvas badge).                                     |
+| `--apollon-assessment-negative-text` | Glyph/text for a negative (penalty) score.                                                           |
+| `--apollon-assessment-negative-bg`   | Soft tint behind a negative score.                                                                   |
+| `--apollon-assessment-zero-text`     | Glyph/text for a zero score.                                                                         |
+| `--apollon-assessment-zero-bg`       | Soft tint behind a zero score.                                                                       |
+| `--apollon-assessment-ungraded-text` | Text for the "Not graded" pill (popover only — ungraded elements get no badge).                      |
+| `--apollon-assessment-ungraded-bg`   | Soft tint behind the "Not graded" pill.                                                              |
 
 ```css
 /* Sharpen the editor's corners and lift its menus a touch more. */