@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/src/core/index.ts

@@ -0,0 +1,127 @@
+export type {
+  Bounds,
+  ChromeIsland,
+  Insets,
+  PaletteRow,
+  Point,
+  ScaledViewbox,
+  ShellHost,
+  Size,
+  ViewportState,
+  ZoomTarget,
+} from "./types.js";
+export { CHROME_ISLANDS } from "./types.js";
+
+export type { ShellSizeName, ShellSizes } from "./sizes.js";
+export { SHELL, SHELL_TOKENS, shellSizesFromTokens } from "./sizes.js";
+
+export type { FitLayout } from "./fit.js";
+export {
+  FIT_ANIMATION_MS,
+  MAX_FIT_ZOOM,
+  VIEW_TOLERANCE,
+  easeStandard,
+  fitInsets,
+  fitViewbox,
+  freeRectCenter,
+  interpolateViewbox,
+  sameView,
+} from "./fit.js";
+
+export type { ZoomReadout } from "./zoom.js";
+export {
+  ZOOM_MAX,
+  ZOOM_MIN,
+  canZoomIn,
+  canZoomOut,
+  formatNumber,
+  formatPercent,
+  zoomReadout,
+} from "./zoom.js";
+
+export type {
+  ChromeKey,
+  KeyAction,
+  KeyContext,
+  KeyDecision,
+  KeyLike,
+  NavigatorLike,
+  Platform,
+} from "./keymap.js";
+export {
+  TEXT_FIELD_SELECTOR,
+  ariaKeyShortcuts,
+  ariaKeyShortcutsFromLabel,
+  commandKeyLabel,
+  decideKey,
+  detectPlatform,
+  isUndoRedoKey,
+  matchChromeKey,
+  shortcutLabel,
+} from "./keymap.js";
+
+export type { Appearance, AppearanceAttributes, ColorThemeSetting, Kontrast, Theme } from "./appearance.js";
+export {
+  REDUCED_MOTION_CLASS,
+  appearanceAttributes,
+  appearanceFromBodyClasses,
+  appearanceFromColorThemeKind,
+  reducedMotionFromBodyClasses,
+  requestedAppearance,
+  resolveAppearance,
+} from "./appearance.js";
+
+export type { ShellMessageOverrides, ShellMessages } from "./messages.js";
+export { defaultMessages, resolveMessages } from "./messages.js";
+
+export type { PaletteRowInput, TooltipPlacementInput } from "./layout.js";
+export {
+  INVALID_STATUS_DELAY_MS,
+  PALETTE_CLEARANCE,
+  TOOLTIP_DELAY_MS,
+  decidePaletteRow,
+  legendStartsOpen,
+  placeTooltip,
+} from "./layout.js";
+
+// ---- Web host (0.2) ----
+
+export type { PrimaryWidths, TopRow, TopRowInput } from "./web-chrome/top-row.js";
+export { decideTopRow } from "./web-chrome/top-row.js";
+export type { BottomRowInput } from "./web-chrome/bottom-row.js";
+export { LEGAL_LINE_HEIGHT, legalLineHeight, zoomRowRaised } from "./web-chrome/bottom-row.js";
+export type { DragContext, DragItemLike, DragVerdict, DropForbiddenReason } from "./web-chrome/drop.js";
+export { acceptsFile, dragVerdict } from "./web-chrome/drop.js";
+
+export type {
+  BottomObstacle,
+  ToastAction,
+  ToastRequest,
+  ToastSlot,
+  ToastStackInput,
+  ToastStatus,
+} from "./feedback/toasts.js";
+export {
+  MAX_TOASTS,
+  TOAST_DURATION_MS,
+  TOAST_MAX_WIDTH,
+  toastLifetime,
+  toastStackBottom,
+  toastStackWidth,
+  toastToEvict,
+} from "./feedback/toasts.js";
+export type {
+  AppearanceChoice,
+  DocumentMode,
+  ThemeColors,
+  WebModeScriptOptions,
+} from "./feedback/appearance.js";
+export {
+  APPEARANCE_STORAGE_KEY,
+  documentMode,
+  parseAppearanceChoice,
+  webHeadMarkup,
+  webModeScript,
+} from "./feedback/appearance.js";
+export type { ProblemItem, ProblemSeverity } from "./feedback/problems.js";
+export { problemSummary } from "./feedback/problems.js";

package/src/core/keymap.ts

@@ -0,0 +1,295 @@
+import type { ShellMessages } from "./messages.js";
+import type { ShellHost } from "./types.js";
+
+/** The only keys the chrome handles (guide §5.8). */
+export type ChromeKey = "zoomIn" | "zoomOut" | "zoomToActual" | "fit";
+
+/** The `KeyboardEvent` fields the keymap reads. */
+export 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).
+ */
+export function matchChromeKey(event: KeyLike): ChromeKey | undefined {
+  if (event.altKey) return undefined;
+  if (isCommand(event)) {
+    if (event.key === "+" || event.key === "=" || event.code === "NumpadAdd") return "zoomIn";
+    if (event.key === "-" || event.key === "_" || event.code === "NumpadSubtract") return "zoomOut";
+    if (event.key === "0" || event.code === "Numpad0") return "zoomToActual";
+    return undefined;
+  }
+  return event.shiftKey && event.code === "Digit1" ? "fit" : undefined;
+}
+
+function isCommand(event: KeyLike): boolean {
+  return event.metaKey || event.ctrlKey;
+}
+
+/**
+ * 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).
+ */
+export function isUndoRedoKey(event: KeyLike): boolean {
+  if (event.altKey || !isCommand(event)) return false;
+  const letter = undoRedoLetter(event);
+  return letter === "z" || (letter === "y" && !event.shiftKey);
+}
+
+// The produced character decides on Latin layouts (QWERTZ swaps the Y and Z keys); only where the
+// layout produces no ASCII character (Cyrillic, Greek, …) the physical key stands in.
+function undoRedoLetter(event: KeyLike): string | undefined {
+  if (event.key.length === 1 && event.key.charCodeAt(0) < 0x80) return event.key.toLowerCase();
+  if (event.code === "KeyZ") return "z";
+  if (event.code === "KeyY") return "y";
+  return undefined;
+}
+
+/** A text field: every input, select list and editable text (label editor, inspector, dialogs). */
+export 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. */
+export 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;
+}
+
+export type KeyAction = ChromeKey | "closeMenu";
+
+export 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.
+ */
+export function decideKey(event: KeyLike, context: KeyContext): KeyDecision {
+  const stop = context.host === "ide";
+  const composing = event.isComposing === true;
+
+  if (event.key === "Escape" && !event.metaKey && !event.ctrlKey && !event.altKey && !event.shiftKey) {
+    if (context.menuOpen && !composing) {
+      return { action: "closeMenu", preventDefault: true, stopPropagation: stop };
+    }
+    if (context.menuOpen || context.dialogOpen) return { preventDefault: false, stopPropagation: stop };
+  }
+
+  const chromeKey = matchChromeKey(event);
+  if (chromeKey !== undefined) {
+    if (context.startScreen === true && !stop) return { preventDefault: false, stopPropagation: false };
+    const blocked = composing || context.inTextField || context.modalOpen;
+    if (!blocked) return { action: chromeKey, preventDefault: true, stopPropagation: stop };
+    // Blocked zoom keys are still kept from VS Code (it would zoom the window); a blocked Shift+1
+    // is a character and travels on like any other.
+    return { preventDefault: false, stopPropagation: chromeKey === "fit" ? false : stop };
+  }
+
+  if (context.inTextField && isUndoRedoKey(event)) return { preventDefault: false, stopPropagation: stop };
+  if (context.defaultPrevented) return { preventDefault: false, stopPropagation: stop };
+  return { preventDefault: false, stopPropagation: false };
+}
+
+/** The keyboard the user sits at; decides the shortcut labels (guide §5.8). */
+export type Platform = "mac" | "other";
+
+/** The `navigator` fields `detectPlatform` reads. */
+export 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).
+ */
+export function detectPlatform(navigator?: NavigatorLike | undefined): Platform {
+  // An empty userAgentData.platform means "unknown", not "not a Mac": fall back to navigator.platform.
+  const platform = navigator?.userAgentData?.platform || navigator?.platform || "";
+  return /mac/i.test(platform) ? "mac" : "other";
+}
+
+/**
+ * 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.
+ */
+export function shortcutLabel(
+  key: ChromeKey,
+  platform: Platform,
+  keyNames: ShellMessages["keyNames"],
+): string {
+  if (platform === "mac") return MAC_SHORTCUT_LABELS[key];
+  switch (key) {
+    case "zoomIn":
+      return `${keyNames.ctrl}+${keyNames.plus}`;
+    case "zoomOut":
+      return `${keyNames.ctrl}+${keyNames.minus}`;
+    case "zoomToActual":
+      return `${keyNames.ctrl}+0`;
+    case "fit":
+      return `${keyNames.shift}+1`;
+  }
+}
+
+/**
+ * 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`.
+ */
+export function commandKeyLabel(
+  key: string,
+  platform: Platform,
+  keyNames: Pick<ShellMessages["keyNames"], "ctrl">,
+): string {
+  return platform === "mac" ? `⌘${key}` : `${keyNames.ctrl}+${key}`;
+}
+
+const MAC_SHORTCUT_LABELS: Readonly<Record<ChromeKey, string>> = {
+  zoomIn: "⌘+",
+  zoomOut: "⌘\u2212",
+  zoomToActual: "⌘0",
+  fit: "⇧1",
+};
+
+/**
+ * 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`.
+ */
+export function ariaKeyShortcuts(key: ChromeKey, platform: Platform): string {
+  const command = platform === "mac" ? "Meta" : "Control";
+  switch (key) {
+    case "zoomIn":
+      return `${command}+= ${command}+Plus`;
+    case "zoomOut":
+      return `${command}+-`;
+    case "zoomToActual":
+      return `${command}+0`;
+    case "fit":
+      return "Shift+1";
+  }
+}
+
+const MAC_MODIFIER_SYMBOLS: Readonly<Record<string, string>> = {
+  "⌘": "Meta",
+  "⇧": "Shift",
+  "⌥": "Alt",
+  "⌃": "Control",
+};
+
+const MODIFIER_NAMES: Readonly<Record<string, string>> = {
+  cmd: "Meta",
+  command: "Meta",
+  meta: "Meta",
+  ctrl: "Control",
+  control: "Control",
+  strg: "Control",
+  shift: "Shift",
+  umschalt: "Shift",
+  alt: "Alt",
+  option: "Alt",
+  opt: "Alt",
+};
+
+const NAMED_KEYS: Readonly<Record<string, string>> = {
+  esc: "Escape",
+  escape: "Escape",
+  del: "Delete",
+  delete: "Delete",
+  entf: "Delete",
+  backspace: "Backspace",
+  enter: "Enter",
+  return: "Enter",
+  tab: "Tab",
+  space: "Space",
+  home: "Home",
+  end: "End",
+  pageup: "PageUp",
+  pagedown: "PageDown",
+  arrowup: "ArrowUp",
+  arrowdown: "ArrowDown",
+  arrowleft: "ArrowLeft",
+  arrowright: "ArrowRight",
+  "↑": "ArrowUp",
+  "↓": "ArrowDown",
+  "←": "ArrowLeft",
+  "→": "ArrowRight",
+  plus: "Plus",
+};
+
+function ariaKeyName(key: string): string | undefined {
+  const named = NAMED_KEYS[key.toLowerCase()];
+  if (named) return named;
+  if (/^f\d{1,2}$/i.test(key)) return key.toUpperCase();
+  if (key.length !== 1 || MAC_MODIFIER_SYMBOLS[key]) return undefined;
+  if (key === "+") return "Plus";
+  if (key === " ") return "Space";
+  return key.toUpperCase();
+}
+
+/**
+ * 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).
+ */
+export function ariaKeyShortcutsFromLabel(label: string): string | undefined {
+  let rest = label.trim();
+  const modifiers: string[] = [];
+  for (let symbol = MAC_MODIFIER_SYMBOLS[rest.charAt(0)]; symbol && rest.length > 1;) {
+    modifiers.push(symbol);
+    rest = rest.slice(1).trim();
+    symbol = MAC_MODIFIER_SYMBOLS[rest.charAt(0)];
+  }
+  if (!rest || /\s/.test(rest.replace(/\s*\+\s*/g, "+"))) return undefined;
+  const parts = rest.split("+").map((part) => part.trim());
+  let key = parts.pop() ?? "";
+  if (key === "" && parts.at(-1) === "") {
+    parts.pop();
+    key = "+";
+  }
+  for (const part of parts) {
+    const modifier = MODIFIER_NAMES[part.toLowerCase()];
+    if (!modifier) return undefined;
+    modifiers.push(modifier);
+  }
+  const name = ariaKeyName(key);
+  return name ? [...new Set(modifiers), name].join("+") : undefined;
+}

package/src/core/layout.ts

@@ -0,0 +1,69 @@
+import { SHELL } from "./sizes.js";
+import type { Bounds, PaletteRow, Point, Size } from "./types.js";
+
+/** Free space the top row needs between the palette and a neighbouring island (guide §5.15). */
+export const PALETTE_CLEARANCE = 16;
+
+/** Hover delay of the chrome tooltip, equal to diagram-js `HoverTooltip` `SHOW_DELAY`. */
+export const TOOLTIP_DELAY_MS = 300;
+
+/** The status box for an invalid file shows after this long without a valid import (guide §5.12). */
+export const INVALID_STATUS_DELAY_MS = 800;
+
+export interface PaletteRowInput {
+  containerWidth: number;
+  /**
+   * The palette's intrinsic border-box width (`scrollWidth` plus its borders), so the decision does
+   * not flip once the second row clips it.
+   */
+  paletteWidth: number;
+  /** Right edge of the menu trigger, relative to the shell root. */
+  menuRight: number;
+  /** Left edge of the primary action (web app), relative to the shell root; absent in IDE hosts. */
+  primaryLeft?: number | undefined;
+}
+
+/**
+ * `second-row` when the container is at most `SHELL.narrow` wide or a centred palette would keep
+ * less than `PALETTE_CLEARANCE` to the menu trigger (or the primary action); `top` otherwise.
+ */
+export function decidePaletteRow(input: PaletteRowInput): PaletteRow {
+  const { containerWidth, paletteWidth, menuRight, primaryLeft } = input;
+  if (containerWidth <= SHELL.narrow) return "second-row";
+  const paletteLeft = (containerWidth - paletteWidth) / 2;
+  const paletteRight = (containerWidth + paletteWidth) / 2;
+  if (paletteLeft < menuRight + PALETTE_CLEARANCE) return "second-row";
+  if (primaryLeft !== undefined && paletteRight > primaryLeft - PALETTE_CLEARANCE) return "second-row";
+  return "top";
+}
+
+/** The legend starts open unless the container is at most `SHELL.low` high (guide §5.10). */
+export function legendStartsOpen(containerHeight: number): boolean {
+  return containerHeight > SHELL.low;
+}
+
+export interface TooltipPlacementInput {
+  /** The hovered or focused control, relative to the shell root (horizontal centre). */
+  anchor: Bounds;
+  /** The island the control sits in, relative to the shell root (vertical placement). */
+  island: Bounds;
+  tooltip: Size;
+  container: Size;
+}
+
+/**
+ * The tooltip's top-left corner relative to the shell root (guide §5.6): below an island in the
+ * upper half (`island.bottom + 8`: top row 60, second row 112), above one in the lower half
+ * (`island.top − 8 − height`: bottom row ends at `bottom: 60px`); centred on the anchor, shifted to
+ * keep `SHELL.edge` to the container's sides.
+ */
+export function placeTooltip(input: TooltipPlacementInput): Point {
+  const { anchor, island, tooltip, container } = input;
+  const inUpperHalf = island.y + island.height / 2 < container.height / 2;
+  const y = inUpperHalf ? island.y + island.height + SHELL.gap : island.y - SHELL.gap - tooltip.height;
+  const centred = anchor.x + anchor.width / 2 - tooltip.width / 2;
+  const rightmost = container.width - SHELL.edge - tooltip.width;
+  // In a container narrower than the tooltip plus both edges, the left edge wins.
+  const x = Math.max(SHELL.edge, Math.min(centred, rightmost));
+  return { x, y };
+}

package/src/core/messages.ts

@@ -0,0 +1,159 @@
+import type { ProblemSeverity } from "./feedback/problems.js";
+import type { DropForbiddenReason } from "./web-chrome/drop.js";
+
+/**
+ * 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.
+ */
+export 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 };
+
+  // ---- Web host (0.2): guide §2 shared terms, §5.4, §5.7, §5.10, §8, §9 ----
+
+  /** 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). */
+export type ShellMessageOverrides = {
+  [Key in Exclude<keyof ShellMessages, "keyNames">]?: ShellMessages[Key] | undefined;
+} & {
+  keyNames?: { [Key in keyof ShellMessages["keyNames"]]?: string | undefined } | undefined;
+};
+
+export const defaultMessages: ShellMessages = {
+  menu: "Menu",
+  tools: "Tools",
+  canvas: "Diagram",
+  zoom: "Zoom",
+  zoomOut: "Zoom out",
+  zoomIn: "Zoom in",
+  zoomToActual: (percent) => `Zoom to ${percent}`,
+  zoomToActualNow: (percent, now) => `Zoom to ${percent} (now ${now})`,
+  fit: "Fit to view",
+  legend: "Legend",
+  closeLegend: "Close legend",
+  problems: (count, formattedCount) => `${formattedCount} ${count === 1 ? "problem" : "problems"}`,
+  problemsLabel: (count, errors, formattedCount, formattedErrors) =>
+    `${formattedCount} ${count === 1 ? "problem" : "problems"}, ${
+      errors === 0 ? "no errors" : `${formattedErrors} ${errors === 1 ? "error" : "errors"}`
+    }`,
+  showProblems: "Show in Problems view",
+  emptyHint: "Pick a tool from the palette to start.",
+  insertExample: "Insert example",
+  invalidFile: (diagram) =>
+    `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: "Ctrl", shift: "Shift", plus: "Plus", minus: "Minus" },
+  share: "Share",
+  legal: "Legal",
+  copyright: (year) => `© ${year} Miragon GmbH`,
+  opensInNewTab: "Opens in a new tab",
+  newDiagram: "New diagram",
+  openFile: "Open…",
+  showExample: "Show example",
+  importFile: "Import…",
+  appearance: "Appearance",
+  appearanceSystem: "System",
+  appearanceLight: "Light",
+  appearanceDark: "Dark",
+  problemsTitle: "Problems",
+  problemSeverity: (severity) => (severity === "error" ? "Error" : "Warning"),
+  close: "Close",
+  dropFile: "Drop file here",
+  dropForbidden: (reason) =>
+    reason === "multiple"
+      ? "Drop one file at a time"
+      : reason === "dialog"
+        ? "Close the dialog to drop a file"
+        : "This modeler can't open this file type",
+  dropHint: "Or drop a file here",
+  openFileLink: "Open a file…",
+  cannotOpenFile: (name, accepted) => `Couldn't open “${name}”. Drop a ${accepted} file.`,
+};
+
+/** `defaultMessages` with `overrides` applied (`keyNames` merged key by key). */
+export function resolveMessages(overrides?: ShellMessageOverrides | undefined): ShellMessages {
+  const { keyNames, ...texts } = overrides ?? {};
+  return {
+    ...defaultMessages,
+    ...definedEntries(texts),
+    keyNames: { ...defaultMessages.keyNames, ...definedEntries(keyNames ?? {}) },
+  };
+}
+
+// `{ menu: undefined }` (a spread of optional fields, a conditional override) keeps the default
+// instead of blanking the text.
+function definedEntries<T extends object>(partial: T): { [Key in keyof T]?: Exclude<T[Key], undefined> } {
+  return Object.fromEntries(Object.entries(partial).filter(([, value]) => value !== undefined)) as {
+    [Key in keyof T]?: Exclude<T[Key], undefined>;
+  };
+}