@miragon/modeler-shell 0.0.0-stage → 0.2.0

package/src/testing/harness.ts

@@ -0,0 +1,187 @@
+import type { Appearance, ColorThemeSetting, ShellHost, Size, Theme, ToastStatus } from "../core/index.js";
+import { createCases } from "./cases.js";
+import type { PageLike } from "./page.js";
+
+export interface OpenContext {
+  /** The page's viewport, which is the modeler's container in an own document. */
+  size: Size;
+  /**
+   * What the host requests before the modeler resolves it: in an IDE host the VS Code color theme
+   * (`vsCodeStubSearch` hands it to a page with the VS Code stub). For an embedded host the kit
+   * itself puts the foreign page's `<html>` in this mode once `open` resolved. In the web host the
+   * system's preference without a stored choice: the kit emulates `prefers-color-scheme` and
+   * `prefers-contrast` (`PageLike.emulateMedia`) before `open`, and `open` loads the page with an
+   * empty `localStorage` entry `miragon.darstellung`.
+   */
+  requested: Appearance;
+}
+
+/**
+ * How the kit makes the optional islands visible (`geometry`, `aria`) and puts the modeler into its
+ * invalid-file state (`readOnly`).
+ */
+export interface ShowHooks<P extends PageLike = PageLike> {
+  problems?: ((page: P) => Promise<void>) | undefined;
+  status?: ((page: P) => Promise<void>) | undefined;
+  legend?: ((page: P) => Promise<void>) | undefined;
+  inspector?: ((page: P) => Promise<void>) | undefined;
+  /**
+   * Puts the modeler into its invalid-file state the way its host does (an invalid import): a
+   * read-only canvas and the status box. The kit waits `INVALID_STATUS_DELAY_MS` afterwards.
+   */
+  invalid?: ((page: P) => Promise<void>) | undefined;
+  /**
+   * Web host: puts the page on its start screen, the way a fresh visit without a document shows
+   * it (`shell.setEmptyState(true)`); `open` itself loads a document.
+   */
+  emptyState?: ((page: P) => Promise<void>) | undefined;
+  /**
+   * Web and embedded hosts: shows `toast` through the modeler's `shell.toast`, with
+   * `{ label: toast.actionLabel, onSelect() {} }` as its action when `actionLabel` is given.
+   */
+  toast?: ((page: P, toast: ToastFixture) => Promise<void>) | undefined;
+}
+
+/** A toast the kit asks the `toast` hook to show (cases `toasts`, `geometry`). */
+export interface ToastFixture {
+  status: ToastStatus;
+  text: string;
+  actionLabel?: string | undefined;
+}
+
+/** A file the kit drops on the page (case `dropZone`), built in the page as `new File([text], name, { type })`. */
+export interface DropFixture {
+  name: string;
+  type: string;
+  text: string;
+}
+
+export interface DropFixtures {
+  /** A file `DropZoneOptions.accept` takes; dropping it on the start screen opens it (the card goes). */
+  accepted: DropFixture;
+  /** A file outside `accept`; dropping it opens nothing and shows a danger toast (or the modeler's `onReject`). */
+  rejected?: DropFixture | undefined;
+  /** `DropZoneOptions.multiple` of the modeler; default `false`, so a drag of two files is forbidden. */
+  multiple?: boolean | undefined;
+}
+
+/**
+ * A show hook by name: the islands `legend`, `inspector`, `problems`, `status`, the state
+ * `invalid`, and in the web column `emptyState` and `toast`.
+ */
+export type ShowHook = keyof ShowHooks;
+
+/**
+ * What a harness can lack: a show hook, the web app's drop zone (`drop`), or problems that point at
+ * an element (`problemSelection`: the modeler's diagnostics only name lines, so no row selects).
+ */
+export type AbsentFeature = ShowHook | "drop" | "problemSelection";
+
+export interface ShellConformanceHarness<P extends PageLike = PageLike> {
+  host: ShellHost;
+  /** The modes the modeler declares (static); the appearance case requests dark from `["light"]`. */
+  themes: readonly Theme[];
+  /** Load the modeler with the shell at `size`, as the host would with `requested`; resolve once the first import is done. */
+  open(page: P, context: OpenContext): Promise<void>;
+  /** Tear modeler and shell down through the page's own path; `undefined` skips the cleanup case. */
+  destroy?: ((page: P) => Promise<void>) | undefined;
+  /** CSS selector of the shell root; default `.cd-shell`. */
+  root?: string | undefined;
+  /** Hooks for the islands and states the modeler has; one that is neither given nor `absent` is reported as skipped. */
+  show?: ShowHooks<P> | undefined;
+  /** Web host: the files the `dropZone` case drops; without them (and not `absent`) it is skipped with `hook: "drop"`. */
+  drop?: DropFixtures | undefined;
+  /**
+   * The islands and states the modeler does not have. An absent hook is not reported as skipped,
+   * and `geometry` and `aria` assert that its island is never visible. Listing a hook that `show`
+   * also gives fails every case that uses it.
+   */
+  absent?: readonly AbsentFeature[] | undefined;
+  /** Container sizes of the geometry case; default wide 1280 × 900, narrow 720 × 700, very narrow 420 × 700. */
+  sizes?: readonly Size[] | undefined;
+}
+
+/** One part of a case the harness could not feed. */
+export interface ShellSkip {
+  /**
+   * The harness field that would feed it: a show hook, `destroy`, or `open` when the document it
+   * opens lacks what the case needs (a shape on the canvas).
+   */
+  hook: ShowHook | "drop" | "destroy" | "open";
+  reason: string;
+}
+
+export interface ShellCaseOutcome {
+  /** What the case could not (fully) run, one entry per missing harness field. */
+  skipped?: readonly ShellSkip[];
+}
+
+export interface ShellConformanceCase {
+  name: string;
+  run<P extends PageLike>(page: P, harness: ShellConformanceHarness<P>): Promise<ShellCaseOutcome | void>;
+}
+
+/**
+ * The cases: `geometry` (every `data-chrome` island ±1px, per host and breakpoint), `aria`
+ * (roles, names, `aria-expanded`/`-controls`/`-keyshortcuts`/`-disabled`, DOM order, no positive
+ * tabindex), `keys` (each chrome key acts exactly once; in the IDE host a `keydown` listener on
+ * `window` never fires for a handled key; unmodified `+`/`-` never zoom; select all acts on the
+ * canvas only), `create` (Enter on the first creating palette entry places one selected element in
+ * the free rectangle and focuses the canvas), `readOnly` (the invalid-file lock of guide §13.5),
+ * `appearance` (dark requested from a light-only modeler: nothing turns dark, `color-scheme` light
+ * everywhere, the canvas surround and the palette's tool colours from the roles; the web app's mode
+ * and its Appearance group) and `cleanup` (after `destroy` no shell element, class, attribute or
+ * key handling remains); then the web column's `webChrome`, `emptyState`, `toasts`,
+ * `problemsList` and `dropZone`, which assert in the other hosts that nothing of them shows.
+ */
+export function shellConformanceCases(): ShellConformanceCase[] {
+  return createCases();
+}
+
+/** Playwright's `test` (or any runner whose body receives `{ page }`). */
+export type ShellConformanceTest<P extends PageLike = PageLike> = (
+  name: string,
+  body: (fixtures: { page: P }) => Promise<void>,
+) => unknown;
+
+export interface RegisterShellConformanceOptions {
+  /** Default: `console.warn`, one line per case with its skips joined by "; ". */
+  onSkip?: ((caseName: string, skips: readonly ShellSkip[]) => void) | undefined;
+}
+
+/**
+ * The query string for a test page that installs the VS Code stub of
+ * `@miragon/modeler-shell/testing/vscode-stub` with `stubOptionsFromSearch(location.search)`:
+ * `theme=dark&kontrast=hoch`, plus the `colorTheme` setting and VS Code's reduce motion.
+ */
+export function vsCodeStubSearch(
+  requested: Appearance,
+  extra: { colorTheme?: ColorThemeSetting | undefined; reduceMotion?: boolean | undefined } = {},
+): string {
+  const query = new URLSearchParams({ theme: requested.theme });
+  if (requested.kontrast) query.set("kontrast", requested.kontrast);
+  if (extra.colorTheme) query.set("colorTheme", extra.colorTheme);
+  if (extra.reduceMotion) query.set("reduceMotion", "");
+  return query.toString();
+}
+
+/** Registers every case as `shell conformance: <name>`. */
+export function registerShellConformance<P extends PageLike>(
+  harness: ShellConformanceHarness<P>,
+  test: ShellConformanceTest<P>,
+  options: RegisterShellConformanceOptions = {},
+): void {
+  const onSkip =
+    options.onSkip ??
+    ((caseName: string, skips: readonly ShellSkip[]) => {
+      console.warn(
+        `@miragon/modeler-shell conformance: SKIPPED "${caseName}" (${harness.host} host): ${skips.map((skip) => skip.reason).join("; ")}`,
+      );
+    });
+  for (const conformanceCase of shellConformanceCases()) {
+    test(`shell conformance: ${conformanceCase.name}`, async ({ page }) => {
+      const outcome = await conformanceCase.run(page, harness);
+      if (outcome?.skipped && outcome.skipped.length > 0) onSkip(conformanceCase.name, outcome.skipped);
+    });
+  }
+}

package/src/testing/index.ts

@@ -0,0 +1,19 @@
+export type { PageLike } from "./page.js";
+export type { ChromeMeasurement, ExpectedBox, IslandBox } from "./geometry.js";
+export { GEOMETRY_TOLERANCE_PX, expectedChromeBoxes, measureChrome } from "./geometry.js";
+export type {
+  AbsentFeature,
+  DropFixture,
+  DropFixtures,
+  OpenContext,
+  RegisterShellConformanceOptions,
+  ShellCaseOutcome,
+  ShellConformanceCase,
+  ShellConformanceHarness,
+  ShellConformanceTest,
+  ShellSkip,
+  ShowHook,
+  ShowHooks,
+  ToastFixture,
+} from "./harness.js";
+export { registerShellConformance, shellConformanceCases, vsCodeStubSearch } from "./harness.js";

package/src/testing/page-tools.ts

@@ -0,0 +1,457 @@
+import type { Size } from "../core/index.js";
+import type { PageLike } from "./page.js";
+
+/*
+ * Everything here that is handed to `page.evaluate` runs in the browser: Playwright serializes the
+ * function source, so these functions must not reference anything outside their own body. They
+ * only collect facts; every judgement happens in Node (`checks.ts`, `geometry.ts`), where it is
+ * unit-tested. `installPageTools` puts the shared helpers and the recorders under one page global.
+ */
+
+/** A box relative to the shell root's padding box (where `position: absolute` islands anchor). */
+export interface RelativeBox {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** A `keydown` that reached the kit's listener on `window` (bubble phase), where VS Code's host page listens. */
+export interface RecordedKey {
+  key: string;
+  code: string;
+  ctrlKey: boolean;
+  metaKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+  defaultPrevented: boolean;
+}
+
+/** The facts the kit reads about one element. */
+export interface ElementFacts {
+  tag: string;
+  description: string;
+  attributes: Record<string, string>;
+  text: string;
+  visible: boolean;
+  /** The native `disabled` property (a disabled `<button>` loses focus, `aria-disabled` keeps it). */
+  disabled: boolean;
+}
+
+/** The helpers and recorders `installPageTools` keeps under the page global. */
+export interface PageTools {
+  /** `keydown`s that reached `window`, where VS Code's host page listens. */
+  keys: RecordedKey[];
+  /**
+   * `keydown`s seen on `document` after every listener registered before the kit's (the shell's,
+   * the modeler's), so `defaultPrevented` is final even where the shell stops the key.
+   */
+  documentKeys: RecordedKey[];
+  errors: string[];
+  injected: Element[];
+  cleanups: Array<() => void>;
+  armedRoot?: HTMLElement;
+  /** Clicks a kit listener counted on a control (the web app's primary action). */
+  clicks: number;
+  /** Changes of the document's mode the kit records while it switches the web app's appearance. */
+  modeWatch?: ModeWatch | undefined;
+  /** `newState` of every `beforetoggle` of the web app's toast stack since the kit started listening. */
+  toastToggles?: string[] | undefined;
+  frame(): Promise<void>;
+  settle(): Promise<void>;
+  visible(element: Element): boolean;
+  container(root: HTMLElement): Size;
+  box(element: Element, root: HTMLElement): RelativeBox;
+  describe(element: Element): string;
+  facts(element: Element): ElementFacts;
+}
+
+export type ToolWindow = Window & { __modelerShellConformance?: PageTools };
+
+/** One change of `<html>`'s mode or of its meta tags, with the animation frame it landed in. */
+export interface ModeChange {
+  part: "theme" | "kontrast" | "color-scheme" | "theme-color" | "no-transition";
+  value: string | null;
+  frame: number;
+}
+
+export interface ModeWatch {
+  changes: ModeChange[];
+  stop(): void;
+}
+
+/** Installs the in-page helpers once per document (idempotent; a navigation drops them). */
+export const installPageTools = (_: null): void => {
+  const scope = window as ToolWindow;
+  if (scope.__modelerShellConformance) return;
+  const modifierKeys = ["Control", "Meta", "Shift", "Alt", "AltGraph", "CapsLock", "Fn"];
+  const frame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  const borders = (element: Element) => {
+    const style = getComputedStyle(element);
+    return {
+      left: parseFloat(style.borderLeftWidth) || 0,
+      top: parseFloat(style.borderTopWidth) || 0,
+      right: parseFloat(style.borderRightWidth) || 0,
+      bottom: parseFloat(style.borderBottomWidth) || 0,
+    };
+  };
+  const visible = (element: Element): boolean => {
+    if (!element.isConnected) return false;
+    if (typeof element.checkVisibility === "function") {
+      if (!element.checkVisibility({ visibilityProperty: true })) return false;
+    } else {
+      if (element.closest("[hidden]")) return false;
+      for (let node: Element | null = element; node; node = node.parentElement) {
+        if (getComputedStyle(node).display === "none") return false;
+      }
+      if (getComputedStyle(element).visibility === "hidden") return false;
+    }
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  };
+  const describe = (element: Element): string => {
+    const id = element.id ? `#${element.id}` : "";
+    const classes = [...element.classList]
+      .slice(0, 3)
+      .map((name) => `.${name}`)
+      .join("");
+    const chrome = element.getAttribute("data-chrome");
+    return `${element.tagName.toLowerCase()}${id}${classes}${chrome ? `[data-chrome="${chrome}"]` : ""}`;
+  };
+  const tools: PageTools = {
+    keys: [],
+    documentKeys: [],
+    errors: [],
+    injected: [],
+    cleanups: [],
+    clicks: 0,
+    frame,
+    async settle() {
+      await frame();
+      await frame();
+      const running =
+        typeof document.getAnimations === "function"
+          ? document.getAnimations().filter((animation) => {
+              const end = animation.effect?.getComputedTiming().endTime;
+              return animation.playState === "running" && typeof end === "number" && Number.isFinite(end);
+            })
+          : [];
+      if (running.length > 0) {
+        await Promise.race([
+          Promise.allSettled(running.map((animation) => animation.finished)),
+          new Promise((resolve) => setTimeout(resolve, 2000)),
+        ]);
+      }
+      await frame();
+    },
+    visible,
+    container(root) {
+      const rect = root.getBoundingClientRect();
+      const border = borders(root);
+      return {
+        width: rect.width - border.left - border.right,
+        height: rect.height - border.top - border.bottom,
+      };
+    },
+    box(element, root) {
+      const rect = element.getBoundingClientRect();
+      const origin = root.getBoundingClientRect();
+      const border = borders(root);
+      return {
+        left: rect.left - origin.left - border.left,
+        top: rect.top - origin.top - border.top,
+        width: rect.width,
+        height: rect.height,
+      };
+    },
+    describe,
+    facts(element) {
+      const attributes: Record<string, string> = {};
+      for (const name of element.getAttributeNames()) attributes[name] = element.getAttribute(name) ?? "";
+      return {
+        tag: element.tagName.toLowerCase(),
+        description: describe(element),
+        attributes,
+        text: (element.textContent ?? "").replace(/\s+/g, " ").trim(),
+        visible: visible(element),
+        disabled: Boolean((element as HTMLButtonElement).disabled),
+      };
+    },
+  };
+  const recorder = (into: RecordedKey[]) => (event: KeyboardEvent) => {
+    if (modifierKeys.includes(event.key)) return;
+    into.push({
+      key: event.key,
+      code: event.code,
+      ctrlKey: event.ctrlKey,
+      metaKey: event.metaKey,
+      shiftKey: event.shiftKey,
+      altKey: event.altKey,
+      defaultPrevented: event.defaultPrevented,
+    });
+  };
+  document.addEventListener("keydown", recorder(tools.documentKeys));
+  window.addEventListener("keydown", recorder(tools.keys));
+  window.addEventListener("error", (event) => {
+    tools.errors.push(event.message || String(event.error));
+  });
+  window.addEventListener("unhandledrejection", (event) => {
+    tools.errors.push(`unhandled rejection: ${String(event.reason)}`);
+  });
+  scope.__modelerShellConformance = tools;
+};
+
+/** Runs `pageFunction` in the page after making sure the helpers are installed. */
+export async function inPage<Arg, Result>(
+  page: PageLike,
+  pageFunction: (arg: Arg) => Result | Promise<Result>,
+  arg: Arg,
+): Promise<Result> {
+  await page.evaluate(installPageTools, null);
+  return page.evaluate(pageFunction, arg);
+}
+
+/** Two frames plus every finite running animation (pop-ins, slide-ins), capped at 2s. */
+export const settleInPage = (_: null): Promise<void> =>
+  (window as ToolWindow).__modelerShellConformance!.settle();
+
+export function settle(page: PageLike): Promise<void> {
+  return inPage(page, settleInPage, null);
+}
+
+/** The controls the kit hovers, clicks or focuses, found inside the shell root. */
+export type ChromeTarget =
+  | "menu"
+  | "palette-entry"
+  | "palette-tab-stop"
+  | "zoom-out"
+  | "zoom-actual"
+  | "zoom-in"
+  | "zoom-fit"
+  | "canvas"
+  | "primary"
+  | "pill";
+
+export const CHROME_TARGET_SELECTORS: Readonly<Record<ChromeTarget, string>> = {
+  menu: '[data-chrome="menu"]',
+  "palette-entry": '[data-chrome="palette"] [data-action]',
+  "palette-tab-stop": '[data-chrome="palette"] [data-action][tabindex="0"]',
+  "zoom-out": '[data-chrome="zoom"] [data-zoom="out"]',
+  "zoom-actual": '[data-chrome="zoom"] [data-zoom="actual"]',
+  "zoom-in": '[data-chrome="zoom"] [data-zoom="in"]',
+  "zoom-fit": '[data-chrome="zoom"] [data-zoom="fit"]',
+  canvas: ".djs-container > svg",
+  primary: '[data-chrome="primary"]',
+  pill: '[data-chrome="problems"]',
+};
+
+export interface TargetFacts {
+  /** Viewport coordinates of the centre, for `page.mouse`. */
+  client: { x: number; y: number };
+  box: RelativeBox;
+  /** `aria-label`, else the text. */
+  label: string;
+}
+
+/** The first visible match of `selector` inside the root; `null` when there is none. */
+export const targetProbe = ({ root, selector }: { root: string; selector: string }): TargetFacts | null => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const rootElement = document.querySelector<HTMLElement>(root);
+  if (!rootElement) return null;
+  const element = [...rootElement.querySelectorAll(selector)].find((candidate) => tools.visible(candidate));
+  if (!element) return null;
+  const rect = element.getBoundingClientRect();
+  return {
+    client: { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 },
+    box: tools.box(element, rootElement),
+    label: (element.getAttribute("aria-label") ?? element.textContent ?? "").replace(/\s+/g, " ").trim(),
+  };
+};
+
+export async function findTarget(
+  page: PageLike,
+  root: string,
+  target: ChromeTarget,
+): Promise<TargetFacts | null> {
+  return inPage(page, targetProbe, { root, selector: CHROME_TARGET_SELECTORS[target] });
+}
+
+/** Focuses the first match of `selector` inside the root; the description of the focused element. */
+export const focusProbe = ({ root, selector }: { root: string; selector: string }): string | null => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const element = document.querySelector(root)?.querySelector<HTMLElement | SVGElement>(selector);
+  if (!element) return null;
+  element.focus();
+  return document.activeElement === element ? tools.describe(element) : null;
+};
+
+export async function focusTarget(
+  page: PageLike,
+  root: string,
+  target: ChromeTarget,
+): Promise<string | null> {
+  return inPage(page, focusProbe, { root, selector: CHROME_TARGET_SELECTORS[target] });
+}
+
+/** A visible popup with `role` inside the root (the dropdown, the chrome tooltip). */
+export interface OverlayFacts {
+  box: RelativeBox;
+  text: string;
+  /** How many visible elements carry the role. */
+  count: number;
+  id: string;
+}
+
+export const overlayProbe = ({ root, role }: { root: string; role: string }): OverlayFacts | null => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const rootElement = document.querySelector<HTMLElement>(root);
+  if (!rootElement) return null;
+  const shown = [...rootElement.querySelectorAll(`[role="${role}"]`)].filter((element) =>
+    tools.visible(element),
+  );
+  const first = shown[0];
+  if (!first) return null;
+  return {
+    box: tools.box(first, rootElement),
+    text: (first.textContent ?? "").replace(/\s+/g, " ").trim(),
+    count: shown.length,
+    id: first.id,
+  };
+};
+
+export async function findOverlay(
+  page: PageLike,
+  root: string,
+  role: "menu" | "tooltip",
+): Promise<OverlayFacts | null> {
+  return inPage(page, overlayProbe, { root, role });
+}
+
+export interface PressFacts {
+  /** The readout as a whole percentage; `null` without a readout. */
+  zoom: number | null;
+  keys: RecordedKey[];
+  documentKeys: RecordedKey[];
+}
+
+/** After a key press: settles, then reads the readout and takes the keys `window` and `document` saw. */
+export const afterPressProbe = async ({ root }: { root: string }): Promise<PressFacts> => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  await tools.settle();
+  const readout = document
+    .querySelector(root)
+    ?.querySelector('[data-chrome="zoom"] [data-zoom="actual"]')?.textContent;
+  const digits = (readout ?? "").replace(/[^0-9]/g, "");
+  return {
+    zoom: digits ? Number(digits) : null,
+    keys: tools.keys.splice(0),
+    documentKeys: tools.documentKeys.splice(0),
+  };
+};
+
+/** Drops what `window` saw so far. */
+export const clearKeysProbe = (_: null): void => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  tools.keys.splice(0);
+  tools.documentKeys.splice(0);
+};
+
+export type InjectedKind = "input" | "textarea" | "contenteditable" | "modal" | "popover" | "focus-target";
+
+/**
+ * Adds a stand-in for what modelers render inside the shell (text fields: an input, a textarea, an
+ * editable label; a modal dialog, a popover, a plain focus target), inside the root or, once it is
+ * gone, the body; focuses it.
+ */
+export const injectProbe = ({ root, kind }: { root: string; kind: InjectedKind }): boolean => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const parent = document.querySelector(root) ?? tools.armedRoot ?? document.body;
+  const host = parent.isConnected ? parent : document.body;
+  const element =
+    kind === "input" || kind === "textarea"
+      ? document.createElement(kind)
+      : (document.createElement("div") as HTMLElement);
+  element.setAttribute("data-modeler-shell-conformance", kind);
+  element.style.cssText = "position:absolute;left:0;top:0;width:40px;height:20px;";
+  if (kind === "modal" || kind === "popover") {
+    element.setAttribute("role", "dialog");
+    element.setAttribute("aria-label", "Conformance stand-in");
+    if (kind === "modal") element.setAttribute("aria-modal", "true");
+  }
+  if (kind === "contenteditable") element.setAttribute("contenteditable", "true");
+  else if (kind !== "input" && kind !== "textarea") element.tabIndex = -1;
+  host.append(element);
+  tools.injected.push(element);
+  element.focus();
+  return document.activeElement === element;
+};
+
+export const removeInjectedProbe = (_: null): void => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  for (const element of tools.injected.splice(0)) element.remove();
+  for (const cleanup of tools.cleanups.splice(0)) cleanup();
+};
+
+/** Makes the canvas `<svg>` handle `key` (`preventDefault`), as a modeler's own canvas binding would. */
+export const canvasHandlesProbe = ({ root, key }: { root: string; key: string }): boolean => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const svg = document.querySelector(root)?.querySelector(".djs-container > svg");
+  if (!svg) return false;
+  const listener = (event: Event) => {
+    if ((event as KeyboardEvent).key === key) event.preventDefault();
+  };
+  svg.addEventListener("keydown", listener);
+  tools.cleanups.push(() => svg.removeEventListener("keydown", listener));
+  return true;
+};
+
+/** Remembers the root right before `destroy` (its class is gone afterwards) and clears the recorders. */
+export const armCleanupProbe = ({ root }: { root: string }): boolean => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const rootElement = document.querySelector<HTMLElement>(root);
+  if (rootElement) tools.armedRoot = rootElement;
+  tools.errors.splice(0);
+  tools.keys.splice(0);
+  tools.documentKeys.splice(0);
+  return Boolean(rootElement);
+};
+
+/** What the shell left behind after `destroy`. */
+export interface LeftoverFacts {
+  /** Elements (other than `<html>`) with a `cd-shell*` class. */
+  classedElements: string[];
+  /** `cd-shell*` classes on `<html>`. */
+  documentClasses: string[];
+  /** Elements still carrying `data-chrome`. */
+  chromeElements: string[];
+  /** The remembered root's `class` and attributes. */
+  rootClasses: string[];
+  rootAttributes: string[];
+  errors: string[];
+}
+
+export const leftoverProbe = (_: null): LeftoverFacts => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const ours = (element: Element) => element.hasAttribute("data-modeler-shell-conformance");
+  const shellClass = (name: string) => name.startsWith("cd-shell");
+  const root = tools.armedRoot;
+  return {
+    classedElements: [...document.querySelectorAll("[class]")]
+      .filter((element) => element !== document.documentElement && !ours(element))
+      .filter((element) => [...element.classList].some(shellClass))
+      .map((element) => tools.describe(element)),
+    documentClasses: [...document.documentElement.classList].filter(shellClass),
+    chromeElements: [...document.querySelectorAll("[data-chrome]")].map((element) => tools.describe(element)),
+    rootClasses: root ? [...root.classList].filter(shellClass) : [],
+    rootAttributes: root ? root.getAttributeNames() : [],
+    errors: [...tools.errors],
+  };
+};
+
+/** Puts a foreign page's `<html>` in a mode, as a themed host page around an embedded modeler. */
+export const hostPageModeProbe = ({ theme, kontrast }: { theme: string; kontrast: string | null }): void => {
+  const html = document.documentElement;
+  html.setAttribute("data-cd-theme", theme);
+  if (kontrast) html.setAttribute("data-cd-kontrast", kontrast);
+  else html.removeAttribute("data-cd-kontrast");
+};

package/src/testing/page.ts

@@ -0,0 +1,27 @@
+/**
+ * The part of Playwright's `Page` the kit drives, typed structurally: the kit has no runtime
+ * dependency on Playwright, the consumer's e2e suite passes its own `page`.
+ */
+export interface PageLike {
+  evaluate<R, Arg>(pageFunction: (arg: Arg) => R | Promise<R>, arg: Arg): Promise<R>;
+  setViewportSize(size: { width: number; height: number }): Promise<void>;
+  keyboard: { press(key: string): Promise<void> };
+  mouse: {
+    click(x: number, y: number): Promise<void>;
+    dblclick(x: number, y: number): Promise<void>;
+    move(x: number, y: number): Promise<void>;
+    down(): Promise<void>;
+    up(): Promise<void>;
+  };
+  waitForTimeout(timeout: number): Promise<void>;
+  /**
+   * Playwright's `page.emulateMedia`; the web-host cases need it for the system's mode and contrast
+   * (`appearance`) and report a skip with `hook: "open"` without it.
+   */
+  emulateMedia?(options: {
+    colorScheme?: "light" | "dark" | "no-preference" | null;
+    contrast?: "more" | "no-preference" | null;
+    reducedMotion?: "reduce" | "no-preference" | null;
+    forcedColors?: "active" | "none" | null;
+  }): Promise<void>;
+}