@astryxdesign/core 0.7.5 → 0.7.6-canary.00507ba

package/locales/en.json

@@ -791,6 +791,14 @@
     "defaultMessage": "Open menu",
     "description": "Screen-reader-only label on the `⋯` overflow-menu button embedded in a SideNav section heading. Same string as `topNav.heading.openMenu` — translations may share."
   },
+  "@astryx.slider.minimumThumb": {
+    "defaultMessage": "Minimum value",
+    "description": "Accessible name of the lower thumb of a range Slider (two thumbs), announced together with the Slider's own label, for example \"Price range, Minimum value, 20\". Never shown on screen."
+  },
+  "@astryx.slider.maximumThumb": {
+    "defaultMessage": "Maximum value",
+    "description": "Accessible name of the upper thumb of a range Slider (two thumbs), announced together with the Slider's own label, for example \"Price range, Maximum value, 80\". Never shown on screen."
+  },
   "@astryx.tabList.label": {
     "defaultMessage": "Tabs",
     "description": "Screen-reader-only fallback name for a horizontal tab bar. Plural noun; \"Tabs\" here = UI tab panels, not browser tabs or the Tab key."
@@ -803,6 +811,10 @@
     "defaultMessage": "No data",
     "description": "Fallback empty-state text in the table body when there are zero rows. Neutral tone (not error-y); consumers commonly override with something specific like \"No results\"."
   },
+  "@astryx.table.columnResize.resizeColumn": {
+    "defaultMessage": "Resize column {label}",
+    "description": "Accessible name for a Table column-resize handle (a vertical separator between header cells). `label` is the column header's visible text, or the column key when the header has no text."
+  },
   "@astryx.table.filter.allPlaceholder": {
     "defaultMessage": "All",
     "description": "Placeholder on a per-column filter dropdown when nothing is selected, meaning \"no filter — all rows match\". Determiner form (as in \"all values\"), not the pronoun."
@@ -1009,11 +1021,11 @@
   },
   "@astryx.dateTimeInput.timeHint12h": {
     "defaultMessage": "e.g., 2:30 PM",
-    "description": "Placeholder hint shown in the DateTimeInput time field when focused and empty with 12-hour format. Gives an example of expected input format."
+    "description": "Placeholder hint shown in the TimeInput and DateTimeInput time fields when focused and empty with 12-hour format. Gives an example of expected input format; write the example time as your locale writes 12-hour time."
   },
   "@astryx.dateTimeInput.timeHint24h": {
     "defaultMessage": "e.g., 14:30",
-    "description": "Placeholder hint shown in the DateTimeInput time field when focused and empty with 24-hour format. Gives an example of expected input format."
+    "description": "Placeholder hint shown in the TimeInput and DateTimeInput time fields when focused and empty with 24-hour format. Gives an example of expected input format; write the example time as your locale writes 24-hour time."
   },
   "@astryx.dateTimeInput.timeSuffix": {
     "defaultMessage": "{label} time",
@@ -1567,6 +1579,10 @@
     "defaultMessage": "Expand all rows",
     "description": "Aria label for the Table tree-data header toggle when rows are collapsed and clicking it expands them."
   },
+  "@astryx.textArea.counter": {
+    "defaultMessage": "{count, number}/{limit, number}",
+    "description": "Visible character counter at the bottom of a TextArea that has a character limit, for example `62/2,000`. `{count}` is the characters typed so far and `{limit}` the limit; keep both numbers and reorder or change the separator if your language needs to."
+  },
   "@astryx.textArea.charactersRemaining": {
     "defaultMessage": "{count, number} {count, plural, one {character} other {characters}} remaining",
     "description": "Screen-reader-only announcement of how many characters the user can still type before hitting a TextArea's maxLength. Announced politely as the count nears the limit. `{count}` is the number remaining — example: `12 characters remaining`."
@@ -1643,6 +1659,10 @@
     "defaultMessage": "{count, number} of {total, number} selected",
     "description": "Polite screen-reader announcement of how many MultiSelector options are selected out of the total, spoken after each toggle. Live-region text, never shown on screen; example: `3 of 12 selected`."
   },
+  "@astryx.multiSelector.selectedCount": {
+    "defaultMessage": "{count, plural, one {# selected} other {# selected}}",
+    "description": "Visible text on a closed MultiSelector's trigger when it shows a count of the chosen options (`triggerDisplay=\"count\"`), for example `2 selected`. `{count}` is the number of chosen options; use a plural form if your language needs one."
+  },
   "@astryx.multiSelector.createOption": {
     "defaultMessage": "Create \"{query}\"",
     "description": "Label of the first row in a MultiSelector's search panel when `hasCreate` is set and the typed text matches no option. Picking it reports a creation to the caller. `{query}` is the trimmed text the person typed, shown in quotes."
@@ -1693,7 +1713,7 @@
   },
   "@astryx.tokenizer.create": {
     "defaultMessage": "Create \"{value}\"",
-    "description": "Label of the create row inside a Tokenizer's bottom sheet when `hasCreate` is set and the typed text matches no existing item. `{value}` is the typed text, e.g. `Create \"Marketing\"`."
+    "description": "Label of a Tokenizer's create row, in the inline menu and the bottom sheet, when `hasCreate` is set and the typed text matches no existing item. `{value}` is the typed text, e.g. `Create \"Marketing\"`."
   },
   "@astryx.tokenizer.add": {
     "defaultMessage": "Add",
@@ -2151,6 +2171,10 @@
     "defaultMessage": "Resolved by {name}",
     "description": "Tooltip of the Resolved text on a comment thread in a lab Comments panel. `name` is the person who resolved it."
   },
+  "@astryx.comments.errorAnnouncement": {
+    "defaultMessage": "{title} {description}",
+    "description": "Screen-reader announcement for an error Banner in a lab Comments panel that has a title and a description, read once when the Banner appears. `title` is the Banner's title (for example `Couldn't send this comment.`) and `description` its description (for example `Retrying didn't work.`). Reorder or punctuate as the language needs."
+  },
   "@astryx.comments.retryFailed": {
     "defaultMessage": "Retrying didn't work.",
     "description": "Error shown on a comment in a lab Comments panel that failed to post when retrying it failed too."

package/locales/pseudo.json

@@ -593,6 +593,12 @@
   "@astryx.sideNav.heading.openMenu": {
     "defaultMessage": "⟦Óþéñ ɱéñú⟧"
   },
+  "@astryx.slider.minimumThumb": {
+    "defaultMessage": "⟦Ṁíñíɱúɱ ṽàłúé⟧"
+  },
+  "@astryx.slider.maximumThumb": {
+    "defaultMessage": "⟦Ṁàẋíɱúɱ ṽàłúé⟧"
+  },
   "@astryx.tabList.label": {
     "defaultMessage": "⟦Ţàƀš⟧"
   },
@@ -602,6 +608,9 @@
   "@astryx.table.noData": {
     "defaultMessage": "⟦Ñó ðàţà⟧"
   },
+  "@astryx.table.columnResize.resizeColumn": {
+    "defaultMessage": "⟦Řéšížé çółúɱñ {label}⟧"
+  },
   "@astryx.table.filter.allPlaceholder": {
     "defaultMessage": "⟦Àłł⟧"
   },
@@ -1175,6 +1184,9 @@
   "@astryx.tableTree.expandAllRows": {
     "defaultMessage": "⟦Éẋþàñð àłł řóŵš⟧"
   },
+  "@astryx.textArea.counter": {
+    "defaultMessage": "⟦{count, number}/{limit, number}⟧"
+  },
   "@astryx.textArea.charactersRemaining": {
     "defaultMessage": "⟦{count, number} {count, plural, one {character} other {characters}} řéɱàíñíñĝ⟧"
   },
@@ -1232,6 +1244,9 @@
   "@astryx.multiSelector.selectionCount": {
     "defaultMessage": "⟦{count, number} óƒ {total, number} šéłéçţéð⟧"
   },
+  "@astryx.multiSelector.selectedCount": {
+    "defaultMessage": "⟦{count, plural, one {# selected} other {# selected}}⟧"
+  },
   "@astryx.multiSelector.createOption": {
     "defaultMessage": "⟦Çřéàţé \"{query}\"⟧"
   },
@@ -1613,6 +1628,9 @@
   "@astryx.comments.resolvedBy": {
     "defaultMessage": "⟦Řéšółṽéð ƀý {name}⟧"
   },
+  "@astryx.comments.errorAnnouncement": {
+    "defaultMessage": "⟦{title} {description}⟧"
+  },
   "@astryx.comments.retryFailed": {
     "defaultMessage": "⟦Řéţřýíñĝ ðíðñ'ţ ŵóřķ.⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.5",
+  "version": "0.7.6-canary.00507ba",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -847,6 +847,9 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@astryxdesign/a11y-spec": "0.7.6-canary.00507ba",
+    "@astryxdesign/cli": "0.7.6-canary.00507ba",
+    "@astryxdesign/interaction-harness": "0.7.6-canary.00507ba",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",
@@ -857,9 +860,7 @@
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
     "@types/babel__core": "^7.20.5",
-    "tailwindcss": "^4.3.2",
-    "@astryxdesign/cli": "0.7.5",
-    "@astryxdesign/a11y-spec": "0.0.0"
+    "tailwindcss": "^4.3.2"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/src/AlertDialog/AlertDialog.tsx

@@ -18,18 +18,19 @@
 
 import React, {useId, useCallback} from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {Dialog} from '../Dialog';
+import {Dialog} from '../Dialog/Dialog';
 import {Layout} from '../Layout/Layout';
 import {LayoutContent} from '../Layout/LayoutContent';
 import {LayoutFooter} from '../Layout/LayoutFooter';
-import {Stack} from '../Stack';
+import {Stack} from '../Stack/Stack';
 import {Heading} from '../Heading/Heading';
 import {Text} from '../Text/Text';
-import {Button, type ButtonVariant} from '../Button';
+import {Button} from '../Button/Button';
+import type {ButtonVariant} from '../Button';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
-import {useTranslator} from '../i18n';
+import {useTranslator} from '../i18n/useTranslator';
 import {useMediaQuery} from '../hooks/useMediaQuery';
 
 const SMALL_SCREEN_QUERY = '(max-width: 640px)';

package/src/AlertDialog/__tests__/AlertDialog.a11y.chromium.spec.ts

@@ -91,15 +91,27 @@ async function runState(
   });
 }
 
-test('every alert-dialog expectation is exercised by an AlertDialog state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every alert-dialog expectation is exercised by an AlertDialog state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of ALERT_DIALOG_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      ALERT_DIALOG_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of ALERT_DIALOG_BINDING_STATES) {

package/src/AppShell/AppShell.doc.mjs

@@ -96,7 +96,7 @@ export const docs = {
         name: 'Main content',
         required: true,
         description:
-          'children, rendered in the main landmark. Scrolls internally when height is fill, and with the page when it is auto.',
+          'children, rendered in the main landmark. Scrolls internally when height is fill, and with the page when it is auto. While it scrolls content that overflows, it is a stop in the tab order; Tab entry moves on when its first focusable element is a plain link or button, and otherwise main is one stop before it.',
       },
       {
         name: 'Mobile nav drawer',

package/src/AppShell/AppShell.spec.md

@@ -36,7 +36,7 @@ system_specs: [spec:AST-012, spec:AST-027]
 | Behavior                | One page frame: skip link, then a header region, an inline side region, and one `main` region. Below the mobile breakpoint the side nav leaves the page and AppShell composes a mobile drawer from the nav slots, unless `mobileNav` disables or replaces it.                                                                                                                                        |
 | End-user impact         | Keyboard users get a skip link to the main region; screen-reader users get one banner and one main landmark; phone-width users reach the side nav through a toggle and drawer while page content, its input values, and focus survive the layout switch. When the side nav collapses or expands, the content's old and new wrap swap on the rail's clock instead of re-wrapping in one frame (FR17). |
 | Builder impact          | None. Callers fill slots and choose height, variant, content padding, and mobile behavior.                                                                                                                                                                                                                                                                                                           |
-| Compatibility/readiness | Records shipped behavior; no prop, default, or export changes. Five current-state gaps, listed under Current-state impact: page-level stacking values, a banner pinned against its docs, an unmeasured late header, a raw `content` drawer the toggle cannot reach, and a fill-height main region that is not a tab stop.                                                                            |
+| Compatibility/readiness | Records shipped behavior; no prop, default, or export changes. Four current-state gaps, listed under Current-state impact: page-level stacking values, a banner pinned against its docs, an unmeasured late header, and a raw `content` drawer the toggle cannot reach.                                                                                                                              |
 | Review checks           | Reject a second `main` or banner landmark from AppShell, a skip link that is not the first focusable element or does not move focus to `main`, a breakpoint that treats equality as mobile, or remounting page content when the breakpoint changes. Also reject a content area that animates its width during a side nav collapse or expand (FR17).                                                  |
 | Governing rules         | `spec:AST-012` FR8 (width points), `family:layout-regions` FR9, `architecture:theme-application` INV10, `spec:AST-027` FR1–FR5 (local stacking), `architecture:component-theming-surface`; `component:SideNav` FR6 and `spec:AST-105` FR8 (the content swap).                                                                                                                                        |
 
@@ -86,11 +86,6 @@ Consumer migration instructions belong in consumer docs and release notes.
   the auto toggle still renders, so its `aria-controls` names no element and its
   presses open nothing. WCAG 4.1.2 requires a control's relationships and state
   to be programmatically correct.
-- **The fill-height main region is not a tab stop while it overflows.** In
-  `height="fill"` the main region is a scroll container, but it is never a
-  sequential tab stop, so keyboard users reach overflowing content only through
-  the skip link or focusable content inside it. `spec:AST-025` FR12 requires
-  effective scroll content to stay keyboard reachable.
 
 ## Ownership boundary
 
@@ -155,7 +150,7 @@ the only component record in the AppShell root.
 | FR1  | The root element carries `app-shell`, the forwarded `ref`, `data-testid`, and other DOM props, and contains, in order: the skip link, the Layout frame (header region, inline side region, content region), then any mobile drawer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests                    |
 | FR2  | A slot is present when its value is renderable: not `null`, `undefined`, a boolean, or an empty string. A component that renders nothing still counts as present.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and public types             |
 | FR3  | The header region renders only when `topNav` or `banner` is present; it carries `app-shell-header` and `role="banner"`, places `banner` above `topNav`, and is never inside another landmark. The sidenav-only mobile top bar (FR9) also carries `app-shell-header` and takes `role="banner"` only when no header region renders. AppShell renders at most one banner landmark.                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests                    |
-| FR4  | `children` render in one region with `role="main"` and `id="astryx-app-shell-main"`, programmatically focusable so the skip link can move focus to it; programmatic focus on it draws no focus ring. Its padding is `contentPadding`, default `0`. Whether it is a sequential tab stop is keyboard access to a scroll region (`spec:AST-025` FR12).                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests                    |
+| FR4  | `children` render in one region with `role="main"` and `id="astryx-app-shell-main"`, programmatically focusable so the skip link can move focus to it; programmatic focus on it draws no focus ring. Its padding is `contentPadding`, default `0`. Whether it is a sequential tab stop is keyboard access to a scroll region (`spec:AST-025` FR12). Focus that Tab moves onto it while it is a stop draws the standard focus ring, inset, until focus leaves it; in `elevated` with both navs the region takes the surface's rounded top-start corner while that ring shows.                                                                                                                                                                                               | Current source and tests                    |
 | FR5  | The skip link is the first focusable element in the shell. It links to `#astryx-app-shell-main`, shows the translated `@astryx.appShell.skipToContent` text, is visually hidden until focused, and on activation moves focus to the main region.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | WCAG 2.4.1; current source and tests        |
 | FR6  | `fill` sizes the root to `100dvh` and the inline side region and main region scroll on their own. `auto` gives the root a `100dvh` minimum, makes the header sticky at the block start, keeps the inline side region sticky below the measured height of a header present when the shell mounts in `auto`, with its own scrolling, and lets the page scroll. Header height is measured only in `auto`.                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests                    |
 | FR7  | Variant backgrounds: `wash` paints body background on the frame, nav areas, and content; `surface` paints surface on all three; `section` paints surface on the frame and divides the nav areas from content, and in `auto` the header paints surface itself; `elevated` paints body background on the frame and nav areas and surface on content (FR16 for the corner).                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests                    |
@@ -202,8 +197,10 @@ the only component record in the AppShell root.
 
 ### Performance and resources
 
-- **PR1 — Header measurement.** AppShell observes the header's size only in
-  `auto` and observes nothing in `fill`.
+- **PR1 — Measurement.** AppShell observes the header's size only in `auto`.
+  In `fill` it observes only whether the main region overflows (main's size,
+  its direct children's sizes, and its content), which decides whether main is
+  a sequential tab stop (FR4).
 - **PR2 — One media query.** The breakpoint switch uses one media query
   subscription per shell.
 
@@ -280,9 +277,9 @@ reachability, not a decision that it must stay unthemeable.
 
 | Contract            | Verification                                                                                                                                                                                                                                        | Representative states                                                                                                                                                                                                                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                         | Audit section                  |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1–FR4, AR1        | `AppShell.test.tsx` slot, landmark, banner, and ref suites                                                                                                                                                                                          | Content only; each slot; mobile top bar with banner                                                                                                                                                                                                                | A missing or duplicate landmark, or a nested banner, fails role queries.                                                                                                                                                                                                                                                                                                                                | `audit:AppShell/anatomy`       |
+| FR1–FR4, AR1        | `AppShell.test.tsx` slot, landmark, banner, and ref suites; `AppShellMainKeyboard.a11y.browser.spec.ts` for main as a tab stop and its focus ring                                                                                                   | Content only; each slot; mobile top bar with banner; Tab, Shift+Tab, click and skip link onto an overflowing main                                                                                                                                                  | A missing or duplicate landmark, or a nested banner, fails role queries.                                                                                                                                                                                                                                                                                                                                | `audit:AppShell/anatomy`       |
 | FR5, AR2            | `AppShell.test.tsx` skip-link and keyboard suites                                                                                                                                                                                                   | First Tab; Enter; click; translated text                                                                                                                                                                                                                           | Losing the href, the focus move, or tab order fails.                                                                                                                                                                                                                                                                                                                                                    | `audit:AppShell/accessibility` |
-| FR6, PR1            | `AppShell.test.tsx` height-mode suites                                                                                                                                                                                                              | `fill`, `auto`, section header in `auto`                                                                                                                                                                                                                           | Dropping the header's sticky placement or measuring in `fill` fails.                                                                                                                                                                                                                                                                                                                                    | `audit:AppShell/behavior`      |
+| FR6, PR1            | `AppShell.test.tsx` height-mode and main keyboard access suites; `observeMainOverflow.test.ts`                                                                                                                                                      | `fill`, `auto`, section header in `auto`; main fitting and overflowing in `fill`                                                                                                                                                                                   | Dropping the header's sticky placement, measuring the header in `fill`, or not measuring main, fails.                                                                                                                                                                                                                                                                                                   | `audit:AppShell/behavior`      |
 | FR8                 | `AppShell.test.tsx` breakpoint suites                                                                                                                                                                                                               | `lg`, `xl`, `2xl`, explicit `md`, `none`; nearest, root, and built themes; SSR hint                                                                                                                                                                                | Wrong map, inclusive edge, or `none` entering mobile fails.                                                                                                                                                                                                                                                                                                                                             | `audit:AppShell/behavior`      |
 | FR9–FR12            | `AppShell.test.tsx` mobile suites; `MobileNavCloseEdgeCases.test.tsx` AppShell drawer suites                                                                                                                                                        | Sidenav only; both navs; heading-only TopNav; custom node                                                                                                                                                                                                          | A missing toggle, duplicated items, a stale drawer, or an early hide fails.                                                                                                                                                                                                                                                                                                                             | `audit:AppShell/behavior`      |
 | FR13, AR3           | `AppShell.test.tsx` keyboard drawer and `useAppShellMobile` suites                                                                                                                                                                                  | Outside a shell; inside, closed and open                                                                                                                                                                                                                           | A wrong id link or stale state fails.                                                                                                                                                                                                                                                                                                                                                                   | `audit:AppShell/accessibility` |
@@ -298,7 +295,7 @@ Read from source, with no focused test or baseline yet:
 - FR2: `null`, `true`, `false`, and `''` slots counting as absent, and a slot that renders
   nothing counting as present.
 - FR3: `banner` above `topNav`, and no header region with only `sideNav`.
-- FR4: the `contentPadding` value and its `0` default, and no focus ring on main.
+- FR4: the `contentPadding` value and its `0` default.
 - FR5: the skip link's visual hiding until focus; AR2: its shared focus outline.
 - FR6: root sizing and region scrolling in each height mode, and the sticky side
   region in `auto`.

package/src/AppShell/AppShell.test.tsx

@@ -860,7 +860,7 @@ describe('AppShell', () => {
     expect(observeSpy).toHaveBeenCalled();
   });
 
-  it('does not set up ResizeObserver in fill mode', () => {
+  it('does not observe the header in fill mode', () => {
     const observeSpy = vi.fn();
     vi.stubGlobal(
       'ResizeObserver',
@@ -878,7 +878,13 @@ describe('AppShell', () => {
       </AppShell>,
     );
 
-    expect(observeSpy).not.toHaveBeenCalled();
+    // Only the header offset needs measuring for sticky positioning, which
+    // fill mode does not use. (Main is measured for keyboard access.)
+    const observed = new Set<unknown>();
+    for (const call of observeSpy.mock.calls) {
+      observed.add(call[0]);
+    }
+    expect(observed.has(screen.getByRole('banner'))).toBe(false);
   });
 
   // ===========================================================================
@@ -1146,3 +1152,159 @@ describe('AppShell', () => {
     ).toBe(true);
   });
 });
+
+describe('AppShell main keyboard access', () => {
+  let frames: FrameRequestCallback[];
+
+  beforeEach(() => {
+    frames = [];
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn((callback: FrameRequestCallback) => {
+        frames.push(callback);
+        return frames.length;
+      }),
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+    // jsdom does not expand LayoutContent's `overflow` into its longhands.
+    const nativeGetComputedStyle = window.getComputedStyle.bind(window);
+    vi.spyOn(window, 'getComputedStyle').mockImplementation(
+      (element, pseudo) => {
+        const computed = nativeGetComputedStyle(element, pseudo);
+        return new Proxy(computed, {
+          // eslint-disable-next-line @typescript-eslint/promise-function-async -- Proxy traps must remain synchronous
+          get(target, property) {
+            if (property === 'overflowX' || property === 'overflowY') {
+              return target.overflow || 'visible';
+            }
+            return Reflect.get(target, property, target);
+          },
+        });
+      },
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.stubGlobal('ResizeObserver', MockResizeObserver);
+  });
+
+  function setMainGeometry(main: HTMLElement, scrollHeight: number) {
+    for (const [key, value] of [
+      ['clientWidth', 800],
+      ['scrollWidth', 800],
+      ['clientHeight', 300],
+      ['scrollHeight', scrollHeight],
+      ['scrollTop', 0],
+      ['scrollLeft', 0],
+    ] as const) {
+      Object.defineProperty(main, key, {
+        configurable: true,
+        value,
+        writable: true,
+      });
+    }
+  }
+
+  function remeasure() {
+    act(() => {
+      window.dispatchEvent(new Event('resize'));
+    });
+    act(() => {
+      const pending = frames.splice(0);
+      pending.forEach(callback => callback(performance.now()));
+    });
+  }
+
+  it('makes main a keyboard stop while it scrolls overflowing content, and a skip target again once it fits', () => {
+    render(
+      <AppShell topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    const main = screen.getByRole('main');
+    expect(main).toHaveAttribute('tabindex', '-1');
+
+    setMainGeometry(main, 1200);
+    remeasure();
+    expect(main).toHaveAttribute('tabindex', '0');
+
+    setMainGeometry(main, 300);
+    remeasure();
+    expect(main).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('observes main only with fill, where it can become a keyboard stop', () => {
+    const observed: Element[] = [];
+    vi.stubGlobal(
+      'ResizeObserver',
+      class {
+        constructor(public callback: ResizeObserverCallback) {}
+        observe(target: Element) {
+          observed.push(target);
+        }
+        unobserve() {}
+        disconnect() {}
+      },
+    );
+    const inMain = (main: HTMLElement) =>
+      observed.filter(target => target === main || main.contains(target));
+
+    const {unmount} = render(
+      <AppShell height="auto" topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    expect(inMain(screen.getByRole('main'))).toEqual([]);
+    unmount();
+
+    render(
+      <AppShell topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    expect(inMain(screen.getByRole('main')).length).toBeGreaterThan(0);
+  });
+
+  it('stops observing main when the shell switches to auto, and measures it again back in fill', () => {
+    const {rerender} = render(
+      <AppShell topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    const main = screen.getByRole('main');
+    setMainGeometry(main, 1200);
+    remeasure();
+    expect(main).toHaveAttribute('tabindex', '0');
+
+    rerender(
+      <AppShell height="auto" topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    expect(screen.getByRole('main')).toHaveAttribute('tabindex', '-1');
+    remeasure();
+    expect(screen.getByRole('main')).toHaveAttribute('tabindex', '-1');
+
+    // Back in fill, main is measured as it attaches, with no other signal.
+    rerender(
+      <AppShell topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    expect(screen.getByRole('main')).toHaveAttribute('tabindex', '0');
+  });
+
+  it('never makes main a keyboard stop when the page scrolls instead (auto)', () => {
+    render(
+      <AppShell height="auto" topNav={<div>Nav</div>}>
+        <p>Long content</p>
+      </AppShell>,
+    );
+    const main = screen.getByRole('main');
+
+    setMainGeometry(main, 1200);
+    remeasure();
+    expect(main).toHaveAttribute('tabindex', '-1');
+  });
+});