@miragon/modeler-shell 0.0.0-stage → 0.1.0

package/src/core/fit.ts

@@ -0,0 +1,205 @@
+import { SHELL } from "./sizes.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;
+  /** 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 92),
+ * 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, legendWidth, inspector } = layout;
+  const insets: Insets = {
+    top: paletteRow === "second-row" ? SHELL.fitInsetTopSecondRow : SHELL.fitInsetTop,
+    right: SHELL.fitInsetSide,
+    bottom: host === "web" && problemsVisible ? SHELL.fitInsetBottomWeb : 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));
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,84 @@
+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,
+  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";

package/src/core/keymap.ts

@@ -0,0 +1,275 @@
+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;
+}
+
+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).
+ * 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) {
+    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`;
+  }
+}
+
+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 };
+}