paperlint 14.1.0 → 14.3.0

package/skills/build-label-page/scripts/label-page-browser.test.ts

@@ -9,9 +9,11 @@ import {
   chromium,
   type Locator,
   type Page,
+  selectors,
 } from "playwright-core";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import * as R from "remeda";
 import { afterAll, test } from "vitest";
 import { z } from "zod";
 import { chromiumPath } from "../../../test/chromium.ts";
@@ -19,7 +21,9 @@ import {
   APPROVAL_PRACTICE,
   PRACTICE,
   QUESTIONS,
+  ITEMS,
   approval,
+  approvalCard,
   build,
   config,
   setup,
@@ -32,6 +36,7 @@ const STORE = (
   answers: Record<string, unknown> = {},
 ): string => `
   window.__writes = [];
+  window.__ids = [];
   (function () {
     var docs = { answers: ${JSON.stringify(answers)}, groups: {}, practice: ${JSON.stringify(practice)} };
     var subs = {};
@@ -44,6 +49,7 @@ const STORE = (
       onSnapshot: function (cb) { (subs[n] = subs[n] || []).push(cb); snap(n); },
       doc: function (id) { return { set: function (body) {
         window.__writes.push(body);
+        window.__ids.push(n + "/" + id);
         docs[n][id] = body;
         return new Promise(function (r) { setTimeout(function () { r(); snap(n); }, ${String(echoMs)}); });
       } }; }
@@ -358,9 +364,9 @@ async function onWitnessPage(
   }
 }
 
-/** The code, the linter's message, the question, the rule docs' toggle: one read of the laid-out card,
+/** The code, the linter's message, the question, the rule docs' heading: one read of the laid-out card,
  * so a re-render between reads cannot mix two layouts. */
-const LAYOUT_OF = ["pre.numbered", "p.said", ".ask", "details > summary"];
+const LAYOUT_OF = ["pre.numbered", "p.said", ".ask", ".rulebox > h3"];
 const Layout = z.array(z.object({ top: z.number(), bottom: z.number() }));
 const layout = async (card: Locator) =>
   Layout.parse(
@@ -375,7 +381,7 @@ const layout = async (card: Locator) =>
   );
 
 test(
-  "🔴 at phone width a witness card labels the caught line in its numbered code, asks its question right under that code, folds the rule docs and the settings, opens a long text on «more», and nothing pushes the page sideways",
+  "🔴 at phone width a witness card labels the caught line in its numbered code, asks its question right under that code, shows the rule docs and the settings in place, opens a long text on «more», and nothing pushes the page sideways",
   async () => {
     await onWitnessPage("browser-witness", async (page) => {
       // Measure after the store's practice answers arrived: before them the practice cards sit above.
@@ -386,19 +392,24 @@ test(
         await card.locator("pre.numbered .hit").textContent(),
         '▶18print(f"seeded {len(rows)} rows")◀ this line',
       );
-      // Guards: the rule docs, the files like it and the settings are folded.
+      // Guards: nothing a card needs is folded (#392); the rule docs, the files like it and the
+      // settings are shown in place, each under its heading.
       assert.deepEqual(
         [
           await card.locator("details").count(),
-          await card.locator("details[open]").count(),
+          await card.locator(".rulebox > h3").allTextContents(),
+        ],
+        [
+          0,
+          [
+            "What the linter rule does (official docs)",
+            "3 more file(s) with the same situation",
+            "Settings behind this card",
+          ],
         ],
-        [3, 0],
       );
       // The question sits right under the code it is about: only the linter's message between them,
       // and the rule's docs start below the answers.
-      const docsSummary = card.locator("summary", {
-        hasText: "What the linter rule does (official docs)",
-      });
       const box = await layout(card);
       const [code, said, ask, docs] = box;
       assert.ok(code && said && ask && docs, JSON.stringify(box));
@@ -408,7 +419,6 @@ test(
       );
       assert.ok(ask.top - said.bottom < 40, JSON.stringify(box));
       assert.ok(docs.top >= ask.bottom, JSON.stringify(box));
-      await docsSummary.click();
       const why = card.locator(".clamped", { hasText: "Why:" });
       const folded = (await why.boundingBox())?.height ?? 0;
       await card.getByRole("button", { name: "more" }).first().click();
@@ -606,3 +616,744 @@ test(
   },
   BROWSER_TEST_MS,
 );
+
+/** The collection and document id of every write, in order. */
+const writtenIds = async (page: Page): Promise<readonly string[]> =>
+  z.array(z.string()).parse(await page.evaluate("window.__ids"));
+/** A page served from an origin of its own, so it has a localStorage that a reload keeps. */
+async function served(page: Page, html: string): Promise<void> {
+  await page.route("http://label.test/", (route) =>
+    route.fulfill({ body: html, contentType: "text/html" }),
+  );
+  await page.goto("http://label.test/");
+}
+const prefixedPractice = (who: string) =>
+  R.mapKeys(PRACTICE_DONE, (k) => `${who}~${k}`);
+
+test(
+  "🔴 without answerers the page asks nobody's name and writes the documents it always wrote, with no seconds",
+  async () => {
+    const { page: html } = build(
+      setup(
+        "browser-plain-ids",
+        approval({ items: ITEMS.slice(0, 2).map(approvalCard) }),
+      ),
+    );
+    const page = await (await sharedBrowser()).newPage();
+    try {
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.goto("about:blank");
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      assert.equal(await page.getByText("Who is answering?").count(), 0);
+      await page.getByRole("button", { name: /Keep/ }).first().click();
+      await page.waitForTimeout(100);
+      assert.deepEqual(await writtenIds(page), ["answers/G001"]);
+      assert.deepEqual(Object.keys((await writes(page))[0] ?? {}).sort(), [
+        "answers",
+        "reasons",
+        "savedAt",
+        "source",
+      ]);
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+/** Three approval cards: the first two for both answerers, the third for `author` only. */
+const TWO_PAGE = (over: Record<string, unknown> = {}) =>
+  approval({
+    answerers: ["author", "second"],
+    items: ITEMS.slice(0, 3)
+      .map(approvalCard)
+      .map((i, n) => (n === 2 ? R.merge(i, { answerers: ["author"] }) : i)),
+    ...over,
+  });
+
+test(
+  "🔴 with answerers the page asks who is answering, remembers it, writes and reads only that answerer's documents, and can switch",
+  async () => {
+    const dir = setup("browser-answerers", TWO_PAGE());
+    const { page: html, key } = build(dir);
+    const third = Object.entries(key.ids).find(
+      ([, v]) => v.source_id === "case-1002",
+    )?.[0];
+    const [first] = Object.keys(key.ids).filter((n) => n !== third);
+    assert.ok(third !== undefined && first !== undefined);
+    const page = await (await sharedBrowser()).newPage();
+    try {
+      await page.addInitScript(
+        STORE(prefixedPractice("second"), 20, {
+          [`author~${first}`]: { answers: { keep: "keep" }, source: "page" },
+        }),
+      );
+      await served(page, html);
+      assert.equal(await page.getByText("Who is answering?").count(), 1);
+      assert.equal(await page.locator("article.item").count(), 0);
+      await page.getByRole("button", { name: "second", exact: true }).click();
+      // Guards: second sees two items, none answered: author's answer is not theirs.
+      assert.equal(await page.locator("article.item").count(), 2);
+      assert.equal(await page.getByText("0 of 2 items complete").count(), 1);
+      await page
+        .locator("article.item", { hasText: first })
+        .getByRole("button", { name: /Keep/ })
+        .click();
+      await page.waitForTimeout(100);
+      assert.deepEqual(await writtenIds(page), [`answers/second~${first}`]);
+      // A reload remembers who is answering.
+      await page.reload();
+      // (The stand-in store starts afresh on a reload: only the name is checked here.)
+      assert.equal(await page.getByText("Answering as second").count(), 1);
+      await page.getByRole("button", { name: "Switch" }).click();
+      await page.getByRole("button", { name: "author", exact: true }).click();
+      // author has not done the practice: it opens, and its answers go under author's name.
+      assert.equal(
+        await page.getByText("Practice: 0 of 3 answered").count(),
+        1,
+      );
+      await page
+        .locator("article.item")
+        .first()
+        .getByRole("button", { name: /Keep/ })
+        .click();
+      await page.waitForTimeout(100);
+      assert.equal((await writtenIds(page)).at(-1), "practice/author~r1-P1");
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 with answerers and no localStorage the page still works: it asks, and writes under the name picked",
+  async () => {
+    const { page: html } = build(setup("browser-answerers-nols", TWO_PAGE()));
+    const page = await (await sharedBrowser()).newPage();
+    try {
+      await page.addInitScript(
+        `Object.defineProperty(window, "localStorage", { get: function () { throw new Error("denied"); } });`,
+      );
+      await page.addInitScript(STORE(prefixedPractice("author"), 20));
+      await served(page, html);
+      await page.getByRole("button", { name: "author", exact: true }).click();
+      assert.equal(await page.locator("article.item").count(), 3);
+      await page
+        .locator("article.item", { hasText: "G001" })
+        .getByRole("button", { name: /Keep/ })
+        .click();
+      await page.waitForTimeout(100);
+      assert.deepEqual(await writtenIds(page), ["answers/author~G001"]);
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 with min_seconds a card's answer saves only after the card was that long on screen; a card never on screen stays locked; the seconds are stored",
+  async () => {
+    const { page: html } = build(
+      setup("browser-dwell", approval({ min_seconds: 2 })),
+    );
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 700 } });
+    try {
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.goto("about:blank");
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      const cards = page.locator("article.item");
+      const firstCard = cards.first();
+      const lastCard = cards.last();
+      await firstCard.scrollIntoViewIfNeeded();
+      const keep = firstCard.getByRole("button", { name: /Keep/ });
+      assert.equal(await keep.isDisabled(), true);
+      assert.match((await firstCard.textContent()) ?? "", /answer in [12] s/);
+      await keep.click({ force: true });
+      assert.deepEqual(await writes(page), [], "nothing saves before the time");
+      await page.waitForTimeout(2600);
+      assert.equal(await keep.isDisabled(), false);
+      assert.equal(
+        await lastCard.getByRole("button", { name: /Keep/ }).isDisabled(),
+        true,
+        "the last card was never on screen",
+      );
+      await keep.click();
+      await page.waitForTimeout(100);
+      const [stored] = z
+        .array(z.object({ seconds: z.number().int() }).loose())
+        .parse(await page.evaluate("window.__writes"));
+      assert.ok(
+        stored !== undefined && stored.seconds >= 2 && stored.seconds <= 4,
+        JSON.stringify(stored),
+      );
+      await lastCard.scrollIntoViewIfNeeded();
+      await page.waitForTimeout(2600);
+      assert.equal(
+        await lastCard.getByRole("button", { name: /Keep/ }).isDisabled(),
+        false,
+      );
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 with min_seconds a tall card's clock stops when less than its share is in view, even between the observer's steps",
+  async () => {
+    const { page: html } = build(
+      setup("browser-dwell-tall", approval({ min_seconds: 2 })),
+    );
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 300 } });
+    try {
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.goto("about:blank");
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      await page.addStyleTag({
+        content: "article.item { min-height: 1200px; box-sizing: border-box; }",
+      });
+      const lastCard = page.locator("article.item").last();
+      const keep = lastCard.getByRole("button", { name: /Keep/ });
+      await keep.waitFor();
+      // Show `px` of the last card at the bottom of the viewport. The card is 1200 px and the
+      // viewport 300 px, so it is on screen with half the viewport, 150 px (12.5 %), in view.
+      const show = (px: number) =>
+        page.evaluate(
+          `(() => { const c = document.querySelectorAll("article.item"); const r = c[c.length - 1].getBoundingClientRect(); window.scrollTo(0, window.scrollY + r.top - window.innerHeight + ${String(px)}); })()`,
+        );
+      await show(170); // 14.2 %: above the share
+      await page.waitForTimeout(200);
+      await show(140); // 11.7 %: below it, and no 5 % step is crossed on the way
+      await page.waitForTimeout(2600);
+      assert.equal(
+        await keep.isDisabled(),
+        true,
+        "140 px of the card in view for 2.6 s does not count",
+      );
+      await show(200);
+      await page.waitForTimeout(2600);
+      assert.equal(
+        await keep.isDisabled(),
+        false,
+        "200 px in view for 2.6 s counts",
+      );
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 with min_seconds a card over 20 viewports tall still unlocks when it fills the screen, and one that grows is judged at its new height",
+  async () => {
+    const { page: html } = build(
+      setup("browser-dwell-huge", approval({ min_seconds: 2 })),
+    );
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 300 } });
+    try {
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.goto("about:blank");
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      const cards = page.locator("article.item");
+      const huge = cards.last();
+      await huge.getByRole("button", { name: /Keep/ }).waitFor();
+      // The card grows after it was drawn and watched, with no render.
+      await huge.evaluate((el) => {
+        el.style.minHeight = "7000px";
+        el.scrollIntoView({ block: "start" });
+        window.scrollBy(0, 2000);
+      });
+      await page.waitForTimeout(2600);
+      assert.equal(
+        await huge.getByRole("button", { name: /Keep/ }).isDisabled(),
+        false,
+        "a 7000 px card filling a 300 px viewport for 2.6 s counts",
+      );
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 with min_seconds a page that loaded in a hidden tab starts the clock of a card in view when the tab comes back",
+  async () => {
+    const { page: html } = build(
+      setup("browser-dwell-hidden", approval({ min_seconds: 2 })),
+    );
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 700 } });
+    try {
+      await page.addInitScript(
+        `window.__vis = "hidden"; Object.defineProperty(Document.prototype, "visibilityState", { configurable: true, get: function () { return window.__vis; } });`,
+      );
+      await page.addInitScript(STORE(PRACTICE_DONE, 20));
+      await page.goto("about:blank");
+      await page.setContent(html, { waitUntil: "domcontentloaded" });
+      const firstCard = page.locator("article.item").first();
+      await firstCard.scrollIntoViewIfNeeded();
+      await page.waitForTimeout(300);
+      await page.evaluate(
+        `window.__vis = "visible"; document.dispatchEvent(new Event("visibilitychange"));`,
+      );
+      await page.waitForTimeout(2600);
+      assert.equal(
+        await firstCard.getByRole("button", { name: /Keep/ }).isDisabled(),
+        false,
+        "the card was in view for 2.6 s after the tab came back",
+      );
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+// ── the approved card (#392): a code-review note on the marked line, tap-to-see notes on terms ──
+// Every element these tests touch carries `data-test`, found only by getByTestId; its values are the
+// JSON in `data-test-meta`. A text that is content (the annotation, the quote) is read against the
+// fixture's own value, never retyped here.
+selectors.setTestIdAttribute("data-test");
+const V7_FIXTURE = join(import.meta.dirname, "fixtures", "v7-cards-items.json");
+const V7_CARD = z
+  .object({
+    source_id: z.string(),
+    terms: z.array(
+      z.object({
+        term: z.string(),
+        note: z.array(
+          z
+            .object({
+              quote: z.string().optional(),
+              url: z.string(),
+              url_label: z.string(),
+            })
+            .loose(),
+        ),
+      }),
+    ),
+    excerpt: z.object({
+      gutter_header: z.string().optional(),
+      annotation: z.string(),
+      lines: z.array(
+        z.object({
+          n: z.number(),
+          mark: z.boolean(),
+          context: z.boolean().optional(),
+          gutter: z.string().optional(),
+        }),
+      ),
+    }),
+    answer_notes: z.object({ forbid: z.record(z.string(), z.string()) }),
+  })
+  .loose();
+const V7_CONFIG = z
+  .object({ practice: z.array(z.unknown()), items: z.array(z.unknown()) })
+  .loose()
+  .parse(JSON.parse(readFileSync(V7_FIXTURE, "utf8")));
+const V7_CARDS = z.array(V7_CARD).parse(V7_CONFIG.items);
+/** The fixture's card of that source id. */
+const fixtureCard = (sourceId: string) => {
+  const found = V7_CARDS.find((i) => i.source_id === sourceId);
+  assert.ok(found !== undefined, sourceId);
+  return found;
+};
+/** A fixture text as the page shows it: its `backticks` are code spans, not characters. */
+const unticked = (text: string): string => text.split("`").join("");
+/** The values an element carries in `data-test-meta`. */
+const metaOf = async (l: Locator): Promise<unknown> =>
+  JSON.parse((await l.getAttribute("data-test-meta")) ?? "null");
+/** The elements of one kind, each with its values. */
+const allByKind = async (scope: Page | Locator, kind: string) =>
+  Promise.all(
+    (await scope.getByTestId(kind).all()).map(async (loc) => ({
+      loc,
+      meta: await metaOf(loc),
+    })),
+  );
+const Id = z.object({ id: z.string() });
+const Term = z.object({ term: z.string() });
+const Answer = z.object({ question: z.string(), value: z.string() });
+const CodeLine = z.object({
+  line: z.number(),
+  marked: z.boolean(),
+  gutter: z.string(),
+  context: z.boolean(),
+});
+/** The three-card fixture, practice done, without its time on screen, at 400 px wide. */
+async function onV7Page(
+  name: string,
+  steps: (
+    page: Page,
+    cardOf: (sourceId: string) => Promise<Locator>,
+  ) => Promise<void>,
+  withTime = false,
+): Promise<void> {
+  const { page: html, key } = build(
+    setup(name, withTime ? V7_CONFIG : R.omit(V7_CONFIG, ["min_seconds"])),
+  );
+  const done = ["forbid", "allow", "elsewhere"];
+  const page = await (
+    await sharedBrowser()
+  ).newPage({ viewport: { width: 400, height: 800 } });
+  try {
+    await page.addInitScript(
+      STORE(
+        Object.fromEntries(
+          done.map((v, n) => [
+            `r1-P${String(n + 1)}`,
+            { answers: { forbid: v }, source: "page" },
+          ]),
+        ),
+        20,
+      ),
+    );
+    await page.goto("about:blank");
+    await page.setContent(html, { waitUntil: "domcontentloaded" });
+    await page.getByTestId("item").first().waitFor();
+    const cardOf = async (sourceId: string) => {
+      const id = Object.entries(key.ids).find(
+        ([, v]) => v.source_id === sourceId,
+      )?.[0];
+      const found = (await allByKind(page, "item")).find(
+        (c) => Id.parse(c.meta).id === id,
+      );
+      assert.ok(found !== undefined, `${sourceId} is drawn`);
+      return found.loc;
+    };
+    await steps(page, cardOf);
+  } finally {
+    await page.context().close();
+  }
+}
+/** The term of that text on a card. */
+const termOf = async (card: Locator, term: string) => {
+  const found = (await allByKind(card, "term")).find(
+    (t) => Term.parse(t.meta).term === term,
+  );
+  assert.ok(found !== undefined, `${term} is a button`);
+  return found.loc;
+};
+const answerOf = async (card: Locator, value: string) => {
+  const found = (await allByKind(card, "answer")).find(
+    (a) => Answer.parse(a.meta).value === value,
+  );
+  assert.ok(found !== undefined, `${value} is an answer`);
+  return found.loc;
+};
+/** The open note: whether it shows, which term, its box, and the terms marked open. */
+const Tip = z.object({ term: z.string(), open: z.boolean() });
+const tipNow = async (page: Page) => {
+  const tip = page.getByTestId("tip");
+  const drawn = (await tip.count()) > 0;
+  const state = drawn
+    ? Tip.parse(await metaOf(tip))
+    : { term: "", open: false };
+  const box = drawn && state.open ? await tip.boundingBox() : null;
+  const expanded = await Promise.all(
+    (await allByKind(page, "term")).map(async (t) => ({
+      term: Term.parse(t.meta).term,
+      open: (await t.loc.getAttribute("aria-expanded")) === "true",
+    })),
+  );
+  return {
+    ...state,
+    left: box?.x ?? -1,
+    right: box ? box.x + box.width : -1,
+    width: box?.width ?? -1,
+    expanded: expanded.filter((t) => t.open).map((t) => t.term),
+  };
+};
+
+/** Wait until the note reports itself closed (it closes on its own schedule). */
+const noteClosed = (page: Page) =>
+  page.waitForFunction(
+    `JSON.parse(document.querySelector('[data-test="tip"]').getAttribute("data-test-meta")).open === false`,
+    undefined,
+    { timeout: 5_000 },
+  );
+
+test(
+  "🔴 a dotted term opens one floating note on a tap, with its quote and its source link, anchored and inside a 400 px viewport",
+  async () => {
+    await onV7Page("browser-v7-tip", async (page, cardOf) => {
+      const docstring = fixtureCard("card-docstring");
+      const google = docstring.terms.find((t) => t.term === "Google-style");
+      assert.ok(google !== undefined);
+      await (await termOf(await cardOf("card-docstring"), google.term)).click();
+      const tip = await tipNow(page);
+      assert.deepEqual(
+        [tip.term, tip.open, tip.expanded],
+        [google.term, true, [google.term]],
+      );
+      assert.deepEqual(
+        [
+          await page.getByTestId("tip-quote").allTextContents(),
+          (await allByKind(page, "tip-link")).map((l) => l.meta),
+          await page.getByTestId("tip-link").allTextContents(),
+        ],
+        [
+          google.note.flatMap((e) => e.quote ?? []),
+          google.note.map((e) => ({ url: e.url })),
+          google.note.map((e) => e.url_label),
+        ],
+      );
+      // Inside the viewport and at most 300 px wide, for a term near either edge.
+      const edges = [];
+      for (const [source, term] of [
+        ["card-docstring", ".github/copilot-instructions.md"],
+        ["card-depth", "guard clauses"],
+        ["card-call", "document.getElementById"],
+      ] as const) {
+        // Each term is measured on its own: the note of the one before may cover this one.
+        await page.keyboard.press("Escape");
+        await noteClosed(page);
+        await (await termOf(await cardOf(source), term)).click();
+        const t = await tipNow(page);
+        edges.push([t.term, t.left >= 0 && t.right <= 400 && t.width <= 300]);
+      }
+      assert.deepEqual(edges, [
+        [".github/copilot-instructions.md", true],
+        ["guard clauses", true],
+        ["document.getElementById", true],
+      ]);
+    });
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 a tap outside the open note closes it and answers nothing; Esc closes it; a second term closes the first",
+  async () => {
+    await onV7Page("browser-v7-close", async (page, cardOf) => {
+      const depth = await cardOf("card-depth");
+      // The note covers the first answers; the tap lands on an answer it leaves visible.
+      await (await termOf(depth, "guard clauses")).click();
+      await (await answerOf(depth, "unsettled")).click();
+      await page.waitForTimeout(100);
+      assert.deepEqual(
+        [(await tipNow(page)).open, (await writes(page)).length],
+        [false, 0],
+      );
+      await (await termOf(await cardOf("card-call"), "AGENTS.md")).click();
+      await page.keyboard.press("Escape");
+      assert.equal((await tipNow(page)).open, false);
+      const docstring = await cardOf("card-docstring");
+      const d413 = fixtureCard("card-docstring").terms.find(
+        (t) => t.term === "D413",
+      );
+      assert.ok(d413 !== undefined);
+      await (await termOf(docstring, "Ruff")).click();
+      await (await termOf(docstring, d413.term)).click();
+      const t = await tipNow(page);
+      assert.deepEqual(
+        [
+          t.open,
+          t.expanded,
+          await page.getByTestId("tip-quote").allTextContents(),
+        ],
+        [true, [d413.term], d413.note.flatMap((e) => e.quote ?? [])],
+      );
+      // With the note closed, the same answer saves.
+      await page.keyboard.press("Escape");
+      await (await answerOf(depth, "unsettled")).click();
+      await page.waitForTimeout(100);
+      assert.equal((await writes(page)).length, 1);
+    });
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 a note opened by hover stays open while the pointer crosses the gap to it, keeps its link reachable, and closes after the pointer leaves for good",
+  async () => {
+    await onV7Page("browser-v7-hover", async (page, cardOf) => {
+      const docstring = await cardOf("card-docstring");
+      const google = fixtureCard("card-docstring").terms.find(
+        (t) => t.term === "Google-style",
+      );
+      assert.ok(google !== undefined);
+      const term = await termOf(docstring, google.term);
+      // A slow runner must not outrun the grace delay while the pointer crosses the gap.
+      await page.evaluate("window.__tipGraceMs = 5000");
+      // At its top left corner: a term that wraps has a box whose middle may lie over another term.
+      await term.hover({ position: { x: 4, y: 4 } });
+      assert.deepEqual(
+        [(await tipNow(page)).term, (await tipNow(page)).open],
+        [google.term, true],
+      );
+      // Straight down from the term, in small steps, through the gap into the note. Only the gap
+      // lies between them on this path, so no other term opens on the way.
+      const tip = page.getByTestId("tip");
+      const from = await term.boundingBox();
+      const to = await tip.boundingBox();
+      assert.ok(from !== null && to !== null);
+      const top = from.y + from.height;
+      // The other terms do not react while the pointer crosses: only the gap is under test, and
+      // which term lies in it depends on how the line wraps. The arrow bridges the gap at the
+      // middle of the term, so the crossing is at its right end.
+      await page.addStyleTag({
+        content: 'button.term[aria-expanded="false"] { pointer-events: none; }',
+      });
+      const x = from.x + from.width - 8;
+      assert.ok(
+        to.y > top && x > to.x && x < to.x + to.width,
+        "the note lies below the term and covers that column",
+      );
+      await page.mouse.move(x, from.y + from.height - 1);
+      for (const k of R.range(0, Math.ceil((to.y + 10 - top) / 3))) {
+        await page.mouse.move(x, top + 3 * k);
+      }
+      await page.mouse.move(x, to.y + 10);
+      const inside = await tipNow(page);
+      assert.deepEqual(
+        [inside.term, inside.open, inside.expanded],
+        [google.term, true, [google.term]],
+      );
+      // Guards: the link answers a click at its own position, nothing covers it.
+      await page.getByTestId("tip-link").first().click({ trial: true });
+      // Far from the term and the note, it closes by itself once the grace delay has run out.
+      await page.evaluate("window.__tipGraceMs = 50");
+      await page.mouse.move(2, 2, { steps: 20 });
+      await noteClosed(page);
+      assert.equal((await tipNow(page)).open, false);
+    });
+  },
+  BROWSER_TEST_MS,
+);
+
+/** What the depth card shows around its marked line, read from the page. */
+async function annotatedFacts(depth: Locator) {
+  const lines = await allByKind(depth, "code-line");
+  const header = depth.getByTestId("code-header");
+  const anno = depth.getByTestId("annotation");
+  const subs = await allByKind(depth, "answer-sub");
+  return {
+    annotation: [await metaOf(anno), await anno.textContent()],
+    header: [
+      await metaOf(header),
+      await header.getByTestId("gutter").textContent(),
+    ],
+    lines: lines.map((l) => l.meta),
+    gutters: await Promise.all(
+      lines.map((l) => l.loc.getByTestId("gutter").textContent()),
+    ),
+    gaps: (await allByKind(depth, "gap")).map((g) => g.meta),
+    subs: await Promise.all(
+      subs.map(async (s) => [s.meta, await s.loc.textContent()]),
+    ),
+  };
+}
+/** The same facts, as the fixture states them. */
+function annotatedExpected(fixture: z.infer<typeof V7_CARD>) {
+  const rows = fixture.excerpt.lines;
+  return {
+    annotation: [
+      { line: rows.find((l) => l.mark)?.n },
+      unticked(fixture.excerpt.annotation),
+    ],
+    header: [
+      { gutter: fixture.excerpt.gutter_header },
+      fixture.excerpt.gutter_header,
+    ],
+    lines: rows.map((l) => ({
+      line: l.n,
+      marked: l.mark,
+      gutter: l.gutter ?? "",
+      context: l.context ?? false,
+    })),
+    gutters: rows.map((l) => l.gutter ?? ""),
+    gaps: R.zip(rows, rows.slice(1))
+      .filter(([a, b]) => b.n > a.n + 1)
+      .map(([a, b]) => ({ from: a.n + 1, to: b.n - 1 })),
+    subs: Object.entries(fixture.answer_notes.forbid).map(([v, text]) => [
+      { question: "forbid", value: v },
+      unticked(text),
+    ]),
+  };
+}
+
+test(
+  "🔴 the annotation sits right under the marked line inside the code; the gutter column has its header and its values; each answer carries its sub-line",
+  async () => {
+    await onV7Page("browser-v7-card", async (page, cardOf) => {
+      const depth = await cardOf("card-depth");
+      const lines = await allByKind(depth, "code-line");
+      const marked = lines.find((l) => CodeLine.parse(l.meta).marked);
+      assert.ok(marked !== undefined, "the marked line is drawn");
+      const [hit, note] = [
+        await marked.loc.boundingBox(),
+        await depth.getByTestId("annotation").boundingBox(),
+      ];
+      assert.ok(hit && note, "both drawn");
+      assert.ok(
+        note.y >= hit.y + hit.height && note.y - (hit.y + hit.height) < 16,
+        JSON.stringify([hit, note]),
+      );
+      assert.deepEqual(
+        await annotatedFacts(depth),
+        annotatedExpected(fixtureCard("card-depth")),
+      );
+      assert.equal(
+        await page.evaluate(() => document.documentElement.scrollWidth),
+        400,
+      );
+    });
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 a card still on its time shows its wait bar with the seconds left, in the page's own words, and the answers wait",
+  async () => {
+    await onV7Page(
+      "browser-v7-wait",
+      async (page, cardOf) => {
+        const { labels, min_seconds: total } = z
+          .object({
+            labels: z.object({ wait: z.string() }),
+            min_seconds: z.number(),
+          })
+          .loose()
+          .parse(V7_CONFIG);
+        const bar = (await cardOf("card-depth")).getByTestId("wait");
+        // One read of both, so a tick between two reads cannot mix them.
+        const [text, raw] = z
+          .tuple([z.string(), z.string()])
+          .parse(
+            await bar.evaluate((n) => [
+              n.textContent,
+              n.getAttribute("data-test-meta"),
+            ]),
+          );
+        const meta = z
+          .object({ id: z.string(), seconds: z.number() })
+          .parse(JSON.parse(raw));
+        assert.deepEqual(
+          [
+            meta.seconds > 0 && meta.seconds <= total,
+            text,
+            await (
+              await answerOf(await cardOf("card-depth"), "forbid")
+            ).isDisabled(),
+          ],
+          [true, labels.wait.replace("{s}", String(meta.seconds)), true],
+        );
+      },
+      true,
+    );
+  },
+  BROWSER_TEST_MS,
+);