@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/src/core/appearance.ts

@@ -0,0 +1,104 @@
+/** The modes a Miragon modeler can show (guide §13.3). */
+export type Theme = "light" | "dark";
+
+/** High contrast; written as `data-cd-kontrast="hoch"` on the same element as `data-cd-theme`. */
+export type Kontrast = "hoch";
+
+export interface Appearance {
+  theme: Theme;
+  kontrast?: Kontrast | undefined;
+}
+
+/**
+ * The one appearance decision of guide §13.5: a theme the modeler cannot show is never shown
+ * (`themes[0]` wins, so `["light"]` stays light whatever the host requests); `kontrast` always
+ * passes through. Throws when `themes` is empty.
+ */
+export function resolveAppearance(requested: Appearance, themes: readonly Theme[]): Appearance {
+  const [fallback] = themes;
+  if (fallback === undefined) {
+    throw new Error(
+      "@miragon/modeler-shell: resolveAppearance needs at least one theme the modeler can show",
+    );
+  }
+  const theme = themes.includes(requested.theme) ? requested.theme : fallback;
+  return withKontrast(theme, requested.kontrast);
+}
+
+// Appearances arrive through postMessage and settings, so only the one known value passes.
+function withKontrast(theme: Theme, kontrast: unknown): Appearance {
+  return kontrast === "hoch" ? { theme, kontrast } : { theme };
+}
+
+/**
+ * The appearance VS Code requests for `vscode.window.activeColorTheme.kind`:
+ * 1 Light → light, 2 Dark → dark, 3 HighContrast → dark + hoch, 4 HighContrastLight → light + hoch;
+ * any other value → light.
+ */
+export function appearanceFromColorThemeKind(kind: number): Appearance {
+  switch (kind) {
+    case 2:
+      return { theme: "dark" };
+    case 3:
+      return { theme: "dark", kontrast: "hoch" };
+    case 4:
+      return { theme: "light", kontrast: "hoch" };
+    default:
+      return { theme: "light" };
+  }
+}
+
+/** The values of the setting `miragon.<modeler>.colorTheme` (it ships once a modeler can show dark). */
+export type ColorThemeSetting = "automatic" | "light" | "dark";
+
+/**
+ * The requested appearance in an IDE host: the setting's theme unless it is `automatic` (or
+ * missing), the contrast always from the color theme kind.
+ */
+export function requestedAppearance(kind: number, setting?: ColorThemeSetting | undefined): Appearance {
+  const fromKind = appearanceFromColorThemeKind(kind);
+  const theme = setting === "light" || setting === "dark" ? setting : fromKind.theme;
+  return withKontrast(theme, fromKind.kontrast);
+}
+
+/**
+ * The fallback signal inside a VS Code webview: the body classes `vscode-high-contrast-light`
+ * (checked first, VS Code adds `vscode-high-contrast` to it as well), `vscode-high-contrast`,
+ * `vscode-dark`, `vscode-light`. `undefined` when none is set. Never use them for styling.
+ */
+export function appearanceFromBodyClasses(classes: Iterable<string>): Appearance | undefined {
+  const present = new Set(classes);
+  if (present.has("vscode-high-contrast-light")) return { theme: "light", kontrast: "hoch" };
+  if (present.has("vscode-high-contrast")) return { theme: "dark", kontrast: "hoch" };
+  if (present.has("vscode-dark")) return { theme: "dark" };
+  if (present.has("vscode-light")) return { theme: "light" };
+  return undefined;
+}
+
+/**
+ * VS Code's `workbench.reduceMotion` as the webview sees it: the body class `vscode-reduce-motion`
+ * (the webview host page sets it). Never use it for styling; the shell mirrors it as
+ * `REDUCED_MOTION_CLASS` on `<html>`.
+ */
+export function reducedMotionFromBodyClasses(classes: Iterable<string>): boolean {
+  return new Set(classes).has("vscode-reduce-motion");
+}
+
+/**
+ * On `<html>` while the host asks for reduced motion although the OS does not (VS Code's
+ * `workbench.reduceMotion`): the shell's animations stop as under `prefers-reduced-motion`, and an
+ * explicit fit jumps.
+ */
+export const REDUCED_MOTION_CLASS = "cd-shell-reduce-motion";
+
+export interface AppearanceAttributes {
+  "data-cd-theme": Theme;
+  "data-cd-kontrast"?: Kontrast;
+}
+
+/** The attributes for `<html>` (own document) or the modeler container (foreign page). */
+export function appearanceAttributes(appearance: Appearance): AppearanceAttributes {
+  return appearance.kontrast === "hoch"
+    ? { "data-cd-theme": appearance.theme, "data-cd-kontrast": "hoch" }
+    : { "data-cd-theme": appearance.theme };
+}

package/src/core/feedback/appearance.ts

@@ -0,0 +1,141 @@
+import type { Theme } from "../appearance.js";
+
+/** The web app's mode choice (guide §13.3): Appearance, System · Light · Dark. */
+export type AppearanceChoice = "system" | "light" | "dark";
+
+/** Where the web app keeps the choice: `light` or `dark`; "System" removes the entry (guide §13.3). */
+export 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.
+ */
+export interface ThemeColors {
+  light: string;
+  dark: string;
+}
+
+/** `"light"` and `"dark"` pass, everything else (a missing entry, a foreign value) is `"system"`. */
+export function parseAppearanceChoice(stored: unknown): AppearanceChoice {
+  return stored === "light" || stored === "dark" ? stored : "system";
+}
+
+/** What `<html>` and the meta tags carry for a choice. */
+export 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.
+ */
+export function documentMode(
+  choice: AppearanceChoice,
+  themes: readonly Theme[],
+  colors: ThemeColors,
+): DocumentMode {
+  if (!themes.includes("dark")) return fixedMode("light", colors.light);
+  const parsed = parseAppearanceChoice(choice);
+  if (parsed === "system") {
+    return {
+      theme: "system",
+      colorScheme: "light dark",
+      themeColor: { light: colors.light, dark: colors.dark },
+    };
+  }
+  return fixedMode(parsed, colors[parsed]);
+}
+
+function fixedMode(theme: Theme, color: string): DocumentMode {
+  return { theme, colorScheme: theme, themeColor: { light: color, dark: color } };
+}
+
+export 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.
+ */
+export function webModeScript(options: WebModeScriptOptions): string {
+  const contrast = [
+    `if (window.matchMedia && window.matchMedia(${scriptString("(prefers-contrast: more)")}).matches)`,
+    `  document.documentElement.setAttribute("data-cd-kontrast", "hoch");`,
+  ];
+  if (!options.themes.includes("dark")) return contrast.join("\n");
+  const { light, dark } = options.themeColors;
+  return [
+    "(function () {",
+    "  var html = document.documentElement;",
+    "  var choice = null;",
+    "  try {",
+    `    choice = window.localStorage.getItem(${scriptString(APPEARANCE_STORAGE_KEY)});`,
+    "  } catch (error) {}",
+    `  if (choice === "light" || choice === "dark") {`,
+    `    var color = choice === "dark" ? ${scriptString(dark)} : ${scriptString(light)};`,
+    `    html.setAttribute("data-cd-theme", choice);`,
+    `    var scheme = document.querySelector("meta[name=color-scheme]");`,
+    `    if (scheme) scheme.setAttribute("content", choice);`,
+    `    var metas = document.querySelectorAll("meta[name=theme-color]");`,
+    `    for (var index = 0; index < metas.length; index++) metas[index].setAttribute("content", color);`,
+    "  }",
+    ...contrast.map((line) => `  ${line}`),
+    "})();",
+  ].join("\n");
+}
+
+// The script sits inline in <head>: "<" never appears in a literal, so a value cannot end the
+// element ("</script>"), and U+2028/U+2029 are escaped because ES5 forbids them in string literals.
+function scriptString(value: string): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\u003c")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * 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.
+ */
+export function webHeadMarkup(options: WebModeScriptOptions): string {
+  const mode = documentMode("system", options.themes, options.themeColors);
+  const script = `<script>\n${webModeScript(options)}\n</script>`;
+  if (mode.theme !== "system") {
+    return [`<meta name="theme-color" content="${escapeAttribute(mode.themeColor.light)}">`, script].join(
+      "\n",
+    );
+  }
+  return [
+    `<meta name="color-scheme" content="${escapeAttribute(mode.colorScheme)}">`,
+    `<meta name="theme-color" content="${escapeAttribute(mode.themeColor.light)}" media="(prefers-color-scheme: light)">`,
+    `<meta name="theme-color" content="${escapeAttribute(mode.themeColor.dark)}" media="(prefers-color-scheme: dark)">`,
+    script,
+  ].join("\n");
+}
+
+function escapeAttribute(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/src/core/feedback/problems.ts

@@ -0,0 +1,23 @@
+/** The severity of one problem; the pill and the list show `circle-x` or `triangle-alert` (guide §5.10). */
+export type ProblemSeverity = "error" | "warning";
+
+/** One row of the web app's problems list (guide §5.10). */
+export 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. */
+export function problemSummary(items: readonly ProblemItem[]): {
+  count: number;
+  errors: number;
+  items: readonly ProblemItem[];
+} {
+  const errors = items.filter((item) => item.severity === "error").length;
+  return { count: items.length, errors, items };
+}

package/src/core/feedback/toasts.ts

@@ -0,0 +1,118 @@
+import { SHELL } from "../sizes.js";
+
+/** The statuses of guide §3.3 and §9; each colours bar and dot through `--cd-ui-<status>`. */
+export type ToastStatus = "success" | "info" | "warning" | "danger";
+
+/** A ghost button before Close (guide §8); the toast then never closes by itself. */
+export interface ToastAction {
+  label: string;
+  /** Runs after the toast closed. */
+  onSelect(): void;
+}
+
+export interface ToastRequest {
+  status: ToastStatus;
+  /** What happened and what you can do (guide §2): "Link copied", "Couldn't read this file. …". */
+  text: string;
+  action?: ToastAction | undefined;
+  /** Only to give a long text more time than `TOAST_DURATION_MS`; ignored with an `action`. */
+  durationMs?: number | undefined;
+}
+
+/** At most three toasts at once, the newest at the bottom (guide §8). */
+export const MAX_TOASTS = 3;
+
+/**
+ * How long a toast stays without hover or focus (guide §8: about 2.8 s, errors about 5 s). A
+ * warning asks you to read a sentence and act on it like an error, so it gets the error's 5 s.
+ */
+export const TOAST_DURATION_MS: Readonly<Record<ToastStatus, number>> = {
+  success: 2800,
+  info: 2800,
+  warning: 5000,
+  danger: 5000,
+};
+
+/** The stack's widest toast: `min(480px, 100cqw − 24px)` (guide §8). */
+export const TOAST_MAX_WIDTH = 480;
+
+/**
+ * Milliseconds until the toast closes by itself: `undefined` with an `action` (it never closes by
+ * itself, guide §8), else `max(TOAST_DURATION_MS[status], durationMs ?? 0)`.
+ */
+export function toastLifetime(request: ToastRequest): number | undefined {
+  if (request.action) return undefined;
+  const requested = request.durationMs;
+  // A NaN or an infinite duration would reach setTimeout, which fires at once for both.
+  const longer = requested !== undefined && Number.isFinite(requested) ? requested : 0;
+  return Math.max(TOAST_DURATION_MS[request.status], longer);
+}
+
+/** A toast in the stack as the eviction sees it, oldest first. */
+export interface ToastSlot {
+  id: number;
+  hasAction: boolean;
+  /** Hovered or holding the focus. */
+  engaged: boolean;
+}
+
+/**
+ * Which toast leaves when a fourth arrives (`MAX_TOASTS`): the oldest that is neither engaged nor
+ * has an action, else the oldest that is not engaged, else the oldest. `undefined` while the
+ * stack has room.
+ */
+export function toastToEvict(stack: readonly ToastSlot[]): number | undefined {
+  if (stack.length < MAX_TOASTS) return undefined;
+  const evicted =
+    stack.find((slot) => !slot.engaged && !slot.hasAction) ?? stack.find((slot) => !slot.engaged) ?? stack[0];
+  return evicted?.id;
+}
+
+/** Something in the bottom row the toast stack must clear, relative to the shell root. */
+export interface BottomObstacle {
+  left: number;
+  right: number;
+  /** Distance of its top edge from the container's bottom edge. */
+  top: number;
+}
+
+export interface ToastStackInput {
+  containerWidth: number;
+  /** The visible zoom panel, legal line and problems pill (not the legend card). */
+  obstacles: readonly BottomObstacle[];
+  /**
+   * Measured width of the widest toast in the stack. The cards are sized to their text and centred
+   * in the stack, so only this column can touch an obstacle; absent = the whole `toastStackWidth`.
+   */
+  cardWidth?: number | undefined;
+}
+
+/** `min(TOAST_MAX_WIDTH, containerWidth − 2 · SHELL.edge)`. */
+export function toastStackWidth(containerWidth: number): number {
+  return Math.max(0, Math.min(TOAST_MAX_WIDTH, containerWidth - 2 * SHELL.edge));
+}
+
+/**
+ * The stack's `bottom` in px. Guide §8 anchors it at `bottom: 12px`, centred; where the column of
+ * its widest card (`cardWidth`, at most `toastStackWidth`, centred) comes closer than `SHELL.gap`
+ * horizontally to an obstacle, the stack stands `SHELL.gap` above the highest such obstacle instead
+ * (above the legal line 40, above the zoom panel 60, above a raised zoom panel or the web pill 88).
+ * Guide §8 does not settle this collision of a narrow container; it is the shell's rule until it does.
+ */
+export function toastStackBottom(input: ToastStackInput): number {
+  const stackWidth = toastStackWidth(input.containerWidth);
+  const { cardWidth } = input;
+  const width =
+    cardWidth !== undefined && Number.isFinite(cardWidth)
+      ? Math.min(stackWidth, Math.max(0, cardWidth))
+      : stackWidth;
+  const left = (input.containerWidth - width) / 2;
+  const right = left + width;
+  let highest: number | undefined;
+  for (const obstacle of input.obstacles) {
+    const distance = Math.max(obstacle.left - right, left - obstacle.right);
+    if (distance >= SHELL.gap) continue;
+    highest = highest === undefined ? obstacle.top : Math.max(highest, obstacle.top);
+  }
+  return highest === undefined ? SHELL.edge : Math.max(SHELL.edge, highest + SHELL.gap);
+}

package/src/core/fit.ts

@@ -0,0 +1,220 @@
+import { SHELL } from "./sizes.js";
+import { LEGAL_LINE_HEIGHT, legalLineHeight } from "./web-chrome/bottom-row.js";
+import type { Bounds, Insets, PaletteRow, Point, ScaledViewbox, ShellHost, Size } from "./types.js";
+
+/** Fit never zooms above 100 % (guide §5.9). */
+export const MAX_FIT_ZOOM = 1;
+
+/** Duration of the explicit, animated fit (`--cd-motion-base`). */
+export const FIT_ANIMATION_MS = 250;
+
+/**
+ * The viewbox that shows `bounds` centred in the free rectangle (`container` minus `insets`) at the
+ * largest scale that fits, capped at `maxZoom`. The box has the container's aspect ratio, so
+ * diagram-js's `canvas.viewbox(box)` sets exactly this view. Returns `undefined` when the container
+ * is 0 × 0 or `bounds` has neither width nor height; a zero width or height scales by the other
+ * dimension. Where the insets leave no free room on an axis (a container lower or narrower than
+ * its chrome), that axis centres in the whole container instead.
+ */
+export function fitViewbox(
+  bounds: Bounds,
+  container: Size,
+  insets: Insets,
+  maxZoom: number = MAX_FIT_ZOOM,
+): ScaledViewbox | undefined {
+  if (!(container.width > 0 && container.height > 0)) return undefined;
+  const hasWidth = bounds.width > 0;
+  const hasHeight = bounds.height > 0;
+  if (!hasWidth && !hasHeight) return undefined;
+
+  const horizontal = freeExtent(container.width, insets.left, insets.right);
+  const vertical = freeExtent(container.height, insets.top, insets.bottom);
+  const contentWidth = hasWidth ? bounds.width : 0;
+  const contentHeight = hasHeight ? bounds.height : 0;
+  const scale = Math.min(
+    maxZoom,
+    hasWidth ? horizontal.extent / contentWidth : Infinity,
+    hasHeight ? vertical.extent / contentHeight : Infinity,
+  );
+  const box: ScaledViewbox = {
+    x: bounds.x + contentWidth / 2 - (horizontal.start + horizontal.extent / 2) / scale,
+    y: bounds.y + contentHeight / 2 - (vertical.start + vertical.extent / 2) / scale,
+    width: container.width / scale,
+    height: container.height / scale,
+    scale,
+  };
+  return Object.values(box).every(Number.isFinite) && scale > 0 ? box : undefined;
+}
+
+function freeExtent(total: number, before: number, after: number): { start: number; extent: number } {
+  const extent = total - before - after;
+  return extent > 0 ? { start: before, extent } : { start: 0, extent: total };
+}
+
+/**
+ * The centre of the free rectangle (`container` minus `insets`) in pixels from the container's top
+ * left, where `fitViewbox` centres the content and keyboard creation places an element (guide
+ * §5.5). An axis the insets leave no room on centres in the whole container, as in `fitViewbox`.
+ * Returns `undefined` when the container is 0 × 0.
+ */
+export function freeRectCenter(container: Size, insets: Insets): Point | undefined {
+  if (!(container.width > 0 && container.height > 0)) return undefined;
+  const horizontal = freeExtent(container.width, insets.left, insets.right);
+  const vertical = freeExtent(container.height, insets.top, insets.bottom);
+  return {
+    x: horizontal.start + horizontal.extent / 2,
+    y: vertical.start + vertical.extent / 2,
+  };
+}
+
+/** What is open or shown when a fit runs (guide §5.9: every fit counts what is open right now). */
+export interface FitLayout {
+  container: Size;
+  host: ShellHost;
+  paletteRow: PaletteRow;
+  /** The problems pill is shown (only the web app reserves room for it). */
+  problemsVisible: boolean;
+  /**
+   * Web app: the zoom panel stands above the legal line (`bottom: 40px`) because the two would
+   * meet in the bottom row of a narrow container (`zoomRowRaised`); the bottom then keeps 92px as
+   * with the pill.
+   */
+  zoomRaised?: boolean | undefined;
+  /**
+   * Web app: the measured height of the legal line (`LEGAL_LINE_HEIGHT`, more where a narrow
+   * container wraps it); the raised bottom row stands on it. Default one line.
+   */
+  legalHeight?: number | undefined;
+  /** Rendered width of the open legend; `undefined` when it is closed or the modeler has none. */
+  legendWidth?: number | undefined;
+  /**
+   * The open inspector; `undefined` when closed. Above `SHELL.narrow` it is the side panel; up to it
+   * a bottom sheet whose top edge (`sheetTop`, px from the container top) must be measured.
+   */
+  inspector?: { sheetTop?: number | undefined } | undefined;
+}
+
+/**
+ * The fit insets of guide §5.9: top 88 (second row 140), sides 24, bottom 64 (web app with pill or
+ * with the zoom panel raised above the legal line 92, plus 20 per extra line of a wrapped legal line),
+ * right 324 with an open side inspector, left 12 + legend width + 24 with an open legend above
+ * `SHELL.veryNarrow`, bottom = distance to the sheet's top edge + 12 with an open bottom sheet.
+ */
+export function fitInsets(layout: FitLayout): Insets {
+  const { container, host, paletteRow, problemsVisible, zoomRaised, legendWidth, inspector } = layout;
+  const raisedBottomRow = host === "web" && (problemsVisible || zoomRaised === true);
+  const wrappedLegalLines = legalLineHeight(layout.legalHeight) - LEGAL_LINE_HEIGHT;
+  const insets: Insets = {
+    top: paletteRow === "second-row" ? SHELL.fitInsetTopSecondRow : SHELL.fitInsetTop,
+    right: SHELL.fitInsetSide,
+    bottom: raisedBottomRow ? SHELL.fitInsetBottomWeb + wrappedLegalLines : SHELL.fitInsetBottom,
+    left: SHELL.fitInsetSide,
+  };
+
+  const bottomSheetOpen = inspector !== undefined && container.width <= SHELL.narrow;
+  if (inspector !== undefined && !bottomSheetOpen) {
+    insets.right = SHELL.edge + SHELL.inspectorWidth + SHELL.fitInsetSide;
+  }
+  if (bottomSheetOpen) {
+    // Guide §5.11: the sheet hides zoom panel, pill and legend, so only the sheet itself counts.
+    insets.bottom =
+      inspector.sheetTop === undefined
+        ? SHELL.fitInsetBottom
+        : container.height - inspector.sheetTop + SHELL.edge;
+  } else if (legendWidth !== undefined && legendWidth > 0 && container.width > SHELL.veryNarrow) {
+    insets.left = SHELL.edge + legendWidth + SHELL.fitInsetSide;
+  }
+  return insets;
+}
+
+/** Relative tolerance of `sameView` (diagram-js rounds the transform to three decimals). */
+export const VIEW_TOLERANCE = 1e-3;
+
+/**
+ * True when two views are the same within `tolerance`: the scale and the translation in screen
+ * pixels (`x · scale`, `y · scale`) agree relative to `max(1, |value|)`. Width and height are
+ * ignored, so a container resize is never a difference.
+ */
+export function sameView(
+  a: Pick<ScaledViewbox, "x" | "y" | "scale">,
+  b: Pick<ScaledViewbox, "x" | "y" | "scale">,
+  tolerance: number = VIEW_TOLERANCE,
+): boolean {
+  const close = (first: number, second: number): boolean =>
+    Math.abs(first - second) <= tolerance * Math.max(1, Math.abs(first), Math.abs(second));
+  return (
+    close(a.scale, b.scale) && close(a.x * a.scale, b.x * b.scale) && close(a.y * a.scale, b.y * b.scale)
+  );
+}
+
+/**
+ * The view at `progress` (0…1) between two viewboxes of the same container: the scale is
+ * interpolated in log space, the centre linearly. Used per animation frame by the animated fit.
+ */
+export function interpolateViewbox(from: ScaledViewbox, to: ScaledViewbox, progress: number): ScaledViewbox {
+  if (!(progress > 0)) return { ...from };
+  if (progress >= 1) return { ...to };
+  const linear = (start: number, end: number): number => start + (end - start) * progress;
+  const scale =
+    from.scale > 0 && to.scale > 0
+      ? Math.exp(linear(Math.log(from.scale), Math.log(to.scale)))
+      : linear(from.scale, to.scale);
+  const centreX = linear(from.x + from.width / 2, to.x + to.width / 2);
+  const centreY = linear(from.y + from.height / 2, to.y + to.height / 2);
+  const width = linear(from.width * from.scale, to.width * to.scale) / scale;
+  const height = linear(from.height * from.scale, to.height * to.scale) / scale;
+  return { x: centreX - width / 2, y: centreY - height / 2, width, height, scale };
+}
+
+/** `--cd-ease`, `cubic-bezier(0.4, 0, 0.2, 1)`, as a function of time 0…1. */
+export function easeStandard(progress: number): number {
+  return STANDARD_EASING(progress);
+}
+
+const STANDARD_EASING = cubicBezier(0.4, 0, 0.2, 1);
+
+/** A CSS `cubic-bezier(x1, y1, x2, y2)` timing function (`x1`, `x2` within 0…1, so x(t) is monotone). */
+function cubicBezier(x1: number, y1: number, x2: number, y2: number): (progress: number) => number {
+  const polynomial = (first: number, second: number) => {
+    const c = 3 * first;
+    const b = 3 * (second - first) - c;
+    const a = 1 - c - b;
+    return {
+      at: (t: number): number => ((a * t + b) * t + c) * t,
+      slope: (t: number): number => (3 * a * t + 2 * b) * t + c,
+    };
+  };
+  const curveX = polynomial(x1, x2);
+  const curveY = polynomial(y1, y2);
+  const precision = 1e-7;
+
+  const parameterFor = (x: number): number => {
+    let t = x;
+    for (let iteration = 0; iteration < 8; iteration++) {
+      const error = curveX.at(t) - x;
+      if (Math.abs(error) < precision) return t;
+      const slope = curveX.slope(t);
+      if (Math.abs(slope) < 1e-6) break;
+      t -= error / slope;
+      if (t < 0 || t > 1) break;
+    }
+    // Newton left the curve or stalled on a flat stretch: bisection always converges.
+    let low = 0;
+    let high = 1;
+    t = x;
+    for (let iteration = 0; iteration < 60; iteration++) {
+      const value = curveX.at(t);
+      if (Math.abs(value - x) < precision) break;
+      if (value < x) low = t;
+      else high = t;
+      t = (low + high) / 2;
+    }
+    return t;
+  };
+
+  return (progress) => {
+    if (!(progress > 0)) return 0;
+    if (progress >= 1) return 1;
+    return curveY.at(parameterFor(progress));
+  };
+}