@astryxdesign/core 0.7.2-canary.fbc03f7 → 0.7.2-canary.fdd384f

package/src/DropdownMenu/DropdownMenuDivider.spec.md

@@ -0,0 +1,192 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:DropdownMenuDivider
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [public-api, behavior, theming, accessibility, testing]
+verified_by:
+  [
+    packages/core/src/DropdownMenu/DropdownMenu.test.tsx,
+    packages/core/src/ContextMenu/ContextMenu.test.tsx,
+    packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/DropdownMenuDivider.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:component-test-sufficiency,
+  ]
+contributing: []
+system_specs: [spec:AST-020, spec:AST-029]
+---
+
+# DropdownMenuDivider component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                           |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `DropdownMenuDivider` / `DropdownMenuDividerProps`, plus the `ContextMenuDivider` and `BreadcrumbMenuDivider` aliases and their props; `BaseProps<HTMLDivElement>` minus caller-owned `role` and `aria-orientation`; a root `ref`. |
+| Behavior                | One unlabelled horizontal separator divides pointer-menu rows and stays out of arrow-key order; data and compound pointer modes render the same component.                                                                         |
+| End-user impact         | Pointer-menu sections remain visually separated without adding a focus stop or changing row operation.                                                                                                                             |
+| Builder impact          | No new caller choice. Host attributes, handlers, and styling inputs continue to compose on the separator.                                                                                                                          |
+| Compatibility/readiness | Patch-compatible observational contract. Runtime behavior, exports, defaults, and target names remain unchanged; authority stays `draft` until exact-head owner approval.                                                          |
+| Review checks           | Reject a focusable separator, changed role/orientation, pointer data/compound divergence, dropped root inputs, or a target moved off the visible separator.                                                                        |
+| Governing rules         | `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV6`; WCAG 2.2 SC 1.3.1 and 4.1.2 through `spec:AST-020/FR1`.                                                                    |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+DropdownMenuDivider provides the visual and programmatic boundary between groups
+of rows in pointer-menu presentations. It ships directly under the DropdownMenu
+name and through ContextMenu and Breadcrumbs aliases. It owns the separator
+semantics, menu spacing, root input composition, and the
+`dropdown-menu-divider` theme target. The surrounding DropdownMenu, ContextMenu,
+or BreadcrumbItem owns menu lifecycle and row navigation; Divider supplies the
+base rule geometry and paint.
+
+Consumer syntax and examples belong in `DropdownMenuDivider.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: yes — one horizontal, unlabelled separator.
+- Compatibility class: observational patch; no behavior or public surface changes.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: none.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- One horizontal separator root and its public ref, DOM/data/ARIA, class, style,
+  event, and `xstyle` composition.
+- Menu-specific block-axis spacing.
+- The `dropdown-menu-divider` target on the same visible root.
+- Pointer-menu data/compound rendering parity for the divider row across
+  DropdownMenu, ContextMenu, and breadcrumb menus.
+
+**Does not own / non-goals**
+
+- Menu open state, focus entry, row activation, or arrow-key navigation — owned by
+  DropdownMenu, ContextMenu, BreadcrumbItem, and their shared hooks.
+- Touch and bottom-sheet data dividers — those presentations render Divider
+  directly and are owned by their parent menu surface.
+- Base separator rule geometry and token paint — delegated to Divider.
+- Caller-authored grouping meaning — owned by the product callsite.
+
+## Public concepts
+
+| Concept       | Closed values or states                       | Meaning                                                                        | Availability by variant/orientation/state | Default                | Owner                | Stability | Invalid-value behavior                                                          |
+| ------------- | --------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------- | ---------------------- | -------------------- | --------- | ------------------------------------------------------------------------------- |
+| Separator row | one horizontal unlabelled separator           | Divides adjacent pointer-menu row groups without becoming a row or focus stop. | Data and compound pointer-menu modes      | present where authored | component            | stable    | Role and orientation are excluded from caller props and remain component-owned. |
+| Root surface  | ref; DOM/data/ARIA; class/style/xstyle/events | Extends the separator root while preserving component semantics.               | Every separator row                       | omitted                | public component API | stable    | Accepted inputs compose; role and orientation remain authoritative.             |
+
+## Behavioral and layout contract
+
+Draft requirements identify their basis so observed code is not mistaken for an
+intentional decision.
+
+| ID  | Candidate invariant                                                                                                                                                                | Basis                                                            | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------ |
+| FR1 | The component MUST render one unlabelled horizontal separator with pointer-menu-specific block spacing.                                                                            | Released source/docs and focused tests                           | verify             |
+| FR2 | The root MUST expose `role="separator"` and `aria-orientation="horizontal"`, remain outside menu-item collection and arrow-key order, and never become focusable.                  | WCAG 2.2 SC 1.3.1 and 4.1.2; focused tests                       | verify             |
+| FR3 | In pointer-menu presentation, `{type: "divider"}` in the data API and the compound divider component or alias MUST render the same component DOM, spacing, semantics, and targets. | Released docs/source; data/compound parity test                  | verify             |
+| FR4 | The visible root MUST carry both the delegated `divider` target and the menu-specific `dropdown-menu-divider` target; menu spacing applies before caller `xstyle`.                 | `architecture:component-theming-surface/INV3–INV6`; source/tests | verify             |
+| FR5 | Accepted ref, DOM/data/ARIA, class, style, events, and `xstyle` MUST reach or compose on the separator root without replacing component-owned role or orientation.                 | `architecture:public-component-api/INV5–INV8`                    | verify             |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** The delegated Divider and menu-specific targets may restyle
+  their owned surface without changing separator semantics or focus behavior.
+- **AV2 — Caller root inputs.** Supported host attributes, handlers, and styling
+  inputs may vary while the owned role and orientation remain fixed.
+
+### Representative states
+
+| State                     | Required invariant                                                   | Allowed variation                                             |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Pointer data-mode divider | One horizontal separator between data-driven rows.                   | Adjacent row content and active theme may vary.               |
+| Pointer compound divider  | DOM and behavior match the pointer data-mode divider.                | Host attributes and supported styling inputs may be supplied. |
+| Public aliases            | ContextMenuDivider and BreadcrumbMenuDivider render this component.  | The containing menu owns lifecycle and navigation.            |
+| Touch data divider        | Outside this component; the parent surface renders Divider directly. | Touch-menu layout follows the parent contract.                |
+| RTL                       | The horizontal, full-width rule remains direction-neutral.           | Surrounding text and menu alignment may mirror.               |
+| Narrow viewport           | The rule remains inside the menu without horizontal overflow.        | Menu width follows its owner.                                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Root composition.** Apply menu spacing, then caller `xstyle`; combine the
+  menu-specific target class with caller `className`; preserve caller `style` and
+  host props; keep role and orientation component-owned.
+
+### Performance and resources
+
+- **PR1 — No external lifecycle.** DropdownMenuDivider installs no listener,
+  observer, timer, request, state machine, or Effect.
+
+## Accessibility contract
+
+- **AR1 — Separator semantics.** The root exposes a horizontal separator and no
+  interactive role or tab stop.
+- **AR2 — Navigation exclusion.** Menu navigation collects menu-item roles only, so
+  ArrowDown and ArrowUp pass across the separator without focusing it.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                              | Representation authority                                                              | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -------------- | ------------------ |
+| Menu separator   | Visually separates adjacent menu row groups without competing with row content. | Current source and delegated Divider tokens; no component-local visual decision added | supporting     | FR1–FR4            |
+
+No component-local visual decision is settled by this draft.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns exports and root input composition.
+- `architecture:component-theming-surface` owns target placement and composed target
+  ownership.
+- `architecture:component-test-sufficiency` owns proportionate, observable evidence.
+- DropdownMenu exports the implementation directly. ContextMenu and Breadcrumbs
+  re-export it as `ContextMenuDivider` and `BreadcrumbMenuDivider`, with matching
+  props aliases; their pointer presentations retain the same component contract.
+- Touch and bottom-sheet data dividers bypass this component and delegate directly
+  to Divider under the parent menu contract.
+- Divider provides the base separator implementation; its draft record is
+  observational context, not authority for this contract.
+- `spec:AST-029` keeps this observational draft separate from the audit receipt.
+
+## Verification map
+
+| Contract         | Verification                                                                                            | Representative states                                         | Mutation or failure expectation                                                                                     | Audit section                           |
+| ---------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1–FR3, AR1–AR2 | `DropdownMenu.test.tsx`; ContextMenu and Breadcrumbs alias tests; dedicated Storybook state; scoped axe | pointer data/compound, aliases, open menu, keyboard traversal | Pointer DOM modes drift, an alias disappears, the role/orientation changes, or the separator enters arrow-key order | `audit:DropdownMenuDivider/§1,§3,§4,§6` |
+| FR4              | Focused root-composition test; exact-head Neutral/Butter browser frames                                 | light/dark themes; menu and delegated targets                 | A target leaves the visible root or caller `xstyle` stops composing after menu spacing                              | `audit:DropdownMenuDivider/§2,§5`       |
+| FR5              | Focused root-composition test; lint and typecheck                                                       | ref, host attributes, class/style/xstyle/events               | An accepted input is dropped or owned semantics are overwritten                                                     | `audit:DropdownMenuDivider/§3`          |
+| PR1              | Source review                                                                                           | every state                                                   | A lifecycle mechanism appears without a resource contract                                                           | `audit:DropdownMenuDivider/§7`          |
+
+## Decision log
+
+None. This draft records current facts and introduces no product decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit scores,
+screenshot matrices, implementation steps, or system rules. The audit pull request
+owns the closed run evidence required by `spec:AST-029/FR5`.

package/src/DropdownMenu/__tests__/DropdownMenuDividerAudit.a11y.chromium.spec.ts

@@ -0,0 +1,280 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuDividerAudit.a11y.chromium.spec.ts
+ * @input Exact-head DropdownMenuDivider story across themes, color modes, direction, and viewport widths
+ * @output Screenshots and fail-closed sensor receipts for the DropdownMenuDivider component audit
+ * @position Component-owned Night Watch browser evidence; CI runs it only for a DropdownMenuDivider audit pull request
+ */
+
+import {createHash} from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {expect, test, type Page} from '@playwright/test';
+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const OUTPUT = path.resolve('dropdown-menu-divider-audit-evidence');
+const STORY_ID = 'core-dropdownmenudivider--menu-separator';
+const WIDE = {width: 1024, height: 768};
+const NARROW = {width: 320, height: 720};
+
+type Mode = 'light' | 'dark';
+type Direction = 'ltr' | 'rtl';
+type Theme = 'neutral' | 'butter';
+type AuditCase = {
+  key: string;
+  mode: Mode;
+  direction: Direction;
+  theme: Theme;
+  viewport: {width: number; height: number};
+};
+
+const cases: AuditCase[] = [
+  {
+    key: 'neutral-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'neutral-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'butter-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'butter',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-light',
+    mode: 'light',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'rtl-dark',
+    mode: 'dark',
+    direction: 'rtl',
+    theme: 'neutral',
+    viewport: WIDE,
+  },
+  {
+    key: 'narrow-light',
+    mode: 'light',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+  {
+    key: 'narrow-dark',
+    mode: 'dark',
+    direction: 'ltr',
+    theme: 'neutral',
+    viewport: NARROW,
+  },
+];
+
+test.describe.configure({mode: 'serial', retries: 0});
+let server: StaticServer;
+let checkoutSha: string;
+let storybookSha: string;
+
+function storyUrl(item: AuditCase) {
+  return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;
+}
+
+async function settle(page: Page) {
+  await holdMotionStill(page);
+  await page.evaluate(async () => document.fonts.ready);
+  await page.waitForTimeout(40);
+}
+
+test.beforeAll(async () => {
+  fs.rmSync(OUTPUT, {recursive: true, force: true});
+  fs.mkdirSync(OUTPUT, {recursive: true});
+  checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+    encoding: 'utf8',
+  }).trim();
+  const expected = process.env.ASTRYX_HEAD_SHA;
+  if (expected && expected !== checkoutSha) {
+    throw new Error(
+      `checkout ${checkoutSha} does not match expected head ${expected}`,
+    );
+  }
+  server = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+  const response = await fetch(`${server.origin}/astryx-build-sha.txt`);
+  if (!response.ok) {
+    throw new Error(`Storybook build has no SHA stamp (${response.status})`);
+  }
+  storybookSha = (await response.text()).trim();
+  if (storybookSha !== checkoutSha) {
+    throw new Error(
+      `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,
+    );
+  }
+});
+
+test.afterAll(async () => {
+  await server?.close();
+});
+
+for (const item of cases) {
+  test(item.key, async ({browser}) => {
+    const context = await browser.newContext({
+      viewport: item.viewport,
+      colorScheme: item.mode,
+      reducedMotion: 'reduce',
+    });
+    const page = await context.newPage();
+    const pageErrors: string[] = [];
+    page.on('pageerror', error => pageErrors.push(String(error)));
+    await page.goto(storyUrl(item), {waitUntil: 'load'});
+    await page.locator('#storybook-root').waitFor();
+    const menu = page.getByRole('menu').last();
+    await expect(menu).toBeVisible();
+    const separator = page.getByRole('separator');
+    await expect(separator).toBeVisible();
+    await expect(separator).toHaveAttribute('aria-orientation', 'horizontal');
+    await settle(page);
+
+    const menuItems = page.getByRole('menuitem');
+    await expect(menuItems).toHaveCount(2);
+    await menu.focus();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.first()).toBeFocused();
+    await page.keyboard.press('ArrowDown');
+    await expect(menuItems.last()).toBeFocused();
+    await expect(separator).not.toBeFocused();
+
+    const observed = await separator.evaluate(element => {
+      const rootBox = element.getBoundingClientRect();
+      const rule = element.firstElementChild;
+      const ruleBox = rule?.getBoundingClientRect() ?? null;
+      const rootStyle = getComputedStyle(element);
+      const ruleStyle = rule ? getComputedStyle(rule) : null;
+      return {
+        theme: document
+          .querySelector('[data-astryx-theme]')
+          ?.getAttribute('data-astryx-theme'),
+        mode: document.documentElement.getAttribute('data-theme'),
+        direction: rootStyle.direction,
+        viewport: {width: innerWidth, height: innerHeight},
+        reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+        horizontalOverflow:
+          document.documentElement.scrollWidth > innerWidth + 1,
+        fonts: document.fonts.status,
+        role: element.getAttribute('role'),
+        orientation: element.getAttribute('aria-orientation'),
+        tabIndex: element.getAttribute('tabindex'),
+        targetClasses: {
+          menuDivider: element.classList.contains(
+            'astryx-dropdown-menu-divider',
+          ),
+          divider: element.classList.contains('astryx-divider'),
+        },
+        geometry: {
+          root: {
+            x: rootBox.x,
+            y: rootBox.y,
+            width: rootBox.width,
+            height: rootBox.height,
+          },
+          rule:
+            ruleBox === null
+              ? null
+              : {
+                  x: ruleBox.x,
+                  y: ruleBox.y,
+                  width: ruleBox.width,
+                  height: ruleBox.height,
+                },
+        },
+        ruleBackground: ruleStyle?.backgroundColor ?? null,
+      };
+    });
+
+    const geometryPass =
+      observed.geometry.root.width > 0 &&
+      observed.geometry.root.height > 0 &&
+      observed.geometry.rule !== null &&
+      observed.geometry.rule.width > 0 &&
+      observed.geometry.rule.height > 0;
+    const paintPass =
+      observed.ruleBackground !== null &&
+      observed.ruleBackground !== 'rgba(0, 0, 0, 0)' &&
+      observed.ruleBackground !== 'transparent';
+    const png = await page.screenshot({animations: 'disabled', fullPage: true});
+    const image = `${item.key}.png`;
+    const receipt = {
+      schemaVersion: 1,
+      expected: {
+        build: checkoutSha,
+        storyId: STORY_ID,
+        mode: item.mode,
+        direction: item.direction,
+        theme: item.theme,
+        viewport: item.viewport,
+      },
+      observed: {
+        build: storybookSha,
+        ...observed,
+        menuItemCount: await menuItems.count(),
+        pageErrors,
+      },
+      image: {
+        file: image,
+        sha256: createHash('sha256').update(png).digest('hex'),
+        width: png.readUInt32BE(16),
+        height: png.readUInt32BE(20),
+      },
+      checks: {geometryPass, paintPass},
+      passed:
+        storybookSha === checkoutSha &&
+        pageErrors.length === 0 &&
+        observed.theme === item.theme &&
+        observed.mode === item.mode &&
+        observed.direction === item.direction &&
+        observed.viewport.width === item.viewport.width &&
+        observed.viewport.height === item.viewport.height &&
+        observed.reducedMotion &&
+        !observed.horizontalOverflow &&
+        observed.fonts === 'loaded' &&
+        observed.role === 'separator' &&
+        observed.orientation === 'horizontal' &&
+        observed.tabIndex === null &&
+        observed.targetClasses.menuDivider &&
+        observed.targetClasses.divider &&
+        geometryPass &&
+        paintPass,
+    };
+    fs.writeFileSync(path.join(OUTPUT, image), png);
+    fs.writeFileSync(
+      path.join(OUTPUT, `${item.key}.sensors.json`),
+      `${JSON.stringify(receipt, null, 2)}\n`,
+    );
+    expect(receipt.passed).toBe(true);
+    await context.close();
+  });
+}

package/src/Heading/Heading.test.tsx

@@ -269,3 +269,60 @@ describe('Heading', () => {
     expect(element).not.toHaveAttribute('data-type', 'editorial');
   });
 });
+
+// With hasTruncateTooltip={false} nothing reads the measured overflow, so a
+// long table of truncated cells must not pay a layout read per cell.
+function countScrollWidthReads(run: () => void): number {
+  const proto = window.HTMLElement.prototype;
+  const original = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');
+  let reads = 0;
+  Object.defineProperty(proto, 'scrollWidth', {
+    configurable: true,
+    get() {
+      reads += 1;
+      return 0;
+    },
+  });
+  try {
+    run();
+  } finally {
+    if (original) {
+      Object.defineProperty(proto, 'scrollWidth', original);
+    } else {
+      delete (proto as {scrollWidth?: number}).scrollWidth;
+    }
+  }
+  return reads;
+}
+
+describe('Heading maxLines without a truncation tooltip', () => {
+  it('takes no truncation measurement when hasTruncateTooltip is false', () => {
+    const reads = countScrollWidthReads(() => {
+      render(
+        <>
+          {Array.from({length: 20}, (_, index) => (
+            <Heading
+              level={3}
+              maxLines={1}
+              hasTruncateTooltip={false}
+              key={index}>
+              Cell {index} with text far wider than its column
+            </Heading>
+          ))}
+        </>,
+      );
+    });
+    expect(reads).toBe(0);
+  });
+
+  it('still measures when the tooltip is enabled', () => {
+    const reads = countScrollWidthReads(() => {
+      render(
+        <Heading level={3} maxLines={1}>
+          Text far wider than its column
+        </Heading>,
+      );
+    });
+    expect(reads).toBeGreaterThan(0);
+  });
+});

package/src/Heading/Heading.tsx

@@ -253,8 +253,12 @@ export function Heading({
   // the closed built-in StyleX maps with an unknown name.
   const builtinType = type && isBuiltinHeadingType(type) ? type : undefined;
 
-  // Truncation detection
-  const truncation = useTruncation({maxLines});
+  // Truncation detection. Only the tooltip reads the measured overflow, so
+  // with the tooltip off the text is clipped by CSS alone and nothing is
+  // measured or observed.
+  const truncation = useTruncation({
+    maxLines: hasTruncateTooltip === false ? 0 : maxLines,
+  });
 
   // Tooltip for truncated text
   const tooltipPlacement: LayerPlacement =

package/src/MobileNav/MobileNav.tsx

@@ -260,8 +260,15 @@ const dynamicStyles = stylex.create({
 // Close timing
 // =============================================================================
 
-/** Longest the drawer will wait before closing, however long the hold is. */
-const MAX_CLOSE_DELAY_MS = 250;
+/**
+ * Longest the drawer will wait before closing, however long the hold is.
+ *
+ * Exported so `AppShell` can defer hiding this drawer's `Activity` boundary
+ * by at least this long too (`ACTIVITY_HIDE_BUFFER_MS` in AppShell.tsx) —
+ * otherwise Activity's `display: none !important` lands before this delay's
+ * own scheduled `dialog.close()` has a chance to run (#5701).
+ */
+export const MAX_CLOSE_DELAY_MS = 250;
 /** Fraction of the hold to close at, so the close never lands on its boundary. */
 const CLOSE_WITHIN_HOLD = 0.6;
 
@@ -488,6 +495,21 @@ export function MobileNav({
   // Element that was focused when the drawer opened; focus goes back to it
   // once the native dialog has closed (see closeAndRestoreFocus).
   const triggerElementRef = useRef<HTMLElement | null>(null);
+
+  // Keeps the dialog rendered from the commit that closes it until the delayed
+  // `close()` below has run. The `display` transition on the dialog is meant to
+  // do this, but a browser that does not hold a discrete `display` transition
+  // (WebKit) drops the dialog to `display: none` at once while it is still an
+  // open modal: nothing is visible, yet the whole page stays inert until the
+  // timer fires. Set during render, so it is already true in the commit that
+  // closes. The drawer's transform and the backdrop stay keyed to `isOpen`, so
+  // the slide-out is unchanged.
+  const [isCloseHeld, setIsCloseHeld] = useState(false);
+  const [wasOpen, setWasOpen] = useState(isOpen);
+  if (wasOpen !== isOpen) {
+    setWasOpen(isOpen);
+    setIsCloseHeld(!isOpen);
+  }
   const gutterRef = useRef<ScrollbarGutterHold | null>(null);
 
   // Gives back the gutter held open in place of the hidden scrollbar.
@@ -563,7 +585,12 @@ export function MobileNav({
 
       closeTimeoutRef.current = setTimeout(() => {
         closeAndRestoreFocus(dialog, triggerElementRef);
+        setIsCloseHeld(false);
       }, resolveCloseDelay(dialog));
+    } else {
+      // Nothing is open, so there is no close to hold the dialog for, and no
+      // close timer is left to release the hold.
+      setIsCloseHeld(false);
     }
 
     return () => {
@@ -647,7 +674,7 @@ export function MobileNav({
           layerStructureReset.reset,
           styles.dialog,
           overlayPaddingReset.reset,
-          isOpen && styles.open,
+          (isOpen || isCloseHeld) && styles.open,
           styles.backdrop,
           isOpen && styles.backdropOpen,
           xstyle,