@terpjs/react-core 0.9.0 → 0.10.0

package/src/previewBridge.ts

@@ -0,0 +1,278 @@
+/**
+ * A channel into a running app, for the tool that is showing it.
+ *
+ * A development tool that embeds a running app in an iframe cannot see into it — a cross-origin
+ * frame is opaque by design, and deliberately so. Which leaves someone looking at a button they
+ * want changed with no way to say WHICH button, except in prose.
+ *
+ * This package does not know or name who is asking. It answers a protocol, not a product.
+ *
+ * The hook this uses already exists: every sanctioned component stamps `data-terp` on its root,
+ * and the marker inventory is a pinned, gated list. So "which component is this?" is a question
+ * the DOM can already answer; what was missing is someone to ask it.
+ *
+ * FOUR DECISIONS, and each is the reason a bridge like this is usually a bad idea.
+ *
+ * **It exists only in a development build.** The whole module is behind `import.meta.env.DEV`,
+ * which a production build folds to `false` and strips — the same mechanism the template uses for
+ * its dev sign-in credentials, and for the same reason. A deployed app has no listener, so none of
+ * what follows is a production attack surface. It is not a setting that can be left on.
+ *
+ * **The tool speaks first, and the FIRST one wins.** The app never volunteers anything: it
+ * records the origin and the window of the first well-formed handshake and answers that one
+ * alone, thereafter — a second party cannot take the conversation over, and cannot start one.
+ * First-come rather than validated, because there is nothing to validate against: a tool
+ * embedding an app has no way to configure this package, and the two are on different origins by
+ * design (an embedded preview sharing its host would carry that host's session cookie into app
+ * code). An opaque origin is refused, since `"null"` is what a sandboxed or `file://` document
+ * reports and it matches every other one.
+ *
+ * The window is kept as well as the origin. `window.parent` is the frame's embedder only when
+ * there IS an embedder — open the app in a tab and `window.parent` is the app itself, so a reply
+ * addressed there talks to nobody while looking like it worked.
+ *
+ * **Three things leave, and they are named exhaustively.** A reply carries `data-terp` markers,
+ * element tag names, and the route path the page is on. Never text, never values, never
+ * attributes — nothing an app renders data into. An app under development is an app with real
+ * data in it, and a channel that could read the page would be a way out for that data, dev-only
+ * or not.
+ *
+ * The route path is the one of the three that is not purely structural, and it is listed rather
+ * than glossed: `/records/42` carries an identifier. It is sent because "which component" is not
+ * a useful answer without "on which screen", it is the same string already visible in the address
+ * bar of the frame the asker is displaying, and it is bounded below. An earlier version of this
+ * docstring said "structure, never content" and sent it anyway, which is the kind of sentence
+ * this file exists to not write.
+ *
+ * A bounding rectangle used to leave too. Nothing consumed it, so it does not.
+ *
+ * **The app draws its own highlight.** Nothing outside a cross-origin iframe can paint over it,
+ * so pointing at something has to happen on this side. One outline, from the token layer, removed
+ * with the mode.
+ *
+ * ADR 0006's quadruple is not fully satisfied and the missing halves are named in ADR 0101 §5:
+ * there is a typed protocol with a safe default (off, and absent in production) and a fail-closed
+ * runtime check (every message is validated and a stranger is ignored), but no build-time rule and
+ * no escape hatch — a lint rule would have nothing to check, since the module is not something an
+ * app writes, and there is nothing to opt out of in a build where it does not exist.
+ */
+
+/**
+ * The protocol name, carried on every message in both directions.
+ *
+ * Versioned in the name rather than in a field: a tool and an app can be from different releases,
+ * and a version mismatch has to be silence rather than a half-understood conversation. An app that
+ * does not recognise the name ignores the message, which is exactly what an older app does with a
+ * newer tool and the reverse.
+ */
+export const PREVIEW_BRIDGE_PROTOCOL = "terp.preview.1";
+
+/** One step of the chain from the clicked element up to the page root. */
+export interface PreviewBridgeStep {
+  /** The sanctioned component's marker, e.g. "button" or "dataview". */
+  readonly marker: string;
+  /** The element it was stamped on, lowercased. */
+  readonly tag: string;
+}
+
+/** What the app answers with when something is picked. */
+export interface PreviewBridgeSelection {
+  /** Innermost first: the marker chain from what was clicked up to the page. */
+  readonly path: readonly PreviewBridgeStep[];
+  /** The route the preview is on, so a tool can say where the component was found. */
+  readonly path_name: string;
+}
+
+/**
+ * The shape a marker may have: the shape every name in the pinned inventory has.
+ *
+ * Checked rather than trusted, even though this code runs inside the app it is describing.
+ * `getAttribute("data-terp")` returns whatever is on the element, and an app under development
+ * is allowed to put anything anywhere — so an unbounded string here is an app writing arbitrary
+ * text into whatever the asking tool does with it. Bounded in length for the same reason.
+ */
+const MARKER_RE = /^[a-z0-9-]{1,64}$/;
+
+/** A tag name, bounded the same way. Custom elements are hyphenated ASCII. */
+const TAG_RE = /^[a-z0-9-]{1,64}$/;
+
+/** A route path, bounded. Long enough for any real route, short enough not to be a payload. */
+const MAX_PATH_NAME = 512;
+
+/** The attribute the highlight is styled from — an attribute, like every other marker here. */
+const HIGHLIGHT_ATTRIBUTE = "data-terp-preview-pick";
+
+const STYLE_ID = "terp-preview-bridge";
+
+const HIGHLIGHT_CSS = `
+[${HIGHLIGHT_ATTRIBUTE}] {
+  outline: 2px solid var(--color-brand-primary, #2563eb);
+  outline-offset: 1px;
+  cursor: crosshair;
+}
+`;
+
+interface Incoming {
+  protocol?: unknown;
+  kind?: unknown;
+  on?: unknown;
+}
+
+function isIncoming(data: unknown): data is Incoming & { protocol: string; kind: string } {
+  return (
+    typeof data === "object" &&
+    data !== null &&
+    (data as Incoming).protocol === PREVIEW_BRIDGE_PROTOCOL &&
+    typeof (data as Incoming).kind === "string"
+  );
+}
+
+/**
+ * The chain of sanctioned components from *element* up to the document.
+ *
+ * A step whose marker or tag is not the shape a marker has is DROPPED rather than sent. The
+ * attribute is whatever is on the element, and this code cannot tell a component's marker from
+ * a string an app put there — so the reply carries only what looks like the closed vocabulary the
+ * asker is expecting, and never becomes a way to write arbitrary text into that asker's tools.
+ */
+function markerPath(element: Element | null): PreviewBridgeStep[] {
+  const path: PreviewBridgeStep[] = [];
+  for (let node: Element | null = element; node !== null; node = node.parentElement) {
+    const marker = node.getAttribute("data-terp");
+    const tag = node.tagName.toLowerCase();
+    if (marker !== null && MARKER_RE.test(marker) && TAG_RE.test(tag)) {
+      path.push({ marker, tag });
+    }
+  }
+  return path;
+}
+
+/** The nearest ancestor that a sanctioned component stamped, including *element* itself. */
+function nearestMarked(element: Element | null): Element | null {
+  for (let node: Element | null = element; node !== null; node = node.parentElement) {
+    if (node.getAttribute("data-terp")) return node;
+  }
+  return null;
+}
+
+/**
+ * Listen for a tool asking about this app, and answer it.
+ *
+ * Returns a function that removes every listener, the style element and the highlight — so a test
+ * can run this twice without leaking, and so a caller that ever wants to stop can.
+ *
+ * Safe to call with no `window` (server rendering): it does nothing and returns a no-op.
+ */
+export function installPreviewBridge(): () => void {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return () => {};
+  }
+
+  /**
+   * Who said hello: the origin to address a reply to, and the window to send it to.
+   *
+   * Both, because they answer different questions. The origin is what stops another site
+   * reading a reply; the window is what makes the reply arrive at all — `window.parent` is the
+   * embedder only when the app IS embedded, and is the app itself when it is open in a tab.
+   */
+  let asker: { origin: string; window: MessageEventSource } | null = null;
+  /**
+   * Who turned select mode on, or `null` when it is off.
+   *
+   * The asker rather than a boolean, and that is what removes the last unreachable branch from
+   * this module: "select mode is on" and "there is someone to answer" are the same fact, so a
+   * click handler holding this holds a destination and `reply` has no null case to guard. Written
+   * as a boolean first, which left a `if (asker === null) return` in `reply` that no test could
+   * reach — dead defensive code in the one module where dead code is least welcome.
+   */
+  let selecting: { origin: string; window: MessageEventSource } | null = null;
+  let highlighted: Element | null = null;
+
+  const reply = (to: { origin: string; window: MessageEventSource }, message: object) => {
+    (to.window as Window).postMessage(
+      { protocol: PREVIEW_BRIDGE_PROTOCOL, ...message },
+      to.origin,
+    );
+  };
+
+  const clearHighlight = () => {
+    highlighted?.removeAttribute(HIGHLIGHT_ATTRIBUTE);
+    highlighted = null;
+  };
+
+  const onPointerOver = (event: Event) => {
+    if (selecting === null) return;
+    const target = nearestMarked(event.target as Element | null);
+    if (target === highlighted) return;
+    clearHighlight();
+    if (target !== null) {
+      target.setAttribute(HIGHLIGHT_ATTRIBUTE, "");
+      highlighted = target;
+    }
+  };
+
+  const onClick = (event: MouseEvent) => {
+    const to = selecting;
+    if (to === null) return;
+    // Captured and cancelled: in select mode a click picks a component rather than doing what it
+    // normally does. Letting it through would navigate away from the thing being pointed at.
+    event.preventDefault();
+    event.stopPropagation();
+    const target = nearestMarked(event.target as Element | null);
+    if (target === null) return;
+    reply(to, {
+      kind: "selected",
+      selection: {
+        path: markerPath(target),
+        path_name: window.location.pathname.slice(0, MAX_PATH_NAME),
+      } satisfies PreviewBridgeSelection,
+    });
+  };
+
+  const setSelecting = (to: { origin: string; window: MessageEventSource } | null) => {
+    selecting = to;
+    if (to === null) clearHighlight();
+    if (to !== null && document.getElementById(STYLE_ID) === null) {
+      const style = document.createElement("style");
+      style.id = STYLE_ID;
+      // textContent, never innerHTML: no HTML-injection sink is touched, which is the same rule
+      // the component stylesheet's own injector follows.
+      style.textContent = HIGHLIGHT_CSS;
+      document.head.appendChild(style);
+    }
+  };
+
+  const onMessage = (event: MessageEvent) => {
+    if (!isIncoming(event.data)) return;
+    if (asker === null && event.data.kind === "hello") {
+      // `"null"` is what a sandboxed iframe, a `file://` page and a data: URL all report, so it
+      // identifies nobody and matches everybody — adopting it would make the next such document
+      // the asker too. A source is required for the same reason: without one there is no window
+      // to answer.
+      if (event.origin === "null" || event.origin === "" || event.source === null) return;
+      asker = { origin: event.origin, window: event.source };
+    }
+    if (asker === null || event.origin !== asker.origin || event.source !== asker.window) return;
+    if (event.data.kind === "hello") {
+      reply(asker, { kind: "ready" });
+      return;
+    }
+    if (event.data.kind === "select") {
+      setSelecting(event.data.on === true ? asker : null);
+      return;
+    }
+  };
+
+  window.addEventListener("message", onMessage);
+  document.addEventListener("pointerover", onPointerOver, true);
+  document.addEventListener("click", onClick, true);
+
+  return () => {
+    window.removeEventListener("message", onMessage);
+    document.removeEventListener("pointerover", onPointerOver, true);
+    document.removeEventListener("click", onClick, true);
+    selecting = null;
+    clearHighlight();
+    document.getElementById(STYLE_ID)?.remove();
+  };
+}

package/src/raw.d.ts

@@ -1,6 +1,10 @@
 /**
- * Minimal ambient declarations for the source-scanning tests only — the package keeps
- * `"types": []` so component source never sees ambient Node globals.
+ * Minimal ambient declarations for the two things this package reads off `import.meta` — the
+ * package keeps `"types": []` so component source never sees ambient Node globals.
+ *
+ * Safe to declare here even though every consuming app already has `vite/client`: nothing
+ * imports this file, so it is part of THIS package's program and not of a consumer's, and the
+ * two `ImportMeta` augmentations never meet.
  *
  * Both live here rather than inline in the tests that use them: a global augmentation
  * repeated in two files is a TS2717 the moment the copies disagree, and they disagree
@@ -18,4 +22,12 @@ interface ImportMeta {
     pattern: string,
     options: { query: "?raw"; import: "default"; eager: true },
   ) => Record<string, string>;
+  /**
+   * The build-mode flag, `false` in a production build.
+   *
+   * Written out verbatim at its one call site rather than read through a helper or a cast: a
+   * bundler folds the expression `import.meta.env.DEV` TEXTUALLY, so anything else leaves the
+   * branch — and the module behind it — in a production bundle.
+   */
+  readonly env: { readonly DEV: boolean };
 }

package/src/review.test.tsx

@@ -0,0 +1,272 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { Checkbox } from "./ui/Checkbox";
+import { Radio } from "./ui/Radio";
+import { Switch } from "./ui/Switch";
+import { Popover } from "./ui/Popover";
+import { Tabs } from "./ui/Tabs";
+import { TERP_STYLES_CSS } from "./styles";
+
+// Defects the phases 1-4 review found, gated.
+//
+// Every one of these shipped past four browser lanes and a full unit suite, so an assertion that
+// merely restates the fix would be worth nothing. Each row names the mutation that turns it red
+// and was checked against it.
+//
+// Several read SOURCE TEXT or the stylesheet rather than behaviour, which is unusual here and
+// deliberate rather than lazy. Each of those is a fact about something this suite cannot execute:
+// what a DIFFERENT React major serializes, what an entry point no test mounts forwards, or which
+// rule wins a cascade jsdom does not compute. A behavioural assertion would pass under the bug in
+// every one of those cases. Where behaviour CAN see it — the frozen controls, the tabpanel's
+// name, the popover's focus return — the test renders and asserts on the result instead.
+//
+// No count here on purpose: an earlier version of this comment said "two of the four" and was
+// wrong by the time the file had ten. A citation keeps; a tally rots.
+//
+// One trap has now appeared twice in gates written for this very review, so it is worth stating
+// where the next reader will meet it: a `toContain` on a CSS selector is satisfied by any LONGER
+// selector containing it. `:root[data-density="x"]` contains `[data-density="x"]`, and the pager's
+// own disabled rule contains the shared one. Both mutations came back GREEN until the assertions
+// were anchored to the start of a line with a regex.
+
+const sources = import.meta.glob("./**/*.tsx", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+}) as Record<string, string>;
+
+/** The package manifest as text, so the peer range can be asserted without importing it. */
+const packageJson = import.meta.glob("../package.json", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+}) as Record<string, string>;
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("defects the phases 1-4 review found", () => {
+  it("warns when a checked control is given no onChange, instead of freezing silently", () => {
+    // React's own guard is the only thing that would tell an author they pinned `checked` and
+    // forgot the handler. Passing `onChange` unconditionally suppresses it, so the control looked
+    // operable, never changed, and said nothing — the exact failure `Select` documents at its own
+    // call site (ui/Select.tsx) and avoids. Mutation: restore the unconditional handler in any of
+    // the three and the count drops.
+    const seen: string[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((...args: unknown[]) => {
+      seen.push(args.map(String).join(" "));
+    });
+    try {
+      render(
+        <>
+          <Checkbox label="frozen box" checked />
+          <Switch label="frozen switch" checked />
+          <Radio name="group" value="a" label="frozen radio" checked />
+        </>,
+      );
+    } finally {
+      spy.mockRestore();
+    }
+    // React de-duplicates this warning per component type, so three distinct components warn
+    // three times. Matched loosely because the exact wording differs across React majors.
+    const complaints = seen.filter((line) => /without an .?onChange.? handler/.test(line));
+    expect(complaints).toHaveLength(3);
+  });
+
+  it("does not repaint an invalid field's border on hover", () => {
+    // Both rules live in terp.state, so the cascade is decided by specificity alone: the hover
+    // selector weighed (0,4,0) against the danger border's (0,2,0) and won. Pointing at a field
+    // that had just failed validation removed its error border for as long as the pointer rested
+    // there — and the pointer rests there precisely because the user is about to fix it.
+    // Mutation: drop the :not([aria-invalid="true"]).
+    expect(TERP_STYLES_CSS).toContain(
+      '[data-terp="input"]:hover:not(:disabled):not(:focus):not([aria-invalid="true"])',
+    );
+    // And the unnarrowed aggressor must not exist anywhere, in any form.
+    expect(TERP_STYLES_CSS).not.toContain(
+      '[data-terp="input"]:hover:not(:disabled):not(:focus) {',
+    );
+  });
+
+  it("does not promise a React major on which the drawer's containment does not exist", () => {
+    // The drawer inerts the page column and marks it aria-hidden. Measured with
+    // renderToStaticMarkup against both renderers:
+    //
+    //   spelling        React 18.3.1              React 19.2.8
+    //   inert={true}    DROPPED (warns)           inert=""
+    //   inert=""        inert=""                  DROPPED (warns: treated as false)
+    //
+    // So under the old `^18.3.0 || ^19.0.0` peer range, an app on 18.3 got the worst half of
+    // the pair — a subtree announced as hidden to assistive technology with every control in it
+    // still focusable and clickable — and no spelling is correct and quiet on both. The review
+    // that found this proposed `inert=""`, which would have broken React 19 instead; the
+    // measurement is the only reason that did not ship. The defect is the promise, so the fix
+    // is the range. Mutation: widen the peer range back to include ^18.3.0.
+    const manifest = JSON.parse(
+      (packageJson as Record<string, string>)["../package.json"] ?? "{}",
+    ) as { peerDependencies?: Record<string, string> };
+    const peers = manifest.peerDependencies ?? {};
+    for (const name of ["react", "react-dom"] as const) {
+      expect(peers[name], `${name} peer range`).toBeDefined();
+      expect(peers[name]).not.toMatch(/18\./);
+    }
+    // And the attribute stays the spelling React 19 actually renders.
+    const shell = sources["./AppShell.tsx"] ?? "";
+    expect(shell, "AppShell.tsx is not in the scanned sources").not.toBe("");
+    expect(shell).toContain("inert={isMobile && drawerOpen ? true : undefined}");
+  });
+
+  it("gives a tabpanel an accessible name even when the tab value contains whitespace", () => {
+    // `Tabs` built element ids by interpolating the caller's `value`. A value is caller data and
+    // an id is an IDREF, so a value with a space turned `aria-labelledby` into a list of two
+    // tokens, neither of which resolves — and the tabpanel silently lost its name. Nothing
+    // reported it: axe sees a well-formed reference to nothing, and the visible tab still reads
+    // correctly. Ids key on the tab's index now.
+    // Mutation: interpolate `tab.value` / `selectedTab.value` back into the two ids.
+    render(
+      <Tabs
+        label="Sections"
+        tabs={[
+          { value: "my tab", label: "My tab", content: <p>first</p> },
+          { value: "other one", label: "Other one", content: <p>second</p> },
+        ]}
+      />,
+    );
+    expect(screen.getByRole("tabpanel", { name: "My tab" })).toBeInTheDocument();
+  });
+
+  it("wins the density tie against the contract's own :root declarations", () => {
+    // The shell's density attribute sets the same custom properties the contract declares on
+    // :root, both unlayered. A bare [data-density="..."] on <html> weighs (0,1,0) — exactly what
+    // :root weighs — so the two tied and only the order the sheets happened to load decided it.
+    // A production build extracts tokens.css to a <link> that precedes the injected sheet, so
+    // react-core won by construction and the exposure was the dev server and any host loading
+    // the tokens late. The :root-qualified copy is (0,2,0) and wins outright.
+    // Mutation: drop either :root-qualified selector.
+    for (const density of ["comfortable", "compact"] as const) {
+      expect(TERP_STYLES_CSS).toContain(`:root[data-density="${density}"]`);
+      // The unqualified copy stays, for a density island on a subtree where there is no :root.
+      // Anchored to the start of a line, because `:root[data-density="x"]` CONTAINS
+      // `[data-density="x"]` — a bare toContain here would be satisfied by the qualified copy
+      // alone and could never notice the unqualified one being deleted.
+      expect(TERP_STYLES_CSS).toMatch(
+        new RegExp(`^\\[data-density="${density}"\\]`, "m"),
+      );
+    }
+  });
+
+  it("forwards logoDark from both sanctioned entry points", () => {
+    // The third slot to exist on the shell and be unreachable from the entry points every app
+    // uses, after `headerActions` — which ADR 0097's own Context complains about. This one was
+    // worse: the project template instructs every new app to pass `logoDark` to `renderTerpApp`
+    // (template/project/frontend/src/main.tsx.jinja), so the documented example did not
+    // typecheck. Mutation: delete either forwarding line.
+    //
+    // Matched as "the option appears in what the prop is given" rather than as one exact
+    // expression, because the exact expression changed the day `shell.brand` landed and the
+    // invariant did not: the slot now prefers a declared PATH and falls back to the option, and
+    // the old `toContain("logoDark={options.logoDark}")` failed on a router that still forwards
+    // it perfectly. An assertion on a spelling fails for the wrong reason, which is only one
+    // step better than passing for the wrong reason.
+    const router = sources["./router.tsx"] ?? "";
+    const bootstrap = sources["./bootstrap.tsx"] ?? "";
+    expect(router, "router.tsx is not in the scanned sources").not.toBe("");
+    expect(bootstrap, "bootstrap.tsx is not in the scanned sources").not.toBe("");
+    expect(router).toMatch(/logoDark=\{[^}]*options\.logoDark/);
+    // `logo=` alone would also match inside `logoDark=`; the negated class stops at the
+    // first `}`, so this reads the whole expression the slot is given.
+    expect(router).toMatch(/[^a-zA-Z]logo=\{[^}]*options\.logo}/);
+    expect(bootstrap).toContain("logoDark: options.logoDark,");
+    expect(bootstrap).toMatch(/logoDark\?: ReactNode;/);
+  });
+
+  it("returns focus to the trigger when Tab leaves a popover panel", () => {
+    // The panel is portalled to the END of document.body, so with no Tab branch the
+    // sequential-navigation starting point stayed inside a node at the wrong end of the
+    // document: Tab out landed past every piece of page content, and Shift+Tab landed on the
+    // last focusable element on the page rather than back on the control that opened it. `Menu`
+    // has implemented the APG contract for this all along and documents the exact failure;
+    // `Popover` carried the same portal with an Escape-only handler.
+    // Mutation: delete the Tab branch from the panel's onKeyDown.
+    render(
+      <Popover trigger={<button type="button">Open</button>}>
+        {() => (
+          <button type="button">Inside</button>
+        )}
+      </Popover>,
+    );
+    const trigger = screen.getByRole("button", { name: "Open" });
+    fireEvent.click(trigger);
+    const inside = screen.getByRole("button", { name: "Inside" });
+    inside.focus();
+    expect(document.activeElement).toBe(inside);
+    fireEvent.keyDown(inside, { key: "Tab" });
+    // Closed, and focus is back on the trigger — from which the browser's own Tab default
+    // moves on to whatever genuinely follows it in the document.
+    expect(screen.queryByRole("button", { name: "Inside" })).not.toBeInTheDocument();
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it("keeps a pager button focusable when its own click disables it", () => {
+    // Each of the pager's four buttons has a bound condition recomputed from what its own click
+    // just changed, so pressing "next" until the last page disabled the control the user was
+    // operating — and a disabled element cannot hold focus, so the browser dropped it to
+    // <body>. A keyboard user paging to the end lost their place at the moment they arrived.
+    // Mutation: change aria-disabled back to disabled on the next/last pair.
+    const pagination = sources["./dataview/DataViewPagination.tsx"] ?? "";
+    expect(pagination, "DataViewPagination.tsx is not in the scanned sources").not.toBe("");
+    expect(pagination, "the native disabled attribute drops focus to <body>").not.toContain(
+      "disabled={atFirst}",
+    );
+    expect(pagination).not.toContain("disabled={atLast}");
+    expect(pagination).toContain("aria-disabled={atLast || undefined}");
+    expect(pagination).toContain("aria-disabled={atFirst || undefined}");
+    // And the sheet must paint the announced state exactly as it painted the native one, or the
+    // fix trades a focus bug for a visual one.
+    // Both anchored to the start of a line. The pager rule CONTAINS the shared selector as a
+    // substring, so a bare toContain on the shared one is satisfied by the pager rule alone
+    // and cannot notice it being deleted — which is exactly what the mutation showed.
+    expect(TERP_STYLES_CSS).toMatch(
+      /^\[data-terp="iconbutton"\]\[aria-disabled="true"\]/m,
+    );
+    expect(TERP_STYLES_CSS).toMatch(
+      /^\[data-terp="dataview-pager"\] > \[data-terp="iconbutton"\]\[aria-disabled="true"\]/m,
+    );
+  });
+
+  it("caps Markdown's blocks in a measured shell, past its own boxless wrapper", () => {
+    // Markdown is display: contents, so it generates no box — and a non-inherited property on a
+    // boxless element is dropped. The measured-width rule is a child-star selector on the page's
+    // body children, so it MATCHED the markdown wrapper and then had nothing to apply a width
+    // to: prose ran the full width of a measured shell, on the one component whose entire
+    // purpose is long-form text. The sheet's own comment beside the wrapper asserted that no
+    // child-star selector existed in the sheet, which the measured-width rule had already
+    // falsified. Mutation: delete the reach-through rule.
+    expect(TERP_STYLES_CSS).toContain('[data-terp="page"] > [data-terp="markdown"] > *');
+  });
+
+  it("paints the account menu from the sidebar family it actually sits on", () => {
+    // The trigger renders inside the sidebar (and inside the header group under
+    // navPlacement="header", which takes the sidebar surface), so its ink against that
+    // background is a pairing in play — but it read the NEUTRAL family, which the contrast gate
+    // has no sidebar-scoped pairing for. Reading the sidebar family instead puts it under
+    // `sidebar-text` and `sidebar-muted-text`, both already declared, so the gate covers it with
+    // no new entries. Provably zero-diff: the two families are byte-equal in all five themes.
+    //
+    // The role marker renders TWICE — trigger and portalled panel — so it is scoped rather than
+    // swapped; the panel is in document.body and the sidebar palette does not apply there.
+    // Mutation: put --color-neutral-900 back on the trigger.
+    const menuRule = TERP_STYLES_CSS.slice(
+      TERP_STYLES_CSS.indexOf('[data-terp="user-menu"] [data-terp="menu-trigger"] {'),
+    ).slice(0, 900);
+    expect(menuRule).toContain("color: var(--color-sidebar-fg)");
+    expect(menuRule).not.toContain("color: var(--color-neutral-900)");
+    const roleRule = TERP_STYLES_CSS.slice(
+      TERP_STYLES_CSS.indexOf('[data-terp="user-menu"] [data-terp="user-menu-role"] {'),
+    ).slice(0, 120);
+    expect(roleRule).toContain("color: var(--color-sidebar-muted)");
+  });
+});