@astryxdesign/core 0.7.5 → 0.7.6-canary.0ef60dd

package/src/Kbd/Kbd.spec.md

@@ -1,37 +1,57 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Kbd
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-31
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, theming, accessibility]
 verified_by: [packages/core/src/Kbd/Kbd.test.tsx, scripts/check-knowledge.mjs]
 modules: []
 families: []
 design_specs: []
-architecture: [architecture:component-theming-surface]
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-102]
 ---
 
 # Kbd component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                            |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | None changes. Kbd takes a `keys` string and base props.                                                                                                                                             |
+| Behavior                | Kbd splits `keys` on `+`, draws one hidden key badge per key with platform-aware glyphs, and names the whole shortcut once with spoken key names.                                                   |
+| End-user impact         | Sighted people see familiar key glyphs; screen-reader users hear the shortcut as words. Those words are English in every locale.                                                                    |
+| Builder impact          | None.                                                                                                                                                                                               |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Badges hold a fixed height; listed under Current-state impact.                                                                            |
+| Review checks           | Reject a badge that is exposed to assistive technology, a caller `role` or `aria-label` that replaces the computed one, duplicate React keys for repeated keys, or `mod` that ignores the platform. |
+| Governing rules         | `architecture:component-theming-surface`; `architecture:internationalization` INV1, INV1a; `architecture:public-component-api` INV5; `spec:AST-102` FR4.                                            |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-Kbd presents a keyboard shortcut as one or more painted key badges. This draft
-records current consumer anatomy and theming reachability without changing
-runtime behavior, styling, targets, or public API.
+Kbd presents a keyboard shortcut as one or more painted key badges. It owns
+parsing the shortcut string, the platform-aware glyph for each key, the
+shortcut's accessible name, and the `kbd` target. Consumer usage lives in
+`Kbd.doc.mjs`.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, aliases, and public API remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default,
+  export, or DOM change
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
@@ -43,54 +63,70 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 - The shortcut group, its current `kbd` target, and the painted key badges it
   renders from the supplied shortcut string.
+- Key parsing, aliases, platform-aware glyphs, and the spoken name.
 
 **Does not own / non-goals**
 
 - The action associated with the shortcut or how the shortcut is discovered —
   owned by the product callsite.
-- Whether an individual key badge should gain a public target — unresolved by
-  this factual backfill.
+- Whether an individual key badge should gain a public target — open (OQ1).
+- Listening for or handling the shortcut — not provided; Kbd is display only.
+- Caller DOM props, `ref`, `className`, `style`, and `xstyle` on the group —
+  shipped and documented, uncontracted here beyond FR4's role and label
+  precedence.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `Kbd.doc.mjs`.
+| Concept | Closed values or states                                             | Meaning               | Availability by variant/orientation/state | Default  | Owner           | Stability | Invalid-value behavior                    |
+| ------- | ------------------------------------------------------------------- | --------------------- | ----------------------------------------- | -------- | --------------- | --------- | ----------------------------------------- |
+| Keys    | `+`-separated key names; `mod`, named keys, aliases, any other text | The shortcut to show. | Always.                                   | required | `component:Kbd` | Stable    | An unknown key shows uppercased as typed. |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                          | Basis                           | Draft review state                                  |
-| --- | ------------------------------------------------------------------------------------------------------------ | ------------------------------- | --------------------------------------------------- |
-| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment.       | Current source, docs, and tests | Verified current behavior; no new behavior decided  |
-| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target. | Current source, docs, and tests | Verified current behavior; theming intent unsettled |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Basis                                                                     |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment. `keys` splits on `+`; each segment is trimmed and lowercased, `esc` reads as `escape` and `return` as `enter`, and a repeated key gets its own badge. Each badge is at least the `--spacing-5` size and MUST grow with a set text size so its glyph never clips (`spec:AST-102` FR4). Implementation gap: the badge height is fixed at `--spacing-5`.                                                                                    | Current source, docs, and tests; `spec:AST-102` FR4                       |
+| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target (OQ1).                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source, docs, and tests                                           |
+| FR3 | Each badge shows a glyph: `mod` is ⌘ on Apple platforms and the catalog's short Control text ("Ctrl" in English) elsewhere and before hydration; `escape` shows the catalog's short Escape text ("Esc"); `ctrl`, `alt`, `shift`, `enter`, `backspace`, `tab`, and the arrows show their symbols; `plus` shows "+"; any other key shows uppercased.                                                                                                                                                                                              | `architecture:internationalization` INV1a; current source and tests       |
+| FR4 | The group has `role="img"` and an `aria-label` built from each key's spoken name, taken from the Astryx catalog (`mod` is "Command" on Apple platforms and "Control" elsewhere and before hydration; an unknown key is spoken uppercased), joined pairwise through the catalog's shortcut message (" + " in English, for example "Command + K"); every badge is `aria-hidden`. A caller's `role` and `aria-label` never replace the computed ones; other caller ARIA props, such as `aria-labelledby` and `aria-hidden`, still reach the group. | `architecture:internationalization` INV1, INV1a; current source and tests |
 
 ### Allowed variation
 
-- Platform-specific key text and caller-supplied shortcut combinations may vary
-  without changing the two-part anatomy recorded here.
+- **AV1 — Shortcut content.** Platform-specific key text and caller-supplied
+  shortcut combinations may vary without changing the two-part anatomy recorded
+  here.
 
 ### Representative states
 
-- The same anatomy applies to single-key, multi-key, modifier, and
-  platform-resolved shortcuts.
+| State        | Required invariant                                        | Allowed variation |
+| ------------ | --------------------------------------------------------- | ----------------- |
+| Single key   | One badge; the name is the key's spoken name.             | Key.              |
+| Mod + key    | ⌘ or Ctrl by platform; name "Command" or "Control" + key. | Platform.         |
+| Repeated key | One badge per occurrence.                                 | —                 |
 
 ### Transformation and precedence order
 
-- No new parsing, layout, or styling precedence rule is introduced.
+- **ORD1 — Key resolution.** Split on `+` → trim → lowercase → alias → glyph
+  and spoken name.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — No listener.** Kbd attaches no event listener.
 
 ## Accessibility contract
 
-This draft does not change or extend Kbd's existing accessible-name behavior.
+- **AR1 — One name.** The shortcut is one image named by its spoken keys,
+  unless a caller's `aria-labelledby` names it; the glyph badges are hidden
+  (FR4).
+- **AR2 — Localization.** Visible short texts and spoken names follow the
+  provider locale through the catalog (FR3, FR4).
 
 ## Design relationships
 
 | Anatomy or state | Design requirement                                                 | Representation authority       | Hierarchy role | Component contract |
 | ---------------- | ------------------------------------------------------------------ | ------------------------------ | -------------- | ------------------ |
-| Shortcut         | Groups the complete shortcut and carries its accessible name.      | Current source and public docs | Supporting     | FR1, FR2           |
-| Key badge        | Paints one visible badge for each key in the supplied combination. | Current source and public docs | Prominent      | FR1, FR2           |
+| Shortcut         | Groups the complete shortcut and carries its accessible name.      | Current source and public docs | Supporting     | FR1, FR2, FR4      |
+| Key badge        | Paints one visible badge for each key in the supplied combination. | Current source and public docs | Prominent      | FR1–FR3            |
 
 ### Theming anatomy
 
@@ -116,25 +152,32 @@ target.
 - `architecture:component-theming-surface` owns anatomy qualification, target
   mapping, and the difference between factual reachability and intended public
   theming API.
+- `architecture:internationalization` owns catalog-backed Astryx text; FR3
+  and FR4 take their short texts, spoken names, and joining message from it.
 
 ## Verification map
 
-| Contract            | Verification                                     | Representative states           | Mutation or failure expectation                                                                  | Audit section       |
-| ------------------- | ------------------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------- |
-| FR1                 | `Kbd.test.tsx` key rendering suites              | Single-key and multi-key output | Removing the group or a parsed badge fails existing role, element, or text assertions.           | `audit:Kbd/anatomy` |
-| FR2                 | Source inspection and current target inventories | Root target and child badges    | Adding or documenting a current target without updating the anatomy map fails repository checks. | `audit:Kbd/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                    | Canonical anatomy and targets   | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.            | `audit:Kbd/theming` |
+| Contract            | Verification                                                                                                                                         | Representative states                                                   | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                       | Audit section             |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| FR1                 | `Kbd.test.tsx` single-key, multi-key, whitespace, alias, and repeated-key cases                                                                      | Single and multiple keys; spaced and mixed-case input; repeated aliases | A missing or extra badge, an untrimmed or wrongly cased key, or a lost alias fails. Evidence gap: no test asserts badge height or text growth.                                                                                                                                                                                                        | `audit:Kbd/anatomy`       |
+| FR2                 | `Kbd.test.tsx` theme-class case                                                                                                                      | Root target and child badges                                            | A missing root `kbd` target fails. Evidence gap: no test asserts that badges carry no target.                                                                                                                                                                                                                                                         | `audit:Kbd/theming`       |
+| FR3, FR4            | `Kbd.test.tsx` glyph, platform, accessible-name, override, and localization cases ("localizes visible key text and the spoken shortcut combination") | Mac and non-Mac; special and unknown keys                               | A wrong glyph for `mod`, `ctrl`, `alt`, `shift`, `enter`, `escape`, `plus`, or an unknown key, an exposed badge, a caller `role` or `aria-label` that replaces the computed one, or text that skips the catalog fails. Evidence gap: no test asserts the `backspace`, `tab`, or arrow glyphs, or the "Ctrl" text and "Control" name before hydration. | `audit:Kbd/accessibility` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                        | Canonical anatomy and targets                                           | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation.                                                                                                                                                                                                                                                                 | `audit:Kbd/theming`       |
+| ORD1, PR1, AR1, AR2 | ORD1 is covered by the FR1 and FR3 rows and AR1 and AR2 by the FR3, FR4 row. Evidence gap: no test asserts the absence of listeners                  | —                                                                       | —                                                                                                                                                                                                                                                                                                                                                     | `audit:Kbd/behavior`      |
+
+## Current-state impact
+
+- **Fixed badge height (FR1).** Badges hold a fixed height instead of growing
+  with a set text size, against `spec:AST-102` FR4.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-or theming decision.
+No component-local decision.
 
 ## Open questions
 
 - **OQ1 — Should each Key badge gain a stable public theming target?**
-  (`human-api`) Target exposure is unsettled; the current lack of reachability
-  does not decide the answer.
+  (`human-api`) The current lack of reachability does not decide the answer.
 
 ## Content boundary
 

package/src/Layer/__tests__/LayerBrowserHide.a11y.chromium.spec.ts

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope core/Layer
+
+/**
+ * @file LayerBrowserHide.a11y.chromium.spec.ts
+ * @input The `Core/Layer` BrowserHideWakesAFocusLayer story in a built
+ *   Storybook, driven by real Chromium pointer and keyboard input.
+ * @output Real-engine proof that a show the browser's own hide wakes — its
+ *   close watcher's Escape returning focus to a trigger whose focus-driven
+ *   layer asks to show — reaches the page as no error and ends with that
+ *   layer shown; that a tap outside, which returns no focus, hides the
+ *   layer with no error and wakes nothing; and that a press which
+ *   light-dismisses one layer and opens another opens it at once. Only a real engine
+ *   decides when a popover operation is in flight and refuses a show inside
+ *   it; the unit suite (useLayer.test.tsx) covers the same rules on a
+ *   mirrored Popover API. The in-flight rule is Chromium 150+: on the
+ *   Chromium this repository's Playwright pins (149) the first case passes
+ *   with or without the fix, so until that pin moves it guards the end state
+ *   only.
+ * @position Run with `pnpm test:a11y-contract`.
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/** Every error the page reports while the test runs: a refused show is one. */
+function collectPageErrors(page: Page): string[] {
+  const errors: string[] = [];
+  page.on('pageerror', error => {
+    errors.push(`${error.name}: ${error.message}`);
+  });
+  return errors;
+}
+
+async function openStory(page: Page, id: string): Promise<void> {
+  await page.goto(`${storybook.origin}/iframe.html?id=${id}&viewMode=story`);
+  await page.locator('#storybook-root button').first().waitFor();
+}
+
+test('an Escape the browser answers, with focus inside the layer, returns focus to the trigger and shows its focus-driven layer, without an error', async ({
+  page,
+}) => {
+  const errors = collectPageErrors(page);
+  await openStory(page, 'core-layer--browser-hide-wakes-a-focus-layer');
+  const trigger = page.getByRole('button', {name: 'Show layer'});
+  const inside = page.getByRole('button', {name: 'Inside', exact: true});
+  const hint = page.getByRole('tooltip');
+
+  // Keyboard focus shows the focus-driven layer; the press opens the content
+  // and Tab moves into it, which hides the focus-driven layer.
+  await page.keyboard.press('Tab');
+  await expect(trigger).toBeFocused();
+  await expect(hint).toBeVisible();
+  await page.keyboard.press('Enter');
+  await expect(inside).toBeVisible();
+  await page.keyboard.press('Tab');
+  await expect(inside).toBeFocused();
+  await expect(hint).toBeHidden();
+
+  // No layer handles Escape here: the browser's own close watcher hides the
+  // content layer and returns focus to the trigger inside that hide.
+  await page.keyboard.press('Escape');
+  await expect(inside).toBeHidden();
+  await expect(trigger).toBeFocused();
+  await expect(hint).toBeVisible();
+  expect(errors).toEqual([]);
+});
+
+test('a tap outside the layer, with focus inside it, hides the layer without an error; it returns no focus, so the focus-driven layer stays hidden', async ({
+  page,
+}) => {
+  const errors = collectPageErrors(page);
+  await openStory(page, 'core-layer--browser-hide-wakes-a-focus-layer');
+  const trigger = page.getByRole('button', {name: 'Show layer'});
+  const inside = page.getByRole('button', {name: 'Inside', exact: true});
+  const hint = page.getByRole('tooltip');
+
+  await page.keyboard.press('Tab');
+  await page.keyboard.press('Enter');
+  await expect(inside).toBeVisible();
+  await page.keyboard.press('Tab');
+  await expect(inside).toBeFocused();
+
+  // A light dismiss returns no focus: the press moves focus to the page
+  // before the hide runs, so nothing wakes the focus-driven layer.
+  await page.mouse.click(5, 5);
+  await expect(inside).toBeHidden();
+  await expect(trigger).not.toBeFocused();
+  await expect(hint).toBeHidden();
+  expect(errors).toEqual([]);
+});
+
+test('a press that light-dismisses one layer and opens another opens it at once: focus moves into it, without an error', async ({
+  page,
+}) => {
+  const errors = collectPageErrors(page);
+  await openStory(page, 'core-layer--browser-hide-wakes-a-focus-layer');
+  const inside = page.getByRole('button', {name: 'Inside', exact: true});
+  const otherTrigger = page.getByRole('button', {name: 'Show the other layer'});
+  const otherInside = page.getByRole('button', {name: 'Inside the other'});
+
+  await page.getByRole('button', {name: 'Show layer'}).click();
+  await expect(inside).toBeVisible();
+
+  // The browser light-dismisses the first layer at pointerup; the click opens
+  // the other one in the same gesture and focuses into it right away.
+  await otherTrigger.click();
+  await expect(inside).toBeHidden();
+  await expect(otherInside).toBeVisible();
+  await expect(otherInside).toBeFocused();
+  expect(errors).toEqual([]);
+});

package/src/Layer/popoverOperations.test.ts

@@ -0,0 +1,205 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file popoverOperations.test.ts
+ * @input Uses vitest, the popoverOperations ledger
+ * @output Unit tests for the per-document ledger of popover operations
+ * @position Core testing; validates popoverOperations.ts
+ */
+
+import {afterEach, describe, it, expect, vi} from 'vitest';
+import {
+  afterPopoverOperations,
+  isBrowserHideInFlight,
+  isPopoverOperationInFlight,
+  observeBrowserHide,
+  runPopoverOperation,
+} from './popoverOperations';
+
+/** The replay runs a microtask after the end, then one microtask per callback. */
+async function settle(): Promise<void> {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+describe('popoverOperations', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('runs a callback at once when the document has no operation in flight', () => {
+    const callback = vi.fn();
+    afterPopoverOperations(document, callback);
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('counts one of the layers’ own operations while it runs and replays a show that arrived inside it once the script has unwound', async () => {
+    const callback = vi.fn();
+    runPopoverOperation(document, () => {
+      expect(isPopoverOperationInFlight(document)).toBe(true);
+      afterPopoverOperations(document, callback);
+      expect(callback).not.toHaveBeenCalled();
+    });
+    // The operation has ended, but its caller is still on the stack.
+    expect(isPopoverOperationInFlight(document)).toBe(false);
+    expect(callback).not.toHaveBeenCalled();
+    await settle();
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('counts the browser’s own hide apart from the layers’ operations, from its start until the element’s toggle', async () => {
+    const popover = document.createElement('div');
+    document.body.appendChild(popover);
+    try {
+      const callback = vi.fn();
+      observeBrowserHide(popover);
+      observeBrowserHide(popover);
+      // A show asked now is not refused ahead of time: the engine decides.
+      expect(isPopoverOperationInFlight(document)).toBe(false);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      afterPopoverOperations(document, callback);
+      await settle();
+      expect(callback).not.toHaveBeenCalled();
+
+      popover.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(false);
+      await settle();
+      expect(callback).toHaveBeenCalledTimes(1);
+      // The toggle ended it once; the next task finds nothing to end.
+      await new Promise(resolve => setTimeout(resolve, 0));
+      expect(isBrowserHideInFlight(document)).toBe(false);
+    } finally {
+      popover.remove();
+    }
+  });
+
+  it('ends each hide exactly once: the loser of toggle and backstop is released, so a second in-flight hide keeps its count', () => {
+    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
+    const first = document.createElement('div');
+    const second = document.createElement('div');
+    document.body.append(first, second);
+    try {
+      const removeListener = vi.spyOn(second, 'removeEventListener');
+      observeBrowserHide(first);
+      observeBrowserHide(second);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      expect(vi.getTimerCount()).toBe(2);
+
+      // The first hide's toggle wins: its backstop is cleared, not left to
+      // run later against another hide's count.
+      first.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      expect(vi.getTimerCount()).toBe(1);
+      // The second hide's backstop wins: it ends the hide once and drops the
+      // one-shot toggle listener.
+      vi.runOnlyPendingTimers();
+      expect(isBrowserHideInFlight(document)).toBe(false);
+      expect(removeListener).toHaveBeenCalledWith(
+        'toggle',
+        expect.any(Function),
+      );
+
+      // A toggle after the backstop won, and a second toggle after the toggle
+      // won, change nothing: the one-shot listeners are gone.
+      observeBrowserHide(first);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      second.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      first.dispatchEvent(new Event('toggle'));
+      first.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(document)).toBe(false);
+
+      // Nothing drifted negative: a later hide is still counted.
+      observeBrowserHide(second);
+      expect(isBrowserHideInFlight(document)).toBe(true);
+      vi.runOnlyPendingTimers();
+      expect(isBrowserHideInFlight(document)).toBe(false);
+    } finally {
+      first.remove();
+      second.remove();
+    }
+  });
+
+  it('ends a counted hide at the next task when its toggle never arrives (the element left the document)', async () => {
+    const popover = document.createElement('div');
+    document.body.appendChild(popover);
+    const callback = vi.fn();
+    observeBrowserHide(popover);
+    popover.remove();
+    afterPopoverOperations(document, callback);
+    await settle();
+    expect(callback).not.toHaveBeenCalled();
+    await new Promise(resolve => setTimeout(resolve, 0));
+    expect(isBrowserHideInFlight(document)).toBe(false);
+    await settle();
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+
+  it('postpones the replay when another operation starts before it runs', async () => {
+    const callback = vi.fn();
+    runPopoverOperation(document, () => {
+      afterPopoverOperations(document, callback);
+    });
+    // Before the replay's microtask: a browser-run hide starts, and ends.
+    const second = document.createElement('div');
+    document.body.appendChild(second);
+    try {
+      observeBrowserHide(second);
+      await settle();
+      expect(callback).not.toHaveBeenCalled();
+      second.dispatchEvent(new Event('toggle'));
+      await settle();
+      expect(callback).toHaveBeenCalledTimes(1);
+    } finally {
+      second.remove();
+    }
+  });
+
+  it('replays each callback in its own microtask, so a throw in one reaches the page alone and leaves the rest to run', async () => {
+    const queued = vi.spyOn(globalThis, 'queueMicrotask');
+    try {
+      const first = vi.fn();
+      const second = vi.fn();
+      runPopoverOperation(document, () => {
+        afterPopoverOperations(document, first);
+        afterPopoverOperations(document, second);
+      });
+      // One microtask replays the batch; it queues one more per callback.
+      expect(queued).toHaveBeenCalledTimes(1);
+      await Promise.resolve();
+      expect(queued).toHaveBeenCalledTimes(3);
+      expect(first).not.toHaveBeenCalled();
+      await Promise.resolve();
+      expect(first).toHaveBeenCalledTimes(1);
+      expect(second).toHaveBeenCalledTimes(1);
+      expect(first.mock.invocationCallOrder[0]).toBeLessThan(
+        second.mock.invocationCallOrder[0] ?? 0,
+      );
+    } finally {
+      queued.mockRestore();
+    }
+  });
+
+  it('keeps one ledger per document', async () => {
+    const frame = document.createElement('iframe');
+    document.body.appendChild(frame);
+    const other = frame.contentDocument;
+    if (other == null) {
+      throw new Error('the iframe has no document');
+    }
+    try {
+      const callback = vi.fn();
+      const popover = other.createElement('div');
+      other.body.appendChild(popover);
+      observeBrowserHide(popover);
+      expect(isBrowserHideInFlight(document)).toBe(false);
+      afterPopoverOperations(document, callback);
+      expect(callback).toHaveBeenCalledTimes(1);
+      expect(isBrowserHideInFlight(other)).toBe(true);
+      popover.dispatchEvent(new Event('toggle'));
+      expect(isBrowserHideInFlight(other)).toBe(false);
+    } finally {
+      frame.remove();
+    }
+  });
+});