API.md

# @miragon/modeler-shell 0.2 — public API

The shared, framework-free implementation of everything around a Miragon diagram-js modeler: menu
button with dropdown, horizontal palette skin, chrome tooltip, zoom panel, zoom and fit keys, fit,
problems pill, status box, empty-file hint, legend and inspector slots, the plumbing to a VS Code
webview, and (0.2) the web-app chrome: primary action, legal line, File and Appearance groups,
problems popover, toasts, empty-state card, drop zone and the web app's mode. Planned in
[Miragon/modeler-api#4](https://github.com/Miragon/modeler-api/issues/4) (Phase 4); the first
consumer is the Event Storming modeler, in VS Code (0.1) and in its web app (0.2, see
[Usage: Event Storming in the web app](#usage-event-storming-in-the-web-app)).

- **Look and behaviour** come from the Miragon design system, guide `modeler-design-system.md`
  (skill `miragon-brand:modeler-tool-design`, design system 1.13.0), §2, §5.1 to §5.15, §6, §7, §8,
  §9, §11, §12 and §13.3 to §13.5. Section numbers below (§x.y) refer to it.
- **Mechanics** (diagram-js services, VS Code quirks) are in
  [`docs/shell/implementation-notes.md`](../../docs/shell/implementation-notes.md).
- **Zero runtime dependencies.** The shell never imports `diagram-js`, `didi`, `vscode`, Lucide or
  React, not even for types: diagram-js services are typed structurally, the `vscode` namespace and
  Playwright's `page`/`test` are passed in.
- **Tokens are the consumer's.** The modeler vendors `cd-tokens.generated.css` unchanged; the shell
  CSS reads only `var(--cd-ui-*)` roles, `var(--cd-shell-*)` sizes and the mode-independent
  non-colour tokens `--cd-radius-*`, `--cd-shadow-*`, `--cd-motion-*`, `--cd-ease`, `--cd-ease-out`.
  It contains no colour literal and no fixed palette token (`--cd-blau`, `--cd-schwarz`, …), with
  one exception the guide itself makes: the primary button's fill is `--cd-blau` with `--cd-weiss`
  text in both modes, hover `--cd-blau-link` (§8: "Feste Werte nimmst du nur für die Fläche von
  Primär- und Destruktiv-Button"). Those three tokens appear in `src/dom/buttons.css` only, and the
  stylesheet test allows them nowhere else (see [Buttons](#buttons)). Values the shell needs in
  script (the two `theme-color`s) come from the modeler's vendored JSON as well.
- **English by default.** Every text comes from one messages table (`ShellMessages`), every number
  goes through `Intl` in the UI language.

## Entry points

| Entry                                        | For                                                                                                   | Needs a DOM                    |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------ |
| `@miragon/modeler-shell`                     | the chrome (`mountShell`, web chrome included), icons, plus all of `./core`                           | yes (at call time)             |
| `@miragon/modeler-shell/core`                | fit math, keymap, zoom readout, appearance, sizes, messages, the web host's decisions and head script | no                             |
| `@miragon/modeler-shell/diagram-js`          | `shellModule`, viewport, `connectDiagramJs`                                                           | yes                            |
| `@miragon/modeler-shell/vscode/extension`    | webview HTML, nonce, theme bridge (extension host)                                                    | no                             |
| `@miragon/modeler-shell/vscode/webview`      | `mountVsCodeShell`, appearance handler, webview state                                                 | yes                            |
| `@miragon/modeler-shell/testing`             | Playwright-driven shell conformance kit                                                               | runs in Node, drives a browser |
| `@miragon/modeler-shell/testing/vscode-stub` | a stand-in for VS Code around a webview test page                                                     | yes (in the test page)         |
| `@miragon/modeler-shell/shell.css`           | every style of the shell                                                                              | —                              |

All JavaScript entries ship as ESM and CJS with types (`typesVersions` covers `moduleResolution:
node10`); importing any of them has no side effects. The package also ships `src/` without its tests,
the files the sourcemaps point at, so stack traces and test locations resolve to real files. Every
optional input field also accepts an explicit `undefined`, so consumers compiling with
`exactOptionalPropertyTypes` can forward optional values (`{ view: viewport.getState() }`,
`{ open: stored.legendOpen }`); the shell compiles with it too.

### Stylesheet order

The tokens come first, unless the renderer's stylesheet already imports them (Event Storming's
`event-storming.css` does, in a layer), and are loaded exactly once:

```ts
import "./theme/cd-tokens.generated.css"; // vendored, unchanged, first; left out when the renderer CSS brings it
import "@fontsource-variable/geist/wght.css";
import "@fontsource-variable/geist-mono/wght.css"; // shortcut chips
import "diagram-js/assets/diagram-js.css"; // usually through the renderer's CSS
import "@miragon/<notation>-renderer/…css"; // the renderer
import "@miragon/modeler-shell/shell.css"; // last
```

A bundle ships the fonts as files, not as data URLs (see `./vscode/extension`).

## `./core` — DOM-free

Compiles without the DOM library (`tsconfig.core.json`), usable in the extension host and in workers.

### Geometry and shared types

```ts
interface Point {
  x: number;
  y: number;
}
interface Size {
  width: number;
  height: number;
}
// content bounds and viewboxes are in diagram coordinates
interface Bounds {
  x: number;
  y: number;
  width: number;
  height: number;
}
interface ScaledViewbox extends Bounds {
  scale: number;
}
// px from the edges of the modeler's container
interface Insets {
  top: number;
  right: number;
  bottom: number;
  left: number;
}

type ShellHost = "ide" | "web" | "embedded";
type ChromeIsland =
  | "menu"
  | "palette"
  | "primary"
  | "zoom"
  | "problems"
  | "legend"
  | "inspector"
  | "status"
  // 0.2, web column (toasts and problems-popover also embedded)
  | "legal"
  | "toasts"
  | "empty-state"
  | "drop-zone"
  | "problems-popover";
const CHROME_ISLANDS: readonly ChromeIsland[]; // in this order
type PaletteRow = "top" | "second-row";

interface ZoomTarget {
  zoom(): number; // 1 = 100 %
  stepZoom(direction: 1 | -1): void; // zoomScroll raster, around the container centre
  zoomToActual(): void; // 100 %, a user move
  fit(): void; // explicit fit: animated unless reduced motion; view becomes automatic
  canFit(): boolean; // false while the content bounds are empty
  onChange(listener: () => void): () => void; // every viewbox change and canFit change; unsubscribe
}

// JSON-serializable, for VS Code setState
interface ViewportState {
  viewbox: Bounds;
  userMoved: boolean; // zoomed or panned since the last fit: a resize no longer refits
}
```

`ShellHost` is the host column of §5.2: `ide` (VS Code webview, later IntelliJ), `web` (a Miragon web
app owning its page), `embedded` (a foreign page such as designIQ; geometry like `ide`).

### Sizes

```ts
const SHELL_TOKENS: {
  edge: "--cd-shell-rand";
  gap: "--cd-shell-luecke";
  row: "--cd-shell-zeile";
  target: "--cd-shell-ziel";
  entry: "--cd-shell-eintrag";
  free: "--cd-shell-frei";
  menuMinWidth: "--cd-shell-menue-breite";
  inspectorWidth: "--cd-shell-inspector-breite";
  fitInsetTop: "--cd-shell-einpassen-oben";
  fitInsetTopSecondRow: "--cd-shell-einpassen-oben-schmal";
  fitInsetSide: "--cd-shell-einpassen-seite";
  fitInsetBottom: "--cd-shell-einpassen-unten";
  fitInsetBottomWeb: "--cd-shell-einpassen-unten-web";
  narrow: "--cd-shell-schmal";
  veryNarrow: "--cd-shell-sehr-schmal";
  low: "--cd-shell-niedrig";
  layerIslands: "--cd-shell-ebene-inseln";
  layerInspector: "--cd-shell-ebene-inspector";
  layerTopRow: "--cd-shell-ebene-reihe";
  layerPopups: "--cd-shell-ebene-aufklapper";
  layerDialog: "--cd-shell-ebene-dialog";
  layerToast: "--cd-shell-ebene-toast";
};
type ShellSizeName = keyof typeof SHELL_TOKENS;
type ShellSizes = Readonly<Record<ShellSizeName, number>>;
const SHELL: ShellSizes; // edge 12, gap 8, row 40, target 32, entry 36, free 64, menuMinWidth 248,
// inspectorWidth 288, fitInsetTop 88, fitInsetTopSecondRow 140, fitInsetSide 24, fitInsetBottom 64,
// fitInsetBottomWeb 92, narrow 760, veryNarrow 440, low 820, layers 20, 25, 30, 40, 50, 60
function shellSizesFromTokens(shellGroup: Readonly<Record<string, string>>): ShellSizes;
```

`SHELL` equals `parseFloat` of the `shell` group of `cd-tokens.generated.json`; a drift test pins it
to the token fixture. `shellSizesFromTokens` reads a vendored JSON's `shell` group and throws, naming
the token, when a size is missing or neither `"<n>px"` nor a plain number (so `"12em"` fails instead
of silently becoming 12); unknown tokens are ignored.

A modeler pins its own vendored JSON the same way, in a unit test (Vitest or `node:test`), never in
its e2e suite: the check is pure data. Both expectations, because the fit math reads `SHELL` and the
stylesheet reads the tokens:

```ts
expect(SHELL).toEqual(shellSizesFromTokens(vendoredTokens.shell));
expect(Object.keys(vendoredTokens.shell)).toEqual(expect.arrayContaining(Object.values(SHELL_TOKENS)));
```

### Fit

```ts
const MAX_FIT_ZOOM = 1;
const FIT_ANIMATION_MS = 250;
const VIEW_TOLERANCE = 1e-3;

function fitViewbox(
  bounds: Bounds,
  container: Size,
  insets: Insets,
  maxZoom?: number,
): ScaledViewbox | undefined;

interface FitLayout {
  container: Size;
  host: ShellHost;
  paletteRow: PaletteRow;
  problemsVisible: boolean;
  zoomRaised?: boolean; // web: the zoom panel stands above the legal line (zoomRowRaised)
  legalHeight?: number; // web: the legal line's measured height, 20 per line (default one line)
  legendWidth?: number; // open legend's rendered width, undefined when closed/absent
  inspector?: { sheetTop?: number }; // present = open; sheetTop measured when it is a bottom sheet
}
function fitInsets(layout: FitLayout): Insets;
function freeRectCenter(container: Size, insets: Insets): Point | undefined; // px from the container's top left

function sameView(
  a: Pick<ScaledViewbox, "x" | "y" | "scale">,
  b: Pick<ScaledViewbox, "x" | "y" | "scale">,
  tolerance?: number,
): boolean;
function interpolateViewbox(from: ScaledViewbox, to: ScaledViewbox, progress: number): ScaledViewbox;
function easeStandard(progress: number): number; // cubic-bezier(0.4, 0, 0.2, 1)
```

- `fitViewbox` centres `bounds` in the free rectangle (container minus insets) at the largest scale
  that fits, capped at `maxZoom`, and returns a box with the container's aspect ratio, so
  `canvas.viewbox(box)` shows exactly that view (§5.9). `undefined` for a container with a 0 side,
  for bounds without width and height, or for a non-finite result; a zero width or height scales by
  the other dimension. An axis whose insets leave no room (a container lower or narrower than its
  chrome) centres in the whole container.
- `fitInsets` (§5.9): top 88, 140 in the second row; left and right 24; bottom 64, in the `web` host
  with a visible pill or with the zoom panel raised above the legal line (`zoomRaised`) 92, plus 20
  for every extra line of a wrapped legal line (`legalHeight`); right 324 (12 + 288 + 24) with an
  open side inspector (container wider
  than 760); left 12 + legend width + 24 with an open legend in containers wider than 440
  (`legendWidth <= 0` counts as closed); bottom `container.height − sheetTop + 12` with an open
  bottom sheet (up to 760). The sheet hides zoom panel, pill and legend (§5.11), so while it is open
  neither the legend nor the web pill counts; without a measured `sheetTop` the bottom stays 64.
- `freeRectCenter` is the centre of the free rectangle, where `fitViewbox` centres the content and
  keyboard creation places an element (§5.5), in pixels from the container's top left; an axis whose
  insets leave no room centres in the whole container, as in `fitViewbox`. `undefined` for a
  container with a 0 side. `Viewport.freeRectCenter()` turns it into diagram coordinates.
- `sameView` compares `scale` and the screen translation (`x · scale`, `y · scale`) within
  `tolerance` relative to `max(1, |value|)`; width and height never count, so a resize is no move.
- `interpolateViewbox` interpolates the scale in log space and the centre linearly.

### Zoom readout

```ts
const ZOOM_MIN = 0.2;
const ZOOM_MAX = 4;
function canZoomOut(zoom: number): boolean; // zoom > 0.2 · 1.001
function canZoomIn(zoom: number): boolean; // zoom < 4 · 0.999
function formatPercent(zoom: number, lang: string): string; // "86%", German "86 %" (U+00A0)
function formatNumber(value: number, lang: string): string; // a tag Intl rejects ("") formats as "en"
interface ZoomReadout {
  text: string;
  ariaLabel: string;
  canZoomOut: boolean;
  canZoomIn: boolean;
}
function zoomReadout(
  zoom: number,
  lang: string,
  messages: Pick<ShellMessages, "zoomToActualNow">,
): ZoomReadout;
```

### Keymap

```ts
type ChromeKey = "zoomIn" | "zoomOut" | "zoomToActual" | "fit";
interface KeyLike {
  key: string;
  code: string;
  metaKey: boolean;
  ctrlKey: boolean;
  shiftKey: boolean;
  altKey: boolean;
  isComposing?: boolean;
}
function matchChromeKey(event: KeyLike): ChromeKey | undefined;
function isUndoRedoKey(event: KeyLike): boolean;
const TEXT_FIELD_SELECTOR = "input, textarea, select, [contenteditable]:not([contenteditable='false'])";

interface KeyContext {
  host: ShellHost;
  inTextField: boolean; // target matches TEXT_FIELD_SELECTOR or isContentEditable
  menuOpen: boolean; // the shell's dropdown
  dialogOpen: boolean; // any shown [role="dialog"], [role="alertdialog"] or <dialog open>, modal or not
  modalOpen: boolean; // one of them with aria-modal="true" or :modal
  defaultPrevented: boolean; // the canvas or the modeler handled the key
  startScreen?: boolean; // web: the start screen shows; the chrome keys go to the browser
}
type KeyAction = ChromeKey | "closeMenu";
interface KeyDecision {
  action?: KeyAction;
  preventDefault: boolean;
  stopPropagation: boolean;
}
function decideKey(event: KeyLike, context: KeyContext): KeyDecision;

type Platform = "mac" | "other";
interface NavigatorLike {
  platform?: string;
  userAgentData?: { platform?: string };
}
function detectPlatform(navigator?: NavigatorLike): Platform;
function shortcutLabel(key: ChromeKey, platform: Platform, keyNames: ShellMessages["keyNames"]): string;
function ariaKeyShortcuts(key: ChromeKey, platform: Platform): string;
function ariaKeyShortcutsFromLabel(label: string): string | undefined;
function commandKeyLabel(key: string, platform: Platform, keyNames: { ctrl: string }): string; // "⌘O", "Ctrl+O"
```

`matchChromeKey` (§5.8) — Cmd/Ctrl is `metaKey || ctrlKey` on every platform, nothing matches with
`altKey` (AltGr):

| Chrome key     | Matches                                                                    |
| -------------- | -------------------------------------------------------------------------- |
| `zoomIn`       | Cmd/Ctrl + `key` `+` or `=` (with or without Shift), or `code` `NumpadAdd` |
| `zoomOut`      | Cmd/Ctrl + `key` `-` or `_`, or `code` `NumpadSubtract`                    |
| `zoomToActual` | Cmd/Ctrl + `key` `0`, or `code` `Numpad0` (also with NumLock off)          |
| `fit`          | `code` `Digit1` with Shift, without Cmd, Ctrl and Alt (every layout)       |

`decideKey` holds every key rule of §5.8 and §13.5; the shell's one `keydown` listener only applies
it. `stopPropagation` is only ever `true` in the `ide` host.

| Case                                                      | Action      | preventDefault | stopPropagation (`ide`) |
| --------------------------------------------------------- | ----------- | -------------- | ----------------------- |
| Escape (no modifier), menu open, not composing            | `closeMenu` | yes            | yes                     |
| Escape, popover or dialog open, or menu open while IME    | —           | no             | yes                     |
| zoom key or Shift+1 behind the web app's start screen     | —           | no             | — (web only)            |
| zoom key, not composing, not in a text field, no modal    | the key     | yes            | yes                     |
| zoom key while composing, in a text field or with a modal | —           | no             | yes                     |
| Shift+1, not composing, not in a text field, no modal     | `fit`       | yes            | yes                     |
| Shift+1 otherwise                                         | —           | no             | no (types "!")          |
| undo/redo key in a text field                             | —           | no             | yes                     |
| any other key with `defaultPrevented`                     | —           | no             | yes                     |
| everything else                                           | —           | no             | no                      |

- "No modifier" means no Meta, Ctrl, Alt or Shift. During IME composition Escape belongs to the IME.
- Zoom keys act whatever `defaultPrevented` says (diagram-js's keyboard prevents every key a listener
  answered, the shell's own guard included); a blocked Shift+1 is never stopped.
- `isUndoRedoKey` (Cmd/Ctrl + Z, Shift+Z, Y) decides by the typed character when it is ASCII, so
  QWERTZ and Dvorak work, and falls back to `code` `KeyZ`/`KeyY` only for non-ASCII layouts
  (Cyrillic, Greek). Cmd/Ctrl+Shift+Y is not redo: VS Code toggles its Debug Console with it.

Shortcut labels (§5.8): macOS `⌘+`, `⌘−` (U+2212), `⌘0`, `⇧1`; elsewhere `Ctrl+Plus`, `Ctrl+Minus`,
`Ctrl+0`, `Shift+1` from `keyNames`. `aria-keyshortcuts`: `Meta+= Meta+Plus`, `Meta+-`, `Meta+0`,
`Shift+1`; outside macOS `Control` for `Meta`. The platform is read in the page itself
(`detectPlatform(navigator)`, `userAgentData.platform || platform`, so an empty `userAgentData`
platform falls back), never in the extension host (VS Code Remote).

`ariaKeyShortcutsFromLabel` turns a shortcut chip label into `aria-keyshortcuts` (§5.6) for palette
entries and menu actions: `"L"` → `"L"`, `"⇧L"` → `"Shift+L"`, `"⌘⇧Z"` → `"Meta+Shift+Z"`,
`"Ctrl+Shift+E"` → `"Control+Shift+E"`, `"Del"` → `"Delete"`, `"Ctrl++"` → `"Control+Plus"`; a label
that is not one key combination (`"G then D"`, `"1–9"`) gives `undefined`.

### Appearance

```ts
type Theme = "light" | "dark";
type Kontrast = "hoch";
interface Appearance {
  theme: Theme;
  kontrast?: Kontrast;
}
function resolveAppearance(requested: Appearance, themes: readonly Theme[]): Appearance;
function appearanceFromColorThemeKind(kind: number): Appearance;
type ColorThemeSetting = "automatic" | "light" | "dark";
function requestedAppearance(kind: number, setting?: ColorThemeSetting): Appearance;
function appearanceFromBodyClasses(classes: Iterable<string>): Appearance | undefined;
function reducedMotionFromBodyClasses(classes: Iterable<string>): boolean; // vscode-reduce-motion
const REDUCED_MOTION_CLASS = "cd-shell-reduce-motion"; // on <html>, mirrored by mountVsCodeShell
interface AppearanceAttributes {
  "data-cd-theme": Theme;
  "data-cd-kontrast"?: Kontrast;
}
function appearanceAttributes(appearance: Appearance): AppearanceAttributes;
```

- `resolveAppearance` is the one decision of §13.5: a theme outside `themes` becomes `themes[0]`, so
  a modeler declaring `["light"]` is never half-dark; `kontrast: "hoch"` always passes (VS Code High
  Contrast on a light-only modeler gives `{ theme: "light", kontrast: "hoch" }`), any other value is
  dropped, since appearances arrive by `postMessage`. Throws for empty `themes`. `themes` is a static
  value of the modeler package, known before the first paint.
- `appearanceFromColorThemeKind`: 1 → light, 2 → dark, 3 → dark + hoch, 4 → light + hoch, other →
  light. `requestedAppearance` lets the setting's theme win unless it is `automatic`; the contrast
  always comes from the kind.
- `appearanceFromBodyClasses` checks `vscode-high-contrast-light` before `vscode-high-contrast`.
- `reducedMotionFromBodyClasses` reads VS Code's `workbench.reduceMotion` from the body class
  `vscode-reduce-motion`; while `<html>` carries `REDUCED_MOTION_CLASS`, the shell's animations stop
  and an explicit fit jumps, as under `prefers-reduced-motion`.

### Messages

```ts
interface ShellMessages {
  menu: string; // "Menu"
  tools: string; // "Tools"
  canvas: string; // "Diagram": aria-label of the focusable canvas <svg>, name the notation
  zoom: string; // "Zoom"
  zoomOut: string; // "Zoom out"
  zoomIn: string; // "Zoom in"
  zoomToActual(percent: string): string; // "Zoom to 100%"
  zoomToActualNow(percent: string, now: string): string; // "Zoom to 100% (now 86%)"
  fit: string; // "Fit to view"
  legend: string; // "Legend"
  closeLegend: string; // "Close legend"
  problems(count: number, formattedCount: string): string; // "1 problem", "2 problems"
  problemsLabel(count: number, errors: number, formattedCount: string, formattedErrors: string): string;
  // "2 problems, 1 error", "2 problems, no errors"
  showProblems: string; // "Show in Problems view"
  emptyHint: string; // "Pick a tool from the palette to start."
  insertExample: string; // "Insert example"
  invalidFile(diagram: string): string;
  // "This file isn't a valid <diagram> right now. The diagram shows the last valid version and is read-only until you fix the text."
  keyNames: { ctrl: string; shift: string; plus: string; minus: string }; // Ctrl, Shift, Plus, Minus
  // 0.2, web host (guide §2 shared terms)
  share: string; // "Share": default label of the primary action
  legal: string; // "Legal": aria-label of the legal line's <nav>
  copyright(year: number): string; // "© 2026 Miragon GmbH"
  opensInNewTab: string; // "Opens in a new tab": the legal links' description for screen readers
  newDiagram: string; // "New diagram": File group and the empty state's primary button
  openFile: string; // "Open…"
  showExample: string; // "Show example": File group and the empty state's ghost button
  importFile: string; // "Import…"
  appearance: string; // "Appearance"
  appearanceSystem: string; // "System"
  appearanceLight: string; // "Light"
  appearanceDark: string; // "Dark"
  problemsTitle: string; // "Problems": title of the problems popover
  problemSeverity(severity: ProblemSeverity): string; // "Error", "Warning": a popover row's icon, for screen readers
  close: string; // "Close": a toast's Close button
  dropFile: string; // "Drop file here"
  dropForbidden(reason: DropForbiddenReason): string;
  // "Drop one file at a time", "This modeler can't open this file type", "Close the dialog to drop a file"
  dropHint: string; // "Or drop a file here"
  openFileLink: string; // "Open a file…": the start screen's link to the File group's Open…
  cannotOpenFile(name: string, accepted: string): string;
  // "Couldn't open “map.png”. Drop a .storm, .json, or .txt file." (accepted: Intl.ListFormat disjunction)
}
// every key optional; an undefined value keeps the default
type ShellMessageOverrides = {
  [Key in Exclude<keyof ShellMessages, "keyNames">]?: ShellMessages[Key] | undefined;
} & { keyNames?: { [Key in keyof ShellMessages["keyNames"]]?: string | undefined } | undefined };
const defaultMessages: ShellMessages;
function resolveMessages(overrides?: ShellMessageOverrides): ShellMessages;
```

A localized modeler overrides the whole table (guide §2: one language per tool) and passes `lang`.
"Impressum" and "Datenschutz" are not in the table: they stay German with `lang="de"` in every tool
language (§2).

### Layout decisions

```ts
const PALETTE_CLEARANCE = 16;
const TOOLTIP_DELAY_MS = 300;
const INVALID_STATUS_DELAY_MS = 800;
interface PaletteRowInput {
  containerWidth: number;
  paletteWidth: number;
  menuRight: number;
  primaryLeft?: number;
}
function decidePaletteRow(input: PaletteRowInput): PaletteRow;
function legendStartsOpen(containerHeight: number): boolean; // > 820
interface TooltipPlacementInput {
  anchor: Bounds;
  island: Bounds;
  tooltip: Size;
  container: Size;
}
function placeTooltip(input: TooltipPlacementInput): Point;
```

`decidePaletteRow` (§5.15): `second-row` up to 760px container width, or when the centred palette
would keep less than 16px to the menu trigger (or to the primary action); `paletteWidth` is the
intrinsic border-box width (`offsetWidth − clientWidth + scrollWidth`: the content including the
borders), so the decision does not flip once the palette scrolls in the second row.

`placeTooltip` (§5.6): below an island in the upper half at `island.bottom + 8` (top row 60, second
row 112), above one in the lower half ending 8px above it (bottom row: `bottom: 60px`), centred on
`anchor`, shifted to keep 12px to the sides.

### Web host decisions (0.2)

The web column's DOM-free parts are in `./core` as well, documented with their islands under
[Web host](#web-host-02): `decideTopRow` (label collapse before the second row), `zoomRowRaised`
(legal line and zoom panel), `dragVerdict` and `acceptsFile` (drop zone), `toastLifetime`,
`toastToEvict`, `toastStackWidth`, `toastStackBottom` and their constants (toasts),
`parseAppearanceChoice`, `documentMode`, `webModeScript` and `webHeadMarkup` (mode; they run in a
Vite config or a build script), `problemSummary` (problems popover).

## `.` — the chrome

Exports everything of `./core` plus:

```ts
function mountShell(root: HTMLElement, options: ShellOptions): ShellHandle;

interface ShellOptions {
  host: ShellHost;
  canvas?: HTMLElement; // diagram-js's container; omitted: the shell creates it (handle.canvas)
  lang?: string; // see below; the embedded root carries lang itself
  messages?: ShellMessageOverrides;
  platform?: Platform; // default detectPlatform(navigator)
  keyScope?: "document" | "root"; // default "document", "root" for embedded
  themes?: readonly Theme[]; // default ["light"]; read in the embedded and web hosts, see below
  menu?: MenuGroups;
  problems?: ProblemsOptions;
  legend?: LegendOptions;
  inspector?: InspectorOptions;
  emptyHint?: EmptyHintOptions;
  // 0.2, read in the web host only (see Web host below)
  primary?: PrimaryActionOptions;
  legal?: LegalLineOptions;
  file?: FileMenuOptions;
  appearance?: WebAppearanceOptions; // required when themes includes "dark"
  emptyState?: EmptyStateOptions;
  dropZone?: DropZoneOptions;
}
```

`mountShell` turns `root` into the shell: class `cd-shell`, `container: cd-shell / size`,
`isolation: isolate`. `root` must be sized from outside, otherwise size containment collapses it to 0:
in an own document a root that is a direct child of `<body>` gets `height: 100%` from `shell.css`
(a zero-specificity rule), any other root and an embedded one need an explicit size. In the `ide` and
`web` hosts `<html>` gets `cd-shell-document` (own-document reset). The shell observes the root and
the registered palette with a `ResizeObserver` (palette row, legend start state; 0 × 0 is skipped)
and installs exactly one `keydown` listener (bubble phase) on `document` or on the root.

`lang` is the tool's UI language for `Intl` (guide §2: one language per tool). Default in an own
document (`ide`, `web`): the closest `[lang]` of the root (the `<html lang>` the host wrote), else
`"en"`. In the `embedded` host the page's language is not the tool's, so the default is the root's
own `lang` attribute, else `"en"`; the embedded root carries `lang` itself. A localized modeler
passes `lang` together with its messages.

**The embedded root's mode** (§13.3). The token CSS resolves the roles on the nearest
`[data-cd-theme]`, so a root without one would take the mode of a themed host page (designIQ, a web
app on `system` under a dark OS) and be half-dark against its light-drawn diagram. The `embedded`
root therefore carries `data-cd-theme="<themes[0]>"` itself (until the contract's `appearance`
surface, planned for a later 1.x minor of `@miragon/modeler-api`, there is no channel to ask an
embedded modeler for another mode, so it stays in its first one), and mirrors the host's
`data-cd-kontrast` from the nearest mode carrier above it for as long as it lives (a
`MutationObserver` on the document's `data-cd-theme`/`data-cd-kontrast` attributes), because its own
`data-cd-theme` would otherwise drop the host's high contrast. In the `ide` host the
host writes the mode on `<html>` and `themes` is not read; in the `web` host the page's head script
writes it before the first paint and `themes` decides whether the shell renders the Appearance
group (see [Mode](#mode-133)). An empty `themes` throws before anything is mounted.

**Order with document listeners.** Listeners on one target run in registration order. A modeler
whose own keyboard listens on `document` (Event Storming does) constructs its diagram **before**
`mountShell`, so the shell's listener runs after it and sees `defaultPrevented`; a renderer that
creates its diagram lazily (Event Storming's `Modeler` on the first `get`) calls
`modeler.get("canvas")` first. Listeners on the canvas `<svg>` (diagram-js `keyboard`) have no
ordering constraint. Such a document keyboard must leave alone what is not meant for the canvas:
keys with `defaultPrevented` and keys whose target lies outside the canvas container (the menu
stops the keys it consumes, the palette its own, but the zoom panel's buttons do not); in the IDE
host it binds no undo or redo, and on the canvas it handles Cmd/Ctrl+A (see `./diagram-js`,
Keyboard).

### Menu (§5.4)

```ts
interface MenuGroups {
  model?: readonly MenuEntry[];
  export?: readonly MenuEntry[];
  help?: readonly MenuEntry[];
}
type MenuGroupName = "file" | "model" | "export" | "appearance" | "help"; // data-menu-group
type MenuEntry = MenuActionEntry | MenuDialogEntry | MenuCheckboxEntry | MenuRadioGroup;

interface MenuItemBase {
  id: string;
  label: string;
  icon?: ShellIconName;
  disabled?: () => boolean;
  keepEnabledWhenReadOnly?: boolean; // a Model entry that is pure view state; default false
}
interface MenuActionEntry extends MenuItemBase {
  kind: "action";
  shortcut?: string;
  ariaKeyShortcuts?: string; // default ariaKeyShortcutsFromLabel(shortcut); "" sets none
  danger?: boolean;
  onSelect(): void;
}
interface MenuDialogEntry extends MenuItemBase {
  kind: "dialog";
  shortcut?: string; // 0.2: the chip of a dialog entry ("?" for "Keyboard shortcuts…")
  ariaKeyShortcuts?: string; // as for an action
  onSelect(): void;
}
interface MenuCheckboxEntry extends MenuItemBase {
  kind: "checkbox";
  checked(): boolean;
  onToggle(checked: boolean): void;
}
interface MenuRadioGroup {
  kind: "radio";
  id: string;
  label: string;
  options: readonly MenuRadioOption[];
  value(): string | undefined;
  onSelect(value: string): void;
  disabled?: () => boolean;
  keepEnabledWhenReadOnly?: boolean;
}
interface MenuRadioOption {
  value: string;
  label: string;
}
```

- Groups render in the fixed order File, Model, Export, Appearance, Help with separators; empty
  groups collapse. File and Appearance exist in the web host only and the shell builds them
  (`ShellOptions.file`, the Appearance group of a dark-capable modeler, see
  [File and Appearance groups](#file-and-appearance-groups-54-133)); Model, Export and Help come
  from `MenuGroups`. With a legend (and `legend.menuEntry !== false`) the shell appends the checkbox
  "Legend" to the Model group.
- `action` and `dialog`: the menu closes, focus returns to the trigger, then `onSelect` runs (a host
  dialog then hands focus back to a visible control). `dialog` adds `aria-haspopup="dialog"`; its
  label ends with "…" (U+2026), and in 0.2 the modeler renders the dialog itself (see
  [Modeler dialogs](#modeler-dialogs)).
- `checkbox` and `radio` toggle and keep the menu open. State is read through `checked()`, `value()`
  and `disabled()` whenever the menu opens and on `menu.refresh()`.
- Icons only from the common set and only where the guide gives one; the icon column stays 16px wide
  without an icon. An action or dialog entry with a `shortcut` shows its chip and carries
  `aria-keyshortcuts`.
- On a read-only canvas (`setReadOnly(true)`, §13.5) every Model entry is `aria-disabled` unless it
  sets `keepEnabledWhenReadOnly`; disabled entries stay focusable and do nothing. View toggles stay
  usable on a read-only canvas: the shell's Legend checkbox carries `keepEnabledWhenReadOnly` itself,
  and a modeler sets it on its own pure view state (Event Storming's "Type captions"), never on an
  entry that changes the document (Level, "Map size…"). File, Export, Appearance and Help entries are never locked.
  Guide §13.5 (design system 1.13.0): only Model entries that change the document are `aria-disabled`.
- The trigger is `hidden` while no group has an entry (no menu groups and no Legend entry).
- Keys: Enter, Space and ↓ on the trigger open on the first entry, ↑ on the last; ↑/↓ wrap, Home/End
  jump, a letter jumps to the next entry starting with it; Escape and Tab close (Escape returns focus
  to the trigger). Every key the menu consumes (those, plus Enter, Space, Delete and Backspace in the
  dropdown) is stopped at the menu in every host, so a modeler's keyboard on `document` never acts
  on it (Event Storming would move the selection on ↓); Escape, Tab, modified keys and the chrome
  keys go on (Shift+1 fits, Cmd/Ctrl + `+` zooms with the menu open).
- A `pointerdown` outside (capture phase on `document`) closes without moving focus and without
  stopping the event, so it still acts on its target. So does the window losing the focus (a click
  into the VS Code workbench or another iframe).

### Modeler dialogs

0.2 has no dialog component (a later candidate, see [Out of scope for 0.2](#out-of-scope-for-02)), so
a modeler renders its dialogs, the "Keyboard shortcuts…" dialog of the Help group (§5.4) first among
them, and meets §8 on its own:

- **Layer.** `z-index: var(--cd-shell-ebene-dialog)` (50) applies only to a dialog outside the top
  layer, inside `shell.root`. A `<dialog>` opened with `showModal()` or an element of the popover API
  lies in the browser's top layer above everything, whatever its `z-index`. The shell's keys count it
  either way: any shown `<dialog>`, `[role="dialog"]` or `[role="alertdialog"]` in the document
  (embedded: in the root) is open, and a modal one blocks the zoom keys.
- **Panel and backdrop** (§8): panel `--cd-ui-flaeche-hoch` with 1px `--cd-ui-linie`, radius `md`,
  `shadow-3`, `width: min(560px, 100cqw - 32px)`, `max-height: calc(100cqh - 32px)` with a scrolling
  body; header (padding `16px 16px 8px 24px`, title 21px/600) with Close as a 32 × 32 ghost icon
  button (Lucide `x` 16px, `aria-label` "Close"); backdrop
  `background: var(--cd-ui-backdrop); backdrop-filter: blur(3px) grayscale(1)` in both modes. The
  shortcut chips look like the tooltip's (§5.6).
- **High contrast** (`[data-cd-kontrast="hoch"]`, §6, §5.14): no shadow, border `--cd-ui-kontur`,
  focus ring 3px.
- **Forced colours** (`@media (forced-colors: active)`): border `CanvasText`, focus ring `Highlight`.
  The shell's own high-contrast and forced-colours rules match only `cd-shell-*` classes, so they
  do not reach a modeler's dialog.
- **Focus** (§8): it moves into the dialog and stays there, Escape and a click on the backdrop close
  it, and it returns to the control that opened it (the menu trigger after a menu entry).
- **Read-only:** the shortcuts dialog stays usable on a read-only canvas (§13.5).
- **Teardown:** the dialog is the modeler's content in `shell.root`, removed by the modeler (see
  `destroy()` below).

### Problems, legend, inspector, empty-file hint

```ts
interface ProblemsOptions {
  onActivate?(): void; // the IDE host opens its Problems view (give it there); ignored in the web host
  onSelectItem?(item: ProblemItem): void; // 0.2: a row of the problems popover, after it closed
}
interface LegendOptions {
  render(body: HTMLElement): void; // once; a throw unwinds the whole mount
  open?: boolean; // remembered start state; default (also undefined) legendStartsOpen(container height)
  onToggle?(open: boolean): void; // every change (close button, checkbox, setOpen, toggle); persist it
  menuEntry?: boolean; // default true
}
interface InspectorOptions {
  label: string; // aria-label of the <aside>
}
interface EmptyHintOptions {
  onInsertExample?(): void; // shows "Insert example"; the modeler writes the example as one edit
}
```

### Handle

```ts
interface ShellHandle {
  readonly root: HTMLElement;
  readonly canvas: HTMLElement;
  readonly host: ShellHost;
  readonly lang: string;
  readonly platform: Platform;
  readonly messages: ShellMessages;
  readonly menu: MenuHandle;
  readonly tooltip: TooltipHandle;
  readonly legend: LegendHandle | undefined;
  readonly inspector: InspectorHandle | undefined;
  readonly primary: PrimaryActionHandle | undefined; // 0.2, web host with `primary`
  readonly appearance: AppearanceHandle | undefined; // 0.2, web host with "dark" in `themes`
  setZoomTarget(target: ZoomTarget | null): void;
  fitInsets(): Insets;
  registerPalette(palette: PaletteRegistration): () => void;
  setProblems(summary: ProblemSummary): void;
  setStatus(status: StatusMessage | null, options?: { delayMs?: number }): void;
  setEmptyHint(visible: boolean): void;
  setReadOnly(readOnly: boolean, options?: { delayMs?: number }): void;
  isReadOnly(): boolean;
  setEmptyState(shown: boolean): void; // 0.2, web host with `emptyState`
  isEmptyStateShown(): boolean;
  toast(request: ToastRequest): ToastHandle; // 0.2, web and embedded; inert in the ide host
  destroy(): void;
}
interface MenuHandle {
  readonly trigger: HTMLButtonElement;
  readonly dropdown: HTMLElement;
  isOpen(): boolean;
  open(focus?: "first" | "last"): void;
  close(options?: { restoreFocus?: boolean }): void;
  refresh(): void;
  setGroups(groups: MenuGroups): void;
}
interface TooltipContent {
  label: string;
  shortcut?: string;
}
interface TooltipHandle {
  attach(control: HTMLElement, content: TooltipContent | (() => TooltipContent | null)): () => void;
  hide(): void;
}
interface LegendHandle {
  readonly element: HTMLElement;
  readonly body: HTMLElement;
  isOpen(): boolean;
  setOpen(open: boolean): void;
  toggle(): void;
}
interface InspectorHandle {
  readonly element: HTMLElement;
  isOpen(): boolean;
  open(): void;
  close(): void;
}
interface PaletteRegistration {
  element: HTMLElement; // .djs-palette
  entryTooltip(entry: HTMLElement): TooltipContent | null;
  setReadOnly(state: PaletteReadOnlyState): void; // on registration and on every change
}
interface PaletteReadOnlyState {
  locked: boolean; // veto every entry but Lasso and Hand, from the invalid import on
  shown: boolean; // mark them aria-disabled and muted, once the delay has passed
}
interface ProblemSummary {
  count: number;
  errors: number;
  items?: readonly ProblemItem[]; // 0.2: the popover's rows; the ide host ignores them
}
type StatusSeverity = "danger" | "warning";
interface StatusMessage {
  severity: StatusSeverity;
  text: string;
}
```

- `setZoomTarget` binds zoom panel, readout and chrome keys; the readout reads `zoom()` at most once
  per animation frame after `onChange`. With `null` the three buttons are `aria-disabled`; the readout
  never is (§5.8), its click does nothing then. Buttons and keys never call `stepZoom` past a limit
  (zoom out at or below 20 % never zooms in), never `zoomToActual` at exactly 100 % and never `fit`
  while `canFit()` is false.
- `fitInsets()` is `fitInsets(layout)` of `./core` for what is open and measured right now (palette
  row, pill, legend width, side inspector or measured sheet top).
- `registerPalette` is the adapter's API (`connectDiagramJs` calls it, possibly from inside
  diagram-js's `palette.create`, before any entry exists); a later registration replaces the
  earlier one, and the returned unregister function is safe to call twice and after `destroy()`.
- `setProblems`: the pill shows for `count > 0` with `Intl` numbers in `lang` and the icon by severity;
  its tooltip "Show in Problems view" exists only in the `ide` host (`aria-describedby`, since it
  says more than the label). A click calls `onActivate` in the `ide` host and in an `embedded` host
  that gives it; in the `web` host (and an `embedded` one without `onActivate`) it opens the
  problems popover with `summary.items` (see [Problems popover](#problems-popover-510)).
- `setStatus(status, { delayMs })`: shows after `delayMs` (an invalid file: `INVALID_STATUS_DELAY_MS`,
  so typing does not flicker and `role="alert"` does not re-announce), hides at once with `null`.
  Repeated calls while the delay runs keep the first timer (the box appears once the text stayed
  invalid for 800ms), `null` drops it, and an unchanged text is not written again.
- `setReadOnly(true, { delayMs })` (invalid file, §13.5) locks at once: `isReadOnly()`, the palette
  veto (every entry but Lasso and Hand) and the Model entries of the menu without
  `keepEnabledWhenReadOnly`. The marks follow after `delayMs` (pass `INVALID_STATUS_DELAY_MS`, as for
  the status box): `data-readonly` on the root and the palette entries `aria-disabled`, muted,
  previews in `grayscale(1)`. Repeated calls keep the first timer; `setReadOnly(false)` unlocks and
  hides at once. The legend is a view toggle: its Legend checkbox and its close button keep working
  under the lock (guide §13.5, design system 1.13.0).
- The canvas is the modeler's to lock, from the same invalid import on (§13.5, what the read-only
  state blocks): no context pad, no move, resize, delete or paste, and no label editor (also not on
  a double-click). Selection, zoom, pan, the export of the last valid state and the "Keyboard
  shortcuts…" dialog stay. The modeler reads `isReadOnly()` or keeps a lock of its own next to
  `setReadOnly` (Event Storming's `eventStormingReadOnly` service); the kit's `readOnly` case checks
  each of these.
- `setEmptyHint` shows or hides the hint; `connectDiagramJs` keeps it in sync with the diagram. When
  the hint (its "Insert example") or the closing inspector holds the focus, the focus moves to the
  canvas `<svg>` (else the menu trigger) instead of falling to `<body>`.
- `tooltip.attach` shows the chrome tooltip after `TOOLTIP_DELAY_MS` hover or at once on keyboard
  focus (`:focus-visible`, also on `aria-disabled` buttons); after a hover-hide a neighbour shows at
  once for the same delay. It hides on click (until the pointer leaves), Escape, leave, blur and menu
  open, never on touch. It sets `aria-describedby` only when its text says more than the control's
  name, which a shortcut chip does unless the control names its keys in `aria-keyshortcuts`. The
  shell attaches it to its own buttons; the palette gets it through `registerPalette`.
- The legend's start state comes from `legend.open` or, at the first non-zero container size, from
  `legendStartsOpen`; that automatic decision does not call `onToggle`. Its close button returns the
  focus to the menu trigger.
- `destroy()` removes every element, class, attribute, listener, observer and timer the shell added
  and restores what was there before the mount: a passed `canvas` stays where it is, without
  `cd-shell-canvas`, and a `cd-shell-document` class or a `lang` the page already had stays (the
  class `renderWebviewHtml` writes on `<html>` included). A second call and every later handle call
  are no-ops. A mount that throws (a modeler's `legend.render`) undoes the same before the error
  propagates. Content a modeler adds to `shell.root` (a dialog, a popover) is the modeler's: it
  removes it in its own teardown, before or with `shell.destroy()`, for example on `diagram.destroy`,
  because the shell removes only what it added.
- Element ids (`cd-shell-menu-N`, `cd-shell-tooltip-N`, `cd-shell-legend-title-N`) count on one
  page-global counter (`Symbol.for("@miragon/modeler-shell.mounts")`), so two modelers that each
  bundle the shell never share an id on one foreign page.

### Icons

```ts
type IconNode = ReadonlyArray<readonly [tag: string, attributes: Readonly<Record<string, string>>]>;
type ShellIconName =
  | "menu"
  | "minus"
  | "plus"
  | "maximize"
  | "check"
  | "x"
  | "file-plus"
  | "folder-open"
  | "import"
  | "file-image"
  | "file-code-corner"
  | "keyboard"
  | "share-2"
  | "circle-x"
  | "triangle-alert"
  | "square-dashed-mouse-pointer"
  | "hand"
  | "line-segment"
  | "unfold-horizontal"
  | "workflow";
const ICONS: Readonly<Record<ShellIconName, IconNode>>; // lucide-static 1.59.0, unchanged (ISC); line-segment = spline with a straight segment
interface IconOptions {
  size?: number; // default 16
  strokeWidth?: number; // default 2.5
  className?: string;
}
const PALETTE_TOOL_ICON: Readonly<IconOptions>; // { size: 20, strokeWidth: 2 }
function iconMarkup(icon: ShellIconName | IconNode, options?: IconOptions): string;
function iconElement(icon: ShellIconName | IconNode, options?: IconOptions): SVGSVGElement;
```

`iconMarkup` renders decorative SVG (`aria-hidden="true"`, `focusable="false"`, `fill="none"`,
`stroke="currentColor"`, round caps and joins) and lets only Lucide's elements and geometry
attributes pass, so palette providers can put it into an entry's `html`.

The geometry is Lucide's (ISC, © Lucide Icons and Contributors); `check`, `circle-x`, `maximize`,
`minus`, `plus`, `triangle-alert` and `x` derive from Feather (MIT, © Cole Bemis), as Lucide's
LICENSE lists them (two by their Feather names, `x-circle` and `alert-triangle`). `src/dom/icons.ts`
opens with a legal comment (`/*! … @license … */`) naming both, which esbuild keeps in the `dist`
chunk that carries the icons (ESM and CJS). A consumer's bundler may drop or move legal comments (its
`legalComments` setting), so a VSIX or a web bundle that contains the shell carries the Lucide and
Feather notices of `THIRD_PARTY_NOTICES.md` itself.

### DOM, `data-chrome` and classes

```html
<html class="cd-shell-document" lang="en" data-cd-theme="light">  <!-- own document: ide, web -->
<div class="cd-shell" data-cd-shell-host="ide" data-palette="top"
     data-legend="open" data-inspector="open" data-problems="shown" data-readonly>  <!-- state attributes only while true -->
     <!-- embedded: lang="en" data-cd-theme="light" [data-cd-kontrast="hoch"] on the root itself -->
  <button class="cd-shell-menu-trigger" data-chrome="menu" aria-label="Menu" aria-haspopup="menu"
          aria-expanded="false" aria-controls="cd-shell-menu-1">…</button>
  <div class="cd-shell-canvas">                         <!-- diagram-js container -->
    <div class="djs-container">
      <div class="djs-palette" data-chrome="palette">   <!-- moved before the <svg> -->
        <div class="djs-palette-entries" role="toolbar" aria-label="Tools">
          <div class="group" data-group="tools">
            <div class="entry" data-action="lasso-tool" role="button" aria-label="…" tabindex="0" aria-pressed="false" aria-keyshortcuts="L">…</div>
      <svg tabindex="0" role="application" aria-label="Diagram">…</svg>
  <div class="cd-shell-status" data-chrome="status" data-severity="danger" role="alert">…</div>
  <div class="cd-shell-hint"><p class="cd-shell-hint-text">…</p><button class="cd-shell-hint-action">…</button></div>
  <aside class="cd-shell-inspector" data-chrome="inspector" aria-label="…">…</aside>
  <button class="cd-shell-problems" data-chrome="problems" aria-label="2 problems, 1 error">…</button>
  <section class="cd-shell-legend" data-chrome="legend" aria-labelledby="…">…</section>
  <div class="cd-shell-zoom" data-chrome="zoom" role="group" aria-label="Zoom">
    <button data-zoom="out"> <button class="cd-shell-zoom-readout" data-zoom="actual"> <button data-zoom="in">
    <span class="cd-shell-zoom-separator"> <button data-zoom="fit">
  </div>
  <div class="cd-shell-layer">                           <!-- z 40: dropdown and tooltip -->
    <div class="cd-shell-menu" id="cd-shell-menu-1" role="menu" aria-label="Menu">…</div>
    <div class="cd-shell-tooltip" role="tooltip"><span class="cd-shell-tooltip-label">Zoom in</span><kbd class="cd-shell-kbd">⌘+</kbd></div>
  </div>
</div>
```

The DOM order is the tab order of §5.14 (menu trigger, palette, canvas, status box, hint, inspector,
pill, legend, zoom panel; the web host adds the primary action after the menu trigger, the
empty-state card after the hint and the legal line before the zoom panel, see
[Web host](#web-host-02)); nothing has a positive `tabindex`, and a renderer adds no tab stop of its
own around the canvas (no `tabindex` on `.djs-container`). Islands that are not shown are `hidden`.

| `data-chrome`      | Element                       | Notes                                      |
| ------------------ | ----------------------------- | ------------------------------------------ |
| `menu`             | menu trigger                  | icon only, Lucide `menu`                   |
| `palette`          | diagram-js `.djs-palette`     | set by `shellModule`                       |
| `primary`          | primary action (web)          | only with `primary`, see Web host          |
| `zoom`             | zoom panel                    | `[−][NN%][+] \| [Fit]`                     |
| `problems`         | problems pill                 | `hidden` at 0                              |
| `legend`           | legend card                   | only with `legend`                         |
| `inspector`        | inspector `<aside>`           | only with `inspector`                      |
| `status`           | status box under the palette  | `role="alert"` (danger) or `role="status"` |
| `legal`            | legal line (web)              | always in the web host                     |
| `toasts`           | toast stack (web, embedded)   | always present, no box while empty         |
| `empty-state`      | start screen card (web)       | only with `emptyState`                     |
| `drop-zone`        | drop overlay (web)            | only with `dropZone`, during a file drag   |
| `problems-popover` | problems list (web, embedded) | in the layer, opened by the pill           |

| Class                                                                                                                                                                                                                                                                  | Part                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `cd-shell`, `cd-shell-document`, `cd-shell-canvas`, `cd-shell-layer`                                                                                                                                                                                                   | root, own document, canvas slot, layer      |
| `cd-shell-island`, `cd-shell-target`                                                                                                                                                                                                                                   | glass island, 32px target in an island      |
| `cd-shell-menu-trigger`, `cd-shell-menu`, `cd-shell-menu-item`, `cd-shell-menu-item-icon`, `cd-shell-menu-item-label`, `cd-shell-menu-item-end`, `cd-shell-menu-separator`, `cd-shell-menu-heading`, `cd-shell-menu-group`                                             | menu                                        |
| `cd-shell-menu-shortcut`, `cd-shell-menu-check`                                                                                                                                                                                                                        | shortcut text and check mark of an entry    |
| `cd-shell-tooltip`, `cd-shell-tooltip-label`, `cd-shell-kbd`                                                                                                                                                                                                           | tooltip and shortcut chip                   |
| `cd-shell-zoom`, `cd-shell-zoom-readout`, `cd-shell-zoom-separator`                                                                                                                                                                                                    | zoom panel                                  |
| `cd-shell-problems`, `cd-shell-problems-icon`, `cd-shell-problems-text`                                                                                                                                                                                                | pill                                        |
| `cd-shell-status`, `cd-shell-status-icon`, `cd-shell-status-text`                                                                                                                                                                                                      | status box (bar as `::before`)              |
| `cd-shell-hint`, `cd-shell-hint-text`, `cd-shell-hint-action`                                                                                                                                                                                                          | empty-file hint                             |
| `cd-shell-legend`, `cd-shell-legend-header`, `cd-shell-legend-title`, `cd-shell-legend-close`, `cd-shell-legend-body`                                                                                                                                                  | legend card                                 |
| `cd-shell-legend-row`, `cd-shell-legend-preview`, `cd-shell-legend-separator`                                                                                                                                                                                          | rows the modeler renders into the body      |
| `cd-shell-inspector`                                                                                                                                                                                                                                                   | inspector                                   |
| `cd-shell-no-transition`                                                                                                                                                                                                                                               | on `<html>` for one frame of a mode switch  |
| `cd-shell-button` (`data-variant="primary"` / `"ghost"`)                                                                                                                                                                                                               | buttons of the web chrome (0.2)             |
| `cd-shell-primary`, `cd-shell-primary-label`                                                                                                                                                                                                                           | primary action (0.2)                        |
| `cd-shell-legal`, `cd-shell-legal-item`                                                                                                                                                                                                                                | legal line, a separator with its link (0.2) |
| `cd-shell-empty-state`, `cd-shell-empty-state-mark`, `cd-shell-empty-state-title`, `cd-shell-empty-state-text`, `cd-shell-empty-state-actions`, `cd-shell-empty-state-hint`, `cd-shell-empty-state-open-item`, `cd-shell-empty-state-open`, `cd-shell-empty-state-key` | empty-state card (0.2)                      |
| `cd-shell-drop-zone`, `cd-shell-drop-zone-chip`                                                                                                                                                                                                                        | drop zone (0.2)                             |
| `cd-shell-toasts`, `cd-shell-toast`, `cd-shell-toast-dot`, `cd-shell-toast-text`, `cd-shell-toast-action`, `cd-shell-toast-close`                                                                                                                                      | toasts (0.2)                                |
| `cd-shell-live`, `cd-shell-live-region` (`data-live="polite"` / `"assertive"`)                                                                                                                                                                                         | the toasts' live regions (0.2)              |
| `cd-shell-problems-popover`, `cd-shell-problems-popover-title`, `cd-shell-problems-list`, `cd-shell-problem`, `cd-shell-problem-icon`, `cd-shell-problem-message`, `cd-shell-problem-location`                                                                         | problems popover (0.2)                      |

Internal attributes: `data-severity` on pill and status box, `data-danger` on a dangerous menu
entry, `data-menu-id` on entries and radio groups (the shell's Legend entry is `data-menu-id="legend"`,
so a modeler does not use the id `legend`), `data-menu-group` (`file`, `model`, `export`, `appearance`,
`help`) on entries and radio groups, which the kit's `readOnly` case reads, `data-menu-value` on radio options,
`data-zoom` on the zoom buttons.

Modelers style only their own content (legend rows, inspector fields); every other class is
internal to the shell CSS and may change in a minor release.

### Geometry

Relative to the shell root's padding box (a border a foreign page gives the root does not count),
±1px (§5.2 to §5.15). `ide` and `embedded` share the IDE column.

| Island      | Box                                                                                                                                                   |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `menu`      | 40 × 40 at `top: 12px; left: 12px`                                                                                                                    |
| `palette`   | 40 high at `top: 12px`, horizontally centred; second row `top: 64px`, at most `100cqw − 24px` wide                                                    |
| `zoom`      | 173 × 40 (56px readout) at `right: 12px; bottom: 12px`                                                                                                |
| `problems`  | 40 high at `left: 12px; bottom: 12px` (web `40px`)                                                                                                    |
| `legend`    | `left: 12px`, `bottom: 12px` without pill, `60px` with pill (web `40px`, `88px`); up to 440px width at least `60px`                                   |
| `inspector` | 288 wide at `top: 64px; right: 12px`; up to 760px width a bottom sheet with 12px left, right and bottom                                               |
| `status`    | centred at `top: 64px` (second row `116px`); with an open side inspector centred in the strip left of it; 1px border and 4px bar in the status colour |
| dropdown    | `top: 60px; left: 12px`, at least 248px wide                                                                                                          |
| tooltip     | top row `top: 60px`, second row `top: 112px`, bottom row `bottom: 60px`                                                                               |

The web column adds (see [Web host](#web-host-02)):

| Island             | Box (web host)                                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `primary`          | 40 high at `top: 12px; right: 12px`; 40 wide while `data-primary="collapsed"`, else icon, gap and label with padding `0 16px` |
| `legal`            | 20 high at `left: 12px; bottom: 12px`, at most `100cqw − 24px` wide; wrapped 20 per line, the stack above rising with it      |
| `problems`         | `left: 12px; bottom: 40px` (0.1)                                                                                              |
| `legend`           | `bottom: 40px`, with pill `88px` (0.1); up to 440px width at least `60px`, `88px` with `data-zoom-row="raised"`               |
| `zoom`             | `right: 12px; bottom: 12px`; `bottom: 40px` with `data-zoom-row="raised"`                                                     |
| `problems-popover` | `left: 12px`, its bottom 8px above the pill's top (`bottom: 88px`), `min(320px, 100cqw − 24px)` wide, at most 320 high        |
| `toasts`           | centred, `min(480px, 100cqw − 24px)` wide, `bottom: toastStackBottom(…)` (12px unless its widest card meets the bottom row)   |
| `empty-state`      | centred in the container (`centerX`, `centerY`), `min(400px, 100cqw − 24px)` wide                                             |
| `drop-zone`        | `inset: 12px` while a file drag is on the page                                                                                |

Layers (§5.13): the canvas slot is layer 0 with `isolation: isolate` (palette `z-index: 110` above
context pad and label editor at 100); islands `--cd-shell-ebene-inseln` (20, the legal line and the
empty-state card included), inspector 25, menu trigger and primary action 30, layer 40 (dropdown,
tooltip, problems popover, drop zone), modeler dialogs 50, toasts 60 (in the web host a manual
popover in the top layer, see [Toasts](#toasts-8-9)). The 50 holds only outside the top layer; a `showModal()`
`<dialog>` or a popover-API element lies above everything (see [Modeler dialogs](#modeler-dialogs)).

Inside the canvas slot, persistent overlays a modeler adds (element toolbars, its own context pad,
the label editor) stay at `z-index` 100 or below, under the palette at 110. Transient popups the user
opens from them (diagram-js's popup menu at 200, a colour picker) may cover the palette while they are
open. All of them stay inside `.djs-container`, so they never cover an island. This is the shell's
rule of guide §5.13 (design system 1.13.0).

## Web host (0.2)

`host: "web"` is a Miragon web app that owns its page: the web column of guide §5.2. 0.1 covered its
keys (the chrome keys prevent the browser's page zoom), fit insets and the pill and legend offsets;
0.2 renders the rest of the column. Everything in this section is read in the `web` host only and
ignored by `ide` and `embedded` hosts, except toasts and the problems popover, which an embedded
modeler shows as well (§5.2: until the contract has a channel for messages to the host).
`mountVsCodeShell` does not accept these options at all; the IDE host is unchanged.

| Anchor (§5.2) | Web app                                                  | Option → handle                         | `data-chrome`                                     |
| ------------- | -------------------------------------------------------- | --------------------------------------- | ------------------------------------------------- |
| top left      | menu trigger: File, Model, Export, Appearance, Help      | `file`, `menu`, `themes` + `appearance` | `menu`                                            |
| top centre    | palette                                                  | `shellModule`                           | `palette`                                         |
| top right     | primary action, label collapses first (§5.15)            | `primary` → `shell.primary`             | `primary`                                         |
| bottom left   | legal line; above it the pill (with its list) and legend | `legal`, `problems`, `legend`           | `legal`, `problems`, `problems-popover`, `legend` |
| bottom right  | zoom panel, raised above the legal line where they meet  | —                                       | `zoom`                                            |
| bottom centre | toasts                                                   | `shell.toast()`                         | `toasts`                                          |
| centre        | empty-state card on a fresh start                        | `emptyState` → `shell.setEmptyState()`  | `empty-state`                                     |
| whole page    | drop zone for files                                      | `dropZone`                              | `drop-zone`                                       |

```html
<html lang="en" class="cd-shell-document" data-cd-theme="light">
  <!-- static, see Mode -->
  <div
    class="cd-shell"
    data-cd-shell-host="web"
    data-palette="top"
    data-primary="collapsed"
    data-zoom-row="raised"
    data-empty-state="shown"
    data-drop="over|forbidden"
    data-problems="shown"
  >
    <!-- state attributes only while true -->
    <button class="cd-shell-menu-trigger" data-chrome="menu" …>…</button>
    <button
      class="cd-shell-primary cd-shell-button"
      data-variant="primary"
      data-chrome="primary"
      aria-label="Share"
    >
      <svg … /><span class="cd-shell-primary-label">Share</span>
    </button>
    <div class="cd-shell-canvas" role="main" [inert]>…</div>
    <!-- the page's main landmark; inert behind the start screen -->
    <div class="cd-shell-status" data-chrome="status" …>…</div>
    <div class="cd-shell-hint">…</div>
    <section
      class="cd-shell-empty-state"
      data-chrome="empty-state"
      aria-labelledby="cd-shell-empty-state-title-1"
    >
      …
    </section>
    <aside class="cd-shell-inspector" data-chrome="inspector" …>…</aside>
    <button
      class="cd-shell-problems"
      data-chrome="problems"
      aria-haspopup="dialog"
      aria-expanded="false"
      aria-controls="cd-shell-problems-1"
      …
    >
      …
    </button>
    <section class="cd-shell-legend" data-chrome="legend" …>…</section>
    <nav class="cd-shell-legal" data-chrome="legal" aria-label="Legal">…</nav>
    <div class="cd-shell-zoom" data-chrome="zoom" …>…</div>
    <div class="cd-shell-layer">
      <!-- z 40 -->
      <div class="cd-shell-menu" role="menu" …>…</div>
      <div class="cd-shell-tooltip" role="tooltip">…</div>
      <div
        class="cd-shell-problems-popover"
        data-chrome="problems-popover"
        role="dialog"
        id="cd-shell-problems-1"
        aria-labelledby="cd-shell-problems-title-1"
        hidden
      >
        …
      </div>
      <div class="cd-shell-drop-zone" data-chrome="drop-zone" aria-hidden="true" hidden>…</div>
    </div>
    <div class="cd-shell-live">
      <!-- visually hidden, always rendered: the toasts' live regions -->
      <div class="cd-shell-live-region" role="status" aria-live="polite" aria-atomic="true"></div>
      <div class="cd-shell-live-region" role="alert" aria-live="assertive" aria-atomic="true"></div>
    </div>
    <div class="cd-shell-toasts" data-chrome="toasts" popover="manual">…</div>
    <!-- z 60; embedded: no popover -->
  </div>
</html>
```

Tab order (§5.14): menu trigger, primary action, palette, canvas, status box, hint, empty-state card,
inspector, pill, legend, legal line, zoom panel, then the toasts' buttons. Each 0.2 island has its
`data-chrome` so the kit measures it; ids count on the page-global mount counter as in 0.1. The
canvas slot is the page's `main` landmark (`role="main"`, unless it already has a role; the web host
only: a foreign page has its own).

### Primary action (§5.7, §5.15)

```ts
interface PrimaryActionOptions {
  label?: string; // default messages.share ("Share"); also the aria-label
  icon?: ShellIconName; // default "share-2"
  onSelect(): void;
  disabled?: () => boolean; // read on mount and on primary.refresh(); aria-disabled, stays focusable
}
interface PrimaryActionHandle {
  readonly element: HTMLButtonElement;
  isCollapsed(): boolean; // icon only right now
  refresh(): void;
}

// ./core
interface PrimaryWidths {
  withLabel: number;
  iconOnly: number; // 40
}
interface TopRowInput {
  containerWidth: number;
  paletteWidth: number;
  menuRight: number;
  primary?: PrimaryWidths;
}
interface TopRow {
  paletteRow: PaletteRow;
  primaryLabel: "shown" | "collapsed";
}
function decideTopRow(input: TopRowInput): TopRow;
```

- A blue primary button (§8, [Buttons](#buttons)) at `top: 12px; right: 12px`, 40px high, layer 30
  (`--cd-shell-ebene-reihe`), padding `0 16px`, Lucide icon 16px, 8px gap, label 13px/600. Hover and
  active `--cd-blau-link`, `shadow-2`, lift `translateY(-1px)`; disabled opaque and neutral, no lift.
- **Label collapse** (§5.15: "Wird es oben eng, verliert in der Web-App zuerst die Primäraktion ihr
  Label, erst danach rutscht die Palette"): the layout pass (root and palette resize) runs
  `decideTopRow` with the measured widths. With the label the palette must keep 16px to both the
  menu trigger and the primary action; failing that, the icon-only width is tried; failing that, the
  palette moves to the second row and the label comes back if it fits next to the menu trigger.
  Collapsed: 40 × 40, the label not rendered, `aria-label` unchanged, the chrome tooltip shows the
  label (no `aria-describedby`, it repeats the name); the root carries `data-primary="collapsed"`.
  The labelled width is measured afresh while the label shows (a late web font counts) and, while
  collapsed, in one synchronous layout with the label that is never painted.
- `disabled()` maps to `aria-disabled` (read on mount and on `primary.refresh()`); a click on a
  disabled primary action does nothing.
- One primary action in 0.2; the further actions "links daneben mit 8px Lücke" (§5.7) are a later
  candidate. Hidden on the start screen, never locked by `setReadOnly`.

### Legal line (§5.10, §2)

```ts
interface LegalLink {
  label: string;
  href: string;
  lang?: string;
}
interface LegalLineOptions {
  links?: readonly LegalLink[]; // after Impressum and Datenschutz, e.g. GitHub
  year?: number; // default the current year at mount
}
```

```html
<nav class="cd-shell-legal" data-chrome="legal" aria-label="Legal">
  <a href="https://www.miragon.io/" … aria-describedby="cd-shell-legal-1-new-tab">© 2026 Miragon GmbH</a>
  <span class="cd-shell-legal-item">
    <span aria-hidden="true">·</span>
    <a href="https://www.miragon.io/impressum/" lang="de" target="_blank" rel="noopener noreferrer" …
      >Impressum</a
    >
  </span>
  <span class="cd-shell-legal-item">
    <span aria-hidden="true">·</span>
    <a href="https://www.miragon.io/datenschutz/" lang="de" …>Datenschutz</a>
  </span>
  <span class="cd-shell-legal-item">
    <span aria-hidden="true">·</span>
    <a href="https://github.com/Miragon/event-storming-modeler" …>GitHub</a>
  </span>
  <span id="cd-shell-legal-1-new-tab" hidden>Opens in a new tab</span>
</nav>
```

- Always rendered in the web host, also on the start screen ("die Zeile Rechtliches, die eine
  öffentliche Seite immer zeigt", §8). Copyright, URLs and the two German labels are those of the
  corporate-identity docs-site kit (`miragon/legal.ts`); `messages.copyright` and `messages.legal`
  translate, the URLs and "Impressum"/"Datenschutz" never do.
- One line, 13px, line height 20px, at `left: 12px; bottom: 12px`, glass (§5.3) without border and
  shadow, padding `0 8px`, radius `sm`, links `--cd-ui-link` (underlined on hover and focus, always
  in high contrast and forced colours), separators `--cd-ui-text-leise`, layer 20. Pill and legend
  stand above it (0.1: pill `bottom: 40px`, legend 40/88px). Every link opens a new tab and says so
  to screen readers through `aria-describedby` (`messages.opensInNewTab`, "Opens in a new tab").
- **Narrow containers.** The line is at most `100cqw − 24px` wide; where it does not fit (with a
  GitHub link it is about 391px wide, so below about 415px) it wraps between its entries, each
  separator staying with the link after it, and grows upwards from `bottom: 12px`. Nothing is cut
  off or scrolled away (Datenschutz must stay reachable; WCAG 1.4.10 at 320 CSS px). The shell
  measures the line's height in whole lines (`legalLineHeight`) into `--modeler-shell-legal-height`
  on the root, and everything stacked on it rises with it: the pill and the problems popover, the
  legend, the raised zoom panel and the fit's bottom (`FitLayout.legalHeight`; 112 instead of 92 on
  two lines).
- **Bottom-row collision.** In a narrow container the legal line and the zoom panel meet:
  `zoomRowRaised` (`./core`) is true when the zoom panel at `right: 12px` would keep less than 8px to
  the legal line's measured right edge. The root then carries `data-zoom-row="raised"`, the zoom
  panel stands above the legal line at `bottom: 40px` like the pill (8px above a wrapped line), the
  fit keeps 92px at the bottom (`FitLayout.zoomRaised`), and up to 440px the legend's lowest position
  is 88px. §5.10 and §5.15 do not settle this case; it is the shell's rule until the guide does.

```ts
// ./core
const LEGAL_LINE_HEIGHT = 20; // one line of the legal line
function legalLineHeight(measured: number | undefined): number; // whole lines, at least one: 20, 40, …
interface BottomRowInput {
  containerWidth: number;
  legalRight?: number; // measured, relative to the root; absent while not shown
  zoomWidth?: number; // measured; absent while not shown
}
function zoomRowRaised(input: BottomRowInput): boolean;
```

### File and Appearance groups (§5.4, §13.3)

```ts
interface FileMenuAction {
  onSelect(): void;
  shortcut?: string; // chip, e.g. commandKeyLabel("O", platform, keyNames); the web app binds the key itself
  dialog?: boolean; // kind "dialog": it opens an in-page dialog, not the browser's file picker
  disabled?: () => boolean;
}
interface FileMenuOptions {
  newDiagram?: FileMenuAction;
  open?: FileMenuAction;
  showExample?: FileMenuAction;
  import?: FileMenuAction;
}
```

| Option        | Entry (`messages`) | Icon          | `data-menu-id` |
| ------------- | ------------------ | ------------- | -------------- |
| `newDiagram`  | "New diagram"      | `file-plus`   | `new-diagram`  |
| `open`        | "Open…"            | `folder-open` | `open`         |
| `showExample` | "Show example"     | none (§5.14)  | `show-example` |
| `import`      | "Import…"          | `import`      | `import`       |

- The File group comes first, the shell builds it in this order from what the modeler gives; labels
  and icons are the shared terms of §2 and the common set of §5.14, not the modeler's. Entries are
  `action`s (`dialog` with `FileMenuAction.dialog`), never locked on a read-only canvas. `open` also
  becomes the start screen's text link (see [Empty state](#empty-state-8)).
- The chip of a Cmd/Ctrl key the app binds itself comes from `./core`, so it reads the same in every
  modeler and on every platform:

  ```ts
  function commandKeyLabel(key: string, platform: Platform, keyNames: { ctrl: string }): string;
  // commandKeyLabel("O", "mac", messages.keyNames) → "⌘O"; "other" → "Ctrl+O" (German "Strg+O")
  ```

- The **Appearance** group is a radio group (`data-menu-id="appearance"`, heading and `aria-label`
  "Appearance", options `system`, `light`, `dark`: "System", "Light", "Dark") between Export and
  Help. The shell renders it only when `themes` includes `"dark"`; a light-only modeler has no
  Appearance group (§13.3 "Nur Hell, bis der Modeler Dunkel kann"). Its value is
  `shell.appearance.choice()`, selecting runs `shell.appearance.setChoice()` and keeps the menu open.
- Neither group exists in the IDE host (native, §13.5) or the embedded host (§5.2).

### Mode (§13.3)

```ts
// ./core
type AppearanceChoice = "system" | "light" | "dark";
const APPEARANCE_STORAGE_KEY = "miragon.darstellung";
interface ThemeColors {
  light: string; // the app's theme-color: fest["--cd-blau"] of the vendored JSON
  dark: string; // dunkel["--cd-ui-grund"]
}
function parseAppearanceChoice(stored: unknown): AppearanceChoice; // "light" | "dark", else "system"
interface DocumentMode {
  theme: "system" | Theme; // data-cd-theme on <html>
  colorScheme: "light dark" | Theme; // <meta name="color-scheme">
  themeColor: ThemeColors; // the two theme-color metas
}
function documentMode(choice: AppearanceChoice, themes: readonly Theme[], colors: ThemeColors): DocumentMode;
interface WebModeScriptOptions {
  themes: readonly Theme[];
  themeColors: ThemeColors;
}
function webModeScript(options: WebModeScriptOptions): string; // body of the inline head <script>
function webHeadMarkup(options: WebModeScriptOptions): string; // metas + <script>, for index.html

// .
interface StorageLike {
  getItem(key: string): string | null;
  setItem(key: string, value: string): void;
  removeItem(key: string): void;
}
interface WebAppearanceOptions {
  themeColors: ThemeColors;
  storage?: StorageLike; // default globalThis.localStorage
}
interface AppearanceHandle {
  choice(): AppearanceChoice;
  setChoice(choice: AppearanceChoice): void;
}
```

- **Before the first paint** the page itself decides (§13.3, §13.5: one place, the host). A
  light-only modeler writes `<html lang="en" data-cd-theme="light">` statically, one
  `<meta name="theme-color">` without `media`, and of the guide's script only the contrast line;
  `webHeadMarkup({ themes: ["light"], themeColors })` returns exactly that. A dark-capable modeler
  writes `data-cd-theme="system"` statically and the guide's whole script with both `theme-color`s:
  `webHeadMarkup({ themes: ["light", "dark"], themeColors })`. The markup goes into `<head>` before
  the first stylesheet, for example through a Vite `transformIndexHtml` hook:

  ```ts
  // apps/webapp/vite.config.ts
  import { webHeadMarkup } from "@miragon/modeler-shell/core";
  import tokens from "./src/theme/cd-tokens.generated.json" with { type: "json" };
  import { THEMES } from "./src/themes";

  const themeColors = { light: tokens.fest["--cd-blau"], dark: tokens.dunkel["--cd-ui-grund"] };
  const modePlugin = {
    name: "miragon-mode",
    transformIndexHtml: (html: string) =>
      html.replace("<!-- miragon-mode -->", webHeadMarkup({ themes: THEMES, themeColors })),
  };
  ```

- **At runtime** `mountShell` (web host) follows `(prefers-contrast: more)` changes on `<html>`
  (`data-cd-kontrast="hoch"`), for every modeler. With `"dark"` in `themes` it needs
  `appearance.themeColors` (it throws without them, before anything mounts) and offers
  `shell.appearance`: `setChoice` stores the choice (`"system"` removes the entry; a blocked storage
  is caught and the choice applies for the page), applies `documentMode` on `<html data-cd-theme>`,
  `color-scheme` and both `theme-color` metas (created when missing) in one task with
  `cd-shell-no-transition` for one frame (§7), and a `storage` event from another tab applies the
  same way (a cleared storage means `system`). `choice()` is read from storage once at mount and then
  kept in memory, so a choice a blocked storage refused still holds for the page; mounting does not
  re-apply the mode, the head script owns the first paint. Nothing refits (§5.9). Light-only:
  `shell.appearance` is `undefined`.
- `webModeScript` is the guide's script as ES5 in an immediately invoked function; it reads the
  storage inside `try`/`catch`, tolerates a missing `color-scheme` meta and JSON-escapes every
  literal (with `<`, U+2028 and U+2029), so no value ends the `<script>` element.
- The kit's `appearance` case drives the web host through `PageLike.emulateMedia` and the stored
  choice (see [`./testing`](#testing)).

### Problems popover (§5.10)

```ts
// ./core
type ProblemSeverity = "error" | "warning";
interface ProblemItem {
  severity: ProblemSeverity;
  message: string; // 13px --cd-ui-text
  location?: string; // "Line 12", "“Order Placed”": 13px --cd-ui-text-leise below the message
  elementId?: string; // the element a click on the row selects
}
function problemSummary(items: readonly ProblemItem[]): {
  count: number;
  errors: number;
  items: readonly ProblemItem[];
};
```

- In the web host the pill (0.1) is the trigger of a non-modal dialog: `aria-haspopup="dialog"`,
  `aria-expanded`, `aria-controls` on the pill; the popover `role="dialog"` without `aria-modal`,
  `aria-labelledby` its title "Problems" (13px/600). An embedded shell shows it too unless the
  modeler gives `problems.onActivate` (an embedding host with a list of its own); the IDE host never.
- Above the pill, left-aligned with it: `left: 12px`, its bottom 8px above the pill's top, opaque
  (§5.3), 1px `--cd-ui-linie`, radius `md`, `shadow-3`, `min(320px, 100cqw − 24px)` wide, at most
  320px high with a scrolling list, layer 40, pop-in 150ms (§5.14). Rows at least 36px: the pill's
  icon 16px (`circle-x` in `--cd-ui-danger`, `triangle-alert` in `--cd-ui-warning`), the message,
  below it the location.
- A row with an `elementId` is a button: a click closes the popover, puts the focus on the canvas and
  then calls `problems.onSelectItem(item)`, where the modeler selects the element. Rows without one
  are text that still takes the focus (`<div tabindex="-1">`), so the keyboard reads every row of a
  list longer than its 320px (WCAG 2.1.1); Enter and Space act on row buttons only. The icon carries
  the severity's name for screen readers (`role="img"`, `messages.problemSeverity`), so the shape and
  colour are not its only signal (§12).
- Opening focuses the first row (else the popover, with an inset focus ring); ↑/↓/Home/End move
  between all rows and scroll the focused one into the list (only the list scrolls, never the
  root). Escape and Tab out close it with the focus back on the pill (Tab from the last row then
  moves on from the pill, Shift+Tab from the first stays on it); an outside `pointerdown` and the
  window's blur close it without moving the focus, as for the menu. Not modal: the zoom keys keep
  working. Like the menu it stops Enter, Space, Delete, Backspace and printable keys, so a modeler's
  keyboard on `document` never acts on them.
- `setProblems` re-renders the rows while it is open and keeps the focused problem; `count` 0 hides
  pill and popover, and a focus in the list goes to the canvas (else the menu trigger).

### Toasts (§8, §9)

```ts
// ./core
type ToastStatus = "success" | "info" | "warning" | "danger";
interface ToastAction {
  label: string;
  onSelect(): void; // runs after the toast closed
}
interface ToastRequest {
  status: ToastStatus;
  text: string;
  action?: ToastAction;
  durationMs?: number; // only to lengthen; ignored with an action
}
const MAX_TOASTS = 3;
const TOAST_DURATION_MS: Readonly<Record<ToastStatus, number>>; // success, info 2800; warning, danger 5000
const TOAST_MAX_WIDTH = 480;
function toastLifetime(request: ToastRequest): number | undefined; // undefined with an action
interface ToastSlot {
  id: number;
  hasAction: boolean;
  engaged: boolean; // hovered or focused
}
function toastToEvict(stack: readonly ToastSlot[]): number | undefined; // oldest first
interface BottomObstacle {
  left: number;
  right: number;
  top: number; // px from the container's bottom to its top edge
}
interface ToastStackInput {
  containerWidth: number;
  obstacles: readonly BottomObstacle[];
  cardWidth?: number; // the widest card's measured width; absent = the whole stack width
}
function toastStackWidth(containerWidth: number): number; // min(480, width − 24)
function toastStackBottom(input: ToastStackInput): number;

// .
interface ToastHandle {
  dismiss(): void; // idempotent
}
```

- `shell.toast(request)` in the web and embedded hosts; in the IDE host it shows nothing and returns
  an inert handle (§13.5: the extension shows the host's notification). An import that runs by itself
  never shows a toast (§9); that is the modeler's discipline, the shell does not know imports.
- **Card** (§8): opaque `--cd-ui-flaeche-hoch`, 1px `--cd-ui-linie`, a straight 4px bar and an 8px
  dot in `--cd-ui-<status>` (a dot, not an icon: the common set has no success or info icon, §5.14),
  text 13px/1.5 `--cd-ui-text`, radius `md`, `shadow-3`, at least 40px high, padding `4px 4px 4px
16px`, 8px gap; the action as a 32px ghost button, then Close as a 32 × 32 ghost icon button
  (Lucide `x`, `aria-label` "Close", `aria-describedby` the toast's text, so three Close buttons
  are told apart). Slide and fade in from `translateY(8px)` over 250ms, out the same way; none under
  reduced motion. A card is as wide as its content, at most the stack's width, as in the Wardley and
  Team Topologies web apps (§8's `min(480px, 100% − 24px)` read as the maximum).
- **Screen readers** (§8, §12): two live regions in the root, rendered from mount on and visually
  hidden (`.cd-shell-live`): `role="status"` with `aria-live="polite"`, and `role="alert"`. A toast's
  text goes into the alert region for danger, else into the status region, 100ms after the region
  was emptied (`TOAST_ANNOUNCE_DELAY_MS`), so a repeated toast ("Link copied" twice) is announced
  again; the region empties when its toast closes. A live region created together with its text is
  often not announced, which is why the regions never come and go with the stack. The cards carry no
  live role, so nothing is read twice.
- **Stack**: centred, `toastStackWidth`, column with 8px gap, the newest at the bottom, at most three;
  a fourth evicts per `toastToEvict` (the oldest without action that is not engaged first). A
  request equal to a shown toast (status and text) restarts that toast's time instead of stacking,
  and takes the newer request's action and lifetime (a repeated "Board replaced · Undo" undoes the
  latest replacement). Layer 60; in the web host the stack is a `popover="manual"`, shown with the
  first toast and shown again with a toast that arrives while a modal dialog is open, so it stays
  above a `showModal()` dialog in the top layer (visible, but inert like everything outside a modal
  until the dialog closes); without a modal it is not hidden and re-shown, which would rebuild it for
  screen readers. In the embedded host it is absolute inside the root and never leaves its box.
- **Time**: `toastLifetime` (about 2.8s, errors about 5s, §8; a warning, a sentence to act on, gets
  the error's 5s), paused while hovered or focused and resumed with at least 1.5s left; a toast with
  an action never closes by itself. A closing toast that held the focus hands it to the next
  toast's Close button, else to the canvas; on the start screen to its "New diagram" (the canvas and
  the menu trigger cannot take it there), never silently to `<body>`.
- **Bottom row**: the stack sits at `bottom: 12px` (§8) unless the centred column of its widest card
  comes closer than 8px horizontally to a visible zoom panel, legal line or pill; then it stands 8px
  above the highest of those (`toastStackBottom` with `cardWidth`, recomputed in the layout pass,
  whenever a toast comes or goes, and whenever the pill, the inspector or the start screen changes;
  a bottom sheet hides zoom panel and pill). At 1280px with a GitHub link the legal line ends 7.5px
  before the 480px column, so "Link copied" (146px) stays at 12 while a full-width card rises to 40. §8 does not settle this case; it is the shell's rule until the guide does.

### Empty state (§8)

```ts
interface EmptyStateOptions {
  title: string; // the modeler's name: "Event Storming Modeler"
  text: string; // one line of help: "Start a new diagram, or explore the example."
  komet: string; // URL of the vendored, unchanged miragon-komet-blau.svg (§2, §11)
  onNewDiagram(): void; // "New diagram", blue primary button; the shell hides the card first
  onShowExample?(): void; // "Show example", ghost button; the shell hides the card first
  dropHint?: string; // shown with a dropZone only; default messages.dropHint
}
```

- `shell.setEmptyState(true)` shows the card; the modeler calls it on a fresh start (no document in
  the URL, nothing restored). While it shows (`data-empty-state="shown"` on the root) the work chrome
  is hidden (`visibility: hidden`): menu trigger, primary action, palette, zoom panel, pill, legend,
  status box, hint and inspector; the canvas slot is `inert`, menu and popover close. The chrome keys
  (Cmd/Ctrl + `+`/`−`/`0`, Shift+1) go to the browser unprevented, which zooms the page: there is no
  diagram to zoom, and a low-vision user's Ctrl+ must not be swallowed (WCAG 1.4.4); the shell's
  diagram-js guard returns `false` for them meanwhile, so diagram-js zooms nothing either. Visible:
  the card, the legal line, toasts and the drop zone (§8: "sichtbar sind nur die Karte und die Zeile
  Rechtliches").
- The card: centred in the container, `min(400px, 100cqw − 24px)` wide, glass (§5.3), `shadow-2`,
  radius `lg`, padding `32px 40px`, content centred with 16px gaps: the Komet at 64px (`alt=""`), the
  title as `<h1>` (21px/600), the help line (16px/1.6, `--cd-ui-text-leise`), the two 36px buttons
  side by side with 8px gap, primary first, then the drop hint (13px, `--cd-ui-text-leise`). Layer 20.
  In high contrast its border is `--cd-ui-linie` through the role like every other island (§5.3).
- **Open on the start screen.** The start screen hides the menu, and a drop needs a pointer; so with
  `file.open` the hint ends in a text link "Open a file…" (`messages.openFileLink`, `--cd-ui-link`,
  `aria-keyshortcuts` and a Geist Mono chip from `file.open.shortcut`, the two never parted by a
  line break): "Or drop a .storm file here
  · Open a file… ⌘O". It is part of the hint, not a third action (§8 keeps exactly two buttons), and
  runs `file.open.onSelect` without leaving the start screen: the modeler ends it once the file has
  loaded.
- Either button hides the card (`setEmptyState(false)`), moves the focus to the canvas `<svg>` and
  then runs its handler. `setEmptyState(true)` while the focus is in the work chrome or the canvas
  moves it to "New diagram"; a focus on the legal line or a toast stays. The Komet is not draggable
  (an image drag can carry a file and would open the drop zone). Any other start (Open…, a dropped
  file, a shared link, the first edit) is the modeler's to end with `setEmptyState(false)`; the card
  does not come back in the session.
- The IDE and embedded hosts have no start screen; they use the empty-file hint (§13.5).

### Drop zone (§9)

```ts
interface DropZoneOptions {
  accept: readonly string[]; // ".storm", "application/json", "text/*"; empty: any file
  multiple?: boolean; // default false
  onDrop(files: readonly File[]): void; // the accepted files
  onReject?(files: readonly File[]): void; // default: a danger toast messages.cannotOpenFile
}

// ./core
type DropForbiddenReason = "multiple" | "type" | "dialog";
interface DragItemLike {
  kind: string;
  type: string;
}
interface DragContext {
  accept: readonly string[];
  multiple: boolean;
  dialogOpen: boolean;
}
type DragVerdict =
  { state: "none" } | { state: "over" } | { state: "forbidden"; reason: DropForbiddenReason };
function dragVerdict(items: readonly DragItemLike[], context: DragContext): DragVerdict;
function acceptsFile(file: { name: string; type: string }, accept: readonly string[]): boolean;
```

- Page-wide (`window` listeners) and for drags that carry files only, so palette drags and text
  dragged into the label editor stay alone; every file drag is `preventDefault`-ed, so the browser
  never navigates to the file. `dragVerdict` decides: a modal dialog open → forbidden (`dialog`);
  more than one file without `multiple` → forbidden (`multiple`); every file of a MIME type that none
  of `accept`'s MIME entries matches → forbidden (`type`; extensions are unreadable before the drop,
  so list the MIME types as well; an empty type never forbids); else over. Only items of kind
  `"file"` count. `accept` entries are trimmed and lower-cased (extensions match the name's suffix
  case-insensitively, MIME types exactly or as `type/*`), blank ones dropped; a list without a usable
  entry accepts every file, like `<input accept>`.
- **Drag-over**: `data-drop="over"` on the root, the overlay at `inset: 12px`, fill `--cd-ui-hover`,
  2px dashed `--cd-ui-interaktion`, radius `lg`, the chip "Drop file here" centred on
  `--cd-ui-flaeche-hoch`, `dropEffect = "copy"`. **Forbidden**: `data-drop="forbidden"`, fill
  `--cd-ui-danger-flaeche`, dashed `--cd-ui-danger`, the chip `messages.dropForbidden(reason)`,
  `dropEffect = "none"` (the cursor shows not allowed). Layer 40, `aria-hidden`.
- **Drop**: `acceptsFile` splits the files; `onDrop(accepted)` when there are any, `onReject(rest)`
  for the others (default: one danger toast per file, "Couldn't open “map.png”. Drop a .storm,
  .json, or .txt file.", the extensions of `accept` joined by `Intl.ListFormat` in `lang`, its MIME
  entries where it lists no extension). A drop forbidden for `dialog` or `multiple` opens nothing and
  shows no toast. After a `type` verdict a browser fires no `drop` (`dropEffect = "none"`); a
  synthetic one is split by `acceptsFile` like any other. Whether the drop replaces the open document is the modeler's
  (see the usage below for an undo toast instead of `confirm()`).

### Buttons

`src/dom/buttons.css` styles `.cd-shell-button` for the web chrome (§8): `data-variant="primary"`
(`--cd-blau` with `--cd-weiss` text in both modes, `shadow-1`, hover and active `--cd-blau-link`,
`shadow-2` and a 1px lift, no lift under reduced motion; disabled `--cd-ui-hover` with
`--cd-ui-linie` border, muted text, no lift) and `data-variant="ghost"` (transparent, hover
`--cd-ui-hover`); 36px high, padding `0 16px`,
13px/600, radius `md`; focus ring 2px `--cd-ui-fokus` with 2px offset (3px in high contrast, which
also drops the shadow); under forced colours borders in `ButtonText`, rings in `Highlight`. It is
the only stylesheet that reads fixed palette tokens, and only these three.

## `./diagram-js`

```ts
// a Diagram, a renderer's Modeler, a didi injector
interface InjectorLike {
  get<T>(name: string): T;
}
interface ModuleDeclarationLike {
  __init__?: string[];
  __depends__?: ModuleDeclarationLike[];
  [name: string]: unknown;
}
type DiagramEventListener = (event: never) => unknown;
interface EventBusLike {
  on(events: string | string[], priority: number, listener: DiagramEventListener): void;
  on(events: string | string[], listener: DiagramEventListener): void;
  off(events: string | string[], listener?: DiagramEventListener): void;
}
interface DiagramViewbox extends ScaledViewbox {
  inner: Bounds;
  outer: Size;
}
interface CanvasLike {
  getContainer(): HTMLElement;
  getSize(): Size;
  viewbox(): DiagramViewbox;
  viewbox(box: Bounds): void;
  zoom(): number;
  zoom(scale: number, center?: Point): number;
  resized(): void;
}
interface ZoomScrollLike {
  stepZoom(delta: number, position?: Point): void;
}
interface KeyboardLike {
  addListener(priority: number, listener: (context: { keyEvent: KeyboardEvent }) => unknown): void;
}
interface PaletteLike {
  getEntries(): Record<
    string,
    { title?: string; shortcut?: string; ariaKeyShortcuts?: string; group?: string }
  >;
}

const shellModule: ModuleDeclarationLike;

interface ConnectOptions {
  contentBounds(): Bounds | undefined; // tight, no padding: the fit insets are the only margin (§5.9)
  isEmpty?(): boolean; // §13.5 empty file (no element); default: the content bounds are empty
  prefersReducedMotion?(): boolean;
}
interface DiagramJsConnection {
  readonly viewport: Viewport;
  destroy(): void;
}
function connectDiagramJs(
  shell: ShellHandle,
  diagram: InjectorLike,
  options: ConnectOptions,
): DiagramJsConnection;

interface ViewportOptions {
  contentBounds(): Bounds | undefined;
  insets(): Insets;
  prefersReducedMotion?(): boolean;
}
interface Viewport extends ZoomTarget {
  fit(options?: { animate?: boolean }): void;
  freeRectCenter(): Point | undefined; // diagram coordinates; undefined at 0 × 0 and after destroy
  afterImport(): void;
  newDocument(): void; // 0.2, web app: the next afterImport() counts as the first again
  restore(viewbox: Bounds): void;
  getViewbox(): Bounds | undefined;
  isAutomatic(): boolean;
  getState(): ViewportState | undefined;
  setState(state: ViewportState): void;
  destroy(): void;
}
function createViewport(diagram: InjectorLike, options: ViewportOptions): Viewport;
```

**`shellModule`** goes into the modeler's modules after the renderer's own (`additionalModules`). It
registers one internal didi service named `modelerShell` (a modeler does not reuse the name):

- `paletteTooltip: ["value", null]` replaces diagram-js's (and a renderer's) palette tooltip; the
  chrome tooltip takes over with `title` and `shortcut` from `palette.getEntries()`.
- Palette skin: on `palette.create` it sets `data-chrome="palette"` and moves the container in front
  of the canvas `<svg>` (`canvas.getContainer()`'s child), so tab order puts the palette first. A
  renderer's export (`saveSVG`) must therefore take the container's own `<svg>` child, not the
  first `<svg>` it finds (`container.querySelector("svg")` now gets a palette icon), and strip the
  `tabindex`, `role="application"` and `aria-label` the live canvas carries from its copy. After
  every `palette.changed` it re-applies `role="toolbar"` and `aria-label` (`messages.tools`) on
  `.djs-palette-entries`, `role="button"` on every entry, `aria-keyshortcuts` from the entry's
  `ariaKeyShortcuts` or `ariaKeyShortcutsFromLabel(shortcut)` (§5.6; split the shortcut off the
  title: `title: "Domain event", shortcut: "E"`), roving `tabindex` (the last focused entry keeps the
  tab stop across rebuilds) and `aria-pressed` for the tool of the last
  `tool-manager.update` (group `tools`, `data-action="<tool>-tool"`), styled through
  `[aria-pressed="true"]`: diagram-js's `highlighted-entry` goes stale after a rebuild, and its
  `two-column` class is ignored. `separator` entries become vertical rules.
- Palette keys, without modifiers: ← and → move and wrap, Home and End jump, Enter and Space trigger
  the entry once (repeats ignored). They are stopped at the palette, so a modeler's document listener
  and VS Code never see them; chrome keys still bubble to the shell.
- Enter and Space trigger through a synthetic `click`, and that click is a contract: a `MouseEvent`
  with `detail === 0` (a pointer click has 1 or more), `clientX`/`clientY` at the entry's centre,
  bubbling and cancelable, dispatched on the entry. It goes through diagram-js's click delegate and
  `palette.trigger` like a pointer click, so under the read-only lock it is vetoed the same way. A
  provider tells the keyboard apart by `detail === 0` (see Palette keyboard creation below).
- Read-only (§13.5): only `lasso-tool` and `hand-tool` stay active. Every other entry, also tools of
  group `tools` such as draw, space or connect, is vetoed on `palette.trigger` from the lock on (a
  vetoed `dragstart` is `preventDefault`-ed) and marked `aria-disabled` once the shell shows the
  read-only state; an entry's own `aria-disabled` comes back afterwards. Without an entry element
  in the event only group `tools` passes.
- Keyboard: `keyboard.addListener(2000, …)` returns `true` for every `matchChromeKey` hit, so
  `KeyboardBindings` and the modeler's keyboard modules (priority 1000) never act on them; the
  shell's `keydown` listener executes them exactly once. It returns `false` (stops them without
  `preventDefault`) for a chrome key from a text field inside the `<svg>`, which stays the field's,
  for a chrome key while the web app's start screen shows (the browser zooms the page), and, while
  the attached shell's host is `ide`, for undo and redo (`isUndoRedoKey`): the canvas
  `commandStack` never takes them, VS Code undoes the document (§13.5). A modeler's own DOM undo
  binding must go in the IDE host as well; the kit's `keys` case checks it.
- Keys the canvas uses beyond the chrome keys are the modeler's (§13.5). Cmd/Ctrl+A on the focused
  canvas selects every element, or is at least `preventDefault`-ed: diagram-js 15 binds no select
  all, and an unprevented key reaches VS Code, whose Select All then selects the chrome's text. The
  shell stops a prevented key in the IDE host; the kit's `keys` case presses Control+A and Meta+A on
  the canvas.
- While a shell is attached, the canvas `<svg>` is `role="application"` with `aria-label`
  `messages.canvas` (WCAG 4.1.2; screen readers switch to focus mode, so single-key commands reach the
  canvas); a role or name the modeler set stays, and both are restored on detach.
- It buffers the palette until `connectDiagramJs`, so the diagram may exist before the shell.

**`connectDiagramJs`** creates the viewport with `insets: shell.fitInsets`, binds it
(`shell.setZoomTarget`), registers the palette and calls `canvas.resized()` (the canvas element has
moved). After every `import.done` and `elements.changed` it calls `shell.setEmptyHint(isEmpty())`,
so the first element the user creates on the canvas hides the hint (and its "Insert example").
`isEmpty` defaults to empty content bounds; a notation whose bounds are never empty (Wardley's plot)
passes its own. It throws when `shellModule` is missing. A later connection to another shell takes
the palette over; `destroy()` (idempotent, also run on `diagram.destroy`) unregisters the palette,
unbinds the zoom target and the hint sync and destroys the viewport, while the keyboard guard stays
until `diagram.destroy`. `contentBounds` returns the tight bounds of the content, without a padding
of its own (Event Storming: `boardBounds.contentBounds(0)`, not its default of 120px): the shell's fit
insets are the only margin (§5.9), and a padding would add to them.

**`Viewport`** (§5.8, §5.9):

- `stepZoom` is `zoomScroll.stepZoom(±1)` (the wheel's raster, snapping to the nearest step);
  `zoomToActual` is `canvas.zoom(1)`; both around the container centre. No rounding of its own. A
  step past a limit is refused (`canZoomOut`/`canZoomIn`), so zoom out never zooms in, whatever the
  caller checks; without a `zoomScroll` service it steps on the same raster itself.
- `fit()` uses `fitViewbox(contentBounds(), canvas.getSize(), insets())` and `canvas.viewbox(box)`,
  never `canvas.zoom("fit-viewport")`; animated over 250ms in `requestAnimationFrame` with
  `easeStandard` unless `animate: false` or reduced motion (`prefers-reduced-motion`, or
  `REDUCED_MOTION_CLASS` on `<html>`); a `wheel`, `pointerdown` or zoom key cancels the animation. A
  no-op when the bounds are empty.
- `canFit()` reads `contentBounds()` once per content change (`elements.changed`, `shape.added`,
  `shape.removed`, `connection.added`, `connection.removed`, `diagram.clear`, `import.done` and the
  viewport's own `afterImport`, `restore`, `setState`), not on every frame the zoom panel renders.
- `afterImport()` jump-fits the first import whose bounds are non-empty (also after an empty file got
  its first content), unless the user moved the view or a stored view was set with `setState` while
  there was content. `restore` does not block it: a modeler restores on every re-import, and an
  empty file must still fit its first content ("Insert example"). Content the user creates on the
  canvas does (§5.9: an element created on the canvas never fits): an `elements.changed` outside an
  import window after the first import, with content, ends the wait for the first fit, so the next
  external change keeps the view. A renderer that changes elements through the command stack while
  it imports therefore fires `import.parse.start` or `import.render.start` first.
- An empty file shows 100 %, whatever zoom the renderer's import left: on the first import with
  empty bounds, without a stored view (`setState`) and without a user move, `afterImport()` zooms to
  1 around the centre of the free rectangle (at 0 × 0 once the container has a size). That write is
  the viewport's own, not a user move, so the first content still fits; later re-imports and
  `restore`s of the empty file keep the view (guide §5.9 and §13.5, design system 1.13.0).
- `newDocument()` (0.2): in the web app every new document (New diagram, Open…, Import…, Show
  example, a shared link, a dropped file) opens like the first (§5.9). Called before the import, it
  forgets the user's moves, a stored view and a pending restore and stops a fit animation, so the
  next `afterImport()` jump-fits non-empty content or shows an empty document at 100 %.
- `freeRectCenter()` is the centre of the free rectangle (the container minus `insets()`, as fit
  uses them) in diagram coordinates, for the current viewbox; `undefined` while the container is
  0 × 0 and after `destroy`. It is where keyboard creation places an element.
- A `ResizeObserver` on `canvas.getContainer()`, coalesced per frame, skips 0 × 0 (hidden tab) and
  compares with the size the view was last set for, so a tab coming back at the same size neither
  refits nor calls `resized()`. On a real change it calls `canvas.resized()` and refits while the view
  is automatic. A `restore` or `setState` made at 0 × 0 waits for a size and is not refitted then.
- User moves: every `canvas.viewbox.changed` (and `canvas.viewbox.changing` for the readout under
  `deferUpdate`) is compared with the last view the viewport set (`sameView`; during an animation
  also with the last written frame); a difference is a user move. Changes between
  `import.parse.start`/`import.render.start` and `import.done` are not (renderers set the viewbox
  while importing); that window also ends on `afterImport`, `restore`, `setState` and user input.
  Fit makes the view automatic again; `restore` updates the reference without resetting it.
- `getViewbox()` takes width and height from the fresh container size; `getState()` is `undefined`
  before the first `afterImport`, `restore` or `setState`. `onChange` fires on
  `canvas.viewbox.changing`/`.changed`, `elements.changed` (so Fit enables with the first element),
  `import.done` and the viewport's own calls.
- The viewport destroys itself on `diagram.destroy`; afterwards `zoom()` returns the last zoom,
  `canFit()` false and `getViewbox()`/`getState()` `undefined`, so a shell still bound to it never
  calls into a destroyed canvas.
- diagram-js events used: `canvas.init`, `palette.create`, `palette.changed`, `tool-manager.update`,
  `palette.trigger`, `keyboard.keydown` (through `keyboard.addListener`), `canvas.viewbox.changing`,
  `canvas.viewbox.changed`, `elements.changed`, `shape.added`, `shape.removed`, `connection.added`,
  `connection.removed`, `diagram.clear`, `import.parse.start`, `import.render.start`, `import.done`,
  `diagram.destroy`. The shell fires no events of its own.

**Palette keyboard creation** (§5.5). Enter or Space on an entry that creates something places the
element in the centre of the free rectangle, selects it, opens the label editor where the notation
has labels and puts the focus on the canvas; tool entries only switch the tool. diagram-js's create
tool follows the pointer and never ends without one, so the provider branches on the synthetic click
and asks the viewport for the point. The provider exists before `connectDiagramJs`, so it gets a
function and reads the viewport only when the entry fires:

```ts
// the renderer's palette provider, given freeRectCenter: () => viewport.freeRectCenter()
const create = (event: Event) => {
  const shape = elementFactory.createShape({ type: "domain-event" });
  const keyboard = event.type === "click" && (event as MouseEvent).detail === 0;
  const center = keyboard ? freeRectCenter() : undefined;
  if (!center) return createTool.start(event, shape); // a pointer: the shape follows it
  const created = modeling.createShape(shape, center, canvas.getRootElement());
  selection.select(created);
  canvas.focus();
  directEditing.activate(created); // where the notation has labels
};
entries["create.domain-event"] = {
  group: "events",
  title: "Domain event",
  shortcut: "E",
  action: { click: create, dragstart: create },
};
```

When the centre is already taken, the provider steps 24px diagonally until it is free (§5.5); a
shared helper for that is a later candidate. The kit's `create` case presses Enter on the first
creating entry and expects exactly one new, selected shape inside the free rectangle.

## `./vscode/extension`

```ts
interface DisposableLike {
  dispose(): unknown;
}
interface ColorThemeLike {
  readonly kind: number;
}
interface VsCodeLike {
  readonly window: {
    readonly activeColorTheme: ColorThemeLike;
    onDidChangeActiveColorTheme(listener: (theme: ColorThemeLike) => unknown): DisposableLike;
  };
  readonly workspace: {
    getConfiguration(section?: string): { get<T>(key: string): T | undefined };
    onDidChangeConfiguration(
      listener: (event: { affectsConfiguration(section: string): boolean }) => unknown,
    ): DisposableLike;
  };
}
interface WebviewPanelLike {
  readonly webview: { postMessage(message: unknown): unknown };
  readonly visible: boolean;
  onDidChangeViewState(
    listener: (event: { readonly webviewPanel: { readonly visible: boolean } }) => unknown,
  ): DisposableLike;
  onDidDispose(listener: () => unknown): DisposableLike;
}

interface WebviewHtmlOptions {
  cspSource: string;
  scriptUri: string;
  styleUris?: readonly string[];
  title: string;
  lang: string;
  appearance: Appearance;
  body?: string;
  nonce?: string;
  inlineStyles?: boolean; // default true: style-src … 'unsafe-inline'
}
function createNonce(): string;
function renderWebviewHtml(options: WebviewHtmlOptions): string;

interface ThemeBridgeOptions {
  themes: readonly Theme[];
  settingKey?: string;
}
function currentAppearance(vscode: VsCodeLike, options: ThemeBridgeOptions): Appearance;
function connectThemeBridge(
  vscode: VsCodeLike,
  panel: WebviewPanelLike,
  options: ThemeBridgeOptions,
): DisposableLike;

function revealFileLabel(platform: string): string;

const APPEARANCE_MESSAGE_TYPE = "modelerShell.appearance";
interface AppearanceMessage {
  type: typeof APPEARANCE_MESSAGE_TYPE;
  appearance: Appearance;
}
function appearanceMessage(appearance: Appearance): AppearanceMessage;
function isAppearanceMessage(value: unknown): value is AppearanceMessage;
```

- The real `vscode` namespace is assignable to `VsCodeLike` and a `WebviewPanel` to
  `WebviewPanelLike` (pinned by a type test against `@types/vscode` 1.96).
- The entry needs a global `crypto` (Node 20 or later, so VS Code 1.90 or later; the types are tested
  against 1.96). A modeler declares `engines.vscode` accordingly and targets `node20` in its
  extension-host bundle. There is no `node:crypto` fallback: the entry imports nothing, so a web
  extension host (vscode.dev) can bundle it as well, and `createNonce` stays synchronous.
- `createNonce()`: 32 characters `[A-Za-z0-9]` from `crypto.getRandomValues`, unbiased.
- `renderWebviewHtml` writes the appearance attributes on `<html>` before the first paint, always
  (also `light`), and the CSP (`default-src 'none'`, the nonce'd script, fonts from `cspSource` and
  `data:`). Its `style-src` allows `'unsafe-inline'` by default because renderers write
  `style` attributes into markup (palette entries, SVG strings); the shell and diagram-js themselves
  style only through the CSSOM and run without it, so a modeler whose renderer does too passes
  `inlineStyles: false`. `lang` is the tool's UI language: English modelers pass `"en"`, not
  `vscode.env.language`. Title and attribute values are escaped, `body` is inserted as markup; the
  script is a classic `<script nonce src>` (an IIFE bundle). It throws for a `nonce` that is not a
  CSP base64 value.

  ```text
  <html lang="en" class="cd-shell-document" data-cd-theme="light" data-cd-kontrast="hoch">
  Content-Security-Policy: default-src 'none'; img-src {cspSource} data: blob:;
    style-src {cspSource} 'unsafe-inline'; font-src {cspSource} data:; script-src 'nonce-{nonce}'
  ```

- `currentAppearance` resolves `requestedAppearance(kind, setting)` against `themes`; a setting value
  outside `automatic | light | dark` counts as `automatic`.
- `connectThemeBridge` posts nothing on connect (the HTML carries the appearance) and then
  `appearanceMessage(currentAppearance(…))` on `onDidChangeActiveColorTheme`, on
  `onDidChangeConfiguration` affecting `settingKey` (no configuration listener without one), and on
  `onDidChangeViewState` when the panel goes from hidden to visible (not on active or column
  changes). It disposes itself with the panel (`onDidDispose`) and throws for empty `themes`. The
  returned disposable only ends it earlier (twice is safe), or goes into a panel-scoped list that is
  disposed with the panel; never into `context.subscriptions`, which keeps one dead bridge per
  opened editor until the extension deactivates.
- `revealFileLabel(process.platform)`: "Reveal in Finder" (`darwin`), "Reveal in File Explorer"
  (`win32`), "Open Containing Folder" (other), for the export notification (§13.5); English, the
  labels of VS Code itself (a localized modeler translates them with `vscode.l10n`).

What the webview bundle needs under this CSP:

- **Fonts as files.** Bundle Geist and Geist Mono as files next to the bundle, not as data URLs:
  esbuild `loader: { ".woff2": "file", ".woff": "file" }` with `assetNames: "fonts/[name]-[hash]"`.
  The browser then fetches only the subsets a page's `unicode-range` needs (Geist Mono alone brings
  six, which inlined roughly double the webview CSS), `font-src {cspSource}` allows them, and `dist`
  must be in the panel's `localResourceRoots`. `data:` stays allowed for renderers that inline
  fonts.
- **zod 4 without eval.** `script-src` admits only the nonce'd script, so eval and `new Function` are
  blocked (correctly, there is no `'unsafe-eval'`). zod 4 probes once for eval when it builds its
  first object schema and catches the error, but the browser still reports that `new Function` as a
  `securitypolicyviolation`; under `jitless` zod skips the probe. A webview that bundles zod 4 runs
  `z.config({ jitless: true })` in a module it imports before any schema module (Event Storming:
  `import "./zod-jitless"`, the first line of `main.ts`).
- **A smoke test of the production bundle.** A test page served by Vite runs the webview from source
  without a CSP, so a loader or CSP mistake of the shipped bundle shows only behind the real HTML.
  Build the bundle as shipped, serve it under a fake origin behind `renderWebviewHtml`, and fail on
  any CSP violation, page error or missing font:

  ```ts
  const ORIGIN = "https://webview.test";
  const NONCE = "c21va2V0ZXN0bm9uY2Uw"; // fixed, so the stub's script can carry it
  await page.route(`${ORIGIN}/**`, async (route) => {
    const { pathname } = new URL(route.request().url());
    if (pathname === "/") {
      const html = renderWebviewHtml({
        cspSource: ORIGIN,
        nonce: NONCE,
        scriptUri: `${ORIGIN}/webview.js`,
        styleUris: [`${ORIGIN}/webview.css`],
        title: "Event Storming Board",
        lang: "en",
        appearance: { theme: "light" },
        // runs before the webview: installs the VS Code stub and records every violation
        body: `<div id="app"></div><script nonce="${NONCE}" src="${ORIGIN}/stub.js"></script>`,
      });
      return route.fulfill({ contentType: "text/html", body: html });
    }
    if (pathname === "/stub.js") return route.fulfill({ contentType: "text/javascript", body: stubIife });
    return route.fulfill({ path: join(dist, pathname) }); // webview.js, webview.css, fonts/
  });
  await page.goto(`${ORIGIN}/`);
  // post the document's init message, wait for the first shape and open the menu, then:
  expect(await page.evaluate(() => window.cspViolations)).toEqual([]);
  ```

  `stubIife` is the esbuild IIFE bundle of a small entry that adds a `securitypolicyviolation`
  listener on `document` (pushing `violatedDirective` and `blockedURI` into `window.cspViolations`)
  and then calls `installVsCodeWebviewStub(…)`.

## `./vscode/webview`

```ts
function applyAppearance(appearance: Appearance, element?: HTMLElement): void; // default <html>
interface AppearanceListenerOptions {
  themes: readonly Theme[];
}
function connectAppearance(options: AppearanceListenerOptions): () => void;
function connectReducedMotion(): () => void;

interface VsCodeShellOptions
  extends Omit<ShellOptions, "host" | "keyScope" | "themes">, AppearanceListenerOptions {}
function mountVsCodeShell(root: HTMLElement, options: VsCodeShellOptions): ShellHandle;

interface WebviewStateApi {
  getState(): unknown;
  setState(state: unknown): void;
}
interface ShellWebviewState {
  legendOpen?: boolean;
  view?: ViewportState;
}
const SHELL_STATE_KEY = "modelerShell";
function readShellState(api: WebviewStateApi): ShellWebviewState;
function writeShellState(api: WebviewStateApi, patch: ShellWebviewState): void;
interface PersistableView {
  onChange(listener: () => void): () => void;
  getState(): ViewportState | undefined;
}
interface PersistViewOptions {
  delayMs?: number; // default 250
}
function persistView(
  api: WebviewStateApi,
  viewport: PersistableView,
  options?: PersistViewOptions,
): () => void;

// re-exported from the shared protocol, as in ./vscode/extension:
// APPEARANCE_MESSAGE_TYPE, AppearanceMessage, appearanceMessage, isAppearanceMessage
```

- `applyAppearance` sets `data-cd-theme` and `data-cd-kontrast` in one task, with
  `cd-shell-no-transition` on `<html>` until a nested `requestAnimationFrame` (no colour fades; after
  several quick switches only the last one lifts it).
- `connectAppearance` applies every `AppearanceMessage` arriving on `window`, resolved against its own
  `themes` once more (what this bundle can show wins over what the extension passed); a message that
  changes nothing leaves `<html>` alone. A page whose `<html>` has no `data-cd-theme` at connect (no
  `renderWebviewHtml`) falls back to the body classes until the first message: a `MutationObserver`
  applies `resolveAppearance(appearanceFromBodyClasses(…), themes)`, at once and on every change.
  With the attributes of `renderWebviewHtml` there is no fallback: the bridge knows the `colorTheme`
  setting, the body classes do not, and VS Code changes them before the bridge's message arrives from
  the extension host, which would flash the mode without the setting. The body classes are never
  used for styling. Throws for empty `themes`.
- `connectReducedMotion` mirrors the body class `vscode-reduce-motion` (VS Code's
  `workbench.reduceMotion`, kept up to date by VS Code) as `REDUCED_MOTION_CLASS` on `<html>` for the
  whole session; its disconnect removes the class.
- `mountVsCodeShell` is `mountShell` with `host: "ide"` and `keyScope: "document"` (both always win)
  plus `connectAppearance(options)` and `connectReducedMotion()`, connected first, so empty `themes`
  throw before anything mounts (and disconnected again if `mountShell` throws). It returns a handle
  that passes every member through and whose `destroy()` disconnects both too. This wires the IDE
  key interception: handled keys are stopped on `document`, before VS Code's listener on `window`
  forwards them to the workbench.
- `readShellState`/`writeShellState` keep the shell's part (legend state, view) under
  `SHELL_STATE_KEY` of `vscode.getState()`. `readShellState` returns `{}` for a missing or malformed
  part and only valid fields (a view with finite `x`/`y`, positive width and height and a boolean
  `userMoved`), as copies. `writeShellState` merges: every other top-level key and unknown keys in its
  own part stay, an `undefined` or malformed value leaves the stored one alone (so
  `{ view: viewport.getState() }` before the first import erases nothing), and nothing is written
  when nothing changed. The modeler owns `acquireVsCodeApi()` (callable once) and passes its API
  object.
- `persistView(api, viewport)` writes `{ view: viewport.getState() }` once the view has rested for
  `delayMs` (trailing), instead of one `vscode.setState` IPC message per frame of a pan, a wheel zoom
  or a fit animation; the returned stop function writes a pending change at once. The legend state
  is written from `legend.onToggle` (see the usage below).
- The custom editor is registered with `webviewOptions: { retainContextWhenHidden: true }`: a hidden
  tab keeps document, view and selection, reports a 0 × 0 container and neither fits nor measures.

## `./testing`

```ts
// Playwright's Page satisfies it
interface PageLike {
  evaluate<R, Arg>(pageFunction: (arg: Arg) => R | Promise<R>, arg: Arg): Promise<R>;
  setViewportSize(size: { width: number; height: number }): Promise<void>;
  keyboard: { press(key: string): Promise<void> };
  mouse: {
    click(x: number, y: number): Promise<void>;
    dblclick(x: number, y: number): Promise<void>;
    move(x: number, y: number): Promise<void>;
    down(): Promise<void>;
    up(): Promise<void>;
  };
  waitForTimeout(timeout: number): Promise<void>;
  // 0.2: Playwright's page.emulateMedia; the web host's appearance needs it (else a skip, hook "open")
  emulateMedia?(options: {
    colorScheme?: "light" | "dark" | "no-preference" | null;
    contrast?: "more" | "no-preference" | null;
    reducedMotion?: "reduce" | "no-preference" | null;
    forcedColors?: "active" | "none" | null;
  }): Promise<void>;
}

interface OpenContext {
  size: Size; // the shell container's size (grow the page by any frame around an embedded root)
  requested: Appearance; // what the host requests; the harness opens the page with it (embedded, web: see below)
}
interface ShowHooks<P extends PageLike = PageLike> {
  problems?(page: P): Promise<void>; // web: with items, so the popover has rows
  status?(page: P): Promise<void>;
  legend?(page: P): Promise<void>;
  inspector?(page: P): Promise<void>;
  invalid?(page: P): Promise<void>; // the invalid-file state, caused the way the host causes it
  emptyState?(page: P): Promise<void>; // 0.2, web: the start screen of a fresh visit
  toast?(page: P, toast: ToastFixture): Promise<void>; // 0.2, web and embedded: through shell.toast
}
type ShowHook = keyof ShowHooks; // … | "emptyState" | "toast"
// "problemSelection": the modeler's problems never point at an element (only at lines), so no row selects
type AbsentFeature = ShowHook | "drop" | "problemSelection";
interface ToastFixture {
  status: ToastStatus;
  text: string;
  actionLabel?: string; // the hook passes { label: actionLabel, onSelect() {} } as action
}
interface DropFixture {
  name: string;
  type: string;
  text: string; // the kit builds new File([text], name, { type }) in the page
}
interface DropFixtures {
  accepted: DropFixture; // dropped on the start screen, it opens (the card goes)
  rejected?: DropFixture; // opens nothing, shows a danger toast (or the modeler's onReject)
  multiple?: boolean; // the modeler's DropZoneOptions.multiple; default false: two files are forbidden
}
interface ShellConformanceHarness<P extends PageLike = PageLike> {
  host: ShellHost;
  themes: readonly Theme[];
  open(page: P, context: OpenContext): Promise<void>;
  destroy?(page: P): Promise<void>;
  root?: string; // default ".cd-shell"
  show?: ShowHooks<P>;
  drop?: DropFixtures; // 0.2, web: the files the dropZone case drops
  absent?: readonly AbsentFeature[]; // islands, states and the drop zone the modeler does not have
  sizes?: readonly Size[]; // default 1280 × 900, 720 × 700, 420 × 700
}
interface ShellSkip {
  hook: ShowHook | "drop" | "destroy" | "open"; // the harness field that would feed the skipped part
  reason: string;
}
interface ShellCaseOutcome {
  skipped?: readonly ShellSkip[];
}
interface ShellConformanceCase {
  name: string;
  run<P extends PageLike>(page: P, harness: ShellConformanceHarness<P>): Promise<ShellCaseOutcome | void>;
}
function shellConformanceCases(): ShellConformanceCase[];
type ShellConformanceTest<P extends PageLike = PageLike> = (
  name: string,
  body: (fixtures: { page: P }) => Promise<void>,
) => unknown;
interface RegisterShellConformanceOptions {
  onSkip?(caseName: string, skips: readonly ShellSkip[]): void; // default: console.warn, joined by "; "
}
function registerShellConformance<P extends PageLike>(
  harness: ShellConformanceHarness<P>,
  test: ShellConformanceTest<P>,
  options?: RegisterShellConformanceOptions,
): void;
// "theme=dark&kontrast=hoch[&colorTheme=…][&reduceMotion]" for a page with the VS Code stub
function vsCodeStubSearch(
  requested: Appearance,
  extra?: { colorTheme?: ColorThemeSetting; reduceMotion?: boolean },
): string;

const GEOMETRY_TOLERANCE_PX = 1;
interface IslandBox {
  left: number;
  top: number;
  width: number;
  height: number;
}
interface ChromeMeasurement {
  container: Size;
  paletteRow: PaletteRow;
  islands: Partial<Record<ChromeIsland, IslandBox>>;
  open: {
    legend: boolean;
    inspector: boolean;
    problems: boolean;
    emptyState: boolean; // 0.2: data-empty-state="shown"
    primaryCollapsed: boolean; // 0.2: data-primary="collapsed"
    zoomRaised: boolean; // 0.2: data-zoom-row="raised"
  };
  toastCardWidth?: number; // 0.2: the widest visible toast card; absent without a toast
}
interface ExpectedBox {
  left?: number;
  top?: number;
  right?: number;
  bottom?: number;
  width?: number;
  height?: number;
  centerX?: number;
  centerY?: number; // 0.2
}
function measureChrome(page: PageLike, root?: string): Promise<ChromeMeasurement>;
function expectedChromeBoxes(
  measurement: ChromeMeasurement,
  host: ShellHost,
): Partial<Record<ChromeIsland, ExpectedBox>>;
```

`IslandBox` and `ExpectedBox` are relative to the root's padding box (`getBoundingClientRect()` minus
the root's box and border), where the islands anchor.

Cases (each named `shell conformance: <name>`; failures throw plain `Error`s listing every problem):

| Case         | Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `geometry`   | per size, as opened and after each show hook in turn (legend, problems, status, inspector): every visible `data-chrome` island against the geometry table, ±1px; the palette row decision (second row up to 760px, 16px clearance); the guide's limits (legend ≥ 184px, status ≤ `min(560px, 100cqw − 24px)`, side inspector ≥ 64px above the bottom, sheet ≤ 45 %, second-row palette ≤ `100cqw − 24px`); root state attributes against what is visible; zoom, pill and legend hidden under a bottom sheet; the dropdown at 60/12 and 248 to `min(320px, 100cqw − 24px)` wide; tooltips on the menu trigger, a palette entry and zoom in at 60, 112 and bottom 60, centred and 12px from the sides; an `absent` island is never visible                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `aria`       | trigger `aria-haspopup`/`-expanded`/`-controls` → `role="menu"`; the menu keyboard (Enter and ↓ open on the first entry, ↑ on the last, wrap, Home/End, Escape returns focus), whose keys never reach a `keydown` listener on `document`; named items, `aria-checked`, labelled radio groups, dialog entries ending in "…"; palette `role="toolbar"` with roving tabindex driven by ←/→/Home/End, `aria-pressed` on tools and `aria-keyshortcuts` on every entry whose tooltip shows a shortcut (each entry focused by keyboard); Tab from the menu trigger lands on the palette's one stop, then on the canvas `<svg>`, nothing in between; the canvas `<svg>` has an accessible name; zoom `role="group"`, readout `aria-label` with the shown percentage, `aria-keyshortcuts` for the page's platform, `aria-disabled` (never native `disabled`) at 400 % and 20 % reached by clicking; roles of pill, status, legend and inspector (an `absent` one is never visible); DOM order; no positive `tabindex`; no native `title`; `lang` on `<html>` or on an embedded root                                                                                                                          |
| `keys`       | on the canvas, each chrome key changes the zoom exactly once (Ctrl, Meta, Shift and numpad variants 100 % → 135 % → 100 %, 0 and Numpad0 to 100 %, Shift+1 fits at most 100 %); unmodified `+`/`-` and Alt combinations do nothing; Escape without menu or dialog passes untouched; input, textarea and editable-label stand-ins block the zoom keys and keep undo/redo (stopped, not prevented), modal and popover stand-ins block, Escape with the open menu closes it; Control+A and Meta+A on the focused canvas are handled by the canvas (select all, or at least prevented). `ide`: a `keydown` listener on `window` never sees a handled or blocked key (select all included) while F1 still arrives, a `document` listener registered after the shell's sees handled keys prevented and blocked ones (Cmd/Ctrl+Z in a text field) not, and Cmd/Ctrl+Z, Shift+Z and Ctrl+Y on the canvas reach `window` once and unprevented (the document's history undoes, §13.5); other hosts: every key reaches `window`, the handled ones prevented                                                                                                                                                    |
| `create`     | §5.5: the palette focused by keyboard and walked with →/Home to the first entry that is not a tool (outside group `tools`, `data-action` not ending in `-tool`), then Enter: exactly one new `.djs-shape[data-element-id]`, selected, its centre inside the free rectangle (the container minus the fit insets recomputed from the measured chrome), the focus on the canvas (its `<svg>` or a label-editor field); Escape afterwards. A notation without a creating entry passes with nothing to verify                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `readOnly`   | §13.5, after `show.invalid` and `INVALID_STATUS_DELAY_MS`: `data-readonly` on the root, the status box visible with `role="alert"`; every palette entry but `lasso-tool` and `hand-tool` `aria-disabled`, those two not, and the disabled tool entries and their icons in `--cd-ui-text-leise`; Enter on a creating entry adds no shape; the shell's Legend checkbox and every Export and Help entry that was enabled before stay enabled; on a shape a pointer reaches: no `.djs-context-pad` entry after a click, a 40px drag changes neither its position nor its size, a double-click opens no text field inside `.djs-container`, Delete and Backspace on the canvas keep it. Skips with `hook: "invalid"` without the hook (unless `absent` lists it) and with `hook: "open"` when the opened document shows no such shape                                                                                                                                                                                                                                                                                                                                                                    |
| `appearance` | the harness opens with dark, dark + high contrast and light + high contrast requested. Own document: the mode on `<html>` is `resolveAppearance(requested, themes)`, recomputed by the kit (a light-only modeler stays light, `hoch` passes). Embedded: the kit puts the foreign page's `<html>` in the requested mode, and the root carries its own `data-cd-theme="<themes[0]>"` with the page's `data-cd-kontrast` (§13.3). Both: no themed descendant; `cd-shell-document` on `<html>` in `ide`/`web`, never in a foreign page; tokens loaded; `color-scheme` and four `--cd-ui-*` roles equal on root, canvas, every island, the open dropdown and the visible tooltip; the painted surround, the first non-transparent `background-color` from `.djs-container` out through `.cd-shell-canvas` to the root, equals `--cd-ui-grund` (§10.1); every palette tool entry (group `tools` or `data-action` ending in `-tool`) and its icon (`<svg>` or `::before`) compute to `--cd-ui-text` at rest and pressed and to `--cd-ui-interaktion` hovered, each tool hovered in turn and Lasso armed by a click, which sets `aria-pressed="true"`; notation previews are exempt (§5.5). Never half-dark |
| `cleanup`    | with a tooltip timer pending: after `destroy` and 800ms, a resize and chrome keys that must arrive unprevented, no `cd-shell*` class or element, no `data-chrome`, no root state attribute (embedded: also no `data-cd-theme`/`data-cd-kontrast`) and no page error is left; skips with `hook: "destroy"` without a `destroy`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

**0.2, the web column.** The 0.1 cases learn the web host's islands, and five cases join them after
`cleanup` (`createWebCases` in `src/testing/web-cases.ts`). Each runs in every host; outside the
hosts it applies to it asserts that nothing of it shows and passes.

| Case / extension        | Checks                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `geometry` (extended)   | web: `primary` at 12/12, 40 high, 40 wide while collapsed; the palette keeping 16px to the primary action in the top row; `legal` at 12/12, 20 high per line and at most `100cqw − 24px` wide; pill, legend and zoom panel per `open.zoomRaised` on the legal line's measured lines; the popover above the pill (after a click on it); toasts at `toastStackBottom` recomputed from the measured bottom row and the widest card (`toastCardWidth`); `empty-state` centred after `show.emptyState`; IDE and embedded: `primary`, `legal`, `empty-state`, `drop-zone` never visible                                                             |
| `aria` (extended)       | web: tab order menu trigger, primary action, palette, canvas; the primary action's `aria-label` in both states; the legal `<nav aria-label>`, Impressum and Datenschutz with `lang="de"`, `rel="noopener noreferrer"`; the File group first with its ids and icons, the Appearance group (dark-capable only) between Export and Help with `aria-checked`; the pill's `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`                                                                                                                                                                                                               |
| `appearance` (extended) | web, with `emulateMedia`: light-only: `<html data-cd-theme="light">` under a dark system, no Appearance group, `data-cd-kontrast="hoch"` under `prefers-contrast: more`; dark-capable: `system` follows the system, choosing Dark writes `miragon.darstellung=dark`, `data-cd-theme="dark"`, `color-scheme` and both `theme-color` metas in one frame, System removes the entry; never half-dark                                                                                                                                                                                                                                              |
| `webChrome`             | primary action: label collapse before the palette moves (widths stepped from wide to narrow), tooltip only while collapsed, `onSelect` on click and on Enter (so a real app runs its own handler, a Share without clipboard permission shows its danger toast meanwhile); legal line content and links, at 320px every link whole inside the wrapped line (WCAG 1.4.10); the raised zoom row where legal line and zoom panel meet; File entries run their handlers and close the menu, never locked under `show.invalid`                                                                                                                      |
| `emptyState`            | after `show.emptyState`: the card centred, `min(400px, 100cqw − 24px)`, Komet 64px with `alt=""`, `<h1>`, primary "New diagram" before ghost "Show example", both 36px (a text link in the hint is no action); the work chrome `visibility: hidden`, the canvas `inert`, Tab reaching only the card and the legal links, chrome keys reaching the browser unprevented without zooming the diagram; with `show.toast`, closing a focused toast puts the focus on the card; "New diagram" hides it, shows the chrome and focuses the canvas `<svg>`                                                                                             |
| `toasts`                | through `show.toast`: a `role="status"` and a `role="alert"` live region in the root before the first toast, the toast's text arriving in the one of its status, no live role on the card; Close named "Close", at most three (the fourth evicts the oldest without action), the newest at the bottom, a repeated text not stacked, closing after `toastLifetime` (with a margin) unless hovered or focused, a toast with an action never; web: shown again in the top layer after a `showModal()` stand-in opened (everything outside a modal is inert, so the kit checks the stacking, not a click); IDE: no hook and no toast element ever |
| `problemsList`          | web (embedded when the pill opens it): after `show.problems`, a click on the pill opens `role="dialog"` titled "Problems" with the rows, Escape returns the focus to the pill, an outside click closes without moving it; Enter on the pill and then ↓ to the last row, Home and End reach every row, text rows included, each scrolled into the list (WCAG 2.1.1); a row with an element closes it and focuses the canvas (skipped with `hook: "problems"` when no item has an `elementId`, unless `absent` lists `"problemSelection"`); geometry left 12, 8px above the pill, at most 320 wide and high                                     |
| `dropZone`              | web with `harness.drop`: synthetic file drags (a `DataTransfer` built in the page) show `data-drop="over"` with the §9 colours and the 12px inset; two files (unless `drop.multiple`) and a modal stand-in show `forbidden`; a drag without files changes nothing; dropping `accepted` on the start screen opens it, `rejected` opens nothing and shows a danger toast; skips with `hook: "drop"` without the fixtures unless `absent` lists `"drop"`                                                                                                                                                                                         |

- **Skips.** A case the harness cannot feed reports what it skipped as `ShellSkip`s, one per missing
  harness field, through `onSkip` (default `console.warn`). A hook that is neither in `show` nor in
  `absent` is skipped with `hook` set to its name, a missing `destroy` with `hook: "destroy"`, and a
  document that lacks what a case needs (a shape a pointer reaches, for `readOnly`) with
  `hook: "open"`. `absent` lists what the modeler does not have (an island or the `invalid` state),
  which is then never reported, while `geometry` and `aria` assert that the island never shows. Listing a hook in both `show` and `absent` fails every case that uses
  it. A suite that lists what it lacks can fail on every remaining skip:
  `onSkip(name, skips) { throw new Error(…) }`.
- **`show.invalid`** makes the file invalid the way the host does (in a webview: a document update
  the parser rejects), not by calling `shell.setReadOnly` alone: the `readOnly` case also checks the
  modeler's own canvas lock, which its invalid-import path sets. The case waits
  `INVALID_STATUS_DELAY_MS` and a margin itself.
- For the `embedded` host the kit writes `data-cd-theme` and `data-cd-kontrast` on the page's
  `<html>` itself after `open`: every consumer suite then proves that the modeler stays in its own
  mode inside a dark host page, the case a foreign page meets in practice (designIQ, a web app on
  `system` under a dark OS).
- For the `web` host (0.2) the kit calls `page.emulateMedia({ colorScheme, contrast })` from
  `requested` before `open`, and `open` loads the page without a stored `miragon.darstellung`; the
  `appearance` case then sets the choice through the Appearance group itself. Without
  `emulateMedia` the web part of `appearance` skips with `hook: "open"`.
- The second-row tooltip of the `geometry` case may stand centred on its entry or in the container:
  guide §5.15 says "mittig im Container", and which of the two it means is an open question; the
  shell centres it on its entry.
- The kit never imports Playwright; a modeler's suite passes its `page` and `test`
  (`registerShellConformance(harness, test)` from `@playwright/test`). It installs one page global,
  `__modelerShellConformance`, with `keydown` recorders on `window` and `document`, and briefly
  injects stand-ins marked `data-modeler-shell-conformance` (an input, a textarea, an editable label,
  a modal dialog, a popover, a focus target) into the shell root.
- `geometry` takes about 10s per host; wrap the registration in
  `test.describe.configure({ timeout: 60_000 })`.
- `registerShellConformance` calls `test` inside the kit, so a runner reports every case at the
  kit's source (the package ships `src/`, so that location resolves). For locations in the suite's
  own spec file, register the cases there:

  ```ts
  for (const conformanceCase of shellConformanceCases()) {
    test(`shell conformance: ${conformanceCase.name}`, async ({ page }) => {
      const outcome = await conformanceCase.run(page, harness);
      if (outcome?.skipped?.length) onSkip(conformanceCase.name, outcome.skipped);
    });
  }
  ```

### `./testing/vscode-stub` — the `ide` host without VS Code

```ts
type ColorThemeKind = 1 | 2 | 3 | 4;
function colorThemeKindOf(appearance: Appearance): ColorThemeKind;
const STUB_SETTING_KEY = "miragon.modeler.colorTheme";
interface VsCodeWebviewStubOptions {
  requested: Appearance; // VS Code's color theme
  themes: readonly Theme[]; // what the modeler's extension passes to the bridge
  lang?: string; // default "en"
  colorTheme?: ColorThemeSetting;
  settingKey?: string; // default STUB_SETTING_KEY
  reduceMotion?: boolean; // workbench.reduceMotion
  state?: unknown; // what acquireVsCodeApi().getState() returns at first
}
interface StubbedVsCodeApi {
  getState(): unknown;
  setState(state: unknown): void;
  postMessage(message: unknown): void;
}
interface VsCodeWebviewStub {
  readonly kind: ColorThemeKind;
  setColorThemeKind(kind: ColorThemeKind): void; // body classes first, then the bridge posts
  setColorTheme(setting: ColorThemeSetting | undefined): void;
  setReduceMotion(reduceMotion: boolean): void;
  pendingMessages(): number; // posted by the bridge, not yet delivered
  readonly posted: readonly unknown[]; // what the webview posted
  state(): unknown;
}
type StubWindow = Window & {
  __modelerShellVsCodeStub?: VsCodeWebviewStub;
  acquireVsCodeApi?: () => StubbedVsCodeApi;
};
function stubOptionsFromSearch(
  search: string,
): Pick<VsCodeWebviewStubOptions, "requested" | "colorTheme" | "reduceMotion">;
function installVsCodeWebviewStub(options: VsCodeWebviewStubOptions): VsCodeWebviewStub;
```

Runs in a test page, before the modeler's webview code: VS Code's default webview stylesheet in
`@layer vscode-default` (with foreign values, so a leak shows), `<html>` with the attributes
`renderWebviewHtml` writes, `<body>` with the host page's theme and reduce-motion classes,
`acquireVsCodeApi()` (once, as in VS Code) and the real `connectThemeBridge` against a fake `vscode`
namespace whose panel posts to the window. The stub is also `window.__modelerShellVsCodeStub`, so a
Playwright suite switches the color theme or the setting at runtime.

A modeler's e2e suite serves `e2e/webview/` as the root of a Vite server, with the test page
`e2e/webview/webview-test.html` (`<div id="app">` and `<script type="module" src="./webview-test.ts">`)
and this entry:

```ts
// e2e/webview/webview-test.ts
import { installVsCodeWebviewStub, stubOptionsFromSearch } from "@miragon/modeler-shell/testing/vscode-stub";

// before the webview runs, which calls acquireVsCodeApi() and mounts the shell
installVsCodeWebviewStub({ ...stubOptionsFromSearch(location.search), themes: ["light"] });
const { webview } = await import("../../src/webview/main"); // exports { shell, modeler, connection, ready }

// for the harness only: the shipped bundle publishes nothing on window
window.shell = webview.shell;
window.modeler = webview.modeler;
window.connection = webview.connection;
void webview.ready.then(() => (window.webviewReady = true)); // the first import settled

// there is no extension host: post the document the way the extension would
window.postMessage({ type: "init", text: EXAMPLE_BOARD }, "*");
```

The harness opens it with ``page.goto(`/webview-test.html?${vsCodeStubSearch(requested)}`)`` and waits
for `window.webviewReady`. `ready`, `webviewReady` and the window globals are the modeler's, not the
shell's: its webview module exports `ready`, resolved once the first `init` import settled, and the
test page turns it into the flag (the Event Storming `main.ts` below exports it).

## `./shell.css`

One stylesheet for everything above, loaded last. Containment: `.cd-shell { container: cd-shell /
size }`; breakpoints are `@container cd-shell (max-width: 760px)`, `(max-width: 440px)` with literal
values (custom properties are not allowed in container conditions), sizes inside are `cqw`/`cqh`,
never viewport units, and no element inside gets a `container-type` of its own. It covers glass
islands (`color-mix(in srgb, var(--cd-ui-flaeche-hoch) var(--cd-ui-chrome-deckkraft), transparent)`
with `backdrop-filter: blur(8px)`), opaque popups, focus rings (inset in dense containers),
`[data-cd-kontrast="hoch"]` (no shadows, 3px focus), `@media (forced-colors: active)` (rings in
`Highlight`, status bar and island borders in `CanvasText`), `prefers-reduced-motion` and
`html.cd-shell-reduce-motion`, `html.cd-shell-no-transition` (no transitions for the frame of a mode
switch), the canvas `<svg>`'s focus ring (2px, 3px in high contrast, inside the slot), and under
`html.cd-shell-document` the own-document reset: no body padding, `--cd-ui-grund` background, Geist
13px/1.5, own `kbd`, `code`, links, focus and scrollbars, never `var(--vscode-*)`. The reset is
unlayered, so it wins over VS Code's `@layer vscode-default`; its button and field font reset has
zero specificity, so the chrome's own rules (the readout's 13px/600) win over it. In a foreign page
the chrome's own islands, controls and texts reset font, colour, letter spacing and text transform
at class specificity, so the page's element rules (`button { text-transform: uppercase }`,
`p { font-size: 18px }`) do not reach them. The canvas slot's layout (`.cd-shell >
.cd-shell-canvas`: absolute, `inset: 0`, layer 0, `isolation: isolate`) wins over a renderer's own
container class, its paint (`background-color: var(--cd-ui-grund)`) has zero specificity, so a
renderer's paper (Event Storming's dot grid) shows. The paper's colour stays `--cd-ui-grund` in
every mode, the dot grid being a background image in `--cd-ui-linie` (§10.1); the kit's `appearance`
case checks the painted colour. Palette tool entries set their colour in every
state (rest and pressed `--cd-ui-text`, hovered `--cd-ui-interaktion`, read-only
`--cd-ui-text-leise`), and their icons (`> svg`, `::before`) inherit it, so a renderer's or
diagram-js's rule on the icon or on the stale `highlighted-entry` does not leak in; notation
previews keep their own colours (§5.5). Private helper properties are named `--modeler-shell-*`.

It is assembled from `dom/shell-dom.css` (0.1 chrome), `dom/buttons.css` (0.2: the buttons of the
web chrome, the one place with fixed palette tokens, see [Buttons](#buttons)), `dom/web/web.css`
(0.2: primary action, legal line, empty state, drop zone, raised zoom row) and
`dom/feedback/feedback.css` (0.2: toasts and the problems popover; they render in a foreign page too,
so they reset the page's element rules like the 0.1 islands), then `diagram-js/palette.css`. A test
pins that `shell.css` imports every stylesheet of `src`.

The shell bundles no font: the modeler loads Geist and Geist Mono (`@fontsource-variable/geist`,
`@fontsource-variable/geist-mono`), as the stylesheet order above shows, as font files (see
`./vscode/extension`).

## Usage: Event Storming in VS Code

The Event Storming extension, the pilot of 0.1. Extension host
(`EventStormingEditorProvider.resolveCustomTextEditor`):

```ts
import * as vscode from "vscode";
import {
  connectThemeBridge,
  currentAppearance,
  renderWebviewHtml,
  revealFileLabel,
} from "@miragon/modeler-shell/vscode/extension";

const THEMES = ["light"] as const; // until the shared dark-mode release of all modelers

// activate(): a hidden tab keeps document, view and selection (and reports 0 × 0 meanwhile)
vscode.window.registerCustomEditorProvider(viewType, provider, {
  webviewOptions: { retainContextWhenHidden: true },
});

// resolveCustomTextEditor():
const dist = vscode.Uri.joinPath(extensionUri, "dist");
webview.options = { enableScripts: true, localResourceRoots: [dist] }; // webview.js, webview.css, fonts/
const asset = (file: string) => webview.asWebviewUri(vscode.Uri.joinPath(dist, file)).toString();
webview.html = renderWebviewHtml({
  cspSource: webview.cspSource,
  scriptUri: asset("webview.js"),
  styleUris: [asset("webview.css")],
  title: "Event Storming Board",
  lang: "en",
  appearance: currentAppearance(vscode, { themes: THEMES }),
});
connectThemeBridge(vscode, webviewPanel, { themes: THEMES }); // disposes itself with the panel

// after an export (exportImage.ts):
const reveal = revealFileLabel(process.platform);
if ((await vscode.window.showInformationMessage(`Exported ${name}.`, reveal)) === reveal) {
  void vscode.commands.executeCommand("revealFileInOS", target);
}
```

The two bundles (`esbuild.config.mjs`):

```js
const host = {
  entryPoints: ["src/extension.ts"],
  outfile: "dist/extension.cjs",
  bundle: true,
  platform: "node",
  format: "cjs",
  target: "node20", // VS Code 1.90 or later: the global crypto of createNonce
  external: ["vscode"],
};
const web = {
  entryPoints: ["src/webview/main.ts"],
  outfile: "dist/webview.js", // and dist/webview.css
  bundle: true,
  platform: "browser",
  format: "iife", // renderWebviewHtml writes a classic <script nonce>
  loader: { ".woff2": "file", ".woff": "file" }, // font files: a page loads only the subsets it needs
  assetNames: "fonts/[name]-[hash]",
};
```

Webview (`src/webview/main.ts`):

```ts
import "./zod-jitless"; // first: z.config({ jitless: true }) before any schema module (CSP)
import "@fontsource-variable/geist/wght.css";
import "@fontsource-variable/geist-mono/wght.css";
// the renderer's stylesheet brings diagram-js.css and the tokens, so they are not imported again
import {
  createCollaborativeModeler,
  type BoardBounds,
  type EventStormingReadOnly,
  type EventStormingViewOptions,
} from "@miragon/event-storming-renderer";
import "./style.css"; // the modeler's own content: the "Keyboard shortcuts…" dialog
import "@miragon/modeler-shell/shell.css";
import { INVALID_STATUS_DELAY_MS } from "@miragon/modeler-shell";
import { connectDiagramJs, shellModule } from "@miragon/modeler-shell/diagram-js";
import { mountVsCodeShell, persistView, readShellState } from "@miragon/modeler-shell/vscode/webview";
import { createShortcutsDialog } from "./shortcutsDialog";

const vscode = acquireVsCodeApi();
const stored = readShellState(vscode);

// 1. The diagram first: Event Storming's keyboard listens on document and must run before the
//    shell's, and the renderer builds its diagram lazily, so get() a service. width/height: the
//    shell's slot sizes it.
const collaborative = createCollaborativeModeler({
  additionalModules: [shellModule],
  // VS Code's document history owns Cmd/Ctrl+Z (§13.5); the kit's keys case checks it
  undoRedoKeys: false,
  // where Enter or Space on a creating palette entry places the element (§5.5): the renderer takes
  // the fit insets and computes the centre of the free rectangle itself, the same point as
  // viewport.freeRectCenter(); a renderer may take that function instead
  freeRectInsets: () => shell.fitInsets(),
});
const modeler = collaborative.diagram;
modeler.get("canvas");
const viewOptions = modeler.get<EventStormingViewOptions>("eventStormingViewOptions");
const levels = modeler.get<{ getLevel(): string; setLevel(level: string): void }>("eventStormingModeling");
// the canvas lock of an invalid file: context pad, move, resize, delete, paste, label editor
const canvasLock = modeler.get<EventStormingReadOnly>("eventStormingReadOnly");
const boardBounds = modeler.get<BoardBounds>("boardBounds");

// 2. The chrome around it.
const shell = mountVsCodeShell(document.getElementById("app")!, {
  themes: ["light"],
  canvas: modeler.container,
  messages: { canvas: "Event Storming board" },
  menu: {
    model: [
      {
        kind: "radio",
        id: "level",
        label: "Level",
        options: [
          { value: "big-picture", label: "Big picture" },
          { value: "process", label: "Process modeling" },
          { value: "design", label: "Software design" },
        ],
        value: () => levels.getLevel(),
        onSelect: (level) => levels.setLevel(level),
      },
      {
        kind: "checkbox",
        id: "type-captions",
        label: "Type captions",
        keepEnabledWhenReadOnly: true, // a view toggle, not board content: usable while read-only
        checked: () => viewOptions.typeCaptionsVisible(),
        onToggle: (visible) => viewOptions.setTypeCaptionsVisible(visible),
      },
    ],
    export: [
      {
        kind: "action",
        id: "export-png",
        label: "Export as PNG",
        icon: "file-image",
        onSelect: () => void exportPng(),
      },
      {
        kind: "action",
        id: "export-svg",
        label: "Export as SVG",
        icon: "file-code-corner",
        onSelect: () => void exportSvg(),
      },
    ],
    help: [
      {
        kind: "dialog",
        id: "keyboard-shortcuts",
        label: "Keyboard shortcuts…",
        icon: "keyboard",
        onSelect: () => shortcutsDialog.open(),
      },
    ],
  },
  problems: { onActivate: () => vscode.postMessage({ type: "showProblems" }) },
  emptyHint: { onInsertExample: () => vscode.postMessage({ type: "insertExample" }) },
});
// The modeler's own dialog in shell.root (see Modeler dialogs); it goes with the diagram.
const shortcutsDialog = createShortcutsDialog(shell);
modeler.on("diagram.destroy", () => shortcutsDialog.destroy());

// 3. Viewport, palette, keys and the empty-file hint. Cheap tests only: canFit() is cached, but
//    exportMap() validates the whole board.
const registry = modeler.get<{ getAll(): Array<{ parent?: unknown; waypoints?: unknown }> }>(
  "elementRegistry",
);
const isEmpty = () => !registry.getAll().some((element) => element.parent && !element.waypoints); // §13.5
const connection = connectDiagramJs(shell, modeler, {
  isEmpty,
  // no padding of its own (the default pads by 120px): the fit insets are the only margin (§5.9)
  contentBounds: () => (isEmpty() ? undefined : boardBounds.contentBounds(0)),
});
const { viewport } = connection;
persistView(vscode, viewport); // vscode.setState once the view rested, not on every frame
modeler.on("commandStack.changed", () => shell.menu.refresh()); // level undo/redo

// 4. Every import from the document (init and external updates), strictly one after another.
async function importText(text: string, first: boolean): Promise<void> {
  const keep = first ? undefined : viewport.getViewbox();
  try {
    await collaborative.importText(text); // silent: no change event comes from an import
    canvasLock.setReadOnly(false);
    shell.setReadOnly(false);
    shell.setStatus(null);
    if (keep) viewport.restore(keep);
    else if (first && stored.view) viewport.setState(stored.view);
    viewport.afterImport(); // first content fits, an empty file shows 100 %, the hint follows import.done
    shell.menu.refresh();
  } catch {
    // locked at once, the canvas included; marks and status box show after 800ms without a valid import
    canvasLock.setReadOnly(true);
    shell.setReadOnly(true, { delayMs: INVALID_STATUS_DELAY_MS });
    shell.setStatus(
      { severity: "danger", text: shell.messages.invalidFile("Event Storming board") },
      { delayMs: INVALID_STATUS_DELAY_MS },
    );
  }
}
let imports = Promise.resolve();
const enqueueImport = (text: string, first = false) =>
  (imports = imports.then(() => importText(text, first)));

// 5. Messages from the extension: the document, the diagnostics and the Command Palette commands,
//    which run the same handlers as the menu.
let firstImportSettled = () => {};
const ready = new Promise<void>((resolve) => (firstImportSettled = resolve));
window.addEventListener("message", (event) => {
  const message = event.data;
  if (message?.type === "init") void enqueueImport(message.text, true).then(firstImportSettled);
  if (message?.type === "update") void enqueueImport(message.text);
  if (message?.type === "problems") shell.setProblems({ count: message.count, errors: message.errors });
  if (message?.type === "command" && message.name === "fitView") viewport.fit();
});
vscode.postMessage({ type: "ready" });

// For the e2e test page (see ./testing/vscode-stub); the bundle publishes nothing on window.
export const webview = { shell, modeler: collaborative, connection, ready };
```

`zod-jitless.ts` is one line, `config({ jitless: true })` from `zod`, in a module of its own so that
it runs before any module that builds a schema.

A modeler with a legend persists it the same way: `legend: { render, open: stored.legendOpen,
onToggle: (open) => writeShellState(vscode, { legendOpen: open }) }`.

What the Event Storming renderer changes for the shell (the kit's `aria`, `keys`, `create` and
`readOnly` cases check each one):

- palette entries carry `title` and `shortcut` separately (`title: "Domain event", shortcut: "E"`),
  not `"Domain event — E"`;
- Enter or Space on a creating entry (a click with `detail === 0`) creates the sticky at the
  centre of the free rectangle (from `freeRectInsets`, the point `viewport.freeRectCenter()`
  returns), 24px further diagonally while that spot is taken, selects it, focuses the canvas and
  opens the label editor;
- no `tabindex` on `canvas.getContainer()` (an extra, unnamed tab stop before the palette); its
  keyboard listens on `document` anyway;
- the document keyboard returns early on `event.defaultPrevented` and for targets outside the canvas
  container (the zoom panel's buttons, the inspector), selects every element on Cmd/Ctrl+A, and in
  the webview binds no Cmd/Ctrl+Z, Shift+Z or Y (`undoRedoKeys: false`): VS Code's document history
  owns undo (§13.5), the shell only keeps diagram-js's `KeyboardBindings` off them;
- `eventStormingReadOnly` locks every edit rule (move, resize, create, connect, delete), and the
  keyboard, context pad, label editor and drawing handles consult it;
- its own overlays inside the canvas (the note toolbar, the colour picker) stay at `z-index` 100 or
  below, so the palette at 110 covers them (see Layers above);
- `boardBounds.contentBounds(0)`: the tight bounds of the board, since the fit insets are the margin.

Document sync, echo suppression, minimal edits and undo stay in the modeler for 0.1 (see below).

## Usage: Event Storming in the web app

The Event Storming web app (`apps/webapp`), the pilot of 0.2. It is light-only until the shared
dark-mode release, so its `index.html` is static and its head carries the contrast line only:

```html
<!doctype html>
<html lang="en" data-cd-theme="light">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <!-- miragon-mode: webHeadMarkup({ themes: ["light"], themeColors }) through transformIndexHtml -->
    <title>Event Storming Modeler</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
```

`src/main.ts`, shortened to what touches the shell (the real file is
`apps/webapp/src/main.ts` in Miragon/event-storming-modeler):

```ts
import "@fontsource-variable/geist/wght.css";
import "@fontsource-variable/geist-mono/wght.css";
import "@miragon/event-storming-renderer/assets/event-storming.css"; // the tokens, diagram-js.css
import "@miragon/modeler-shell/shell.css"; // last
import {
  Modeler,
  boardMenu,
  createShortcutsDialog,
  importWarningText,
  type ImportWarning,
} from "@miragon/event-storming-renderer";
import {
  commandKeyLabel,
  defaultMessages,
  detectPlatform,
  mountShell,
  problemSummary,
} from "@miragon/modeler-shell";
import { connectDiagramJs, shellModule } from "@miragon/modeler-shell/diagram-js";
import { copyTextWhenReady } from "./clipboard"; // ClipboardItem with a promise: Safari keeps the gesture
import { hashHoldsBoard, readHashMap, shareUrl, writeHashMap } from "./share";
import { THEMES } from "./themes"; // ["light"]

// 1. The diagram first (its keyboard listens on document); the web app keeps the canvas undo keys.
const modeler = new Modeler({
  width: "100%",
  height: "100%",
  additionalModules: [shellModule],
  freeRectInsets: () => shell.fitInsets(), // keyboard creation lands in the free rectangle
});
modeler.get("canvas");
const platform = detectPlatform(navigator);
const openKey = commandKeyLabel("O", platform, defaultMessages.keyNames); // "⌘O" / "Ctrl+O"
const saveKey = commandKeyLabel("S", platform, defaultMessages.keyNames);

// 2. The chrome, the whole web column.
const shell = mountShell(document.getElementById("app")!, {
  host: "web",
  canvas: modeler.container,
  lang: "en",
  platform,
  themes: THEMES,
  messages: { canvas: "Event Storming board" },
  primary: { onSelect: () => share() }, // "Share", share-2
  legal: { links: [{ label: "GitHub", href: "https://github.com/Miragon/event-storming-modeler" }] },
  file: {
    newDiagram: { onSelect: () => void newDiagram() },
    open: { onSelect: () => pickFile(), shortcut: openKey }, // also the start screen's "Open a file…"
    showExample: { onSelect: () => void showExample() },
  },
  // Model (level, type captions), Export and Help: the same entries the VS Code webview shows.
  menu: boardMenu({
    levels,
    typeCaptions,
    exports: {
      png: { onSelect: () => void exportPicture("png") },
      svg: { onSelect: () => void exportPicture("svg") },
      transparentPng: { onSelect: () => void exportPicture("png-transparent") },
      json: { onSelect: () => exportBoardText("json") },
      storm: { onSelect: () => exportBoardText("storm"), shortcut: saveKey },
    },
    showKeyboardShortcuts: () => shortcutsDialog.open(),
  }),
  problems: { onSelectItem: (item) => selectElement(item.elementId) },
  emptyState: {
    title: "Event Storming Modeler",
    text: "Start a new diagram, or explore the example.",
    komet: "/miragon-komet-blau.svg", // vendored unchanged from corporate-identity
    onNewDiagram: () => void newDiagram(),
    onShowExample: () => void showExample(),
    dropHint: "Or drop a .storm, .json, or .txt file here", // the types the reject toast names
  },
  dropZone: {
    accept: [".storm", ".json", ".txt", "application/json", "text/plain"],
    onDrop: ([file]) => file && void openBoardFile(file),
  },
});
const shortcutsDialog = createShortcutsDialog(shell, { fileKeys: true });

// 3. Viewport, palette, keys.
const { viewport } = connectDiagramJs(shell, modeler, {
  isEmpty,
  contentBounds: () => (isEmpty() ? undefined : boardBounds.contentBounds(0)),
});

// 4. Every new document opens like the first (§5.9); the start screen goes with it.
async function openDocument(load: () => Promise<readonly ImportWarning[]>, announce: boolean) {
  viewport.newDocument();
  let warnings: readonly ImportWarning[];
  try {
    warnings = await load();
  } finally {
    viewport.afterImport();
  }
  shell.setEmptyState(false);
  shell.menu.refresh();
  updateDocumentTitle(); // "Order Checkout · Event Storming Modeler" (§5.4)
  // The parser names lines: "Line 4 · A -> Nowhere" below the message, no element to select.
  shell.setProblems(problemSummary(problemItems(warnings)));
  for (const warning of warnings) console.warn(importWarningText(warning));
  // A toast only after an import the user started, with the count (§9), never on a restore.
  if (announce && warnings.length > 0) {
    const pill = shell.messages.problems(warnings.length, String(warnings.length));
    shell.toast({
      status: "warning",
      text: `Imported with ${warnings.length} warnings. Details under “${pill}” bottom left.`,
    });
  }
}

// Replacing a board clears the canvas history, so instead of confirm() it offers the board back
// (§9 asks for a confirmation; the undo toast is the open guide question): "Board replaced · Undo",
// also on Cmd/Ctrl+Z while the canvas has nothing else to undo. An edit withdraws the offer.
async function replaceBoard(load: () => Promise<readonly ImportWarning[]>) {
  const previous = boardIsEmpty() ? undefined : modeler.exportDSL();
  await openDocument(load, true);
  withdrawReplaceUndo();
  if (previous === undefined || previous === modeler.exportDSL()) return;
  const undo = () => void openDocument(async () => (await modeler.importDSL(previous)).warnings, false);
  replaceUndo = {
    toast: shell.toast({ status: "info", text: "Board replaced", action: { label: "Undo", onSelect: undo } }),
    undo,
  };
}

// Copy inside the click: Safari drops the user activation at the first await before writeText.
function share(): void {
  const dsl = modeler.exportDSL();
  const copied = copyTextWhenReady(shareUrl(dsl));
  void (async () => {
    try {
      await writeHashMap(dsl);
      await copied;
      shell.toast({ status: "success", text: "Link copied" });
    } catch {
      shell.toast({
        status: "danger",
        text: "Couldn't copy the link. Copy it from the address bar instead.",
      });
    }
  })();
}

// The app's own keys: Cmd/Ctrl+O opens a file, Cmd/Ctrl+S exports the .storm file (never the
// browser's dialogs, also not over a modal dialog; on the start screen there is nothing to save).
window.addEventListener("keydown", onAppKey);

modeler.on("commandStack.changed", (event: { trigger?: string }) => {
  if (event.trigger !== "clear") {
    shell.setEmptyState(false); // the first edit is a start as well
    withdrawReplaceUndo(); // an edit makes the undo offer stale
  }
  shell.menu.refresh(); // the level is undoable
  updateDocumentTitle();
});

// 5. Start: the board from the link, else the start screen on an empty board.
const linked = await readHashMap();
if (linked !== null) await openDocument(async () => (await modeler.importDSL(linked)).warnings, true);
else {
  await modeler.importMap(createEmptyBoard("New board"));
  viewport.afterImport(); // an empty board at 100 %
  shell.setEmptyState(true);
  if (hashHoldsBoard())
    shell.toast({
      status: "danger",
      text: "Couldn't read the board in this link. Check that you copied the whole link.",
    });
}
```

`openBoardFile(file)` reads the file before the canvas is touched and then runs `replaceBoard`; a
parse error shows the danger toast "Couldn't read “name”. Check that it contains a valid Event
Storming board." and keeps the board. `pickFile` opens the hidden file input with the same
`accept`. The JSON export writes `JSON.stringify(modeler.exportMap(), null, 2)`, the board's own
element order (the importer stacks overlapping stickies by it). The web app's own `style.css`,
`toast.ts` and the hand-written menu, zoom, fit and legal markup go away.

## Out of scope for 0.2

Later candidates unless noted:

- **VS Code document plumbing**: two-way sync with echo suppression, minimal `WorkspaceEdit`s,
  undo/redo through the document's history, "Insert example" as one edit, diagnostics to the
  Problems view (the pill only means something with a `DiagnosticCollection`), shared webview→host
  messages for the pill ("Show in Problems view") and "Insert example" with their host handlers,
  export save dialog. The modelers keep their own code; the shell keeps diagram-js's
  `KeyboardBindings` off undo/redo in the IDE host, stops undo/redo keys in text fields and stops
  keys the canvas handled.
- An ES-module webview bundle (`renderWebviewHtml` writes a classic script; a `scriptType` option).
- **More of the web column**: further top-right actions left of the primary action (§5.7), the
  loading state (§9 "Laden": spinner or skeleton during asynchronous work), share-link helpers
  (each modeler keeps its own hash encoding), the legend's state across sessions (a modeler persists
  it from `legend.onToggle` in `localStorage`, §5.10).
- **Dialog component and the shared shortcuts dialog** (§5.4, §8; also the confirmation of §9
  "Destruktiv" where an undo toast does not fit): an exported `cd-shell-dialog`
  class (panel, header with Close, body, backdrop with `grayscale(1)`, the high-contrast and
  forced-colours rules, the top layer through `showModal()`, focus trap and focus return), and on
  it `shell.showShortcutsDialog(groups: ShortcutGroup[])` with one table per group and the chips of
  the tooltip's `kbd`. The shell fills the View group itself from the chrome keys. New
  `ShellMessages`: `shortcutsTitle` ("Keyboard shortcuts") and the group names
  "View", "Edit" and "Tools". Popovers (§5.4) follow on the same class. Until then a modeler meets
  the rules of [Modeler dialogs](#modeler-dialogs) itself; one component lets every modeler migrate
  once.
- **Placement helper** for palette keyboard creation: the 24px diagonal steps when the centre of the
  free rectangle is taken (§5.5), next to `Viewport.freeRectCenter()`.
- the `appearance` surface of the modeler-api contract (a later 1.x minor) for embedded hosts and
  the `miragon.<modeler>.colorTheme` setting UI (the bridge already honours `settingKey`).
- **Kit**:
  - cases for reduced motion and forced colours on every host (`PageLike.emulateMedia` exists since
    0.2, but only the web `appearance` case uses it); the shell's CSS covers both, its own e2e
    suite checks VS Code's reduce motion and spot-checks forced colours on the web chrome;
  - a CSP helper: serve the production bundle under `renderWebviewHtml`'s CSP inside the VS Code
    stub, record every `securitypolicyviolation` and fail on any (until then the recipe under
    `./vscode/extension`);
  - a harness field `documents?: readonly string[]` that hands `open` a document key (for example
    `["example", "style-dark", "empty"]`), so `appearance` runs per document; until then a modeler
    registers a second harness whose `open` loads the variant;
  - on those documents, a check that an empty one opens at 100 % with the empty-file hint;
  - a check that selects an element and reports positioned descendants of `.djs-container` above
    `z-index` 100 that are neither the palette, diagram-js's popup menu nor `.djs-hover-tooltip`.
- IntelliJ/JCEF hosts, Electron, Tauri, Theia.
- Canvas theming (`cd-canvas.css`, `cd-c-*` classes), light-only export, the token files themselves.