@miragon/modeler-shell 0.1.0 → 0.2.0

package/src/testing/checks.ts

@@ -15,9 +15,10 @@ import {
   type ZoomButton,
 } from "./facts.js";
 import { GEOMETRY_TOLERANCE_PX, type Rectangle } from "./geometry.js";
-import type { ShellConformanceHarness, ShowHook } from "./harness.js";
+import type { AbsentFeature, ShellConformanceHarness, ShowHook } from "./harness.js";
 import type { ElementFacts, LeftoverFacts, RecordedKey } from "./page-tools.js";
 import type { PageLike } from "./page.js";
+import { legalAriaProblems, primaryAriaProblems } from "./web-checks.js";
 
 /*
  * The judgements of the cases, as pure functions of what the probes saw. Each returns readable
@@ -177,6 +178,7 @@ export function ariaProblems(facts: AriaFacts, host: ShellHost): string[] {
   for (const element of facts.titled) {
     problems.push(`${element} has a native title; the chrome tooltip replaces it (guide §5.6)`);
   }
+  problems.push(...primaryAriaProblems(facts, host), ...legalAriaProblems(facts, host));
   return problems;
 }
 
@@ -245,13 +247,19 @@ export interface TabStop {
 /**
  * Tab from the menu trigger (guide §5.14): the primary action (web app), the palette's one tab
  * stop, then the canvas `<svg>`; nothing else in between (a renderer's own `tabindex` on
- * `.djs-container` would be an extra, unnamed stop).
+ * `.djs-container` would be an extra, unnamed stop). With `primary` the web app shows one, and
+ * Tab from the trigger lands on it first.
  */
-export function tabSequenceProblems(stops: readonly TabStop[]): string[] {
+export function tabSequenceProblems(stops: readonly TabStop[], primary = false): string[] {
   const [first, second, third] = stops;
   const sequence = first?.kind === "primary" ? [second, third] : [first, second];
   const [palette, canvas] = sequence;
   const problems: string[] = [];
+  if (primary && first?.kind !== "primary") {
+    problems.push(
+      `tab order: Tab from the menu trigger lands on ${first?.description ?? "nothing"}, expected the primary action (top left, top right, top centre, guide §5.14)`,
+    );
+  }
   if (palette?.kind !== "palette") {
     problems.push(
       `tab order: Tab from the menu trigger lands on ${palette?.description ?? "nothing"}, expected the palette's roving entry (guide §5.14)`,
@@ -431,21 +439,37 @@ export function expectedEmbeddedAppearance(facts: AppearanceFacts, themes: reado
   return host?.kontrast === "hoch" ? { theme: fallback, kontrast: "hoch" } : { theme: fallback };
 }
 
+/**
+ * The web app's own expectation (guide §13.3): `<html>` carries `carrier` (`system` for a
+ * dark-capable modeler without a stored choice) and the page shows `effective` under the emulated
+ * system preference.
+ */
+export interface WebModeExpectation {
+  carrier: string;
+  effective: Appearance;
+}
+
 /** No half-dark (guide §13.3, §13.5): one mode on `<html>` (own document) or the root (embedded). */
 export function appearanceProblems(
   facts: AppearanceFacts,
   host: ShellHost,
   requested: Appearance,
   themes: readonly Theme[],
+  web?: WebModeExpectation,
 ): AppearanceVerdict {
   const ownDocument = host !== "embedded";
-  const expected = ownDocument
-    ? expectedAppearance(requested, themes)
-    : expectedEmbeddedAppearance(facts, themes);
+  const expected =
+    web?.effective ??
+    (ownDocument ? expectedAppearance(requested, themes) : expectedEmbeddedAppearance(facts, themes));
+  const carrierTheme = web?.carrier ?? expected.theme;
   const problems: string[] = [];
+  const described =
+    carrierTheme === expected.theme
+      ? describeAppearance(expected)
+      : `${carrierTheme} showing ${describeAppearance(expected)}`;
   const label = ownDocument
-    ? `requested ${describeAppearance(requested)}, expected ${describeAppearance(expected)}`
-    : `host page ${describeAppearance(requested)}, expected ${describeAppearance(expected)}`;
+    ? `requested ${describeAppearance(requested)}, expected ${described}`
+    : `host page ${describeAppearance(requested)}, expected ${described}`;
 
   const carrier = ownDocument
     ? facts.themed.find((element) => element.isDocument && element.theme !== null)
@@ -457,7 +481,7 @@ export function appearanceProblems(
         : `the embedded root has no data-cd-theme (${label}): it takes the host page's mode instead of its own (guide §13.3)`,
     );
   } else {
-    if (carrier.theme !== expected.theme) {
+    if (carrier.theme !== carrierTheme) {
       problems.push(`${carrier.description} has data-cd-theme="${carrier.theme}" (${label})`);
     }
     if ((carrier.kontrast ?? undefined) !== expected.kontrast) {
@@ -534,7 +558,7 @@ export function appearanceProblems(
   return { problems };
 }
 
-/** The root attributes the shell writes (API.md, DOM). */
+/** The root attributes the shell writes (API.md, DOM; the web host's state attributes included). */
 const SHELL_ROOT_ATTRIBUTES = [
   "data-cd-shell-host",
   "data-palette",
@@ -542,6 +566,10 @@ const SHELL_ROOT_ATTRIBUTES = [
   "data-inspector",
   "data-problems",
   "data-readonly",
+  "data-primary",
+  "data-zoom-row",
+  "data-empty-state",
+  "data-drop",
 ];
 
 /** What an embedded root carries on top (its own mode). */
@@ -589,14 +617,14 @@ export type AbsentIsland = Extract<ShowHook, "legend" | "inspector" | "problems"
 const ABSENT_ISLANDS: readonly AbsentIsland[] = ["legend", "inspector", "problems", "status"];
 
 /** The islands of `absent` (its state `invalid` has no island). */
-export function absentIslands(absent: readonly ShowHook[] | undefined): AbsentIsland[] {
+export function absentIslands(absent: readonly AbsentFeature[] | undefined): AbsentIsland[] {
   return ABSENT_ISLANDS.filter((island) => absent?.includes(island));
 }
 
 /** An island the harness declares absent must never show. */
 export function absentIslandProblems(
   visible: ReadonlySet<string>,
-  absent: readonly ShowHook[] | undefined,
+  absent: readonly AbsentFeature[] | undefined,
 ): string[] {
   return absentIslands(absent)
     .filter((island) => visible.has(island))
@@ -606,11 +634,19 @@ export function absentIslandProblems(
 /** A hook the harness both gives and lists as absent is a contradiction in the harness itself. */
 export function harnessHookProblems<P extends PageLike>(
   harness: ShellConformanceHarness<P>,
-  hooks: readonly ShowHook[],
+  hooks: readonly AbsentFeature[],
 ): string[] {
   return hooks
-    .filter((hook) => harness.absent?.includes(hook) && harness.show?.[hook])
-    .map((hook) => `harness: absent lists "${hook}", but show.${hook} is given`);
+    .filter((hook) =>
+      hook === "drop"
+        ? harness.absent?.includes("drop") && harness.drop
+        : hook !== "problemSelection" && harness.absent?.includes(hook) && harness.show?.[hook],
+    )
+    .map((hook) =>
+      hook === "drop"
+        ? 'harness: absent lists "drop", but harness.drop is given'
+        : `harness: absent lists "${hook}", but show.${hook} is given`,
+    );
 }
 
 /** Guide §10.1: the surround of the canvas is a container painted in `--cd-ui-grund`, in both modes. */

package/src/testing/facts.ts

@@ -7,7 +7,11 @@ import type { ElementFacts, RelativeBox, ToolWindow } from "./page-tools.js";
 
 export type ZoomButton = "out" | "actual" | "in" | "fit";
 
-/** The chrome parts in the DOM (and tab) order of guide §5.14. */
+/**
+ * The chrome parts in the DOM (and tab) order of guide §5.14; the web app adds the primary action
+ * after the menu trigger, the start screen card after the hint, the legal line before the zoom
+ * panel and the toast stack last (API.md, Web host).
+ */
 export const DOM_ORDER = [
   "menu",
   "primary",
@@ -15,10 +19,13 @@ export const DOM_ORDER = [
   "canvas",
   "status",
   "hint",
+  "empty-state",
   "inspector",
   "problems",
   "legend",
+  "legal",
   "zoom",
+  "toasts",
 ] as const;
 
 export type OrderedPart = (typeof DOM_ORDER)[number];
@@ -27,6 +34,15 @@ export interface PaletteEntryFacts extends ElementFacts {
   group: string | null;
 }
 
+/** A link of the web app's legal line. */
+export interface LinkFacts {
+  text: string;
+  href: string;
+  lang: string | null;
+  target: string | null;
+  rel: string | null;
+}
+
 export interface AriaFacts {
   platform: "mac" | "other";
   documentLang: string;
@@ -54,6 +70,15 @@ export interface AriaFacts {
   legendTitle: string | null;
   legendClose: ElementFacts | null;
   inspector: ElementFacts | null;
+  /** The web app's primary action (`[data-chrome="primary"]`). */
+  primary: ElementFacts | null;
+  /** The root's `data-primary="collapsed"`. */
+  primaryCollapsed: boolean;
+  /** The web app's legal line and its links, in order. */
+  legal: ElementFacts | null;
+  legalLinks: LinkFacts[];
+  /** The element the pill's `aria-controls` names (the web app's problems list). */
+  problemsControlled: ElementFacts | null;
 }
 
 export const ariaProbe = ({ root }: { root: string }): AriaFacts | null => {
@@ -76,6 +101,8 @@ export const ariaProbe = ({ root }: { root: string }): AriaFacts | null => {
   }
   const legend = find('[data-chrome="legend"]');
   const labelledBy = legend?.getAttribute("aria-labelledby");
+  const legal = find('[data-chrome="legal"]');
+  const pillControls = find('[data-chrome="problems"]')?.getAttribute("aria-controls");
   const parts: Array<[string, Element | null]> = [
     ["menu", trigger],
     ["primary", find('[data-chrome="primary"]')],
@@ -85,13 +112,17 @@ export const ariaProbe = ({ root }: { root: string }): AriaFacts | null => {
     ["hint", find(".cd-shell-hint")],
     ["inspector", find('[data-chrome="inspector"]')],
     ["problems", find('[data-chrome="problems"]')],
+    ["empty-state", find('[data-chrome="empty-state"]')],
     ["legend", legend],
+    ["legal", find('[data-chrome="legal"]')],
     ["zoom", zoom],
+    ["toasts", find('[data-chrome="toasts"]')],
   ];
   const present = parts.filter((part): part is [string, Element] => part[1] !== null);
   present.sort(([, a], [, b]) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
   const titledSelector = [
     '[data-chrome="menu"][title]',
+    '[data-chrome="primary"][title]',
     '[data-chrome="palette"] [data-action][title]',
     '[data-chrome="zoom"] [title]',
     '[data-chrome="problems"][title]',
@@ -130,6 +161,17 @@ export const ariaProbe = ({ root }: { root: string }): AriaFacts | null => {
       : null,
     legendClose: factsOf(legend?.querySelector("button")),
     inspector: factsOf(find('[data-chrome="inspector"]')),
+    primary: factsOf(find('[data-chrome="primary"]')),
+    primaryCollapsed: rootElement.getAttribute("data-primary") === "collapsed",
+    legal: factsOf(legal),
+    legalLinks: [...(legal?.querySelectorAll("a") ?? [])].map((link) => ({
+      text: (link.textContent ?? "").replace(/\s+/g, " ").trim(),
+      href: link.getAttribute("href") ?? "",
+      lang: link.getAttribute("lang"),
+      target: link.getAttribute("target"),
+      rel: link.getAttribute("rel"),
+    })),
+    problemsControlled: factsOf(pillControls ? document.getElementById(pillControls) : null),
   };
 };
 
@@ -559,8 +601,17 @@ export interface MenuEntryFacts {
   /** `data-menu-id` of the item or its radio group. */
   menuId: string | null;
   disabled: boolean;
-  /** `data-menu-group` of the item or its radio group: the shell's `model`, `export` or `help`. */
+  /**
+   * `data-menu-group` of the item or its radio group: the shell's `model`, `export` and `help`,
+   * in the web app also `file` and `appearance`.
+   */
   group: string | null;
+  /** `data-menu-value` of a radio option. */
+  value: string | null;
+  /** `aria-checked` of a checkbox or radio entry. */
+  checked: string | null;
+  /** Whether the entry's icon column holds an icon (guide §5.4, only the common set of §5.14). */
+  icon: boolean;
 }
 
 export const menuEntriesProbe = ({ root }: { root: string }): MenuEntryFacts[] | null => {
@@ -581,6 +632,9 @@ export const menuEntriesProbe = ({ root }: { root: string }): MenuEntryFacts[] |
       menuId: element.closest("[data-menu-id]")?.getAttribute("data-menu-id") ?? null,
       disabled: element.getAttribute("aria-disabled") === "true",
       group: element.closest("[data-menu-group]")?.getAttribute("data-menu-group") ?? null,
+      value: element.getAttribute("data-menu-value"),
+      checked: element.getAttribute("aria-checked"),
+      icon: element.querySelector(".cd-shell-menu-item-icon svg") !== null,
     });
   }
   return entries;

package/src/testing/geometry.ts

@@ -1,7 +1,13 @@
 import {
   CHROME_ISLANDS,
+  LEGAL_LINE_HEIGHT,
   PALETTE_CLEARANCE,
   SHELL,
+  legalLineHeight,
+  toastStackBottom,
+  toastStackWidth,
+  zoomRowRaised,
+  type BottomObstacle,
   type ChromeIsland,
   type Insets,
   type PaletteRow,
@@ -31,8 +37,21 @@ export interface ChromeMeasurement {
   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 };
+  /**
+   * State attributes of the root: `[data-legend="open"]`, `[data-inspector="open"]`,
+   * `[data-problems="shown"]`, and in the web host `[data-empty-state="shown"]`,
+   * `[data-primary="collapsed"]` and `[data-zoom-row="raised"]`.
+   */
+  open: {
+    legend: boolean;
+    inspector: boolean;
+    problems: boolean;
+    emptyState: boolean;
+    primaryCollapsed: boolean;
+    zoomRaised: boolean;
+  };
+  /** Width of the widest visible toast card (`[data-status]` in the stack); absent without a toast. */
+  toastCardWidth?: number;
 }
 
 /** Constraints of one island; every given field must hold within `GEOMETRY_TOLERANCE_PX`. */
@@ -45,6 +64,8 @@ export interface ExpectedBox {
   height?: number;
   /** Horizontal centre relative to the root. */
   centerX?: number;
+  /** Vertical centre relative to the root (the web app's empty-state card). */
+  centerY?: number;
 }
 
 export const DEFAULT_ROOT = ".cd-shell";
@@ -52,8 +73,15 @@ 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;
+/** Height of one line of the web app's legal line under the bottom-left stack (guide §5.10). */
+export const LEGAL_LINE = LEGAL_LINE_HEIGHT;
+
+/** The web app's start screen card: `min(400px, 100% − 24px)` wide (guide §8). */
+const EMPTY_STATE_MAX_WIDTH = 400;
+
+/** The web app's problems list above the pill: `min(320px, 100% − 24px)` wide, at most 320 high (guide §5.10). */
+const POPOVER_MAX_WIDTH = 320;
+const POPOVER_MAX_HEIGHT = 320;
 
 /** Minimum width of the legend card (guide §5.10). */
 const LEGEND_MIN_WIDTH = 184;
@@ -80,7 +108,11 @@ const measureProbe = ({ root, islands }: { root: string; islands: readonly strin
     }
     boxes[name] = tools.box(element, rootElement);
   }
+  const cardWidths = [...rootElement.querySelectorAll<HTMLElement>('[data-chrome="toasts"] > [data-status]')]
+    .filter((card) => tools.visible(card))
+    .map((card) => card.getBoundingClientRect().width);
   return {
+    ...(cardWidths.length > 0 ? { toastCardWidth: Math.max(...cardWidths) } : {}),
     container: tools.container(rootElement),
     paletteRow: rootElement.getAttribute("data-palette") === "second-row" ? "second-row" : "top",
     islands: boxes,
@@ -88,6 +120,9 @@ const measureProbe = ({ root, islands }: { root: string; islands: readonly strin
       legend: rootElement.getAttribute("data-legend") === "open",
       inspector: rootElement.getAttribute("data-inspector") === "open",
       problems: rootElement.getAttribute("data-problems") === "shown",
+      emptyState: rootElement.getAttribute("data-empty-state") === "shown",
+      primaryCollapsed: rootElement.getAttribute("data-primary") === "collapsed",
+      zoomRaised: rootElement.getAttribute("data-zoom-row") === "raised",
     },
     duplicates,
   };
@@ -106,6 +141,7 @@ export async function measureChrome(page: PageLike, root: string = DEFAULT_ROOT)
     paletteRow: result.paletteRow,
     islands: result.islands,
     open: result.open,
+    ...(result.toastCardWidth !== undefined ? { toastCardWidth: result.toastCardWidth } : {}),
   };
 }
 
@@ -142,28 +178,63 @@ function sheetOpen(measurement: ChromeMeasurement): boolean {
   return measurement.open.inspector && isNarrow(measurement.container);
 }
 
+/** The bottom of an island as `toastStackBottom` sees it (guide §8, the shell's rule for the bottom row). */
+export function bottomObstacle(box: IslandBox, container: Size): BottomObstacle {
+  return { left: box.left, right: box.left + box.width, top: container.height - box.top };
+}
+
+/** Why an island of the web column never shows in the IDE and embedded hosts (guide §5.2). */
+const WEB_ONLY: Partial<Record<ChromeIsland, string>> = {
+  primary: "the top right stays empty in IDE and embedded hosts (guide §5.7)",
+  legal: "the legal line belongs to the web app; an IDE or an embedding host carries its own (guide §5.2)",
+  "empty-state": "IDE and embedded hosts have no start screen; they show the empty-file hint (guide §13.5)",
+  "drop-zone": "IDE and embedded hosts have no drop zone; their files belong to the host (guide §5.2)",
+};
+
+/** The work chrome the web app's start screen hides (guide §8: only the card and the legal line show). */
+export const WORK_CHROME: readonly ChromeIsland[] = [
+  "menu",
+  "primary",
+  "palette",
+  "zoom",
+  "problems",
+  "legend",
+  "status",
+  "inspector",
+];
+
 /** 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 startScreen = web && open.emptyState;
+  const raised = web && open.zoomRaised;
   const secondRow = paletteRow === "second-row";
   const sheet = sheetOpen(measurement);
   const sideInspector = open.inspector && !isNarrow(container);
+  // A narrow container wraps the legal line; the stack above it stands on its whole lines.
+  const legalHeight = legalLineHeight(web ? islands.legal?.height : undefined);
   const boxes: Partial<Record<ChromeIsland, ExpectedBox>> = {};
   const limits: Partial<Record<ChromeIsland, BoxLimits>> = {};
   const hidden: Partial<Record<ChromeIsland, string>> = {};
-  const required: ChromeIsland[] = ["menu", "palette"];
+  // Behind the start screen the work chrome is hidden; where it shows anyway, it still stands at its anchor.
+  const required: ChromeIsland[] = startScreen ? ["empty-state"] : ["menu", "palette"];
+  if (web) required.push("legal");
 
   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 }
-      : {};
+  const primary = web ? islands.primary : undefined;
+  if (secondRow) {
+    limits.palette = { maxWidth: container.width - 2 * edge };
+  } else {
+    limits.palette = {};
+    if (menu) limits.palette.minLeft = menu.left + menu.width + PALETTE_CLEARANCE;
+    // Guide §5.15: 16px to every island of the top row, the primary action included.
+    if (primary) limits.palette.minRight = container.width - primary.left + PALETTE_CLEARANCE;
+  }
 
   if (sheet) {
     const reason = "hidden while the inspector is a bottom sheet (guide §5.11)";
@@ -171,13 +242,15 @@ export function chromeExpectations(measurement: ChromeMeasurement, host: ShellHo
     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 (!startScreen) required.push("zoom");
+    const legalStack = edge + legalHeight + gap;
+    boxes.zoom = { right: edge, bottom: raised ? legalStack : edge, width: ZOOM_PANEL_WIDTH, height: row };
+    const stackBase = web ? legalStack : 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;
+      const aboveBottomRow = (raised ? legalStack : edge) + row + gap;
+      const bottom = isVeryNarrow(container) ? Math.max(besidePill, aboveBottomRow) : besidePill;
       boxes.legend = { left: edge, bottom };
       limits.legend = { minWidth: LEGEND_MIN_WIDTH };
     }
@@ -203,9 +276,54 @@ export function chromeExpectations(measurement: ChromeMeasurement, host: ShellHo
   }
 
   if (web) {
-    if (islands.primary) boxes.primary = { top: edge, right: edge, height: row };
+    if (primary) {
+      boxes.primary = { top: edge, right: edge, height: row };
+      if (open.primaryCollapsed) boxes.primary.width = row;
+    }
+    boxes.legal = { left: edge, bottom: edge, height: legalHeight };
+    limits.legal = { maxWidth: container.width - 2 * edge };
+    if (islands["empty-state"]) {
+      boxes["empty-state"] = {
+        centerX: container.width / 2,
+        centerY: container.height / 2,
+        width: Math.min(EMPTY_STATE_MAX_WIDTH, container.width - 2 * edge),
+      };
+    }
+    if (islands["drop-zone"]) boxes["drop-zone"] = { left: edge, top: edge, right: edge, bottom: edge };
   } else {
-    hidden.primary = "the top right stays empty in IDE and embedded hosts (guide §5.7)";
+    Object.assign(hidden, WEB_ONLY);
+  }
+
+  if (host === "ide") {
+    hidden.toasts = "the IDE host shows no toasts; the extension shows the host's notification (guide §13.5)";
+    hidden["problems-popover"] =
+      "the IDE host opens its Problems view, never a list of its own (guide §5.10)";
+  } else {
+    if (islands.toasts) {
+      const obstacles = (["zoom", "legal", "problems"] as const).flatMap((name) => {
+        const box = islands[name];
+        return box ? [bottomObstacle(box, container)] : [];
+      });
+      boxes.toasts = {
+        centerX: container.width / 2,
+        width: toastStackWidth(container.width),
+        bottom: toastStackBottom({
+          containerWidth: container.width,
+          obstacles,
+          cardWidth: measurement.toastCardWidth,
+        }),
+      };
+    }
+    const pill = islands.problems;
+    if (pill) {
+      boxes["problems-popover"] = { left: edge, bottom: container.height - pill.top + gap };
+      limits["problems-popover"] = {
+        maxWidth: Math.min(POPOVER_MAX_WIDTH, container.width - 2 * edge),
+        maxHeight: POPOVER_MAX_HEIGHT,
+      };
+    } else {
+      hidden["problems-popover"] = "the problems list opens only above a visible pill (guide §5.10)";
+    }
   }
 
   return { boxes, limits, required, hidden };
@@ -230,6 +348,7 @@ function sides(box: IslandBox, container: Size): Required<ExpectedBox> {
     width: box.width,
     height: box.height,
     centerX: box.left + box.width / 2,
+    centerY: box.top + box.height / 2,
   };
 }
 
@@ -319,12 +438,22 @@ export function geometryProblems(
   }
   const palette = islands.palette;
   const menu = islands.menu;
+  const primary = host === "web" ? islands.primary : undefined;
   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) {
+    const toMenu = topRowLeft - menu.left - menu.width;
+    // Guide §5.15: the primary action loses its label before the palette moves, so it counts icon only.
+    const toPrimary = primary
+      ? container.width - SHELL.edge - SHELL.row - (topRowLeft + palette.width)
+      : Number.POSITIVE_INFINITY;
+    const fits = toMenu >= PALETTE_CLEARANCE + tolerance && toPrimary >= PALETTE_CLEARANCE + tolerance;
+    if (!clipped && fits) {
+      const kept = primary
+        ? `${round(toMenu)}px to the menu trigger and ${round(toPrimary)}px to the primary action's icon`
+        : `${round(toMenu)}px to the menu trigger`;
       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)`,
+        `palette: in the second row although the top row keeps ${kept} (at least ${PALETTE_CLEARANCE}px suffice, guide §5.15)`,
       );
     }
   }
@@ -336,16 +465,62 @@ export function geometryProblems(
     }
     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);
+  state("problems", open.problems, 'data-problems="shown"', sheet || open.emptyState);
+  state("legend", open.legend, 'data-legend="open"', sheet || open.emptyState);
+  state("inspector", open.inspector, 'data-inspector="open"', open.emptyState);
+  state("empty-state", open.emptyState, 'data-empty-state="shown"', false);
+  problems.push(...webRowProblems(measurement, host, tolerance));
 
   return problems;
 }
 
+/**
+ * The web app's state attributes for its top and bottom rows: `data-primary="collapsed"` only with
+ * a visible primary action, and `data-zoom-row="raised"` exactly when the zoom panel at
+ * `bottom: 12px` would keep less than 8px to the legal line (`zoomRowRaised`, the shell's rule).
+ */
+export function webRowProblems(
+  measurement: ChromeMeasurement,
+  host: ShellHost,
+  tolerance: number = GEOMETRY_TOLERANCE_PX,
+): string[] {
+  const { container, islands, open } = measurement;
+  const problems: string[] = [];
+  if (host !== "web") {
+    if (open.primaryCollapsed)
+      problems.push('primary: the root carries data-primary="collapsed" outside the web app');
+    if (open.zoomRaised) problems.push('zoom: the root carries data-zoom-row="raised" outside the web app');
+    return problems;
+  }
+  if (open.primaryCollapsed && !islands.primary && !open.emptyState) {
+    problems.push('primary: the root carries data-primary="collapsed", but no primary action is visible');
+  }
+  const legal = islands.legal;
+  const zoom = islands.zoom;
+  if (legal && zoom) {
+    const legalRight = legal.left + legal.width;
+    const gap = container.width - SHELL.edge - zoom.width - legalRight;
+    const raised = zoomRowRaised({ containerWidth: container.width, legalRight, zoomWidth: zoom.width });
+    // A gap within the tolerance of the 8px limit may go either way.
+    const borderline = Math.abs(gap - SHELL.gap) <= tolerance;
+    if (raised && !open.zoomRaised && !borderline) {
+      problems.push(
+        `zoom: ${round(gap)}px between the legal line and the zoom panel, but the root lacks data-zoom-row="raised" (below ${SHELL.gap}px the zoom panel stands above the legal line)`,
+      );
+    }
+    if (!raised && open.zoomRaised && !borderline) {
+      problems.push(
+        `zoom: the root carries data-zoom-row="raised" although the zoom panel keeps ${round(gap)}px to the legal line (at least ${SHELL.gap}px)`,
+      );
+    }
+  }
+  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
+ * (second row 140), sides 24, bottom 64 (web app with the pill or the zoom panel raised above the
+ * legal line 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.
  */
@@ -354,7 +529,10 @@ export function expectedFitInsets(measurement: ChromeMeasurement, host: ShellHos
   const insets: Insets = {
     top: paletteRow === "second-row" ? SHELL.fitInsetTopSecondRow : SHELL.fitInsetTop,
     right: SHELL.fitInsetSide,
-    bottom: host === "web" && open.problems ? SHELL.fitInsetBottomWeb : SHELL.fitInsetBottom,
+    bottom:
+      host === "web" && (open.problems || open.zoomRaised)
+        ? SHELL.fitInsetBottomWeb + legalLineHeight(islands.legal?.height) - LEGAL_LINE
+        : SHELL.fitInsetBottom,
     left: SHELL.fitInsetSide,
   };
   if (sheetOpen(measurement)) {
@@ -423,8 +601,9 @@ 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.
+ * or the second row (`top: 112px`), 8px above the bottom row (`bottom: 60px`, above the web app's
+ * raised zoom row `bottom: 88px`: give its `bottomRow` of 40); centred on its control and shifted
+ * to keep 12px to the sides.
  */
 export function tooltipProblems(
   tooltip: IslandBox,
@@ -432,13 +611,14 @@ export function tooltipProblems(
   row: TooltipRow,
   container: Size,
   tolerance = GEOMETRY_TOLERANCE_PX,
+  bottomRow: number = SHELL.edge,
 ): 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, bottom: bottomRow + rowHeight + gap }
       : { left, top: (row === "top" ? edge : free) + rowHeight + gap };
   let mismatches = boxMismatches(
     "tooltip",