@miragon/modeler-shell 0.1.0 → 0.2.0

package/src/core/messages.ts

@@ -1,3 +1,6 @@
+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
@@ -35,6 +38,49 @@ export interface ShellMessages {
   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). */
@@ -67,6 +113,31 @@ export const defaultMessages: ShellMessages = {
   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). */

package/src/core/types.ts

@@ -36,9 +36,26 @@ export interface Insets {
  */
 export type ShellHost = "ide" | "web" | "embedded";
 
-/** The `data-chrome` names of the islands (guide §5.2, §13.4). `primary` is reserved for the web app. */
+/**
+ * The `data-chrome` names of the chrome (guide §5.2, §13.4). The web column adds `primary`, `legal`,
+ * `toasts`, `empty-state`, `drop-zone` and `problems-popover` (0.2); IDE and embedded hosts never
+ * show `primary`, `legal`, `empty-state` and `drop-zone`, the IDE host never `toasts` and
+ * `problems-popover`.
+ */
 export type ChromeIsland =
-  "menu" | "palette" | "primary" | "zoom" | "problems" | "legend" | "inspector" | "status";
+  | "menu"
+  | "palette"
+  | "primary"
+  | "zoom"
+  | "problems"
+  | "legend"
+  | "inspector"
+  | "status"
+  | "legal"
+  | "toasts"
+  | "empty-state"
+  | "drop-zone"
+  | "problems-popover";
 
 export const CHROME_ISLANDS: readonly ChromeIsland[] = [
   "menu",
@@ -49,6 +66,11 @@ export const CHROME_ISLANDS: readonly ChromeIsland[] = [
   "legend",
   "inspector",
   "status",
+  "legal",
+  "toasts",
+  "empty-state",
+  "drop-zone",
+  "problems-popover",
 ];
 
 /** Where the palette sits: in the top row, or in the second row below it (guide §5.15). */

package/src/core/web-chrome/bottom-row.ts

@@ -0,0 +1,37 @@
+import { SHELL } from "../sizes.js";
+
+/**
+ * Height of one line of the web app's legal line: 13px text on a 20px line (guide §5.10). Where a
+ * narrow container cannot hold it in one line, it wraps (40 for two lines) and everything stacked
+ * above it rises by as much: the pill, the legend, the raised zoom panel and the fit's bottom.
+ */
+export const LEGAL_LINE_HEIGHT = 20;
+
+/** A measured legal line's height in whole lines, at least one: what the stack above it stands on. */
+export function legalLineHeight(measured: number | undefined): number {
+  if (measured === undefined || !Number.isFinite(measured) || measured <= 0) return LEGAL_LINE_HEIGHT;
+  return Math.max(1, Math.round(measured / LEGAL_LINE_HEIGHT)) * LEGAL_LINE_HEIGHT;
+}
+
+export interface BottomRowInput {
+  containerWidth: number;
+  /** Measured right edge of the legal line relative to the shell root; absent while it is not shown. */
+  legalRight?: number | undefined;
+  /** Measured width of the zoom panel (173 with a 56px readout); absent while it is not shown. */
+  zoomWidth?: number | undefined;
+}
+
+/**
+ * Web app, bottom row: true when the zoom panel at `right: 12px` would keep less than
+ * `SHELL.gap` (8px) to the legal line at `left: 12px`. The zoom panel then stands above the legal
+ * line at `bottom: 40px` (12 + 20 + 8; a wrapped line lifts it further), like the pill
+ * (`data-zoom-row="raised"` on the root), and the fit keeps 92px at the bottom (`FitLayout.zoomRaised`). Guide §5.10 and §5.15 do not settle
+ * this collision of a narrow container; it is the shell's rule until they do.
+ * False when either of the two is not shown.
+ */
+export function zoomRowRaised(input: BottomRowInput): boolean {
+  const { containerWidth, legalRight, zoomWidth } = input;
+  if (legalRight === undefined || zoomWidth === undefined) return false;
+  const zoomLeft = containerWidth - SHELL.edge - zoomWidth;
+  return legalRight + SHELL.gap > zoomLeft;
+}

package/src/core/web-chrome/drop.ts

@@ -0,0 +1,78 @@
+/** Why a drag cannot be dropped (guide §9 Drop forbidden); `messages.dropForbidden` words each one. */
+export type DropForbiddenReason = "multiple" | "type" | "dialog";
+
+/** One entry of `DataTransfer.items` as a drag shows it (names are not readable before the drop). */
+export interface DragItemLike {
+  kind: string;
+  type: string;
+}
+
+export 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). */
+export type DragVerdict =
+  { state: "none" } | { state: "over" } | { state: "forbidden"; reason: DropForbiddenReason };
+
+interface AcceptEntries {
+  extensions: readonly string[];
+  mimeTypes: readonly string[];
+}
+
+/** `<input accept>` tokens: trimmed, lower case, blanks dropped; "." starts an extension, "/" marks a MIME type. */
+function acceptEntries(accept: readonly string[]): AcceptEntries {
+  const entries = accept.map((entry) => entry.trim().toLowerCase()).filter((entry) => entry !== "");
+  return {
+    extensions: entries.filter((entry) => entry.startsWith(".")),
+    mimeTypes: entries.filter((entry) => !entry.startsWith(".") && entry.includes("/")),
+  };
+}
+
+function matchesMimeType(type: string, mimeTypes: readonly string[]): boolean {
+  const normalized = type.trim().toLowerCase();
+  if (normalized === "") return false;
+  return mimeTypes.some((entry) =>
+    entry.endsWith("/*") ? normalized.startsWith(entry.slice(0, -1)) : normalized === entry,
+  );
+}
+
+/**
+ * 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.
+ */
+export function dragVerdict(items: readonly DragItemLike[], context: DragContext): DragVerdict {
+  const files = items.filter((item) => item.kind === "file");
+  if (files.length === 0) return { state: "none" };
+  if (context.dialogOpen) return { state: "forbidden", reason: "dialog" };
+  if (files.length > 1 && !context.multiple) return { state: "forbidden", reason: "multiple" };
+  const { mimeTypes } = acceptEntries(context.accept);
+  const foreignType = (item: DragItemLike) =>
+    item.type.trim() !== "" && !matchesMimeType(item.type, mimeTypes);
+  if (mimeTypes.length > 0 && files.every(foreignType)) return { state: "forbidden", reason: "type" };
+  return { state: "over" };
+}
+
+/**
+ * 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.
+ */
+export function acceptsFile(file: { name: string; type: string }, accept: readonly string[]): boolean {
+  const { extensions, mimeTypes } = acceptEntries(accept);
+  if (extensions.length === 0 && mimeTypes.length === 0) return true;
+  const name = file.name.toLowerCase();
+  return extensions.some((extension) => name.endsWith(extension)) || matchesMimeType(file.type, mimeTypes);
+}

package/src/core/web-chrome/top-row.ts

@@ -0,0 +1,66 @@
+import { PALETTE_CLEARANCE, decidePaletteRow } from "../layout.js";
+import { SHELL } from "../sizes.js";
+import type { PaletteRow } from "../types.js";
+
+/** Border-box widths of the web app's primary action, measured with and without its label. */
+export interface PrimaryWidths {
+  /** Icon and label: padding `0 16px`, icon 16px, gap 8px, label 13px/600 (guide §5.7). */
+  withLabel: number;
+  /** The icon alone: `SHELL.row` (40) square. */
+  iconOnly: number;
+}
+
+export interface TopRowInput {
+  containerWidth: number;
+  /** The palette's intrinsic border-box width, as for `decidePaletteRow`. */
+  paletteWidth: number;
+  /** Right edge of the menu trigger, relative to the shell root. */
+  menuRight: number;
+  /** The primary action at `right: 12px`; absent in IDE and embedded hosts and without one. */
+  primary?: PrimaryWidths | undefined;
+}
+
+export interface TopRow {
+  paletteRow: PaletteRow;
+  /** `collapsed`: the primary action shows its icon only; its `aria-label` keeps the name. */
+  primaryLabel: "shown" | "collapsed";
+}
+
+/**
+ * The top row of guide §5.15 with a primary action: when it gets tight, the primary action loses
+ * its label first, and only then the palette moves to the second row.
+ *
+ * 1. Without `primary`: `decidePaletteRow` alone, label `shown`.
+ * 2. With the label (`primaryLeft = containerWidth − SHELL.edge − withLabel`): palette `top` →
+ *    `{ top, shown }`.
+ * 3. Icon only (`primaryLeft = containerWidth − SHELL.edge − iconOnly`): palette `top` →
+ *    `{ top, collapsed }`.
+ * 4. Otherwise the palette is in the second row and the top row holds only menu trigger and
+ *    primary action: the label shows again when `menuRight + PALETTE_CLEARANCE` stays left of the
+ *    labelled button, else it stays collapsed.
+ *
+ * Up to `SHELL.narrow` the palette is always in the second row (step 4).
+ */
+export function decideTopRow(input: TopRowInput): TopRow {
+  const { containerWidth, paletteWidth, menuRight, primary } = input;
+  if (!primary) {
+    return {
+      paletteRow: decidePaletteRow({ containerWidth, paletteWidth, menuRight }),
+      primaryLabel: "shown",
+    };
+  }
+  const paletteRowBeside = (primaryWidth: number): PaletteRow =>
+    decidePaletteRow({
+      containerWidth,
+      paletteWidth,
+      menuRight,
+      primaryLeft: containerWidth - SHELL.edge - primaryWidth,
+    });
+  if (paletteRowBeside(primary.withLabel) === "top") return { paletteRow: "top", primaryLabel: "shown" };
+  if (paletteRowBeside(primary.iconOnly) === "top") return { paletteRow: "top", primaryLabel: "collapsed" };
+  const labelledLeft = containerWidth - SHELL.edge - primary.withLabel;
+  return {
+    paletteRow: "second-row",
+    primaryLabel: menuRight + PALETTE_CLEARANCE <= labelledLeft ? "shown" : "collapsed",
+  };
+}

package/src/diagram-js/service.ts

@@ -195,7 +195,10 @@ export class ShellDiagramService {
   private readonly onKeyboardKeydown = (context: KeyboardEventContext): boolean | undefined => {
     const event = context.keyEvent;
     if (!event) return undefined;
-    if (matchChromeKey(event)) return !isTextField(event.target);
+    // `false` keeps every other diagram-js listener off the key without preventing it: in a text
+    // field the field keeps it, behind the web app's start screen the browser zooms the page.
+    if (matchChromeKey(event))
+      return !isTextField(event.target) && this.shell?.isEmptyStateShown?.() !== true;
     if (this.shell?.host === "ide" && isUndoRedoKey(event)) return false;
     return undefined;
   };

package/src/diagram-js/viewport.ts

@@ -62,6 +62,13 @@ export interface Viewport extends ZoomTarget {
    * the user created on the canvas does not (guide §5.9), so the next import keeps the view.
    */
   afterImport(): void;
+  /**
+   * The web app opens another document (New diagram, Open…, Import…, Show example, a shared link,
+   * a dropped file): the next `afterImport()` counts as the first again (guide §5.9). Forgets the
+   * user's moves, a stored view and a pending restore, and stops a running fit animation, so
+   * non-empty content fits (jump) and an empty document shows 100 %. Call it before the import.
+   */
+  newDocument(): void;
   /** Restores a viewbox after a re-import (external change): reference updated, user-move state kept. */
   restore(viewbox: Bounds): void;
   /** The current viewbox (x, y, width, height), `undefined` before the canvas has a size. */
@@ -229,6 +236,18 @@ export class DiagramViewport implements Viewport {
     this.notify();
   }
 
+  newDocument(): void {
+    if (this.destroyed) return;
+    this.cancelAnimation();
+    this.userMoved = false;
+    this.firstFitPending = true;
+    this.emptyViewPending = true;
+    this.emptyViewDue = false;
+    this.autoFitDue = false;
+    this.pendingView = undefined;
+    this.fittable = undefined;
+  }
+
   restore(viewbox: Bounds): void {
     if (this.destroyed) return;
     this.importing = false;

package/src/dom/buttons.css

@@ -0,0 +1,124 @@
+/*
+ * Buttons of the web chrome (guide §8): `.cd-shell-button` with `data-variant="primary"` (the top
+ * right primary action, the empty state's "New diagram") or `data-variant="ghost"` ("Show
+ * example", a toast's action). 36px by default (dialogs, panels, empty state); the primary action
+ * of the top row sets its own 40px.
+ *
+ * The one stylesheet of the shell that reads fixed palette tokens, and only these three: the
+ * primary button is --cd-blau with --cd-weiss text in both modes, hover and active --cd-blau-link
+ * (guide §8: "Feste Werte nimmst du nur für die Fläche von Primär- und Destruktiv-Button"). The
+ * stylesheet test allows them here and nowhere else.
+ */
+
+.cd-shell-button {
+  box-sizing: border-box;
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  gap: var(--cd-shell-luecke);
+  height: var(--cd-shell-eintrag);
+  margin: 0;
+  padding: 0 16px;
+  color: var(--cd-ui-text);
+  font: inherit;
+  font-size: 13px;
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: normal;
+  text-transform: none;
+  white-space: nowrap;
+  background: transparent;
+  border: 1px solid transparent;
+  border-radius: var(--cd-radius-md);
+  cursor: pointer;
+  user-select: none;
+  -webkit-user-select: none;
+  transition:
+    background-color var(--cd-motion-fast) var(--cd-ease),
+    border-color var(--cd-motion-fast) var(--cd-ease),
+    box-shadow var(--cd-motion-fast) var(--cd-ease),
+    color var(--cd-motion-fast) var(--cd-ease),
+    transform var(--cd-motion-fast) var(--cd-ease);
+}
+
+.cd-shell-button[hidden] {
+  display: none;
+}
+
+.cd-shell-button svg {
+  display: block;
+  flex: none;
+}
+
+.cd-shell-button[data-variant="primary"] {
+  color: var(--cd-weiss);
+  background: var(--cd-blau);
+  box-shadow: var(--cd-shadow-1);
+}
+
+.cd-shell-button[data-variant="primary"]:is(:hover, :active):not([aria-disabled="true"]) {
+  background: var(--cd-blau-link);
+  box-shadow: var(--cd-shadow-2);
+  transform: translateY(-1px);
+}
+
+.cd-shell-button[data-variant="ghost"]:is(:hover, :active):not([aria-disabled="true"]) {
+  background: var(--cd-ui-hover);
+}
+
+/* Disabled is opaque and neutral, never through opacity (guide §8). */
+.cd-shell-button[aria-disabled="true"] {
+  color: var(--cd-ui-text-leise);
+  cursor: not-allowed;
+}
+
+.cd-shell-button[data-variant="primary"][aria-disabled="true"] {
+  background: var(--cd-ui-hover);
+  border-color: var(--cd-ui-linie);
+  box-shadow: none;
+}
+
+.cd-shell-button:focus {
+  outline: none;
+}
+
+.cd-shell-button:focus-visible {
+  outline: 2px solid var(--cd-ui-fokus);
+  outline-offset: 2px;
+}
+
+/* No lift under reduced motion (guide §7): the hover shows in fill and shadow alone. */
+@media (prefers-reduced-motion: reduce) {
+  .cd-shell .cd-shell-button[data-variant]:is(:hover, :active) {
+    transform: none;
+  }
+}
+
+/* The host asks for it although the OS does not: VS Code's workbench.reduceMotion. */
+html.cd-shell-reduce-motion .cd-shell .cd-shell-button[data-variant]:is(:hover, :active) {
+  transform: none;
+}
+
+.cd-shell:is([data-cd-kontrast="hoch"], [data-cd-kontrast="hoch"] *) .cd-shell-button {
+  box-shadow: none;
+}
+
+.cd-shell:is([data-cd-kontrast="hoch"], [data-cd-kontrast="hoch"] *) .cd-shell-button:focus-visible {
+  outline-width: 3px;
+}
+
+@media (forced-colors: active) {
+  .cd-shell .cd-shell-button {
+    border-color: ButtonText;
+  }
+
+  .cd-shell .cd-shell-button:focus-visible {
+    outline-color: Highlight;
+  }
+
+  .cd-shell .cd-shell-button[aria-disabled="true"] {
+    color: GrayText;
+    border-color: GrayText;
+  }
+}

package/src/dom/feedback/appearance.ts

@@ -0,0 +1,184 @@
+import {
+  APPEARANCE_STORAGE_KEY,
+  documentMode,
+  parseAppearanceChoice,
+  type AppearanceChoice,
+  type Theme,
+} from "../../core/index.js";
+import { createElement, toggleAttribute } from "../element.js";
+import type { AppearanceHandle, StorageLike, WebAppearanceOptions } from "../types.js";
+
+export interface WebAppearanceContext {
+  ownerDocument: Document;
+  themes: readonly Theme[];
+  /** Required when `themes` includes `"dark"`; read only then. */
+  options: WebAppearanceOptions | undefined;
+}
+
+export interface WebAppearanceController extends AppearanceHandle {
+  /** Stops following `prefers-contrast` and other tabs' `storage` events; leaves `<html>` as it is. */
+  destroy(): void;
+}
+
+/** On `<html>` for one frame of a mode switch (guide §7); shell-dom.css turns every transition off. */
+export const NO_TRANSITION_CLASS = "cd-shell-no-transition";
+
+const CONTRAST_QUERY = "(prefers-contrast: more)";
+const SCHEME_MEDIA: Readonly<Record<Theme, string>> = {
+  light: "(prefers-color-scheme: light)",
+  dark: "(prefers-color-scheme: dark)",
+};
+
+/** `change` on a media query list; Safari before 14 only has `addListener`. */
+function onMediaChange(query: MediaQueryList, listener: () => void): () => void {
+  if (typeof query.addEventListener === "function") {
+    query.addEventListener("change", listener);
+    return () => query.removeEventListener("change", listener);
+  }
+  query.addListener(listener);
+  return () => query.removeListener(listener);
+}
+
+/**
+ * The web host's mode at runtime (guide §13.3), after the head script (`webModeScript`) set it
+ * before the first paint. Always: mirrors `(prefers-contrast: more)` as `data-cd-kontrast="hoch"`
+ * on `<html>`, at once and on every change. With `"dark"` in `themes` (throws without `options`):
+ * `choice()` is the stored choice, read once through `parseAppearanceChoice` (a blocked storage
+ * reads `"system"`) and then kept by `setChoice` and other tabs' `storage` events, so a choice the
+ * storage refused still holds for the page. `setChoice` writes it (`"system"` removes the key; a
+ * throwing storage is ignored) and applies `documentMode` on `<html data-cd-theme>`,
+ * `<meta name="color-scheme">` and both `theme-color` metas (created where missing) in one task,
+ * with `cd-shell-no-transition` on `<html>` until a nested `requestAnimationFrame`; a `storage`
+ * event for the key applies the same way. Light-only: `choice()` is `"system"`, `setChoice` does
+ * nothing.
+ */
+export function connectWebAppearance(context: WebAppearanceContext): WebAppearanceController {
+  const { ownerDocument, themes, options } = context;
+  const darkCapable = themes.includes("dark");
+  if (darkCapable && !options) {
+    throw new Error(
+      '@miragon/modeler-shell: a web modeler whose themes include "dark" needs the appearance option ' +
+        "({ themeColors } from its vendored cd-tokens.generated.json)",
+    );
+  }
+  const html = ownerDocument.documentElement;
+  const view = ownerDocument.defaultView;
+  const cleanups: (() => void)[] = [];
+
+  const contrast = typeof view?.matchMedia === "function" ? view.matchMedia(CONTRAST_QUERY) : undefined;
+  if (contrast) {
+    const mirrorContrast = (): void => toggleAttribute(html, "data-cd-kontrast", contrast.matches && "hoch");
+    mirrorContrast();
+    cleanups.push(onMediaChange(contrast, mirrorContrast));
+  }
+
+  function destroy(): void {
+    for (const cleanup of cleanups.splice(0)) cleanup();
+  }
+
+  if (!darkCapable || !options) {
+    return { choice: () => "system", setChoice() {}, destroy };
+  }
+  const { themeColors } = options;
+
+  function storage(): StorageLike | undefined {
+    if (options?.storage) return options.storage;
+    try {
+      return globalThis.localStorage;
+    } catch {
+      return undefined;
+    }
+  }
+
+  function readStored(): AppearanceChoice {
+    try {
+      return parseAppearanceChoice(storage()?.getItem(APPEARANCE_STORAGE_KEY));
+    } catch {
+      return "system";
+    }
+  }
+
+  function store(choice: AppearanceChoice): void {
+    try {
+      const target = storage();
+      if (choice === "system") target?.removeItem(APPEARANCE_STORAGE_KEY);
+      else target?.setItem(APPEARANCE_STORAGE_KEY, choice);
+    } catch {
+      // Blocked or full: the choice still applies for this page.
+    }
+  }
+
+  function nextFrame(callback: () => void): () => void {
+    if (view && typeof view.requestAnimationFrame === "function") {
+      const frame = view.requestAnimationFrame(() => callback());
+      return () => view.cancelAnimationFrame(frame);
+    }
+    const timer = setTimeout(callback, 16);
+    return () => clearTimeout(timer);
+  }
+
+  let cancelTransitionFrame: (() => void) | undefined;
+  function allowTransitions(): void {
+    cancelTransitionFrame?.();
+    cancelTransitionFrame = undefined;
+    html.classList.remove(NO_TRANSITION_CLASS);
+  }
+  cleanups.push(() => {
+    if (cancelTransitionFrame) allowTransitions();
+  });
+
+  // The first frame still computes styles with the new colours; only after it may they fade again.
+  function suspendTransitions(): void {
+    cancelTransitionFrame?.();
+    html.classList.add(NO_TRANSITION_CLASS);
+    cancelTransitionFrame = nextFrame(() => {
+      cancelTransitionFrame = nextFrame(allowTransitions);
+    });
+  }
+
+  function metaFor(name: string, media?: string): HTMLMetaElement {
+    const normalize = (value: string | null): string => (value ?? "").replace(/\s+/g, "").toLowerCase();
+    const existing = [...ownerDocument.querySelectorAll<HTMLMetaElement>(`meta[name="${name}"]`)].find(
+      (meta) => (media === undefined ? true : normalize(meta.getAttribute("media")) === normalize(media)),
+    );
+    if (existing) return existing;
+    const created = createElement(ownerDocument, "meta", { name, media });
+    (ownerDocument.head ?? html).append(created);
+    return created;
+  }
+
+  function apply(choice: AppearanceChoice): void {
+    const mode = documentMode(choice, themes, themeColors);
+    suspendTransitions();
+    html.setAttribute("data-cd-theme", mode.theme);
+    metaFor("color-scheme").setAttribute("content", mode.colorScheme);
+    metaFor("theme-color", SCHEME_MEDIA.light).setAttribute("content", mode.themeColor.light);
+    metaFor("theme-color", SCHEME_MEDIA.dark).setAttribute("content", mode.themeColor.dark);
+  }
+
+  let current = readStored();
+
+  const onStorage = (event: StorageEvent): void => {
+    // A null key is a clear() of the whole storage: the choice is gone, so "system".
+    if (event.key !== null && event.key !== APPEARANCE_STORAGE_KEY) return;
+    const next = event.key === null ? "system" : parseAppearanceChoice(event.newValue);
+    if (next === current) return;
+    current = next;
+    apply(next);
+  };
+  if (view) {
+    view.addEventListener("storage", onStorage);
+    cleanups.push(() => view.removeEventListener("storage", onStorage));
+  }
+
+  return {
+    choice: () => current,
+    setChoice(choice) {
+      const next = parseAppearanceChoice(choice);
+      current = next;
+      store(next);
+      apply(next);
+    },
+    destroy,
+  };
+}