@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/Layout/padding.stylex.ts

@@ -326,21 +326,201 @@ export const paddingBlockStyles = stylex.create({
 });
 
 /**
- * Propagation styles for --astryx-section-padding.
+ * Inline-start-only padding override styles.
+ * Use when a component needs to override the inline-start edge independently
+ * of inline-end. Logical, so it follows the writing direction (left in LTR,
+ * right in RTL).
+ */
+export const paddingInlineStartStyles = stylex.create({
+  0: {paddingInlineStart: spacingVars['--spacing-0']},
+  0.5: {paddingInlineStart: spacingVars['--spacing-0-5']},
+  1: {paddingInlineStart: spacingVars['--spacing-1']},
+  1.5: {paddingInlineStart: spacingVars['--spacing-1-5']},
+  2: {paddingInlineStart: spacingVars['--spacing-2']},
+  3: {paddingInlineStart: spacingVars['--spacing-3']},
+  4: {paddingInlineStart: spacingVars['--spacing-4']},
+  5: {paddingInlineStart: spacingVars['--spacing-5']},
+  6: {paddingInlineStart: spacingVars['--spacing-6']},
+  8: {paddingInlineStart: spacingVars['--spacing-8']},
+  10: {paddingInlineStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Inline-end-only padding override styles.
+ * The inline-end counterpart of paddingInlineStartStyles.
+ */
+export const paddingInlineEndStyles = stylex.create({
+  0: {paddingInlineEnd: spacingVars['--spacing-0']},
+  0.5: {paddingInlineEnd: spacingVars['--spacing-0-5']},
+  1: {paddingInlineEnd: spacingVars['--spacing-1']},
+  1.5: {paddingInlineEnd: spacingVars['--spacing-1-5']},
+  2: {paddingInlineEnd: spacingVars['--spacing-2']},
+  3: {paddingInlineEnd: spacingVars['--spacing-3']},
+  4: {paddingInlineEnd: spacingVars['--spacing-4']},
+  5: {paddingInlineEnd: spacingVars['--spacing-5']},
+  6: {paddingInlineEnd: spacingVars['--spacing-6']},
+  8: {paddingInlineEnd: spacingVars['--spacing-8']},
+  10: {paddingInlineEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-start CSS variable style, set independently of
+ * inline-end so a per-edge override keeps edge-compensating children (Card,
+ * Divider, a nested Section) compensating against the padding actually
+ * applied on that edge.
+ */
+export const containerPaddingInlineStartVarStyles = stylex.create({
+  0: {'--container-padding-inline-start': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-start': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-start': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-start': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-start': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-start': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-start': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-start': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-start': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-start': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-start': spacingVars['--spacing-10']},
+});
+
+/**
+ * Container padding inline-end CSS variable style, the counterpart of
+ * containerPaddingInlineStartVarStyles.
+ */
+export const containerPaddingInlineEndVarStyles = stylex.create({
+  0: {'--container-padding-inline-end': spacingVars['--spacing-0']},
+  0.5: {'--container-padding-inline-end': spacingVars['--spacing-0-5']},
+  1: {'--container-padding-inline-end': spacingVars['--spacing-1']},
+  1.5: {'--container-padding-inline-end': spacingVars['--spacing-1-5']},
+  2: {'--container-padding-inline-end': spacingVars['--spacing-2']},
+  3: {'--container-padding-inline-end': spacingVars['--spacing-3']},
+  4: {'--container-padding-inline-end': spacingVars['--spacing-4']},
+  5: {'--container-padding-inline-end': spacingVars['--spacing-5']},
+  6: {'--container-padding-inline-end': spacingVars['--spacing-6']},
+  8: {'--container-padding-inline-end': spacingVars['--spacing-8']},
+  10: {'--container-padding-inline-end': spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-start-only padding override styles.
+ * Use when a component needs to override the block-start (top) edge
+ * independently of block-end — e.g. a section that sits under a sticky
+ * header and needs less padding above than below.
+ */
+export const paddingBlockStartStyles = stylex.create({
+  0: {paddingBlockStart: spacingVars['--spacing-0']},
+  0.5: {paddingBlockStart: spacingVars['--spacing-0-5']},
+  1: {paddingBlockStart: spacingVars['--spacing-1']},
+  1.5: {paddingBlockStart: spacingVars['--spacing-1-5']},
+  2: {paddingBlockStart: spacingVars['--spacing-2']},
+  3: {paddingBlockStart: spacingVars['--spacing-3']},
+  4: {paddingBlockStart: spacingVars['--spacing-4']},
+  5: {paddingBlockStart: spacingVars['--spacing-5']},
+  6: {paddingBlockStart: spacingVars['--spacing-6']},
+  8: {paddingBlockStart: spacingVars['--spacing-8']},
+  10: {paddingBlockStart: spacingVars['--spacing-10']},
+});
+
+/**
+ * Block-end-only padding override styles.
+ * The block-end counterpart of paddingBlockStartStyles.
+ */
+export const paddingBlockEndStyles = stylex.create({
+  0: {paddingBlockEnd: spacingVars['--spacing-0']},
+  0.5: {paddingBlockEnd: spacingVars['--spacing-0-5']},
+  1: {paddingBlockEnd: spacingVars['--spacing-1']},
+  1.5: {paddingBlockEnd: spacingVars['--spacing-1-5']},
+  2: {paddingBlockEnd: spacingVars['--spacing-2']},
+  3: {paddingBlockEnd: spacingVars['--spacing-3']},
+  4: {paddingBlockEnd: spacingVars['--spacing-4']},
+  5: {paddingBlockEnd: spacingVars['--spacing-5']},
+  6: {paddingBlockEnd: spacingVars['--spacing-6']},
+  8: {paddingBlockEnd: spacingVars['--spacing-8']},
+  10: {paddingBlockEnd: spacingVars['--spacing-10']},
+});
+
+/**
+ * Propagation styles for `--_section-padding-propagated`.
  * When a parent section sets explicit padding, this propagates the value
  * through the CSS custom property cascade so nested sections that use
  * useThemeDefault inherit the parent's padding instead of the theme default.
+ *
+ * This is deliberately NOT the public `--astryx-section-padding` token. The
+ * two carry different authority: the public token is the THEME's section
+ * padding, set once at the theme root, while this one is one ancestor
+ * Section's padding, propagated down the tree. An overlay has to drop the
+ * inherited value at its boundary (see {@link overlayPaddingReset}) without
+ * dropping the theme's — impossible while both live under one name.
+ * `container.stylex.ts` reads this ahead of the public token, so a propagated
+ * value still wins over the theme for nested sections, as before.
  */
 export const sectionPaddingPropagationStyles = stylex.create({
-  0: {'--astryx-section-padding': spacingVars['--spacing-0']},
-  0.5: {'--astryx-section-padding': spacingVars['--spacing-0-5']},
-  1: {'--astryx-section-padding': spacingVars['--spacing-1']},
-  1.5: {'--astryx-section-padding': spacingVars['--spacing-1-5']},
-  2: {'--astryx-section-padding': spacingVars['--spacing-2']},
-  3: {'--astryx-section-padding': spacingVars['--spacing-3']},
-  4: {'--astryx-section-padding': spacingVars['--spacing-4']},
-  5: {'--astryx-section-padding': spacingVars['--spacing-5']},
-  6: {'--astryx-section-padding': spacingVars['--spacing-6']},
-  8: {'--astryx-section-padding': spacingVars['--spacing-8']},
-  10: {'--astryx-section-padding': spacingVars['--spacing-10']},
+  0: {'--_section-padding-propagated': spacingVars['--spacing-0']},
+  0.5: {'--_section-padding-propagated': spacingVars['--spacing-0-5']},
+  1: {'--_section-padding-propagated': spacingVars['--spacing-1']},
+  1.5: {'--_section-padding-propagated': spacingVars['--spacing-1-5']},
+  2: {'--_section-padding-propagated': spacingVars['--spacing-2']},
+  3: {'--_section-padding-propagated': spacingVars['--spacing-3']},
+  4: {'--_section-padding-propagated': spacingVars['--spacing-4']},
+  5: {'--_section-padding-propagated': spacingVars['--spacing-5']},
+  6: {'--_section-padding-propagated': spacingVars['--spacing-6']},
+  8: {'--_section-padding-propagated': spacingVars['--spacing-8']},
+  10: {'--_section-padding-propagated': spacingVars['--spacing-10']},
+});
+
+/**
+ * Padding-variable reset for overlay roots (Dialog, BottomSheet, Drawer,
+ * MobileNav, Lightbox, and every layer surface).
+ *
+ * ## Why an overlay needs this
+ *
+ * The container padding system talks to descendants through inherited custom
+ * properties: a padded container announces its padding, and children read the
+ * value either to apply it or to cancel it with a negative margin
+ * (`Section`, `Divider`, `Layout`, `Table`).
+ *
+ * Inheritance follows the DOM, but an overlay leaves its parent's visual box —
+ * a fixed/top-layer `<dialog>` is a DOM descendant of the padded page while
+ * being nowhere near it on screen. It inherits values describing padding that
+ * is not there, and its content compensates against phantom space: a `Section`
+ * inside a 640px sheet rendered 672px wide and hung off both edges (#5208).
+ *
+ * Two families leak, and they need opposite treatments:
+ *
+ * - `--container-padding-*` -> `0px`. Descendants SUBTRACT these (bleed
+ *   margins). The overlay root has no padding of its own to escape, so the
+ *   honest answer is zero. Nested containers that do set padding (a Dialog's
+ *   content wrapper) re-announce their own values below this point, so
+ *   legitimate edge-to-edge bleed inside the overlay is unaffected.
+ * - `--layout-padding-*` and `--_section-padding-propagated` -> `initial`.
+ *   Descendants ADD these, so zeroing them would strip padding rather than
+ *   restore it. `initial` makes each guaranteed-invalid, so readers fall
+ *   through their own `var(…, fallback)` chain and land on the theme default —
+ *   which is what an overlay at the top of the tree should show.
+ *
+ * `initial` is also why propagation moved off `--astryx-section-padding`: that
+ * name is public theme surface, set at the theme root, and making it invalid
+ * here would blank the theme's own section padding inside every overlay.
+ *
+ * Apply on the overlay's outermost styled element.
+ *
+ * @example
+ * ```
+ * <dialog {...stylex.props(styles.dialog, overlayPaddingReset.reset)} />
+ * ```
+ */
+export const overlayPaddingReset = stylex.create({
+  reset: {
+    // Subtracted by descendants — the overlay root has no padding to escape.
+    '--container-padding-inline-start': '0px',
+    '--container-padding-inline-end': '0px',
+    '--container-padding-block-start': '0px',
+    '--container-padding-block-end': '0px',
+    // Added by descendants — fall through to each reader's own default.
+    '--layout-padding-outer-x': 'initial',
+    '--layout-padding-outer-y': 'initial',
+    '--layout-padding-inner-x': 'initial',
+    '--layout-padding-inner-y': 'initial',
+    '--_section-padding-propagated': 'initial',
+  },
 });

package/src/Lightbox/Lightbox.tsx

@@ -36,6 +36,7 @@ import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -157,13 +158,20 @@ const styles = stylex.create({
     cursor: {
       default: 'zoom-in',
       '@media (hover: hover)': 'zoom-in',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
     },
   },
   imageWrapperZoomed: {
-    cursor: 'grab',
+    cursor: {
+      default: 'grab',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
   },
   imageWrapperDragging: {
-    cursor: 'grabbing',
+    cursor: {
+      default: 'grabbing',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
   },
   image: {
     maxWidth: '100%',
@@ -588,7 +596,7 @@ export function Lightbox({
       aria-label={currentItem.alt || t('@astryx.lightbox.mediaViewer')}
       {...mergeProps(
         themeProps('lightbox'),
-        stylex.props(styles.dialog, xstyle),
+        stylex.props(styles.dialog, overlayPaddingReset.reset, xstyle),
         className,
         style,
       )}

package/src/Link/Link.tsx

@@ -61,11 +61,14 @@ const styles = stylex.create({
     fontWeight: 'inherit',
     textDecoration: {
       default: 'none',
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': 'underline',
       },
     },
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     transitionProperty: 'color, text-decoration',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -85,7 +88,7 @@ const styles = stylex.create({
     textDecoration: 'underline',
   },
   disabled: {
-    cursor: 'not-allowed',
+    cursor: 'default',
     opacity: 0.5,
     pointerEvents: 'none',
   },
@@ -103,7 +106,7 @@ const linkColorStyles = stylex.create({
   primary: {
     color: {
       default: colorVars['--color-text-primary'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-primary']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
@@ -111,7 +114,7 @@ const linkColorStyles = stylex.create({
   secondary: {
     color: {
       default: colorVars['--color-text-secondary'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-secondary']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },
@@ -125,7 +128,7 @@ const linkColorStyles = stylex.create({
   accent: {
     color: {
       default: colorVars['--color-text-accent'],
-      ':hover': {
+      ':hover:where(:not(:disabled,[aria-disabled="true"]))': {
         '@media (hover: hover)': `color-mix(in srgb, ${colorVars['--color-text-accent']}, ${colorVars['--color-tint-hover']} 15%)`,
       },
     },

package/src/MetadataList/MetadataList.tsx

@@ -146,7 +146,10 @@ const styles = stylex.create({
     background: 'none',
     border: 'none',
     padding: `${spacingVars['--spacing-2']} 0`,
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     color: colorVars['--color-accent'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],

package/src/MobileNav/MobileNav.tsx

@@ -23,6 +23,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
+ * - /packages/core/src/hooks/scrollbarGutter.ts (shared scroll-lock gutter)
  * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
 
@@ -47,7 +48,12 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Heading} from '../Heading/Heading';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
+import {
+  holdScrollbarGutter,
+  type ScrollbarGutterHold,
+} from '../hooks/scrollbarGutter';
 import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
+import {overlayPaddingReset} from '../Layout/padding.stylex';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -70,7 +76,16 @@ const styles = stylex.create({
     width: '100vw',
     height: '100dvh',
     backgroundColor: 'transparent',
-    overflow: 'hidden',
+    // `clip`, not `hidden`. Both clip the off-screen drawer, but `hidden` makes
+    // the dialog a SCROLL CONTAINER, and a scroll container in the top layer
+    // whose subtree holds another scroller (the drawer's content area) does not
+    // paint a @starting-style entry transition for its descendants in Chromium:
+    // the transition ticks in the CSSOM while every painted frame shows the
+    // end value, so the drawer appears fully open. `clip` clips without
+    // creating a scroll container and the slide-in paints normally. The dialog
+    // never scrolls anyway — its child is absolutely positioned — so nothing
+    // depended on it being a scroll container.
+    overflow: 'clip',
     overscrollBehavior: 'contain',
     // Prevent touch gestures (pull-to-refresh, background scroll) passing through
     touchAction: 'none',
@@ -112,7 +127,14 @@ const styles = stylex.create({
   },
   backdropOpen: {
     '::backdrop': {
-      opacity: 1,
+      // The ::backdrop only exists once showModal() has put the dialog in the
+      // top layer, so its first rendered frame already has the open opacity.
+      // Without a starting style there is no earlier value to transition from
+      // and the scrim snaps in — @starting-style supplies that value.
+      opacity: {
+        default: 1,
+        '@starting-style': 0,
+      },
     },
   },
   drawer: {
@@ -143,7 +165,17 @@ const styles = stylex.create({
     },
   },
   drawerStartOpen: {
-    transform: 'translateX(0)',
+    // The whole dialog is `display: none` while closed, so the drawer is not
+    // rendered and the open transform is the only value it has ever had — a
+    // transition needs a previous value to run from. @starting-style gives the
+    // first rendered frame the off-screen transform, so the slide-in plays.
+    transform: {
+      default: 'translateX(0)',
+      '@starting-style': {
+        default: 'translateX(-100%)',
+        ':is([dir="rtl"] *)': 'translateX(100%)',
+      },
+    },
   },
   drawerEnd: {
     insetInlineEnd: 0,
@@ -156,7 +188,14 @@ const styles = stylex.create({
     },
   },
   drawerEndOpen: {
-    transform: 'translateX(0)',
+    // See drawerStartOpen — same starting style, mirrored edge.
+    transform: {
+      default: 'translateX(0)',
+      '@starting-style': {
+        default: 'translateX(100%)',
+        ':is([dir="rtl"] *)': 'translateX(-100%)',
+      },
+    },
   },
   header: {
     display: 'flex',
@@ -396,6 +435,15 @@ export function MobileNav({
 
   const dialogRef = useRef<HTMLDialogElement>(null);
   const closeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+  const gutterRef = useRef<ScrollbarGutterHold | null>(null);
+
+  // Gives back the gutter held open in place of the hidden scrollbar.
+  const releaseGutter = useCallback(() => {
+    if (gutterRef.current) {
+      gutterRef.current.release();
+      gutterRef.current = null;
+    }
+  }, []);
   // Resolved side — computed from trigger position when side='auto'
   const [resolvedSide, setResolvedSide] = useState<'start' | 'end'>(
     side === 'auto' ? 'end' : side,
@@ -438,6 +486,10 @@ export function MobileNav({
     }
 
     if (isOpen) {
+      // Taken first: every mutation below is one that can hide the scrollbar,
+      // and the gutter has to be measured while it is still there.
+      gutterRef.current ??= holdScrollbarGutter(document.documentElement);
+
       if (!dialog.open) {
         dialog.showModal();
       }
@@ -445,8 +497,10 @@ export function MobileNav({
       // overflow: clip avoids creating a scroll container (unlike hidden),
       // so there's no scroll bounce and no need to save/restore scroll position.
       document.documentElement.style.overflow = 'clip';
+      gutterRef.current.settle();
     } else if (dialog.open) {
       document.documentElement.style.overflow = '';
+      releaseGutter();
 
       closeTimeoutRef.current = setTimeout(() => {
         dialog.close();
@@ -459,8 +513,9 @@ export function MobileNav({
         closeTimeoutRef.current = null;
       }
       document.documentElement.style.overflow = '';
+      releaseGutter();
     };
-  }, [isOpen]);
+  }, [isOpen, releaseGutter]);
 
   // Close the native dialog on unmount if it's still open. Inside AppShell the
   // drawer is mounted in an <Activity> that switches to mode="hidden" when the
@@ -512,6 +567,7 @@ export function MobileNav({
         themeProps('mobile-nav', {side: resolvedSide}),
         stylex.props(
           styles.dialog,
+          overlayPaddingReset.reset,
           isOpen && styles.open,
           styles.backdrop,
           isOpen && styles.backdropOpen,

package/src/MobileNav/MobileNavEntryAnimation.test.tsx

@@ -0,0 +1,212 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file MobileNavEntryAnimation.test.tsx
+ * @input Uses vitest, @testing-library/react, the TypeScript compiler API
+ * @output Regression tests keeping the drawer's slide-in and scrim fade-in
+ * @position Testing; guards the open path of MobileNav.tsx
+ *
+ * The drawer used to open with no animation at all while closing smoothly.
+ *
+ * The dialog is `display: none` until `isOpen`, so nothing inside it is
+ * rendered while closed. React commits the open `display` and the open
+ * `transform` in the same pass, which means the first frame the drawer is ever
+ * rendered in already holds the open transform: a transition has no earlier
+ * value to run from and the drawer simply appears. Closing looked fine because
+ * both values exist by then — `display` stays in the transition with
+ * `allow-discrete`, so the element is still rendered as the transform animates
+ * out.
+ *
+ * `@starting-style` supplies that before-change style — the off-screen
+ * transform for the drawer, transparent for the `::backdrop`.
+ *
+ * That alone is NOT enough, and the second half is the part that is easy to
+ * undo by accident. The dialog used `overflow: hidden`, which makes it a
+ * SCROLL CONTAINER. A scroll container in the top layer whose subtree holds
+ * another scroller — here the drawer's own content area — does not paint a
+ * `@starting-style` entry transition for its descendants in Chromium: the
+ * transition ticks in the CSSOM (`getComputedStyle` interpolates perfectly)
+ * while every painted frame shows the end value. Measuring the CSSOM says
+ * "animating"; the screen says "snapped". `overflow: clip` clips the
+ * off-screen drawer exactly as `hidden` did without creating a scroll
+ * container, and the slide-in paints.
+ *
+ * Reproduced minimally: dialog `overflow: hidden` + a scrolling child inside
+ * the drawer snaps; either one alone animates.
+ *
+ * Note on scope: jsdom has no top layer, no transitions, no `@starting-style`
+ * evaluation and no compositor, so none of this is observable here. These
+ * tests pin the three declarations the behaviour rests on. Verified in
+ * Chromium by screencasting painted frames (not computed style) at both edges,
+ * LTR and RTL: open and close each paint ~60-100 distinct intermediate
+ * positions, and reduced motion collapses to a 10ms transition.
+ */
+
+import {describe, it, expect, beforeAll} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import ts from 'typescript';
+import {MobileNav} from './MobileNav';
+
+// jsdom doesn't implement showModal/close on <dialog>, so we mock them
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal =
+    HTMLDialogElement.prototype.showModal ||
+    function (this: HTMLDialogElement) {
+      this.setAttribute('open', '');
+    };
+  HTMLDialogElement.prototype.close =
+    HTMLDialogElement.prototype.close ||
+    function (this: HTMLDialogElement) {
+      this.removeAttribute('open');
+    };
+});
+
+/** Every CSS rule StyleX has injected into the document, as text. */
+function injectedRules(): string[] {
+  const rules: string[] = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    let cssRules: CSSRuleList;
+    try {
+      cssRules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    for (const rule of Array.from(cssRules)) {
+      rules.push(rule.cssText);
+    }
+  }
+  return rules;
+}
+
+describe('MobileNav scrim fades in', () => {
+  it('gives the ::backdrop a transparent starting style', () => {
+    render(
+      <MobileNav isOpen onOpenChange={() => {}} data-testid="mobile-nav">
+        <span>Nav content</span>
+      </MobileNav>,
+    );
+
+    const classes = Array.from(screen.getByTestId('mobile-nav').classList);
+    // Without this the scrim is opaque in the frame the dialog enters the top
+    // layer, so it has nothing to fade from and snaps in behind the drawer.
+    const startingStyleForThisDialog = injectedRules().filter(
+      rule =>
+        rule.startsWith('@starting-style') &&
+        rule.includes('::backdrop') &&
+        classes.some(cls => rule.includes(`.${cls}`)),
+    );
+
+    expect(startingStyleForThisDialog).toHaveLength(1);
+    expect(startingStyleForThisDialog[0]).toMatch(/opacity:\s*0/);
+  });
+});
+
+// =============================================================================
+// Drawer slide-in — asserted on the style definition
+// =============================================================================
+
+const SOURCE = readFileSync(join(__dirname, 'MobileNav.tsx'), 'utf8');
+
+/**
+ * The object literal a `styles.<name>` key is defined with, e.g. the value of
+ * `drawerStartOpen` inside the file's `stylex.create({...})` call.
+ */
+function styleDefinition(name: string): ts.ObjectLiteralExpression {
+  const file = ts.createSourceFile(
+    'MobileNav.tsx',
+    SOURCE,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  );
+
+  let found: ts.ObjectLiteralExpression | undefined;
+  const visit = (node: ts.Node) => {
+    if (
+      ts.isPropertyAssignment(node) &&
+      ts.isIdentifier(node.name) &&
+      node.name.text === name &&
+      ts.isObjectLiteralExpression(node.initializer)
+    ) {
+      found = node.initializer;
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(file);
+
+  if (!found) {
+    throw new Error(`No style named "${name}" in MobileNav.tsx`);
+  }
+  return found;
+}
+
+/** The value of one property of a style definition, as source text. */
+function property(style: ts.ObjectLiteralExpression, key: string): string {
+  const prop = style.properties.find(
+    p =>
+      ts.isPropertyAssignment(p) &&
+      (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+      p.name.text === key,
+  );
+
+  if (!prop) {
+    throw new Error(`No "${key}" in ${style.getText().slice(0, 40)}…`);
+  }
+  return (prop as ts.PropertyAssignment).initializer.getText();
+}
+
+describe('MobileNav dialog does not become a scroll container', () => {
+  it('clips the off-screen drawer with `clip`, not `hidden`', () => {
+    // This is the half of the fix with no visible declaration of its own
+    // purpose: `hidden` looks like a pure clipping choice and clips exactly as
+    // well, so it is an easy "harmless tidy-up" to make. It is not harmless —
+    // it makes the dialog a scroll container, and the entry animation then
+    // ticks in the CSSOM without ever painting. See the file header.
+    expect(property(styleDefinition('dialog'), 'overflow')).toBe("'clip'");
+  });
+});
+
+describe.each([
+  {
+    name: 'drawerStartOpen',
+    offscreen: 'translateX(-100%)',
+    offscreenRtl: 'translateX(100%)',
+  },
+  {
+    name: 'drawerEndOpen',
+    offscreen: 'translateX(100%)',
+    offscreenRtl: 'translateX(-100%)',
+  },
+])('MobileNav drawer slides in ($name)', ({name, offscreen, offscreenRtl}) => {
+  it('opens to the on-screen transform', () => {
+    expect(property(styleDefinition(name), 'transform')).toContain(
+      'translateX(0)',
+    );
+  });
+
+  it('starts off-screen so the open transform has something to run from', () => {
+    const transform = property(styleDefinition(name), 'transform');
+
+    // The whole point: the first rendered frame needs the closed transform.
+    // Drop this and the drawer is simply there, fully open, on frame one —
+    // while the close still animates, which is what made the bug look like a
+    // missing entry animation rather than a missing starting style.
+    expect(transform).toContain('@starting-style');
+    expect(transform).toContain(offscreen);
+    // Mirrored, like the closed styles it has to match: sliding in from the
+    // wrong edge in RTL is as broken as not sliding at all.
+    expect(transform).toContain(offscreenRtl);
+  });
+
+  it('starts from the same edge the closed style parks it at', () => {
+    const closed = property(
+      styleDefinition(name.replace('Open', '')),
+      'transform',
+    );
+
+    expect(closed).toContain(offscreen);
+    expect(closed).toContain(offscreenRtl);
+  });
+});