@astryxdesign/core 0.7.2-canary.fe2c655 → 0.7.2

package/scripts/agent-doc-state.mjs

@@ -107,15 +107,75 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
 }
 
 /**
- * The one-line next-step both postinstall nudges print. Kept here so layer 1
- * (core) and layer 2 (cli) can never word it differently.
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
  *
- * Scoped package form (`@astryxdesign/cli`) — always resolves to us, even before
- * the CLI is installed. Bare `npx astryx` would fetch an unrelated look-alike
+ * Coding agents read the agent docs between the repository root and the folder
+ * they work in. So inside a git repository, init's block in any folder from
+ * `startDir` up to the repository root counts: a workspace package of a
+ * monorepo initialized at its root is set up. Outside a repository only
+ * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
+ * per-command nudge and the postinstall nudges ask this.
+ *
+ * @param {string} [startDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function isAstryxPromptInReach(startDir = process.cwd()) {
+  const start = path.resolve(startDir);
+  const repositoryRoot = findRepositoryRoot(start);
+  if (!repositoryRoot) return isAstryxInitialized(start);
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (isAstryxInitialized(dir)) return true;
+    if (dir === repositoryRoot) return false;
+  }
+}
+
+/**
+ * The nearest folder at or above `start` that holds `.git` (a folder, or the
+ * file a worktree uses), or null outside a repository.
+ * @param {string} start
+ * @returns {string | null}
+ */
+function findRepositoryRoot(start) {
+  for (let dir = start; ; ) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * The invocation the setup nudge falls back to when the CLI's picker
+ * (`getCliInvocation`) cannot be loaded. Scoped package form
+ * (`@astryxdesign/cli`) — always resolves to us, even before the CLI is
+ * installed. npx with the unscoped name would fetch an unrelated look-alike
  * package (see PR #4151).
  */
-export const SETUP_NUDGE =
-  '\nNext step: run `npx @astryxdesign/cli init` to finish setup and install the Astryx agent prompt.\n\n';
+export const SETUP_INVOCATION = 'npx @astryxdesign/cli';
+
+/**
+ * The one-line next-step every setup layer prints. Kept here so layer 1
+ * (core), layer 2 (cli postinstall) and layer 3 (each command) can never word
+ * it differently. Each layer passes the stem from the CLI's picker when it can
+ * load it.
+ *
+ * @param {string} [invocation] the CLI invocation stem, e.g. `pnpm exec astryx`
+ * @param {{before?: string | null}} [options] `before`: a command to run
+ *   first, such as the one that adds the CLI to a project that has none
+ * @returns {string}
+ */
+export function setupNudge(
+  invocation = SETUP_INVOCATION,
+  {before = null} = {},
+) {
+  const run = before
+    ? `\`${before}\`, then \`${invocation} init\``
+    : `\`${invocation} init\``;
+  return `\nNext step: run ${run} to finish setup and install the Astryx agent prompt.\n\n`;
+}
+
+/** The nudge with the fallback invocation. */
+export const SETUP_NUDGE = setupNudge();
 
 /**
  * Pure decision: should a postinstall print the setup nudge? Shared by BOTH

package/scripts/postinstall.mjs

@@ -1,7 +1,8 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file @astryxdesign/core postinstall — nudge to run `npx @astryxdesign/cli init`.
+ * @file @astryxdesign/core postinstall — nudge to run `astryx init`, prefixed
+ * the way the project's installed CLI prints commands.
  *
  * Enforcement layer 1 of making `astryx init` foolproof: when the design system
  * is installed and the project hasn't run init yet, print a one-line next-step
@@ -19,6 +20,8 @@
  * during npx's fetch, and once set up.
  */
 
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import {fileURLToPath, pathToFileURL} from 'node:url';
 
 const HERE = fileURLToPath(import.meta.url);
@@ -37,6 +40,39 @@ async function loadContract() {
   }
 }
 
+/**
+ * The stem the project's installed CLI would print, from its picker
+ * (`getCliInvocation`). Core cannot depend on the CLI, so this looks for an
+ * installed copy from the project upward and imports the picker by path; with
+ * no CLI there, or one too old to have the picker, it returns undefined and
+ * the contract's scoped fallback is printed. At install time no integration is
+ * loaded, so this is the package-manager guess.
+ * @param {string} root
+ * @returns {Promise<string | undefined>}
+ */
+export async function cliInvocation(root) {
+  try {
+    let dir = path.resolve(root);
+    for (;;) {
+      const picker = path.join(
+        dir,
+        'node_modules/@astryxdesign/cli/foundation/env/package-manager.mjs',
+      );
+      if (fs.existsSync(picker)) {
+        const {getCliInvocation} = await import(pathToFileURL(picker).href);
+        return typeof getCliInvocation === 'function'
+          ? getCliInvocation(root)
+          : undefined;
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) return undefined;
+      dir = parent;
+    }
+  } catch {
+    return undefined;
+  }
+}
+
 async function main() {
   const contract = await loadContract();
   if (!contract) return;
@@ -45,10 +81,15 @@ async function main() {
     contract.shouldNudge({
       scriptPath: HERE,
       npmCommand: process.env.npm_command,
-      isSetUp: contract.isAstryxInitialized(root),
+      isSetUp: contract.isAstryxPromptInReach(root),
     })
   ) {
-    process.stdout.write(contract.SETUP_NUDGE);
+    const invocation = await cliInvocation(root);
+    process.stdout.write(
+      typeof contract.setupNudge === 'function'
+        ? contract.setupNudge(invocation)
+        : contract.SETUP_NUDGE,
+    );
   }
 }
 

package/src/AppShell/AppShell.tsx

@@ -43,6 +43,7 @@ import {LayoutHeader} from '../Layout/LayoutHeader';
 import {LayoutPanel} from '../Layout/LayoutPanel';
 import {LayoutContent} from '../Layout/LayoutContent';
 import {MobileNavToggle} from '../MobileNav/MobileNavToggle';
+import {MAX_CLOSE_DELAY_MS as MOBILE_NAV_MAX_CLOSE_DELAY_MS} from '../MobileNav/MobileNav';
 import {SideNavRenderContext} from '../SideNav/SideNavRenderContext';
 import {TopNavRenderContext} from '../TopNav/TopNavRenderContext';
 import {TopNavMobileContentContext} from '../TopNav/TopNavMobileContentContext';
@@ -81,6 +82,20 @@ const ActivityWrapper = HasActivity
 
 const MAIN_CONTENT_ID = 'astryx-app-shell-main';
 
+/**
+ * Extra time, on top of MobileNav's own worst-case close delay, that
+ * AppShell waits before flipping its `Activity` boundary to `'hidden'`.
+ *
+ * React's `Activity` hides its subtree with `display: none !important`
+ * synchronously in the same commit as the mode flip, and re-runs the
+ * cleanup of every effect inside it — which would otherwise clear
+ * MobileNav's own scheduled `dialog.close()` before it fires, or cut off
+ * its slide-out CSS transition before it plays (#5701). Waiting strictly
+ * longer than MobileNav's own cap, rather than the same duration, means
+ * this never turns into a race decided by browser timer-firing order.
+ */
+const ACTIVITY_HIDE_BUFFER_MS = 50;
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -525,6 +540,34 @@ export function AppShell({
   const [uncontrolledMobileOpen, setUncontrolledMobileOpen] = useState(false);
   const isMobileNavOpen = mobileNavConfig?.isOpen ?? uncontrolledMobileOpen;
 
+  // Holds the mobile nav's `Activity` boundary visible for a beat after a
+  // close, so MobileNav's own close effect gets a real chance to run its
+  // slide-out transition and schedule its delayed `dialog.close()` before
+  // Activity hides the subtree (#5701). Only the CLOSE is deferred: opening
+  // reads `isMobileNavOpen` directly below, so a controlled open is visible in
+  // the commit that carries it instead of one effect later.
+  const [isMobileNavCloseHeld, setIsMobileNavCloseHeld] =
+    useState(isMobileNavOpen);
+  // Arm the hold during render, from the open state itself, so no Effect has
+  // to copy props into state; the Effect below only owns the release timer.
+  if (isMobileNavOpen && !isMobileNavCloseHeld) {
+    setIsMobileNavCloseHeld(true);
+  }
+  useEffect(() => {
+    if (!HasActivity || isMobileNavOpen) {
+      return;
+    }
+    const delayMs = window.matchMedia('(prefers-reduced-motion: reduce)')
+      .matches
+      ? 0
+      : MOBILE_NAV_MAX_CLOSE_DELAY_MS + ACTIVITY_HIDE_BUFFER_MS;
+    const timeout = setTimeout(() => {
+      setIsMobileNavCloseHeld(false);
+    }, delayMs);
+    return () => clearTimeout(timeout);
+  }, [isMobileNavOpen]);
+  const isMobileNavActivityVisible = isMobileNavOpen || isMobileNavCloseHeld;
+
   const mobileNavOnOpenChange = mobileNavConfig?.onOpenChange;
   const setMobileNavOpen = useCallback(
     (open: boolean) => {
@@ -864,7 +907,8 @@ export function AppShell({
           !mobileNavDisabled &&
           mobileNavReactNode == null &&
           !mobileNavConfigContent && (
-            <ActivityWrapper mode={isMobileNavOpen ? 'visible' : 'hidden'}>
+            <ActivityWrapper
+              mode={isMobileNavActivityVisible ? 'visible' : 'hidden'}>
               {/* SideNav drawer — always mounted so presence detection works.
                 Hidden when TopNav owns the drawer (combined mode passes
                 sideNav via TopNav's mobile content context instead). */}

package/src/AspectRatio/AspectRatio.test.tsx

@@ -9,7 +9,7 @@
  * SYNC: When AspectRatio.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeAll} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {AspectRatio} from './AspectRatio';
 
@@ -230,9 +230,8 @@ describe('AspectRatio', () => {
           <img src="test.jpg" alt="Test" data-testid="image" />
         </AspectRatio>,
       );
-      // The marker sits on the child's actual parent, so the reset.css
-      // sizing rules are direct-child selectors with no dependence on
-      // AspectRatio's internal structure.
+      // Earlier releases documented the marker, so it stays on the child's
+      // direct parent for product CSS that targets it.
       const wrapper = screen.getByTestId('image').parentElement;
       expect(wrapper).toHaveAttribute(
         'data-astryx-aspect-ratio-override',
@@ -274,8 +273,11 @@ describe('AspectRatio', () => {
       );
       const wrapper = screen.getByTestId('image').parentElement;
       expect(wrapper).not.toHaveAttribute('data-astryx-aspect-ratio-override');
-      // Without the marker, none of the reset.css fit rules can match, so
-      // existing self-styled children render exactly as before.
+      // Without fit the wrapper carries no child-sizing styles, so existing
+      // self-styled children render exactly as before.
+      expect(wrapper?.className).not.toContain('childFill');
+      expect(wrapper?.className).not.toContain('childCover');
+      expect(wrapper?.className).not.toContain('childContain');
       expect(screen.getByTestId('image')).not.toHaveAttribute('class');
     });
 
@@ -292,13 +294,37 @@ describe('AspectRatio', () => {
         </AspectRatio>,
       );
       const image = screen.getByTestId('image');
-      // Fit styling is pure CSS (zero-specificity reset rules); the child's
-      // own className/style pass through untouched and always win, so
-      // children that already size themselves keep their behavior.
+      // Fit styling is a direct-child rule on the wrapper; the child's own
+      // className/style pass through untouched, and an inline style still
+      // wins over it.
       expect(image.className).toBe('consumer-class');
       expect(image.style.objectFit).toBe('contain');
     });
 
+    it('sizes the child from the wrapper with fit="cover"', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="cover">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      const wrapper = screen.getByTestId('image').parentElement;
+      expect(wrapper?.className).toContain('childFill');
+      expect(wrapper?.className).toContain('childCover');
+      expect(wrapper?.className).not.toContain('childContain');
+    });
+
+    it('sizes the child from the wrapper with fit="contain"', () => {
+      render(
+        <AspectRatio ratio={16 / 9} fit="contain">
+          <img src="test.jpg" alt="Test" data-testid="image" />
+        </AspectRatio>,
+      );
+      const wrapper = screen.getByTestId('image').parentElement;
+      expect(wrapper?.className).toContain('childFill');
+      expect(wrapper?.className).toContain('childContain');
+      expect(wrapper?.className).not.toContain('childCover');
+    });
+
     it('centers the child via the wrapper with fit="center"', () => {
       render(
         <AspectRatio ratio={16 / 9} fit="center">
@@ -309,6 +335,7 @@ describe('AspectRatio', () => {
       expect(image).not.toHaveAttribute('class');
       const wrapper = image.parentElement;
       expect(wrapper?.className).toContain('childCenter');
+      expect(wrapper?.className).not.toContain('childFill');
     });
 
     it('does not center the wrapper for other fit values', () => {
@@ -353,45 +380,19 @@ describe('AspectRatio', () => {
     });
   });
 
-  describe('reset.css fit baseline rules', () => {
-    // The cover/contain child sizing ships as zero-specificity baseline
-    // rules in reset.css keyed on the data-astryx-aspect-ratio-override
-    // marker the component sets on the child's direct parent. These
-    // assertions keep the stylesheet in sync with the component contract.
-    let resetCSS: string;
-
-    beforeAll(async () => {
+  describe('reset.css', () => {
+    it('carries no AspectRatio rules', async () => {
+      // fit ships with the component's StyleX styles in `astryx-base`. A
+      // rule in reset.css sits below the layer the documented Tailwind
+      // setups give preflight, whose `img, video { height: auto }` would
+      // undo the fill.
       const fs = await import('fs');
       const path = await import('path');
-      resetCSS = fs.readFileSync(
+      const resetCSS = fs.readFileSync(
         path.resolve(__dirname, '../reset.css'),
         'utf-8',
       );
-    });
-
-    it('sizes the child to fill the box for cover and contain', () => {
-      const fillMatch = resetCSS.match(
-        /:where\(\[data-astryx-aspect-ratio-override="cover"\], \[data-astryx-aspect-ratio-override="contain"\]\)\s*>\s*:where\(\*\)\s*\{([^}]+)\}/,
-      );
-      expect(fillMatch).not.toBeNull();
-      expect(fillMatch![1]).toContain('width: 100%');
-      expect(fillMatch![1]).toContain('height: 100%');
-    });
-
-    it('crops media with object-fit: cover for fit="cover"', () => {
-      const coverMatch = resetCSS.match(
-        /:where\(\[data-astryx-aspect-ratio-override="cover"\]\)\s*>\s*:where\(img, video\)\s*\{([^}]+)\}/,
-      );
-      expect(coverMatch).not.toBeNull();
-      expect(coverMatch![1]).toContain('object-fit: cover');
-    });
-
-    it('letterboxes media with object-fit: contain for fit="contain"', () => {
-      const containMatch = resetCSS.match(
-        /:where\(\[data-astryx-aspect-ratio-override="contain"\]\)\s*>\s*:where\(img, video\)\s*\{([^}]+)\}/,
-      );
-      expect(containMatch).not.toBeNull();
-      expect(containMatch![1]).toContain('object-fit: contain');
+      expect(resetCSS).not.toContain('aspect-ratio-override');
     });
   });
 });

package/src/AspectRatio/AspectRatio.tsx

@@ -9,7 +9,6 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/AspectRatio/AspectRatio.doc.mjs
  * - /packages/core/src/AspectRatio/AspectRatio.test.tsx
- * - /packages/core/src/reset.css (AspectRatio fit baseline rules)
  * - /apps/storybook/stories/AspectRatio.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/AspectRatio/ (showcase blocks)
  */
@@ -91,13 +90,12 @@ export interface AspectRatioProps extends BaseProps<HTMLDivElement> {
    *   (`object-fit: contain`).
    * - `center`: child keeps its natural size, centered in the box.
    *
-   * `cover`/`contain` child sizing ships as zero-specificity baseline rules
-   * in `reset.css`, keyed on the `data-astryx-aspect-ratio-override`
-   * attribute the component sets on the child's direct parent. Any styles
-   * the child sets itself still win, so children that already size
-   * themselves keep their behavior. When omitted, the child is left
-   * unstyled (the pre-existing contract). `fit` is structural, not visual,
-   * so it is not exposed on the theming surface.
+   * `cover`/`contain` size the child from the component's own styles, in
+   * the `astryx-base` cascade layer. Styles in a later layer (Tailwind
+   * utilities, `astryx-theme`), unlayered CSS, and inline styles on the
+   * child still win. When omitted, the child is left unstyled (the
+   * pre-existing contract). `fit` is structural, not visual, so it is not
+   * exposed on the theming surface.
    *
    * @example
    * ```
@@ -140,15 +138,33 @@ const styles = stylex.create({
     height: '100%',
   },
   // fit="center" centers the child at its natural size from the wrapper —
-  // no styles on the child itself. The `cover`/`contain` child sizing can't
-  // live here (StyleX has no descendant selectors); it ships as baseline
-  // rules in reset.css keyed on the `data-astryx-aspect-ratio-override`
-  // attribute the wrapper carries (see below).
+  // no styles on the child itself.
   childCenter: {
     display: 'flex',
     alignItems: 'center',
     justifyContent: 'center',
   },
+  // `cover`/`contain` must style the child itself (`object-fit` only applies
+  // on the replaced element), and StyleX has no child selector. The
+  // `:not([stylex-hack])` pseudo-class always matches, so StyleX accepts the
+  // key and emits `.x:not([stylex-hack]) > *`, a direct-child rule in the
+  // `astryx-base` layer like every other component style.
+  childFill: {
+    ':not([stylex-hack]) > *': {
+      width: '100%',
+      height: '100%',
+    },
+  },
+  childCover: {
+    ':not([stylex-hack]) > :is(img, video)': {
+      objectFit: 'cover',
+    },
+  },
+  childContain: {
+    ':not([stylex-hack]) > :is(img, video)': {
+      objectFit: 'contain',
+    },
+  },
 });
 
 // The ratio compiles to a CSS variable + a class-level declaration
@@ -234,14 +250,18 @@ export function AspectRatio({
         style,
       )}
       {...props}>
-      {/* The marker attribute carries the fit value so the reset.css child
-          sizing can use direct-child selectors on this wrapper — the child's
-          actual parent — without depending on AspectRatio's internal
-          structure or on the theming surface (fit is structural, not
-          themeable). The name is namespaced to avoid collisions. */}
+      {/* The marker attribute carries the fit value. No Astryx style keys on
+          it any more, but earlier releases documented it, so product CSS may
+          still target it. */}
       <div
         data-astryx-aspect-ratio-override={fit}
-        {...stylex.props(styles.child, fit === 'center' && styles.childCenter)}>
+        {...stylex.props(
+          styles.child,
+          fit === 'center' && styles.childCenter,
+          (fit === 'cover' || fit === 'contain') && styles.childFill,
+          fit === 'cover' && styles.childCover,
+          fit === 'contain' && styles.childContain,
+        )}>
         {children}
       </div>
     </div>

package/src/AspectRatio/__tests__/AspectRatioFitLayers.a11y.browser.spec.ts

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file AspectRatioFitLayers.a11y.browser.spec.ts
+ * @input The built FitModes story (its rendered markup and compiled CSS) and
+ *   Tailwind's preflight.css
+ * @output Browser evidence that `fit` fills the box on the documented setups
+ * @position AspectRatio integration proof. Which rule sizes the child is a
+ *   cascade-layer question, and only a shipping engine resolves the cascade.
+ */
+
+import * as fs from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {expect, test, type Page} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+const PREFLIGHT_CSS = fs.readFileSync(
+  fileURLToPath(import.meta.resolve('tailwindcss/preflight.css')),
+  'utf8',
+);
+
+// The layer order each setup guide declares, and the layer preflight goes in.
+const TAILWIND_SETUPS = [
+  {
+    name: 'Tailwind v4',
+    order:
+      '@layer reset, theme, base, astryx-base, astryx-theme, components, utilities;',
+    preflightLayer: 'base',
+  },
+  {
+    name: 'Tailwind v3',
+    order: '@layer reset, tw-preflight, astryx-base, astryx-theme;',
+    preflightLayer: 'tw-preflight',
+  },
+];
+
+// A 100×100 image in a 320px-wide 16:9 box: filling the box makes it 320×180.
+const IMAGE =
+  "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='100' height='100'/%3E";
+
+type Fit = 'cover' | 'contain';
+
+let storybook: StaticServer;
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+test.afterAll(async () => {
+  await storybook?.close();
+});
+
+/**
+ * The markup AspectRatio renders for `fit`, and every CSS rule the story
+ * page loaded, taken from the built story so the classes and rules are the
+ * component's real compiled output. The child image gets a fixed id, a
+ * local source and any extra class.
+ */
+async function captureStory(page: Page, fit: Fit, mediaClass: string) {
+  await page.goto(
+    `${storybook.origin}/iframe.html?id=core-aspectratio--fit-modes&viewMode=story`,
+  );
+  const wrapper = page.locator(`[data-astryx-aspect-ratio-override="${fit}"]`);
+  await expect(wrapper).toHaveCount(1);
+  return wrapper.evaluate(
+    (element, {image, extraClass}) => {
+      const root = element.parentElement?.cloneNode(true);
+      const media =
+        root instanceof HTMLElement ? root.querySelector('img') : null;
+      if (!(root instanceof HTMLElement) || media == null) {
+        throw new Error('FitModes no longer renders an img inside AspectRatio');
+      }
+      media.id = 'media';
+      media.src = image;
+      if (extraClass) {
+        media.classList.add(extraClass);
+      }
+      const css = [...document.styleSheets]
+        .flatMap(sheet => [...sheet.cssRules].map(rule => rule.cssText))
+        .join('\n');
+      return {html: root.outerHTML, css};
+    },
+    {image: IMAGE, extraClass: mediaClass},
+  );
+}
+
+/** Re-host the captured story with `before` CSS ahead of it and `after` CSS behind it. */
+async function measureMedia(
+  page: Page,
+  fit: Fit,
+  {
+    before = [],
+    after = [],
+    mediaClass = '',
+  }: {
+    before?: string[];
+    after?: string[];
+    mediaClass?: string;
+  },
+) {
+  const {html, css} = await captureStory(page, fit, mediaClass);
+  await page.setContent(
+    `<!doctype html><div style="width: 320px">${html}</div>`,
+  );
+  for (const content of [...before, css, ...after]) {
+    await page.addStyleTag({content});
+  }
+  await page.waitForFunction(
+    () => (document.getElementById('media') as HTMLImageElement).complete,
+  );
+  return page.evaluate(() => {
+    const media = document.getElementById('media');
+    if (!media) {
+      throw new Error('missing media');
+    }
+    const box = media.getBoundingClientRect();
+    return {
+      width: box.width,
+      height: box.height,
+      objectFit: getComputedStyle(media).objectFit,
+    };
+  });
+}
+
+for (const setup of TAILWIND_SETUPS) {
+  for (const fit of ['cover', 'contain'] as const) {
+    test(`fit="${fit}" fills the box on the ${setup.name} setup`, async ({
+      page,
+    }) => {
+      const media = await measureMedia(page, fit, {
+        before: [
+          setup.order,
+          `@layer ${setup.preflightLayer} { ${PREFLIGHT_CSS} }`,
+        ],
+      });
+      expect(media).toEqual({width: 320, height: 180, objectFit: fit});
+    });
+  }
+}
+
+test('fit fills the box with only Astryx CSS loaded', async ({page}) => {
+  const media = await measureMedia(page, 'cover', {});
+  expect(media).toEqual({width: 320, height: 180, objectFit: 'cover'});
+});
+
+test('a utility class on the child still wins over fit', async ({page}) => {
+  const media = await measureMedia(page, 'cover', {
+    before: [TAILWIND_SETUPS[0].order, `@layer base { ${PREFLIGHT_CSS} }`],
+    after: ['@layer utilities { .h-10 { height: 40px; } }'],
+    mediaClass: 'h-10',
+  });
+  expect(media).toEqual({width: 320, height: 40, objectFit: 'cover'});
+});

package/src/Avatar/Avatar.doc.mjs

@@ -67,8 +67,10 @@ export const docs = {
     },
     {
       name: 'size',
-      type: "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | number",
-      description: "Avatar size. Use a named size ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or a numeric pixel value. Avatar shares Icon's abbreviated scale, but its tiers are larger because avatars align with media rather than glyphs. Inside an AvatarGroup the group's size wins and this prop is ignored.",
+      type:
+        "'xsm' | 'sm' | 'md' | 'lg' | 'xl' | 16 | 20 | 24 | 32 | 36 | 40 | 48 | 60 | 64 | 72 | 96 | 128 | 144 | 180",
+      description:
+        "Avatar size: named sizes are 'xsm' (20px), 'sm' (24px), 'md' (36px), 'lg' (48px), and 'xl' (128px); numeric sizes must be one of the pixel values listed in the type. Inside an AvatarGroup, the group's size always overrides this prop, including when the group uses its default size.",
       default: "'md'",
     },
     {
@@ -169,7 +171,7 @@ export const docsDense = {
     fallbackSrc: 'fallback image when primary fails',
     name: 'user name for initials and alt text',
     alt: 'alt text; falls back to name',
-    size: "avatar size. Named ('xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px) or numeric px. An AvatarGroup's size overrides it.",
+    size: "named sizes: 'xsm' 20px, 'sm' 24px, 'md' 36px, 'lg' 48px, 'xl' 128px; numeric px restricted to values listed in the type. AvatarGroup's size always wins, default included.",
     status:
       'corner content for status indicators; AvatarStatusDot reports its `label`, composed into the avatar accessible name ("Jane Doe, Online"), at any nesting depth',
     tooltip:

package/src/Avatar/Avatar.tsx

@@ -387,9 +387,18 @@ export interface AvatarProps extends BaseProps<HTMLDivElement> {
 /**
  * A character that can stand for a word in initials: a letter, a digit, or an
  * emoji. Punctuation and other symbols, such as `(`, `"` or `-`, cannot.
+ *
+ * Built at runtime, not written as a literal: for targets without property
+ * escapes, or when no browserslist is set, Babel's
+ * transform-unicode-property-regex rewrites a `\p{…}` literal, and the copy
+ * bundled with Next.js lacks the Unicode data it needs, so a source build fails
+ * with "Unknown property". A literal is safe once Next's bundled Babel ships
+ * that data.
  */
-const INITIAL_CHARACTER =
-  /[\p{L}\p{N}\p{Extended_Pictographic}\p{Regional_Indicator}]/u;
+const INITIAL_CHARACTER = new RegExp(
+  '[\\p{L}\\p{N}\\p{Extended_Pictographic}\\p{Regional_Indicator}]',
+  'u',
+);
 
 /**
  * The first character of a word that can stand for it in initials, skipping