@miragon/modeler-shell 0.0.0-stage → 0.1.0

package/src/testing/geometry.ts

@@ -0,0 +1,472 @@
+import {
+  CHROME_ISLANDS,
+  PALETTE_CLEARANCE,
+  SHELL,
+  type ChromeIsland,
+  type Insets,
+  type PaletteRow,
+  type ShellHost,
+  type Size,
+} from "../core/index.js";
+import type { PageLike } from "./page.js";
+import { inPage, type RelativeBox, type ToolWindow } from "./page-tools.js";
+
+/** Every island box must match within this many pixels (guide §13.4). */
+export const GEOMETRY_TOLERANCE_PX = 1;
+
+/**
+ * `getBoundingClientRect()` relative to the shell root's padding box, where its absolutely
+ * positioned islands anchor (a border on the root, as in a framed foreign page, does not count).
+ */
+export interface IslandBox {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+export interface ChromeMeasurement {
+  container: Size;
+  /** From the root's `data-palette` attribute. */
+  paletteRow: PaletteRow;
+  /** The visible islands, found by `[data-chrome]`. */
+  islands: Partial<Record<ChromeIsland, IslandBox>>;
+  /** `[data-legend="open"]`, `[data-inspector="open"]`, `[data-problems="shown"]` on the root. */
+  open: { legend: boolean; inspector: boolean; problems: boolean };
+}
+
+/** Constraints of one island; every given field must hold within `GEOMETRY_TOLERANCE_PX`. */
+export interface ExpectedBox {
+  left?: number;
+  top?: number;
+  right?: number;
+  bottom?: number;
+  width?: number;
+  height?: number;
+  /** Horizontal centre relative to the root. */
+  centerX?: number;
+}
+
+export const DEFAULT_ROOT = ".cd-shell";
+
+/** `[−] [NN%] [+] | [Fit]` with a 56px readout (guide §5.1, §5.8): 1+3+32+2+56+2+32+2+5+2+32+3+1. */
+export const ZOOM_PANEL_WIDTH = 173;
+
+/** Height of the web app's legal line under the bottom-left stack (guide §5.10). */
+const LEGAL_LINE = 20;
+
+/** Minimum width of the legend card (guide §5.10). */
+const LEGEND_MIN_WIDTH = 184;
+
+const STATUS_MAX_WIDTH = 560;
+const DROPDOWN_MAX_WIDTH = 320;
+const TOOLTIP_MAX_WIDTH = 280;
+const SHEET_MAX_HEIGHT_SHARE = 0.45;
+
+type MeasureResult = { error: string } | (ChromeMeasurement & { duplicates: string[] });
+
+const measureProbe = ({ root, islands }: { root: string; islands: readonly string[] }): MeasureResult => {
+  const tools = (window as ToolWindow).__modelerShellConformance!;
+  const rootElement = document.querySelector<HTMLElement>(root);
+  if (!rootElement) return { error: `no element matches the shell root selector "${root}"` };
+  const boxes: Partial<Record<string, RelativeBox>> = {};
+  const duplicates: string[] = [];
+  for (const element of rootElement.querySelectorAll("[data-chrome]")) {
+    const name = element.getAttribute("data-chrome") ?? "";
+    if (!islands.includes(name) || !tools.visible(element)) continue;
+    if (boxes[name]) {
+      duplicates.push(name);
+      continue;
+    }
+    boxes[name] = tools.box(element, rootElement);
+  }
+  return {
+    container: tools.container(rootElement),
+    paletteRow: rootElement.getAttribute("data-palette") === "second-row" ? "second-row" : "top",
+    islands: boxes,
+    open: {
+      legend: rootElement.getAttribute("data-legend") === "open",
+      inspector: rootElement.getAttribute("data-inspector") === "open",
+      problems: rootElement.getAttribute("data-problems") === "shown",
+    },
+    duplicates,
+  };
+};
+
+/** Measures the islands of the shell under `root` (default `.cd-shell`) in the page. */
+export async function measureChrome(page: PageLike, root: string = DEFAULT_ROOT): Promise<ChromeMeasurement> {
+  const result = await inPage(page, measureProbe, { root, islands: CHROME_ISLANDS });
+  if ("error" in result) throw new Error(`@miragon/modeler-shell conformance: ${result.error}`);
+  if (result.duplicates.length > 0) {
+    const names = [...new Set(result.duplicates)].map((name) => `[data-chrome="${name}"]`).join(", ");
+    throw new Error(`@miragon/modeler-shell conformance: more than one visible ${names}`);
+  }
+  return {
+    container: result.container,
+    paletteRow: result.paletteRow,
+    islands: result.islands,
+    open: result.open,
+  };
+}
+
+/** Upper and lower limits the guide gives as "at least" and "at most" (guide §5.4 to §5.15). */
+export interface BoxLimits {
+  minWidth?: number;
+  maxWidth?: number;
+  maxHeight?: number;
+  minLeft?: number;
+  minRight?: number;
+  minBottom?: number;
+}
+
+/** What the guide expects of the chrome in a measured state. */
+export interface ChromeExpectations {
+  boxes: Partial<Record<ChromeIsland, ExpectedBox>>;
+  limits: Partial<Record<ChromeIsland, BoxLimits>>;
+  /** Islands that must be visible. */
+  required: ChromeIsland[];
+  /** Islands that must not be visible, with the rule that hides them. */
+  hidden: Partial<Record<ChromeIsland, string>>;
+}
+
+function isNarrow(container: Size): boolean {
+  return container.width <= SHELL.narrow;
+}
+
+function isVeryNarrow(container: Size): boolean {
+  return container.width <= SHELL.veryNarrow;
+}
+
+/** The open inspector is a bottom sheet up to `SHELL.narrow` (guide §5.11). */
+function sheetOpen(measurement: ChromeMeasurement): boolean {
+  return measurement.open.inspector && isNarrow(measurement.container);
+}
+
+/** The anchors and limits of guide §5.2 to §5.15 for `measurement` in `host`. */
+export function chromeExpectations(measurement: ChromeMeasurement, host: ShellHost): ChromeExpectations {
+  const { container, islands, open, paletteRow } = measurement;
+  const { edge, gap, row, free, inspectorWidth } = SHELL;
+  const web = host === "web";
+  const secondRow = paletteRow === "second-row";
+  const sheet = sheetOpen(measurement);
+  const sideInspector = open.inspector && !isNarrow(container);
+  const boxes: Partial<Record<ChromeIsland, ExpectedBox>> = {};
+  const limits: Partial<Record<ChromeIsland, BoxLimits>> = {};
+  const hidden: Partial<Record<ChromeIsland, string>> = {};
+  const required: ChromeIsland[] = ["menu", "palette"];
+
+  boxes.menu = { left: edge, top: edge, width: row, height: row };
+
+  boxes.palette = { top: secondRow ? free : edge, height: row, centerX: container.width / 2 };
+  const menu = islands.menu;
+  limits.palette = secondRow
+    ? { maxWidth: container.width - 2 * edge }
+    : menu
+      ? { minLeft: menu.left + menu.width + PALETTE_CLEARANCE }
+      : {};
+
+  if (sheet) {
+    const reason = "hidden while the inspector is a bottom sheet (guide §5.11)";
+    hidden.zoom = reason;
+    hidden.problems = reason;
+    hidden.legend = reason;
+  } else {
+    required.push("zoom");
+    boxes.zoom = { right: edge, bottom: edge, width: ZOOM_PANEL_WIDTH, height: row };
+    const stackBase = web ? edge + LEGAL_LINE + gap : edge;
+    if (islands.problems) boxes.problems = { left: edge, bottom: stackBase, height: row };
+    if (islands.legend) {
+      const besidePill = open.problems ? stackBase + row + gap : stackBase;
+      const bottom = isVeryNarrow(container) ? Math.max(besidePill, edge + row + gap) : besidePill;
+      boxes.legend = { left: edge, bottom };
+      limits.legend = { minWidth: LEGEND_MIN_WIDTH };
+    }
+  }
+
+  if (islands.inspector) {
+    if (sheet) {
+      boxes.inspector = { left: edge, right: edge, bottom: edge };
+      limits.inspector = { maxHeight: container.height * SHEET_MAX_HEIGHT_SHARE };
+    } else {
+      boxes.inspector = { top: free, right: edge, width: inspectorWidth };
+      limits.inspector = { minBottom: free };
+    }
+  }
+
+  if (islands.status) {
+    const strip = sideInspector ? container.width - edge - inspectorWidth : container.width;
+    boxes.status = { top: secondRow ? free + row + edge : free, centerX: strip / 2 };
+    limits.status = {
+      minLeft: edge,
+      maxWidth: Math.min(STATUS_MAX_WIDTH, container.width - 2 * edge),
+    };
+  }
+
+  if (web) {
+    if (islands.primary) boxes.primary = { top: edge, right: edge, height: row };
+  } else {
+    hidden.primary = "the top right stays empty in IDE and embedded hosts (guide §5.7)";
+  }
+
+  return { boxes, limits, required, hidden };
+}
+
+/** The boxes guide §5.2–§5.12 expects for what was measured (anchors per host and breakpoint). */
+export function expectedChromeBoxes(
+  measurement: ChromeMeasurement,
+  host: ShellHost,
+): Partial<Record<ChromeIsland, ExpectedBox>> {
+  return chromeExpectations(measurement, host).boxes;
+}
+
+const round = (value: number): number => Math.round(value * 10) / 10;
+
+function sides(box: IslandBox, container: Size): Required<ExpectedBox> {
+  return {
+    left: box.left,
+    top: box.top,
+    right: container.width - box.left - box.width,
+    bottom: container.height - box.top - box.height,
+    width: box.width,
+    height: box.height,
+    centerX: box.left + box.width / 2,
+  };
+}
+
+/** Every field of `expected` that `box` misses by more than `tolerance`, as readable problems. */
+export function boxMismatches(
+  name: string,
+  box: IslandBox,
+  expected: ExpectedBox,
+  container: Size,
+  tolerance: number = GEOMETRY_TOLERANCE_PX,
+): string[] {
+  const actual = sides(box, container);
+  return (Object.keys(expected) as Array<keyof ExpectedBox>).flatMap((field) => {
+    const want = expected[field];
+    if (want === undefined) return [];
+    const have = actual[field];
+    return Math.abs(have - want) > tolerance + 1e-6
+      ? [`${name}: ${field} is ${round(have)}px, expected ${round(want)}px (±${tolerance}px)`]
+      : [];
+  });
+}
+
+/** Every limit `box` breaks by more than `tolerance`. */
+export function limitViolations(
+  name: string,
+  box: IslandBox,
+  limits: BoxLimits,
+  container: Size,
+  tolerance: number = GEOMETRY_TOLERANCE_PX,
+): string[] {
+  const actual = sides(box, container);
+  const problems: string[] = [];
+  const atLeast = (field: string, have: number, limit: number | undefined) => {
+    if (limit !== undefined && have < limit - tolerance - 1e-6) {
+      problems.push(`${name}: ${field} is ${round(have)}px, at least ${round(limit)}px expected`);
+    }
+  };
+  const atMost = (field: string, have: number, limit: number | undefined) => {
+    if (limit !== undefined && have > limit + tolerance + 1e-6) {
+      problems.push(`${name}: ${field} is ${round(have)}px, at most ${round(limit)}px expected`);
+    }
+  };
+  atLeast("width", actual.width, limits.minWidth);
+  atMost("width", actual.width, limits.maxWidth);
+  atMost("height", actual.height, limits.maxHeight);
+  atLeast("left", actual.left, limits.minLeft);
+  atLeast("right", actual.right, limits.minRight);
+  atLeast("bottom", actual.bottom, limits.minBottom);
+  return problems;
+}
+
+/**
+ * Every deviation of a measured state from guide §5.2 to §5.15: missing and unexpected islands,
+ * boxes and limits, the palette row decision and the root's state attributes.
+ */
+export function geometryProblems(
+  measurement: ChromeMeasurement,
+  host: ShellHost,
+  tolerance: number = GEOMETRY_TOLERANCE_PX,
+): string[] {
+  const { container, islands, open, paletteRow } = measurement;
+  const expectations = chromeExpectations(measurement, host);
+  const problems: string[] = [];
+  const sheet = sheetOpen(measurement);
+
+  for (const name of expectations.required) {
+    if (!islands[name]) problems.push(`${name}: [data-chrome="${name}"] is missing or not visible`);
+  }
+  for (const name of CHROME_ISLANDS) {
+    const box = islands[name];
+    if (!box) continue;
+    const expected = expectations.boxes[name];
+    if (!expected) {
+      const reason = expectations.hidden[name] ?? "no anchor of the guide applies";
+      problems.push(`${name}: visible, but ${reason}`);
+      continue;
+    }
+    problems.push(...boxMismatches(name, box, expected, container, tolerance));
+    const limits = expectations.limits[name];
+    if (limits) problems.push(...limitViolations(name, box, limits, container, tolerance));
+  }
+
+  if (isNarrow(container) && paletteRow !== "second-row") {
+    problems.push(
+      `palette: data-palette="${paletteRow}" in a ${round(container.width)}px wide container; up to ${SHELL.narrow}px it is "second-row" (guide §5.15)`,
+    );
+  }
+  const palette = islands.palette;
+  const menu = islands.menu;
+  if (paletteRow === "second-row" && !isNarrow(container) && palette && menu) {
+    const clipped = palette.width >= container.width - 2 * SHELL.edge - tolerance;
+    const topRowLeft = (container.width - palette.width) / 2;
+    if (!clipped && topRowLeft >= menu.left + menu.width + PALETTE_CLEARANCE + tolerance) {
+      problems.push(
+        `palette: in the second row although the top row keeps ${round(topRowLeft - menu.left - menu.width)}px to the menu trigger (at least ${PALETTE_CLEARANCE}px suffice, guide §5.15)`,
+      );
+    }
+  }
+
+  const state = (island: ChromeIsland, flag: boolean, attribute: string, hiddenBySheet: boolean) => {
+    const shown = Boolean(islands[island]);
+    if (flag && !shown && !hiddenBySheet) {
+      problems.push(`${island}: the root carries ${attribute}, but the island is not visible`);
+    }
+    if (!flag && shown) problems.push(`${island}: visible, but the root lacks ${attribute}`);
+  };
+  state("problems", open.problems, 'data-problems="shown"', sheet);
+  state("legend", open.legend, 'data-legend="open"', sheet);
+  state("inspector", open.inspector, 'data-inspector="open"', false);
+
+  return problems;
+}
+
+/**
+ * The fit insets of guide §5.9 for what was measured, recomputed from the guide's table: top 88
+ * (second row 140), sides 24, bottom 64 (web app with the pill 92); right 12 + 288 + 24 with a side
+ * inspector; left 12 + legend width + 24 with an open legend in a container wider than 440px; with
+ * a bottom sheet the bottom is the distance to its top edge plus 12, and the legend does not count.
+ */
+export function expectedFitInsets(measurement: ChromeMeasurement, host: ShellHost): Insets {
+  const { container, islands, open, paletteRow } = measurement;
+  const insets: Insets = {
+    top: paletteRow === "second-row" ? SHELL.fitInsetTopSecondRow : SHELL.fitInsetTop,
+    right: SHELL.fitInsetSide,
+    bottom: host === "web" && open.problems ? SHELL.fitInsetBottomWeb : SHELL.fitInsetBottom,
+    left: SHELL.fitInsetSide,
+  };
+  if (sheetOpen(measurement)) {
+    const sheet = islands.inspector;
+    insets.bottom = sheet ? container.height - sheet.top + SHELL.edge : SHELL.fitInsetBottom;
+    return insets;
+  }
+  if (open.inspector) insets.right = SHELL.edge + SHELL.inspectorWidth + SHELL.fitInsetSide;
+  const legend = islands.legend;
+  if (open.legend && legend && legend.width > 0 && container.width > SHELL.veryNarrow) {
+    insets.left = SHELL.edge + legend.width + SHELL.fitInsetSide;
+  }
+  return insets;
+}
+
+/** A rectangle relative to the shell root's padding box, by its edges. */
+export interface Rectangle {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+/**
+ * The free rectangle of guide §5.9: the container minus `expectedFitInsets`. Where the insets
+ * leave no room on an axis, that axis spans the whole container (as the fit centres there).
+ */
+export function freeRectangle(measurement: ChromeMeasurement, host: ShellHost): Rectangle {
+  const { container } = measurement;
+  const insets = expectedFitInsets(measurement, host);
+  const horizontal = container.width - insets.left - insets.right > 0;
+  const vertical = container.height - insets.top - insets.bottom > 0;
+  return {
+    left: horizontal ? insets.left : 0,
+    top: vertical ? insets.top : 0,
+    right: horizontal ? container.width - insets.right : container.width,
+    bottom: vertical ? container.height - insets.bottom : container.height,
+  };
+}
+
+/** Where the dropdown opens (guide §5.4): under the trigger, at least 248px, inside the container. */
+export function dropdownProblems(
+  box: IslandBox,
+  container: Size,
+  tolerance = GEOMETRY_TOLERANCE_PX,
+): string[] {
+  const { edge, gap, row, menuMinWidth } = SHELL;
+  return [
+    ...boxMismatches("dropdown", box, { top: edge + row + gap, left: edge }, container, tolerance),
+    ...limitViolations(
+      "dropdown",
+      box,
+      {
+        minWidth: menuMinWidth,
+        maxWidth: Math.min(DROPDOWN_MAX_WIDTH, container.width - 2 * edge),
+        minBottom: edge,
+      },
+      container,
+      tolerance,
+    ),
+  ];
+}
+
+/** Which island a tooltip belongs to decides its row (guide §5.6). */
+export type TooltipRow = "top" | "second-row" | "bottom";
+
+/**
+ * Where the chrome tooltip of a control stands (guide §5.6): 8px below the top row (`top: 60px`)
+ * or the second row (`top: 112px`), 8px above the bottom row (`bottom: 60px`); centred on its
+ * control and shifted to keep 12px to the sides.
+ */
+export function tooltipProblems(
+  tooltip: IslandBox,
+  anchor: IslandBox,
+  row: TooltipRow,
+  container: Size,
+  tolerance = GEOMETRY_TOLERANCE_PX,
+): string[] {
+  const { edge, gap, row: rowHeight, free } = SHELL;
+  const clamp = (centred: number) =>
+    Math.max(edge, Math.min(centred, container.width - edge - tooltip.width));
+  const expectedAt = (left: number): ExpectedBox =>
+    row === "bottom"
+      ? { left, bottom: edge + rowHeight + gap }
+      : { left, top: (row === "top" ? edge : free) + rowHeight + gap };
+  let mismatches = boxMismatches(
+    "tooltip",
+    tooltip,
+    expectedAt(clamp(anchor.left + anchor.width / 2 - tooltip.width / 2)),
+    container,
+    tolerance,
+  );
+  // Guide §5.15 reads "mittig im Container" for the second row; until the guide settles whether
+  // that means the container or the entry, either centre conforms.
+  if (row === "second-row" && mismatches.length > 0) {
+    const inContainer = boxMismatches(
+      "tooltip",
+      tooltip,
+      expectedAt(clamp(container.width / 2 - tooltip.width / 2)),
+      container,
+      tolerance,
+    );
+    if (inContainer.length === 0) mismatches = inContainer;
+  }
+  return [
+    ...mismatches,
+    ...limitViolations(
+      "tooltip",
+      tooltip,
+      { minLeft: edge, minRight: edge, maxWidth: Math.min(TOOLTIP_MAX_WIDTH, container.width - 2 * edge) },
+      container,
+      tolerance,
+    ),
+  ];
+}

package/src/testing/harness.ts

@@ -0,0 +1,138 @@
+import type { Appearance, ColorThemeSetting, ShellHost, Size, Theme } 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.
+   */
+  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;
+}
+
+/** A show hook by name: the islands `legend`, `inspector`, `problems`, `status` and the state `invalid`. */
+export type ShowHook = keyof ShowHooks;
+
+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;
+  /**
+   * 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 ShowHook[] | 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 | "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) and `cleanup` (after
+ * `destroy` no shell element, class, attribute or key handling remains).
+ */
+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,15 @@
+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 {
+  OpenContext,
+  RegisterShellConformanceOptions,
+  ShellCaseOutcome,
+  ShellConformanceCase,
+  ShellConformanceHarness,
+  ShellConformanceTest,
+  ShellSkip,
+  ShowHook,
+  ShowHooks,
+} from "./harness.js";
+export { registerShellConformance, shellConformanceCases, vsCodeStubSearch } from "./harness.js";