@miragon/modeler-shell 0.1.0 → 0.2.0

package/README.md

@@ -2,8 +2,9 @@
 
 The shared, framework-free chrome around Miragon diagram-js modelers: the menu button with its
 dropdown, the horizontal palette skin, the chrome tooltip, the zoom panel with its keys and fit, the
-problems pill, the status box, the empty-file hint, legend and inspector slots, and the plumbing to
-a VS Code webview. One implementation for every modeler and every host (VS Code webview, web app,
+problems pill, the status box, the empty-file hint, legend and inspector slots, the plumbing to a
+VS Code webview, and the web-app chrome (primary action, legal line, File and Appearance groups,
+problems list, toasts, empty-state card, drop zone, the web app's mode). One implementation for every modeler and every host (VS Code webview, web app,
 embedded in a foreign page), so the chrome looks and behaves the same everywhere.
 
 - **Look and behaviour** follow the Miragon design system, guide
@@ -154,7 +155,7 @@ const shell = mountVsCodeShell(document.getElementById("app")!, {
   menu: {
     model: [/* Level; Type captions with keepEnabledWhenReadOnly, a view toggle */],
     export: [/* Export as PNG, SVG */],
-    help: [/* Keyboard shortcuts… (the modeler's dialog in 0.1) */],
+    help: [/* Keyboard shortcuts… (the modeler's own dialog) */],
   },
   legend: {
     render: renderLegend,
@@ -225,31 +226,94 @@ resize, delete, paste or label editor. Content the modeler adds to `shell.root`
 shortcuts…" dialog) is the modeler's too: it removes it in its own teardown, for example on
 `diagram.destroy`, since `shell.destroy()` removes only what the shell added. The complete Event
 Storming example, including the export notification, is in [API.md][api]. Document sync, undo through
-the document and diagnostics stay in the modeler for 0.1.
+the document and diagnostics stay in the modeler for now.
 
 ## Usage in a web app
 
+The page's head writes the mode before the first paint. A light-only modeler keeps
+`<html lang="en" data-cd-theme="light">` static and lets the build put the metas and the contrast
+line in place of a marker in `index.html`:
+
+```ts
+// vite.config.ts
+import { webHeadMarkup } from "@miragon/modeler-shell/core";
+import tokens from "./src/theme/cd-tokens.generated.json" with { type: "json" };
+
+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: ["light"], themeColors })),
+};
+```
+
 ```ts
-import { mountShell } from "@miragon/modeler-shell";
+// src/main.ts
+import {
+  commandKeyLabel,
+  defaultMessages,
+  detectPlatform,
+  mountShell,
+  problemSummary,
+} from "@miragon/modeler-shell";
 import { connectDiagramJs, shellModule } from "@miragon/modeler-shell/diagram-js";
 
-// index.html carries <html lang="en" data-cd-theme="light"> statically while the modeler is light-only
+// The diagram first: a modeler keyboard on document must run before the shell's key listener.
 const modeler = new Modeler({ width: "100%", height: "100%", additionalModules: [shellModule] });
+modeler.get("canvas");
+const platform = detectPlatform(navigator);
 const shell = mountShell(document.getElementById("app")!, {
   host: "web",
   canvas: modeler.container,
-  menu: { export: [/* … */], help: [/* Keyboard shortcuts… */] },
+  lang: "en",
+  themes: ["light"], // with "dark": also appearance: { themeColors }, and the menu gets Appearance
+  primary: { onSelect: share }, // "Share", top right; the label collapses before the palette moves
+  legal: { links: [{ label: "GitHub", href: "https://github.com/Miragon/…" }] },
+  file: {
+    newDiagram: { onSelect: newDiagram },
+    // ⌘O or Ctrl+O; also the start screen's "Open a file…" link
+    open: { onSelect: pickFile, shortcut: commandKeyLabel("O", platform, defaultMessages.keyNames) },
+    showExample: { onSelect: example },
+  },
+  menu: { model: [/* … */], export: [/* … */], help: [/* Keyboard shortcuts… */] },
+  problems: { onSelectItem: (item) => selectElement(item.elementId) },
   legend: { render: renderLegend, open: storedLegendOpen(), onToggle: storeLegendOpen },
+  emptyState: {
+    title: "BPMN Modeler",
+    text: "Start a new diagram, or explore the example.",
+    komet: kometUrl, // the vendored, unchanged miragon-komet-blau.svg
+    onNewDiagram: newDiagram,
+    onShowExample: example,
+  },
+  dropZone: { accept: [".bpmn", "application/xml", "text/xml"], onDrop: ([file]) => openFile(file) },
 });
 const { viewport } = connectDiagramJs(shell, modeler, { contentBounds: () => elementBounds() });
-await modeler.importXML(xml);
-viewport.afterImport();
+
+// Every new document opens like the first, and the start screen goes with it.
+async function openDocument(xml: string): Promise<void> {
+  viewport.newDocument();
+  const { warnings } = await modeler.importXML(xml);
+  viewport.afterImport();
+  shell.setEmptyState(false);
+  shell.setProblems(
+    problemSummary(warnings.map((warning) => ({ severity: "warning", message: warning.message }))),
+  );
+}
+
+// A fresh visit without a document in the link shows the start screen.
+if (!linkedDocument) shell.setEmptyState(true);
+shell.toast({ status: "success", text: "Link copied" }); // after a share
 ```
 
-The `web` host prevents the browser's page zoom for the chrome keys (outside text fields and
-dialogs), lifts pill and legend above the legal line and fits with the web insets. The rest of the
-web-app chrome (primary action, legal line, File and Appearance groups, toasts, empty state) is not
-part of 0.1.
+The `web` host renders the whole web column of guide §5.2: the primary action at the top right,
+the legal line at the bottom left with pill and legend above it, the File group first and, for a
+dark-capable modeler, the Appearance group in the menu, the problems list above the pill, toasts at
+the bottom centre (announced through two live regions), the start screen and a page-wide drop zone.
+It prevents the browser's page zoom for the chrome keys (outside text fields, modal dialogs and the
+start screen) and fits with the web insets. The web app's
+own menu, zoom, fit, toast, legal and empty-state markup goes away; what stays the modeler's is its
+content: the share link, file reading, examples, the Model and Export entries and the shortcuts
+dialog. See [API.md][api], "Web host (0.2)", and the complete Event Storming example there.
 
 ## Usage in a foreign page
 
@@ -259,8 +323,9 @@ modeler, and the page's `<html>` stays untouched. Until the `@miragon/modeler-ap
 its `appearance` surface (a later 1.x minor), an embedded modeler has no appearance channel, so the
 root carries its own `data-cd-theme` (the first of `themes`, light) and stays light inside a dark
 host page; it takes the page's `data-cd-kontrast="hoch"` over from the nearest mode carrier above
-it. The page's element styles
-(`button { text-transform: uppercase }`) do not reach the chrome.
+it. The page's element styles (`button { text-transform: uppercase }`) do not reach the chrome.
+Toasts show at the bottom centre of the modeler, and the pill opens the problems list unless the
+modeler passes `problems.onActivate` (an embedding host with a list of its own).
 
 ## The conformance kit
 
@@ -269,7 +334,9 @@ the geometry of every island (±1px), ARIA and the keyboard models, that every c
 once and never reaches VS Code, that the canvas's own keys (Cmd/Ctrl+A) stay on the canvas, that
 nothing is ever half-dark (the painted canvas surround and the palette's colours included), that
 Enter on a creating palette entry adds one selected element, that an invalid file locks the canvas,
-and that `destroy()` leaves nothing behind.
+and that `destroy()` leaves nothing behind. Five more cases cover the web column (`webChrome`,
+`emptyState`, `toasts`, `problemsList`, `dropZone`); in the IDE and embedded hosts they assert that
+none of it shows.
 
 For the `ide` host the suite serves a test page that puts a stand-in for VS Code around the
 modeler's webview code: VS Code's default webview styles, `<html>` as `renderWebviewHtml` writes it,
@@ -352,6 +419,60 @@ test.describe("shell conformance", () => {
 });
 ```
 
+A web app's harness opens its page and adds the web column's hooks and the files to drop. The kit
+emulates the system's colour scheme and contrast (`page.emulateMedia`) before every `open`, so the
+page loads without a stored mode choice:
+
+```ts
+// e2e/shell-conformance.spec.ts of a web app
+registerShellConformance(
+  {
+    host: "web",
+    themes: ["light"],
+    absent: ["inspector", "invalid"],
+    async open(page, { size }) {
+      await page.setViewportSize(size);
+      await page.goto("/?example");
+      await page.waitForFunction(() => window.appReady === true);
+    },
+    async destroy(page) {
+      await page.evaluate(() => window.app.destroy());
+    },
+    show: {
+      async legend(page) {
+        /* … */
+      },
+      async problems(page) {
+        /* setProblems with items, so the list has rows */
+      },
+      async status(page) {
+        /* … */
+      },
+      async emptyState(page) {
+        /* the start screen of a fresh visit */
+      },
+      async toast(page, toast) {
+        await page.evaluate(
+          ({ status, text, actionLabel }) =>
+            window.app.shell.toast({
+              status,
+              text,
+              ...(actionLabel ? { action: { label: actionLabel, onSelect() {} } } : {}),
+            }),
+          toast,
+        );
+      },
+    },
+    drop: {
+      accepted: { name: "board.json", type: "application/json", text: EXAMPLE_JSON },
+      rejected: { name: "notes.md", type: "", text: "# Notes" },
+    },
+  },
+  test,
+  { onSkip: failOnSkips },
+);
+```
+
 The harness opens the modeler with the appearance the kit requests, the way its host would; for
 the `embedded` host the kit puts the foreign page itself in that mode. A skip names the harness
 field it misses (`{ hook: "legend", reason }`; `hook: "destroy"` without a `destroy`; `hook: "open"`
@@ -399,23 +520,32 @@ host requests (`theme`, `kontrast=hoch`; embedded: the foreign page's own mode),
 inside the stub of `./testing/vscode-stub`, and keeps view and legend state through
 `acquireVsCodeApi()`.
 
+The web demo (`/web.html`) is the same modeler as a Miragon web app passes it to `mountShell`: the
+whole web column, the head markup of `webHeadMarkup` through the Vite config, and `window.__webDemo`
+for the harness. Its query parameters: `themes=light,dark`, `empty` (the start screen of a fresh
+visit), `legend` (`legend=open`), `inspector`, `problems` (the pill with its list) and `invalid`.
+
 The e2e suite runs the conformance kit for the `ide`, `web` and `embedded` hosts with a light-only
 and a dark-capable modeler, switches VS Code themes and the `colorTheme` setting at runtime, checks
 VS Code's reduce motion, the chrome's typography against VS Code's default styles and a hostile
-foreign page, the canvas slot's paint and focus ring, and proves with saboteurs that every case of
-the kit fails when its rule is broken.
-
-| Directory                   | Module                                                             |
-| --------------------------- | ------------------------------------------------------------------ |
-| `src/core`                  | DOM-free: fit math, keymap, zoom readout, appearance, sizes, texts |
-| `src/dom`                   | `mountShell`: menu, zoom panel, tooltip, pill, status, slots, keys |
-| `src/diagram-js`            | `shellModule`, viewport, `connectDiagramJs`, palette skin          |
-| `src/vscode`                | extension side (HTML, theme bridge) and webview side               |
-| `src/testing`               | the Playwright-driven conformance kit and the VS Code stub         |
-| `src/*.ts`, `src/shell.css` | the entry points                                                   |
-| `test/`                     | package boundaries, token drift, the unit tests' helpers           |
-| `demo/`, `e2e/`             | the demo modeler and the e2e suite                                 |
-| `fixtures/tokens`           | the token files, vendored unchanged for the tests and the demo     |
+foreign page, the canvas slot's paint and focus ring, the web chrome's colours, radii and states
+(primary action, legal line, toasts, drop zone, empty state, high contrast and forced colours) and
+the web demo's own handlers, and proves with saboteurs that every case of the kit fails when its
+rule is broken.
+
+| Directory                               | Module                                                                                     |
+| --------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `src/core`                              | DOM-free: fit math, keymap, zoom readout, appearance, sizes, texts                         |
+| `src/dom`                               | `mountShell`: menu, zoom panel, tooltip, pill, status, slots, keys                         |
+| `src/dom/web`, `src/core/web-chrome`    | web column: primary action, legal line, File and Appearance groups, empty state, drop zone |
+| `src/dom/feedback`, `src/core/feedback` | toasts, problems popover, the web app's mode                                               |
+| `src/diagram-js`                        | `shellModule`, viewport, `connectDiagramJs`, palette skin                                  |
+| `src/vscode`                            | extension side (HTML, theme bridge) and webview side                                       |
+| `src/testing`                           | the Playwright-driven conformance kit and the VS Code stub                                 |
+| `src/*.ts`, `src/shell.css`             | the entry points                                                                           |
+| `test/`                                 | package boundaries, token drift, the unit tests' helpers                                   |
+| `demo/`, `e2e/`                         | the demo modeler and the e2e suite                                                         |
+| `fixtures/tokens`                       | the token files, vendored unchanged for the tests and the demo                             |
 
 A module imports another one only through its `index.ts`; `src/core` imports nothing outside
 itself and compiles without the DOM library. `test/package-boundaries.test.ts` enforces this, the
@@ -429,7 +559,8 @@ MIT. The inlined Lucide icons are ISC (© Lucide Icons and Contributors), and `c
 Lucide's LICENSE lists them; see [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). `dist` keeps that
 notice as a legal comment in the chunk with the icons, but a bundler's `legalComments` setting may
 drop it: a VSIX or a web bundle that contains the shell carries the Lucide and Feather notices of
-THIRD_PARTY_NOTICES.md itself.
+THIRD_PARTY_NOTICES.md itself. Vite 8 (Rolldown with the Oxc minifier) drops legal comments by
+default; `build.rolldownOptions.output.comments.legal: true` keeps the notice in the bundle.
 
 [guide]: https://github.com/Miragon/corporate-identity/blob/main/plugins/miragon-brand/skills/modeler-tool-design/assets/modeler-design-system.md
 [notes]: https://github.com/Miragon/modeler-api/blob/main/docs/shell/implementation-notes.md

package/dist/appearance-BBaM_4bD.d.ts

@@ -0,0 +1,323 @@
+import { d as ShellHost } from './toasts-Bp0REqdq.js';
+import { T as Theme } from './appearance-D3FUcbu6.js';
+
+/** The severity of one problem; the pill and the list show `circle-x` or `triangle-alert` (guide §5.10). */
+type ProblemSeverity = "error" | "warning";
+/** One row of the web app's problems list (guide §5.10). */
+interface ProblemItem {
+    severity: ProblemSeverity;
+    /** 13px `--cd-ui-text`: "Unknown sticky type “evnt”." */
+    message: string;
+    /** The place in 13px `--cd-ui-text-leise` below the message: "Line 12", "“Order Placed”". */
+    location?: string | undefined;
+    /** The diagram element a click on the row selects (`ProblemsOptions.onSelectItem`). */
+    elementId?: string | undefined;
+}
+/** `ShellHandle.setProblems` input built from the items: count, errors and the items themselves. */
+declare function problemSummary(items: readonly ProblemItem[]): {
+    count: number;
+    errors: number;
+    items: readonly ProblemItem[];
+};
+
+/** Why a drag cannot be dropped (guide §9 Drop forbidden); `messages.dropForbidden` words each one. */
+type DropForbiddenReason = "multiple" | "type" | "dialog";
+/** One entry of `DataTransfer.items` as a drag shows it (names are not readable before the drop). */
+interface DragItemLike {
+    kind: string;
+    type: string;
+}
+interface DragContext {
+    /** `DropZoneOptions.accept`: extensions (".storm") and MIME types ("application/json", "text/*"). */
+    accept: readonly string[];
+    /** `DropZoneOptions.multiple`. */
+    multiple: boolean;
+    /** A modal dialog is open (the shell's dialog test, as for the keys). */
+    dialogOpen: boolean;
+}
+/** What the drop zone shows for the drag over the page right now (guide §9). */
+type DragVerdict = {
+    state: "none";
+} | {
+    state: "over";
+} | {
+    state: "forbidden";
+    reason: DropForbiddenReason;
+};
+/**
+ * The drop zone's state for a drag (guide §9, Drag-over and Drop forbidden):
+ *
+ * - `none`: no item of kind `file` (a palette drag, selected text): the drop zone stays out of it.
+ * - `forbidden` / `dialog`: a modal dialog is open.
+ * - `forbidden` / `multiple`: more than one file and `multiple` is false.
+ * - `forbidden` / `type`: `accept` lists at least one MIME type and every file item carries a
+ *   non-empty type that none of them matches (`type/*` wildcards included). Extensions cannot be
+ *   checked before the drop, and an empty type (".storm" has none) never forbids.
+ * - `over` otherwise.
+ */
+declare function dragVerdict(items: readonly DragItemLike[], context: DragContext): DragVerdict;
+/**
+ * A dropped file matches `accept` like `<input accept>`: an entry starting with "." matches the
+ * end of the name (case-insensitive), an entry with "/" the MIME type exactly or as `type/*`; an
+ * empty `accept` matches every file.
+ */
+declare function acceptsFile(file: {
+    name: string;
+    type: string;
+}, accept: readonly string[]): boolean;
+
+/**
+ * Every text the shell shows or announces, in one table (guide §2, shared terms). English by
+ * default; a localized modeler overrides the whole table in its language, numbers arrive already
+ * formatted through `Intl` in that language.
+ */
+interface ShellMessages {
+    /** Menu trigger `aria-label` and tooltip, dropdown `aria-label`. */
+    menu: string;
+    /** Palette `aria-label`. */
+    tools: string;
+    /** `aria-label` of the focusable canvas `<svg>` (`role="application"`); a modeler names its notation. */
+    canvas: string;
+    /** Zoom panel `aria-label`. */
+    zoom: string;
+    zoomOut: string;
+    zoomIn: string;
+    /** Tooltip of the readout, e.g. `(percent) => "Zoom to " + percent` with percent "100%". */
+    zoomToActual(percent: string): string;
+    /** `aria-label` of the readout: "Zoom to 100% (now 86%)". */
+    zoomToActualNow(percent: string, now: string): string;
+    fit: string;
+    /** Legend title and the Model-group checkbox. */
+    legend: string;
+    closeLegend: string;
+    /** Pill text: "1 problem", "2 problems". */
+    problems(count: number, formattedCount: string): string;
+    /** Pill `aria-label`: "2 problems, 1 error", "2 problems, no errors". */
+    problemsLabel(count: number, errors: number, formattedCount: string, formattedErrors: string): string;
+    /** Pill tooltip in the IDE host. */
+    showProblems: string;
+    /** Empty-file hint (guide §13.5). */
+    emptyHint: string;
+    insertExample: string;
+    /** Status box for an invalid file; `diagram` names the notation ("Event Storming board"). */
+    invalidFile(diagram: string): string;
+    /** Key names in shortcut chips outside macOS (German: Strg, Umschalt, Plus, Minus). */
+    keyNames: {
+        ctrl: string;
+        shift: string;
+        plus: string;
+        minus: string;
+    };
+    /** Default label and `aria-label` of the primary action (web app, top right). */
+    share: string;
+    /** `aria-label` of the legal line's `<nav>`. "Impressum" and "Datenschutz" are never translated (guide §2). */
+    legal: string;
+    /** First entry of the legal line, linking the Miragon home page: "© 2026 Miragon GmbH". */
+    copyright(year: number): string;
+    /** The description of every legal link for screen readers: they open in a new tab. */
+    opensInNewTab: string;
+    /** File group (web app) and the empty state's primary button. */
+    newDiagram: string;
+    /** File group: "Open…" (U+2026, it opens the browser's file dialog). */
+    openFile: string;
+    /** File group and the empty state's ghost button. */
+    showExample: string;
+    /** File group: "Import…". */
+    importFile: string;
+    /** Heading and `aria-label` of the Appearance radio group (web app with dark only, guide §13.3). */
+    appearance: string;
+    appearanceSystem: string;
+    appearanceLight: string;
+    appearanceDark: string;
+    /** Title of the problems popover (web app). */
+    problemsTitle: string;
+    /** A row's severity for screen readers, the `aria-label` of its icon: "Error", "Warning". */
+    problemSeverity(severity: ProblemSeverity): string;
+    /** `aria-label` of a Close button (toasts). */
+    close: string;
+    /** Chip of the drop zone while a drag can be dropped (guide §9 Drag-over). */
+    dropFile: string;
+    /** Chip of the drop zone while the drag cannot be dropped (guide §9 Drop forbidden). */
+    dropForbidden(reason: DropForbiddenReason): string;
+    /** The empty state's drag-and-drop hint when the modeler has a drop zone. */
+    dropHint: string;
+    /** The text link after the empty state's hint that runs the File group's "Open…". */
+    openFileLink: string;
+    /**
+     * Danger toast for a dropped file outside `DropZoneOptions.accept`; `accepted` is the accept list
+     * joined by `Intl.ListFormat` (disjunction) in `lang`: ".storm, .json, or .txt".
+     */
+    cannotOpenFile(name: string, accepted: string): string;
+}
+/** Every key optional; an `undefined` value keeps the default (a conditional override). */
+type ShellMessageOverrides = {
+    [Key in Exclude<keyof ShellMessages, "keyNames">]?: ShellMessages[Key] | undefined;
+} & {
+    keyNames?: {
+        [Key in keyof ShellMessages["keyNames"]]?: string | undefined;
+    } | undefined;
+};
+declare const defaultMessages: ShellMessages;
+/** `defaultMessages` with `overrides` applied (`keyNames` merged key by key). */
+declare function resolveMessages(overrides?: ShellMessageOverrides | undefined): ShellMessages;
+
+/** The only keys the chrome handles (guide §5.8). */
+type ChromeKey = "zoomIn" | "zoomOut" | "zoomToActual" | "fit";
+/** The `KeyboardEvent` fields the keymap reads. */
+interface KeyLike {
+    key: string;
+    code: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    isComposing?: boolean | undefined;
+}
+/**
+ * Which chrome key `event` is, ignoring where it was pressed:
+ * - `zoomIn`: Cmd/Ctrl + `+` or `=` (by `key`, with or without Shift), or `NumpadAdd` (by `code`);
+ * - `zoomOut`: Cmd/Ctrl + `-` or `_`, or `NumpadSubtract`;
+ * - `zoomToActual`: Cmd/Ctrl + `0`, or `Numpad0` (also with NumLock off);
+ * - `fit`: Shift + `Digit1` (by `code`, every layout) without Cmd, Ctrl or Alt.
+ * Cmd/Ctrl is `metaKey || ctrlKey` on every platform; nothing matches with `altKey` (AltGr).
+ */
+declare function matchChromeKey(event: KeyLike): ChromeKey | undefined;
+/**
+ * Cmd/Ctrl + Z, Cmd/Ctrl + Shift + Z or Cmd/Ctrl + Y, without Alt (by `key`, `code` as fallback).
+ * Cmd/Ctrl + Shift + Y is not redo (VS Code toggles its Debug Console with it).
+ */
+declare function isUndoRedoKey(event: KeyLike): boolean;
+/** A text field: every input, select list and editable text (label editor, inspector, dialogs). */
+declare const TEXT_FIELD_SELECTOR = "input, textarea, select, [contenteditable]:not([contenteditable='false'])";
+/** Where a key was pressed, as the shell's one `keydown` listener sees it. */
+interface KeyContext {
+    host: ShellHost;
+    /** The event target matches `TEXT_FIELD_SELECTOR` or is `isContentEditable`. */
+    inTextField: boolean;
+    /** The shell's menu dropdown is open. */
+    menuOpen: boolean;
+    /** A popover or dialog (`[role="dialog"]`, modal or not) is open. */
+    dialogOpen: boolean;
+    /** A modal dialog (`[role="dialog"][aria-modal="true"]`) is open: chrome keys do not act. */
+    modalOpen: boolean;
+    /** `event.defaultPrevented` when the listener ran: the canvas (or the modeler) handled the key. */
+    defaultPrevented: boolean;
+    /**
+     * The web app's start screen shows (`setEmptyState(true)`): there is no diagram to zoom, so the
+     * zoom keys and Shift+1 are left to the browser, which zooms the page.
+     */
+    startScreen?: boolean | undefined;
+}
+type KeyAction = ChromeKey | "closeMenu";
+interface KeyDecision {
+    /** What the shell executes; `undefined` = nothing. */
+    action?: KeyAction;
+    preventDefault: boolean;
+    stopPropagation: boolean;
+}
+/**
+ * The key rules of guide §5.8 and §13.5 in one place:
+ * 1. Escape with the menu open: `closeMenu`, prevented; in the IDE host stopped whenever the menu
+ *    or a dialog/popover is open. During IME composition Escape belongs to the IME: no `closeMenu`.
+ * 2. Zoom keys: executed and prevented unless composing, in a text field or with a modal dialog;
+ *    in the IDE host always stopped, also when not executed (VS Code must never zoom the window).
+ *    Behind the web app's start screen untouched: the browser zooms the page (WCAG 1.4.4).
+ * 3. Shift+1: `fit` under the same conditions; otherwise untouched (it types "!").
+ * 4. IDE host, text field, undo/redo key: stopped only (the field keeps its native undo).
+ * 5. IDE host, `defaultPrevented`: stopped (the canvas handled it; VS Code must not run it again).
+ * Everything else passes untouched. `stopPropagation` is only ever true in the IDE host.
+ */
+declare function decideKey(event: KeyLike, context: KeyContext): KeyDecision;
+/** The keyboard the user sits at; decides the shortcut labels (guide §5.8). */
+type Platform = "mac" | "other";
+/** The `navigator` fields `detectPlatform` reads. */
+interface NavigatorLike {
+    platform?: string | undefined;
+    userAgentData?: {
+        platform?: string | undefined;
+    } | undefined;
+}
+/**
+ * `mac` when `userAgentData.platform ?? platform` matches `/mac/i`, else `other`; `other` without a
+ * navigator. Read it in the webview or page itself, never from the extension host (VS Code Remote).
+ */
+declare function detectPlatform(navigator?: NavigatorLike | undefined): Platform;
+/**
+ * The tooltip chip text: macOS `⌘+`, `⌘−` (U+2212), `⌘0`, `⇧1`; elsewhere `Ctrl+Plus`,
+ * `Ctrl+Minus`, `Ctrl+0`, `Shift+1` with the key names of the messages table.
+ */
+declare function shortcutLabel(key: ChromeKey, platform: Platform, keyNames: ShellMessages["keyNames"]): string;
+/**
+ * The chip of a Cmd/Ctrl key a modeler binds itself (the web app's File entries, guide §5.4): macOS
+ * `⌘O`, elsewhere `Ctrl+O` with the key name of the messages table (`Strg+O`). `key` as printed on
+ * the key cap; pass the result to `FileMenuAction.shortcut` or `MenuActionEntry.shortcut`.
+ */
+declare function commandKeyLabel(key: string, platform: Platform, keyNames: Pick<ShellMessages["keyNames"], "ctrl">): string;
+/**
+ * The `aria-keyshortcuts` value (WAI-ARIA names): zoom in `Meta+= Meta+Plus`, zoom out `Meta+-`,
+ * 100 % `Meta+0`, fit `Shift+1`; outside macOS `Control` instead of `Meta`.
+ */
+declare function ariaKeyShortcuts(key: ChromeKey, platform: Platform): string;
+/**
+ * The `aria-keyshortcuts` value (WAI-ARIA names, guide §5.6) for a shortcut chip label: `"L"` →
+ * `"L"`, `"⇧L"` → `"Shift+L"`, `"⌘⇧Z"` → `"Meta+Shift+Z"`, `"Ctrl+Shift+E"` → `"Control+Shift+E"`,
+ * `"Del"` → `"Delete"`, `"Ctrl++"` → `"Control+Plus"`. `undefined` for a label that is not one key
+ * combination (`"G then D"`, `"1–9"`, empty).
+ */
+declare function ariaKeyShortcutsFromLabel(label: string): string | undefined;
+
+/** The web app's mode choice (guide §13.3): Appearance, System · Light · Dark. */
+type AppearanceChoice = "system" | "light" | "dark";
+/** Where the web app keeps the choice: `light` or `dark`; "System" removes the entry (guide §13.3). */
+declare const APPEARANCE_STORAGE_KEY = "miragon.darstellung";
+/**
+ * The two `theme-color` values (guide §11, §13.3): light is the app's own value (`#335DE5`, `fest`
+ * `--cd-blau` of the vendored `cd-tokens.generated.json`), dark `#1D1D1D` (`dunkel`
+ * `--cd-ui-grund`). The modeler reads both from its vendored JSON; the shell keeps no colour.
+ */
+interface ThemeColors {
+    light: string;
+    dark: string;
+}
+/** `"light"` and `"dark"` pass, everything else (a missing entry, a foreign value) is `"system"`. */
+declare function parseAppearanceChoice(stored: unknown): AppearanceChoice;
+/** What `<html>` and the meta tags carry for a choice. */
+interface DocumentMode {
+    /** `data-cd-theme` on `<html>`. */
+    theme: "system" | Theme;
+    /** `<meta name="color-scheme" content>`. */
+    colorScheme: "light dark" | Theme;
+    /** The `content` of the `theme-color` metas with `media="(prefers-color-scheme: light|dark)"`. */
+    themeColor: ThemeColors;
+}
+/**
+ * The document mode for `choice` (guide §13.3). A modeler that cannot show dark (`themes` without
+ * `"dark"`) is `light` whatever the choice: theme `light`, color-scheme `light`, both theme
+ * colours `colors.light`. Dark-capable: `system` → theme `system`, color-scheme `light dark`,
+ * `colors` as they are; `light`/`dark` → that theme and color-scheme, both theme colours the
+ * chosen mode's, so the browser bar matches a fixed choice under the other system mode.
+ */
+declare function documentMode(choice: AppearanceChoice, themes: readonly Theme[], colors: ThemeColors): DocumentMode;
+interface WebModeScriptOptions {
+    /** The modes the modeler can show, as passed to `mountShell`. */
+    themes: readonly Theme[];
+    themeColors: ThemeColors;
+}
+/**
+ * The body of the inline `<script>` in `<head>`, before the first stylesheet (guide §13.3). With
+ * `themes` including `"dark"`: the guide's script, which reads `APPEARANCE_STORAGE_KEY` inside
+ * `try`/`catch`, writes `data-cd-theme`, `color-scheme` and both `theme-color` metas for a fixed
+ * choice and sets `data-cd-kontrast="hoch"` under `(prefers-contrast: more)`. Light-only: the
+ * contrast line alone. Plain ES5 without the modeler's bundle, so it runs before the first paint.
+ */
+declare function webModeScript(options: WebModeScriptOptions): string;
+/**
+ * The `<head>` markup the web app's `index.html` carries for its mode, as one string (for a Vite
+ * `transformIndexHtml` hook or to paste): dark-capable `<meta name="color-scheme" content="light
+ * dark">`, two `theme-color` metas with `media` and the script; light-only one `theme-color`
+ * without `media` and the contrast script. `<html>` itself carries `lang` and
+ * `data-cd-theme="<documentMode("system", themes, colors).theme>"` statically.
+ */
+declare function webHeadMarkup(options: WebModeScriptOptions): string;
+
+export { APPEARANCE_STORAGE_KEY as A, shortcutLabel as B, type ChromeKey as C, type DocumentMode as D, webHeadMarkup as E, webModeScript as F, type KeyAction as K, type NavigatorLike as N, type Platform as P, type ShellMessageOverrides as S, TEXT_FIELD_SELECTOR as T, type WebModeScriptOptions as W, type AppearanceChoice as a, type DragContext as b, type DragItemLike as c, type DragVerdict as d, type DropForbiddenReason as e, type KeyContext as f, type KeyDecision as g, type KeyLike as h, type ProblemItem as i, type ProblemSeverity as j, type ShellMessages as k, type ThemeColors as l, acceptsFile as m, ariaKeyShortcuts as n, ariaKeyShortcutsFromLabel as o, commandKeyLabel as p, decideKey as q, defaultMessages as r, detectPlatform as s, documentMode as t, dragVerdict as u, isUndoRedoKey as v, matchChromeKey as w, parseAppearanceChoice as x, problemSummary as y, resolveMessages as z };