@astryxdesign/core 0.7.4-canary.626f01e → 0.7.4-canary.768c2f0

package/dist/CommandPalette/CommandPaletteItem.d.ts

@@ -28,6 +28,7 @@ export interface CommandPaletteItemProps extends Omit<BaseProps<HTMLDivElement>,
     isHighlighted?: boolean;
     /**
      * Whether this item is currently selected (picker mode).
+     * When omitted inside CommandPalette, derived from the palette value.
      * @default false
      */
     isSelected?: boolean;

package/dist/CommandPalette/CommandPaletteItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommandPaletteItem.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteItem.tsx"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,EAA0C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAqD5C,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CACnD,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,UAAU,CACxB;IACC,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,EACR,aAAa,EAAE,qBAAqB,EACpC,UAAU,EAAE,kBAAkB,EAC9B,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,gBAAgB,EAC9B,GAAG,KAAK,EACT,EAAE,uBAAuB,+BAoFzB;yBAnGe,kBAAkB"}
+{"version":3,"file":"CommandPaletteItem.d.ts","sourceRoot":"","sources":["../../src/CommandPalette/CommandPaletteItem.tsx"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,OAAO,EAA0C,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE9E,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAqD5C,MAAM,WAAW,uBAAwB,SAAQ,IAAI,CACnD,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,GAAG,UAAU,CACxB;IACC,yCAAyC;IACzC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,iFAAiF;IACjF,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,QAAQ,EACR,aAAa,EAAE,qBAAqB,EACpC,UAAU,EAAE,kBAAkB,EAC9B,UAAkB,EAClB,QAAQ,EACR,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,WAAW,EACpB,YAAY,EAAE,gBAAgB,EAC9B,GAAG,KAAK,EACT,EAAE,uBAAuB,+BAwFzB;yBAvGe,kBAAkB"}

package/dist/CommandPalette/CommandPaletteItem.js

@@ -148,7 +148,11 @@ export function CommandPaletteItem({
     ...pressable,
     onClick: isDisabled ? undefined : composeEventHandlers(onClickProp, handleClick),
     onMouseEnter: onMouseEnterProp,
-    ...mergeProps(themeProps('command-palette-item'), stylex.props(styles.item, !isDisabled && interactionOverlayStyles.backgroundColor, isHighlighted && styles.itemHighlighted, isSelected && styles.itemSelected, isDisabled && styles.itemDisabled, xstyle), className, style),
+    ...mergeProps(themeProps('command-palette-item', {
+      highlighted: isHighlighted ? 'highlighted' : null,
+      selected: isSelected ? 'selected' : null,
+      disabled: isDisabled ? 'disabled' : null
+    }), stylex.props(styles.item, !isDisabled && interactionOverlayStyles.backgroundColor, isHighlighted && styles.itemHighlighted, isSelected && styles.itemSelected, isDisabled && styles.itemDisabled, xstyle), className, style),
     children: children
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.4-canary.626f01e",
+  "version": "0.7.4-canary.768c2f0",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -792,8 +792,8 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@astryxdesign/a11y-spec": "0.7.4-canary.626f01e",
-    "@astryxdesign/cli": "0.7.4-canary.626f01e",
+    "@astryxdesign/a11y-spec": "0.7.4-canary.768c2f0",
+    "@astryxdesign/cli": "0.7.4-canary.768c2f0",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -225,7 +225,10 @@ export const docs = {
       {className: 'astryx-command-palette-group'},
       {className: 'astryx-command-palette-group-heading'},
       {className: 'astryx-command-palette-input'},
-      {className: 'astryx-command-palette-item'},
+      {
+        className: 'astryx-command-palette-item',
+        states: ['highlighted', 'selected', 'disabled'],
+      },
       {className: 'astryx-command-palette-list'},
     ],
   },

package/src/CommandPalette/CommandPaletteItem.doc.mjs

@@ -21,7 +21,12 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use non-interactive child content such as icons, descriptions, and shortcut hints; activate the option itself instead of nesting buttons or links.',
+          'Inside CommandPalette, each item is an option in the listbox popup of the WAI-ARIA combobox pattern: keyboard focus stays in the query field, arrow keys move the highlight through aria-activedescendant, and Enter selects the highlighted item.',
+      },
+      {
+        guidance: false,
+        description:
+          'Nest buttons, links, or other interactive controls inside an item. Option semantics make descendants presentational, so use non-interactive content such as icons, descriptions, and shortcut hints, and activate the option itself.',
       },
       {
         guidance: false,
@@ -45,7 +50,12 @@ export const docs = {
     ],
   },
   theming: {
-    targets: [{className: 'astryx-command-palette-item'}],
+    targets: [
+      {
+        className: 'astryx-command-palette-item',
+        states: ['highlighted', 'selected', 'disabled'],
+      },
+    ],
   },
   props: [
     {
@@ -79,7 +89,7 @@ export const docs = {
       name: 'isSelected',
       type: 'boolean',
       description:
-        'Whether this item represents the selected value in picker mode.',
+        'Whether this item represents the selected value in picker mode. Derived from the CommandPalette value when omitted inside CommandPalette.',
       default: 'false',
     },
     {
@@ -117,7 +127,8 @@ export const docsZh = {
       '通过指针激活此条目后调用。CommandPalette 中的键盘选择通过根组件的 onValueChange 报告。',
     isHighlighted:
       '此条目是否为当前键盘结果。在 CommandPalette 内省略时从上下文派生。',
-    isSelected: '此条目是否代表选择器模式中的已选值。',
+    isSelected:
+      '此条目是否代表选择器模式中的已选值。在 CommandPalette 内省略时从面板的值派生。',
     isDisabled: '条目是否不可用并禁止指针激活。',
     xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',
   },
@@ -135,7 +146,8 @@ export const docsDense = {
     onSelect:
       'called after pointer activation; palette keyboard selection uses root onValueChange',
     isHighlighted: 'active keyboard result; derived from context when omitted',
-    isSelected: 'selected value in picker mode',
+    isSelected:
+      'selected value in picker mode; derived from palette value when omitted',
     isDisabled: 'unavailable; suppresses pointer activation',
     xstyle: 'StyleX layout styles; must be stylex.create() value',
   },

package/src/CommandPalette/CommandPaletteItem.test.tsx

@@ -195,17 +195,6 @@ describe('CommandPaletteItem', () => {
     expect(item).toHaveAttribute('aria-selected', 'true');
   });
 
-  it('paints context-derived highlight when the item is not selected', () => {
-    renderWithContext(
-      <CommandPaletteItem value="test">Item</CommandPaletteItem>,
-      {highlightedIndex: 0},
-    );
-
-    expect(getComputedStyle(screen.getByRole('option')).backgroundColor).toBe(
-      'var(--color-overlay-hover)',
-    );
-  });
-
   it('lets explicit visual state override context-derived state', () => {
     renderWithContext(
       <CommandPaletteItem value="test" isHighlighted={false} isSelected={false}>
@@ -216,7 +205,8 @@ describe('CommandPaletteItem', () => {
 
     const item = screen.getByRole('option');
     expect(item).toHaveAttribute('aria-selected', 'false');
-    expect(getComputedStyle(item).backgroundColor).toBe('rgba(0, 0, 0, 0)');
+    expect(item).not.toHaveAttribute('data-selected');
+    expect(item).not.toHaveAttribute('data-highlighted');
   });
 
   it('protects owned option semantics from native passthrough props', () => {
@@ -354,6 +344,69 @@ describe('CommandPaletteItem', () => {
     expect(item).toHaveStyle({marginBlockStart: '8px'});
   });
 
+  it('reflects selected and disabled state on its theme target', () => {
+    render(
+      <>
+        <CommandPaletteItem value="rest">Rest</CommandPaletteItem>
+        <CommandPaletteItem value="selected" isSelected>
+          Selected
+        </CommandPaletteItem>
+        <CommandPaletteItem value="disabled" isDisabled>
+          Disabled
+        </CommandPaletteItem>
+      </>,
+    );
+
+    const rest = screen.getByRole('option', {name: 'Rest'});
+    expect(rest).not.toHaveAttribute('data-selected');
+    expect(rest).not.toHaveAttribute('data-disabled');
+    expect(screen.getByRole('option', {name: 'Selected'})).toHaveAttribute(
+      'data-selected',
+      'selected',
+    );
+    expect(screen.getByRole('option', {name: 'Disabled'})).toHaveAttribute(
+      'data-disabled',
+      'disabled',
+    );
+  });
+
+  it('reflects context-derived selection on its theme target', () => {
+    renderWithContext(
+      <CommandPaletteItem value="test">Item</CommandPaletteItem>,
+      {value: 'test'},
+    );
+
+    expect(screen.getByRole('option')).toHaveAttribute(
+      'data-selected',
+      'selected',
+    );
+  });
+
+  it('reflects explicit and context-derived highlight on its theme target', () => {
+    renderWithContext(
+      <>
+        <CommandPaletteItem value="test">
+          Context highlighted
+        </CommandPaletteItem>
+        <CommandPaletteItem value="other" isHighlighted>
+          Explicitly highlighted
+        </CommandPaletteItem>
+        <CommandPaletteItem value="rest">Rest</CommandPaletteItem>
+      </>,
+      {highlightedIndex: 0},
+    );
+
+    expect(
+      screen.getByRole('option', {name: 'Context highlighted'}),
+    ).toHaveAttribute('data-highlighted', 'highlighted');
+    expect(
+      screen.getByRole('option', {name: 'Explicitly highlighted'}),
+    ).toHaveAttribute('data-highlighted', 'highlighted');
+    expect(screen.getByRole('option', {name: 'Rest'})).not.toHaveAttribute(
+      'data-highlighted',
+    );
+  });
+
   it('sets data-value attribute', () => {
     render(<CommandPaletteItem value="my-value">Item</CommandPaletteItem>);
     expect(screen.getByRole('option')).toHaveAttribute(

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -88,6 +88,7 @@ export interface CommandPaletteItemProps extends Omit<
   isHighlighted?: boolean;
   /**
    * Whether this item is currently selected (picker mode).
+   * When omitted inside CommandPalette, derived from the palette value.
    * @default false
    */
   isSelected?: boolean;
@@ -202,7 +203,11 @@ export function CommandPaletteItem({
       }
       onMouseEnter={onMouseEnterProp}
       {...mergeProps(
-        themeProps('command-palette-item'),
+        themeProps('command-palette-item', {
+          highlighted: isHighlighted ? 'highlighted' : null,
+          selected: isSelected ? 'selected' : null,
+          disabled: isDisabled ? 'disabled' : null,
+        }),
         stylex.props(
           styles.item,
           !isDisabled && interactionOverlayStyles.backgroundColor,

package/src/CommandPalette/__tests__/CommandPaletteItemAudit.a11y.chromium.spec.ts

@@ -2,7 +2,9 @@
 
 /**
  * @file CommandPaletteItemAudit.a11y.chromium.spec.ts
- * @input Exact-head CommandPaletteItem stories across semantics, states, themes, direction, and viewport sizes
+ * @input Exact-head CommandPaletteItem stories, plus the inline grouped palette in
+ *   the CommandPalette audit matrix, across states, themes, direction, pointers,
+ *   and viewport sizes
  * @output Screenshots and fail-closed sensor receipts for the CommandPaletteItem whole-component audit
  * @position Component-owned Night Watch browser evidence; CI runs it only for a CommandPaletteItem audit pull request
  */
@@ -11,7 +13,13 @@ import {createHash} from 'node:crypto';
 import {execFileSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {expect, test, type Page} from '@playwright/test';
+import {
+  expect,
+  test,
+  type CDPSession,
+  type Locator,
+  type Page,
+} from '@playwright/test';
 import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';
 import {
   DEFAULT_STORYBOOK_DIR,
@@ -26,8 +34,17 @@ const NARROW = {width: 320, height: 720};
 type Mode = 'light' | 'dark';
 type Direction = 'ltr' | 'rtl';
 type Theme = 'neutral' | 'butter';
-type Story = 'states' | 'combined-and-long';
-type State = 'rest' | 'hover';
+type Pointer = 'fine' | 'coarse';
+type Story = 'states' | 'combined-and-long' | 'palette';
+type State =
+  | 'rest'
+  | 'hover'
+  | 'pressed'
+  | 'pressed-highlighted'
+  | 'disabled-hover'
+  | 'touch-press'
+  | 'keyboard-highlight'
+  | 'keyboard-selected-highlight';
 
 type AuditCase = {
   key: string;
@@ -36,6 +53,8 @@ type AuditCase = {
   direction: Direction;
   theme: Theme;
   state: State;
+  pointer: Pointer;
+  forcedColors: boolean;
   viewport: {width: number; height: number};
 };
 
@@ -57,6 +76,8 @@ function addPair(
       direction: options.direction ?? 'ltr',
       theme: options.theme ?? 'neutral',
       state: options.state ?? 'rest',
+      pointer: options.pointer ?? 'fine',
+      forcedColors: options.forcedColors ?? false,
       viewport: options.viewport ?? WIDE,
     });
   }
@@ -64,9 +85,19 @@ function addPair(
 
 addPair('states-rest');
 addPair('states-hover', {state: 'hover'});
+addPair('states-pressed', {state: 'pressed'});
+addPair('states-pressed-highlighted', {state: 'pressed-highlighted'});
+addPair('states-disabled-hover', {state: 'disabled-hover'});
 addPair('states-custom-theme', {theme: 'butter'});
 addPair('states-rtl', {direction: 'rtl'});
 addPair('states-narrow', {viewport: NARROW});
+addPair('states-coarse', {viewport: NARROW, pointer: 'coarse'});
+addPair('states-touch-press', {
+  viewport: NARROW,
+  pointer: 'coarse',
+  state: 'touch-press',
+});
+addPair('states-forced-colors', {forcedColors: true});
 addPair('combined-rest', {story: 'combined-and-long'});
 addPair('combined-custom-theme', {
   story: 'combined-and-long',
@@ -76,6 +107,45 @@ addPair('combined-narrow', {
   story: 'combined-and-long',
   viewport: NARROW,
 });
+addPair('palette-keyboard-highlight', {
+  story: 'palette',
+  state: 'keyboard-highlight',
+});
+addPair('palette-keyboard-selected-highlight', {
+  story: 'palette',
+  state: 'keyboard-selected-highlight',
+});
+addPair('palette-keyboard-selected-highlight-custom-theme', {
+  story: 'palette',
+  state: 'keyboard-selected-highlight',
+  theme: 'butter',
+});
+
+addPair('palette-keyboard-highlight-forced-colors', {
+  story: 'palette',
+  state: 'keyboard-highlight',
+  forcedColors: true,
+});
+addPair('palette-keyboard-selected-highlight-forced-colors', {
+  story: 'palette',
+  state: 'keyboard-selected-highlight',
+  forcedColors: true,
+});
+
+/** Option each pointer state acts on, by its accessible text. */
+const POINTER_TARGET: Partial<Record<State, string>> = {
+  hover: 'Open file',
+  pressed: 'Open file',
+  'pressed-highlighted': 'Search files',
+  'disabled-hover': 'Archived command',
+  'touch-press': 'Open file',
+};
+
+/** Option the palette keyboard states move the active descendant to. */
+const KEYBOARD_TARGET: Partial<Record<State, string>> = {
+  'keyboard-highlight': 'Home',
+  'keyboard-selected-highlight': 'Settings',
+};
 
 test.describe.configure({mode: 'serial', retries: 0});
 let server: StaticServer;
@@ -83,7 +153,9 @@ let checkoutSha: string;
 let storybookSha: string;
 
 function storyId(item: AuditCase) {
-  return `core-commandpaletteitem--${item.story}`;
+  return item.story === 'palette'
+    ? 'core-commandpalette--audit-matrix'
+    : `core-commandpaletteitem--${item.story}`;
 }
 
 function storyUrl(item: AuditCase) {
@@ -96,6 +168,38 @@ async function settle(page: Page) {
   await page.waitForTimeout(40);
 }
 
+async function centerOf(locator: Locator) {
+  const box = await locator.boundingBox();
+  if (box == null) {
+    throw new Error('target option has no rendered bounds');
+  }
+  return {x: box.x + box.width / 2, y: box.y + box.height / 2};
+}
+
+async function highlightedName(input: Locator) {
+  return input.evaluate(element => {
+    const id = element.getAttribute('aria-activedescendant');
+    const option = id ? document.getElementById(id) : null;
+    return option?.textContent?.replace(/\s+/g, ' ').trim() ?? null;
+  });
+}
+
+/** PageUp moves the palette to its first result; ArrowDown walks forward. */
+async function highlightFromKeyboard(
+  page: Page,
+  input: Locator,
+  target: string,
+) {
+  await input.focus();
+  await page.keyboard.press('PageUp');
+  for (let step = 0; step < 4; step++) {
+    if ((await highlightedName(input)) === target) {
+      return;
+    }
+    await page.keyboard.press('ArrowDown');
+  }
+}
+
 test.beforeAll(async () => {
   fs.rmSync(OUTPUT, {recursive: true, force: true});
   fs.mkdirSync(OUTPUT, {recursive: true});
@@ -133,6 +237,8 @@ for (const item of cases) {
       viewport: item.viewport,
       colorScheme: item.mode,
       reducedMotion: 'reduce',
+      hasTouch: item.pointer === 'coarse',
+      forcedColors: item.forcedColors ? 'active' : 'none',
     });
     const page = await context.newPage();
     const pageErrors: string[] = [];
@@ -140,13 +246,20 @@ for (const item of cases) {
     await page.goto(storyUrl(item), {waitUntil: 'load'});
     await page.locator('#storybook-root').waitFor();
 
-    const listName =
-      item.story === 'states'
-        ? 'Command item states'
-        : 'Combined and long command item states';
-    const list = page.getByRole('listbox', {name: listName});
+    const isPalette = item.story === 'palette';
+    const subject = isPalette
+      ? page.getByRole('region', {name: 'Grouped command palette'})
+      : page.locator('#storybook-root');
+    const list = isPalette
+      ? subject.getByRole('listbox')
+      : subject.getByRole('listbox', {
+          name:
+            item.story === 'states'
+              ? 'Command item states'
+              : 'Combined and long command item states',
+        });
     const options = list.getByRole('option');
-    const expectedCount = item.story === 'states' ? 4 : 2;
+    const expectedCount = item.story === 'combined-and-long' ? 2 : 4;
     const expectedDisabled = item.story === 'states' ? 1 : 0;
     await expect(list).toBeVisible();
     await expect(options).toHaveCount(expectedCount);
@@ -156,12 +269,51 @@ for (const item of cases) {
     await expect(
       list.locator('[role="option"][aria-disabled="true"]'),
     ).toHaveCount(expectedDisabled);
-    await expect(list.locator('button, a, [tabindex]')).toHaveCount(0);
+    await expect(
+      list.locator('[role="option"] :is(button, a, [tabindex])'),
+    ).toHaveCount(0);
+
+    const pointerTarget = POINTER_TARGET[item.state];
+    const keyboardTarget = KEYBOARD_TARGET[item.state];
+    const target = pointerTarget ?? keyboardTarget ?? null;
+    const targetOption =
+      target == null ? null : options.filter({hasText: target}).first();
+    let cdp: CDPSession | null = null;
 
-    if (item.state === 'hover') {
-      await options.first().hover();
-    }
     await settle(page);
+    if (item.state === 'hover' || item.state === 'disabled-hover') {
+      await targetOption?.hover();
+    } else if (
+      item.state === 'pressed' ||
+      item.state === 'pressed-highlighted'
+    ) {
+      if (targetOption == null) {
+        throw new Error(`${item.key}: no press target`);
+      }
+      await targetOption.hover();
+      await page.mouse.down();
+    } else if (item.state === 'touch-press') {
+      if (targetOption == null) {
+        throw new Error(`${item.key}: no touch target`);
+      }
+      const point = await centerOf(targetOption);
+      cdp = await context.newCDPSession(page);
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchStart',
+        touchPoints: [{x: point.x, y: point.y, id: 1}],
+      });
+      // The touch press controller believes a stationary press after its
+      // onset delay; hold past it before reading the painted state.
+      await page.waitForTimeout(320);
+    } else if (keyboardTarget != null) {
+      await highlightFromKeyboard(
+        page,
+        subject.getByRole('combobox'),
+        keyboardTarget,
+      );
+    }
+    await page.evaluate(async () => document.fonts.ready);
+    await page.waitForTimeout(40);
 
     const observed = await page.evaluate(() => ({
       theme: document
@@ -173,20 +325,41 @@ for (const item of cases) {
       ).direction,
       viewport: {width: innerWidth, height: innerHeight},
       reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+      coarsePointer: matchMedia('(pointer: coarse)').matches,
+      forcedColors: matchMedia('(forced-colors: active)').matches,
       horizontalOverflow: document.documentElement.scrollWidth > innerWidth + 1,
       fonts: document.fonts.status,
     }));
+    const listBackdrop = await list.evaluate(element => {
+      let node: Element | null = element;
+      while (node) {
+        const color = getComputedStyle(node).backgroundColor;
+        if (color !== 'rgba(0, 0, 0, 0)' && color !== 'transparent') {
+          return color;
+        }
+        node = node.parentElement;
+      }
+      return getComputedStyle(document.body).backgroundColor;
+    });
     const optionStates = await options.evaluateAll(nodes =>
       nodes.map(node => {
         const style = getComputedStyle(node);
         const box = node.getBoundingClientRect();
         return {
           name: node.textContent?.replace(/\s+/g, ' ').trim(),
+          id: node.id || null,
           selected: node.getAttribute('aria-selected'),
           disabled: node.getAttribute('aria-disabled'),
+          themeSelected: node.getAttribute('data-selected'),
+          themeDisabled: node.getAttribute('data-disabled'),
+          active: node.matches(':active'),
+          hovered: node.matches(':hover'),
+          press: node.getAttribute('data-astryx-press'),
           backgroundColor: style.backgroundColor,
+          backgroundImage: style.backgroundImage,
           color: style.color,
           opacity: style.opacity,
+          cursor: style.cursor,
           geometry: {
             x: box.x,
             y: box.y,
@@ -196,6 +369,18 @@ for (const item of cases) {
         };
       }),
     );
+    const combobox = isPalette
+      ? await subject.getByRole('combobox').evaluate(element => ({
+          focused: element === document.activeElement,
+          activeDescendant: element.getAttribute('aria-activedescendant'),
+        }))
+      : null;
+
+    const targetState =
+      target == null
+        ? null
+        : (optionStates.find(option => option.name?.startsWith(target)) ??
+          null);
     const semanticsPass =
       optionStates.length === expectedCount &&
       optionStates.filter(option => option.selected === 'true').length === 1 &&
@@ -204,11 +389,48 @@ for (const item of cases) {
       optionStates.every(
         option => option.geometry.width > 0 && option.geometry.height > 0,
       );
+    let statePass = true;
+    if (item.state === 'hover') {
+      statePass = targetState?.hovered === true;
+    } else if (item.state === 'disabled-hover') {
+      statePass =
+        targetState?.hovered === true &&
+        targetState.disabled === 'true' &&
+        targetState.backgroundColor === 'rgba(0, 0, 0, 0)' &&
+        targetState.cursor === 'default';
+    } else if (
+      item.state === 'pressed' ||
+      item.state === 'pressed-highlighted'
+    ) {
+      statePass = targetState?.active === true;
+    } else if (item.state === 'touch-press') {
+      statePass = targetState?.press === 'on';
+    } else if (keyboardTarget != null) {
+      statePass =
+        combobox?.focused === true &&
+        targetState?.id != null &&
+        combobox.activeDescendant === targetState.id &&
+        (item.state === 'keyboard-selected-highlight'
+          ? targetState.selected === 'true'
+          : targetState.selected === 'false');
+    }
+
+    const png = isPalette
+      ? await subject.screenshot({animations: 'disabled'})
+      : await page.screenshot({animations: 'disabled', fullPage: true});
+    if (item.state === 'pressed' || item.state === 'pressed-highlighted') {
+      await page.mouse.up();
+    }
+    if (cdp != null) {
+      await cdp.send('Input.dispatchTouchEvent', {
+        type: 'touchEnd',
+        touchPoints: [],
+      });
+    }
 
-    const png = await page.screenshot({animations: 'disabled', fullPage: true});
     const image = `${item.key}.png`;
     const receipt = {
-      schemaVersion: 1,
+      schemaVersion: 2,
       expected: {
         build: checkoutSha,
         storyId: storyId(item),
@@ -216,6 +438,9 @@ for (const item of cases) {
         direction: item.direction,
         theme: item.theme,
         state: item.state,
+        target,
+        pointer: item.pointer,
+        forcedColors: item.forcedColors,
         viewport: item.viewport,
         optionCount: expectedCount,
         disabledCount: expectedDisabled,
@@ -226,6 +451,8 @@ for (const item of cases) {
         ...observed,
         listRole: await list.getAttribute('role'),
         listName: await list.getAttribute('aria-label'),
+        listBackdrop,
+        combobox,
         optionStates,
         pageErrors,
       },
@@ -235,7 +462,7 @@ for (const item of cases) {
         width: png.readUInt32BE(16),
         height: png.readUInt32BE(20),
       },
-      checks: {semanticsPass},
+      checks: {semanticsPass, statePass},
       passed:
         storybookSha === checkoutSha &&
         pageErrors.length === 0 &&
@@ -245,9 +472,12 @@ for (const item of cases) {
         observed.viewport.width === item.viewport.width &&
         observed.viewport.height === item.viewport.height &&
         observed.reducedMotion &&
+        observed.coarsePointer === (item.pointer === 'coarse') &&
+        observed.forcedColors === item.forcedColors &&
         !observed.horizontalOverflow &&
         observed.fonts === 'loaded' &&
-        semanticsPass,
+        semanticsPass &&
+        statePass,
     };
     fs.writeFileSync(path.join(OUTPUT, image), png);
     fs.writeFileSync(
@@ -270,7 +500,7 @@ test('manifest is complete', async () => {
       ) as AuditReceipt,
   );
   const manifest = {
-    schemaVersion: 1,
+    schemaVersion: 2,
     component: 'core/CommandPaletteItem',
     build: checkoutSha,
     frames: cases.map(item => ({

package/src/Overlay/Overlay.spec.md

@@ -0,0 +1,304 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Overlay
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-22
+owners: [cixzhang]
+review_triggers: [public-api, layout, accessibility]
+verified_by:
+  [
+    packages/core/src/Overlay/Overlay.test.tsx,
+    apps/storybook/stories/Overlay.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: [design:bidirectionality]
+architecture:
+  [
+    architecture:public-component-api,
+    architecture:component-theming-surface,
+    architecture:internationalization,
+  ]
+contributing: []
+system_specs: [spec:AST-002/DEC-1, spec:AST-017/FR5, spec:AST-027/FR2]
+---
+
+# Overlay component contract
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+This record governs how several pieces of content are placed over an Overlay's
+surface, each at a preset spot or at fractional coordinates, including the
+stacking of a container that holds such content. Overlay's scrim, reveal modes,
+own `position` values, and alignment remain described by its source, tests, and
+`Overlay.doc.mjs` until a record claims them.
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | New `OverlayRegion` component, exported beside Overlay: `position` (required) is a preset (`'fill' \| 'top' \| 'bottom' \| 'center' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end'`) or open placement `{x, y, width?, height?}` in 0–1 fractions; plus `children`, `ref`, `xstyle`, `className`, `style`. |
+| Behavior                | Inside a fill Overlay, a preset region sits at that spot (corners follow the writing direction) and open placement sits at fractions of the media measured from its top-left corner, never mirrored. A sized open region stays inside the media. Regions scale with the media.                                            |
+| End-user impact         | Several captions, tags, badges, or hotspots over one image or video each stay on their spot of the media at every size, in either text direction.                                                                                                                                                                         |
+| Builder impact          | None by default. A builder places content with `OverlayRegion` instead of hand-written absolute positioning; moving a region stays the builder's code.                                                                                                                                                                    |
+| Compatibility/readiness | Additive: a new component and export; an Overlay without a region renders and stacks exactly as before. This record is current authority; `OverlayRegion`, its consumer docs, region tests, and region stories have not shipped yet.                                                                                      |
+| Review checks           | Reject open placement that mirrors in right-to-left, corner presets that do not, JavaScript measurement or observers, drag or resize behavior inside Overlay, a role or focus stop on the region, a theme target on it, or a region placed inside a strip.                                                                |
+| Governing rules         | FR1–FR11 below; `design:bidirectionality/DR3`, `DR5`, `DR6`; `architecture:component-theming-surface/INV4`; `spec:AST-017/FR5`; `spec:AST-027/FR2`.                                                                                                                                                                       |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Overlay layers content over a bounded surface, usually media, and places that
+content as one block: the whole surface or a band at the top or bottom. Some
+surfaces carry several pieces of content, each belonging to its own spot: two
+captions drawn into an image, a badge in a corner beside a caption, a tag on a
+face. A spot is either one of Overlay's familiar places or a point on the media
+described as fractions of its width and height, because the media is shown at
+many sizes and the spot must stay on the same pixels of it. Overlay owns that
+placement because Overlay owns the surface it is measured against.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; an Overlay without a region renders and
+  stacks exactly as before. Only a container that holds a region isolates its
+  stacking (FR10).
+- Compatibility class: additive component and export.
+- Controlled/uncontrolled behavior: not applicable; a region holds no state.
+- Migration decision: none required (`spec:AST-017/FR5`).
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- `OverlayRegion`: its `position` values, their geometry, clamping, scaling, and
+  reference box.
+- The rule that open placement is measured in the media's own physical space.
+- The rule that regions are placed only in fill overlays, and the fallback
+  everywhere else.
+- The stacking isolation of a container that holds a region.
+
+**Does not own / non-goals**
+
+- Moving, dragging, or resizing a region, including pointer capture, keyboard
+  steps, snapping, and when a new position is reported — owned by the product
+  callsite (`component:Overlay/DEC-3`).
+- What a region paints: borders, fills, handles, and text — owned by the
+  region's content.
+- Making the base content fill the surface — owned by the caller, as for every
+  Overlay; fractions are measured against the surface, so media that does not
+  fill it does not line up with them.
+- Overlay's own `position` and `align` — unchanged; a region does not read or
+  alter them beyond FR2.
+- Placement relative to a trigger or outside the surface — owned by the layer
+  runtime (Popover, Tooltip, HoverCard).
+
+## Public concepts
+
+| Concept        | Closed values or states                                                                 | Meaning                                                                                                                                                                                                                             | Availability by variant/orientation/state | Default             | Owner               | Stability | Invalid-value behavior                                                                                  |
+| -------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
+| Preset         | `fill`, `top`, `bottom`, `center`, `top-start`, `top-end`, `bottom-start`, `bottom-end` | `fill`, `top`, and `bottom` are the places Overlay's own `position` names: the whole surface, or a full-width band at that edge. `center` and the corners hold content-sized boxes at that spot.                                    | Fill overlays (FR2)                       | None; required prop | `component:Overlay` | stable    | Other strings are rejected by the public type                                                           |
+| Open placement | `{x, y, width?, height?}`; each a number from 0 to 1                                    | `x`, `y`: the region's top-left corner as fractions of its reference box, measured from that box's top-left corner. `width`, `height`: the region's size as fractions, extending right and down; omitted means it fits its content. | Fill overlays (FR2)                       | None; required prop | `component:Overlay` | stable    | Values clamped into 0–1; a non-finite coordinate is treated as 0 and a non-finite size as omitted (FR6) |
+
+## Behavioral and layout contract
+
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                                       | Draft review state |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
+| FR1  | `OverlayRegion` rendered directly in the content of an Overlay or `useOverlay` host with `position="fill"`, the default, MUST position against that host's scrim box, which is the whole base surface: 0 and 1 are the media's edges, and the box matches the Overlay's `ref`. Any element between the region and the scrim that establishes a containing block for absolutely positioned descendants becomes its reference box instead. In this record, the surface means the region's reference box.                                                            | `component:Overlay/DEC-1`                                   | settled            |
+| FR2  | Regions are placed only in fill hosts. A region rendered anywhere else MUST NOT be placed: in the content of an Overlay or `useOverlay` host whose `position` is `"top"` or `"bottom"`, in an Overlay's `children`, or with no Overlay or `useOverlay` host at all, it renders its content as ordinary in-flow content where it stands (in a strip, that content reveals and slides with the strip) and MUST emit one development warning per mount naming the fill-only rule.                                                                                    | `component:Overlay/DEC-4`                                   | settled            |
+| FR3  | A preset region MUST sit at its spot inside Overlay's content inset: `fill` covers the inset box; `top` and `bottom` span its full width at that edge with content height; `center` is content-sized at its center; each corner is content-sized at that corner. Content larger than the inset box is clipped by the container, not shifted.                                                                                                                                                                                                                      | `component:Overlay/DEC-2`                                   | settled            |
+| FR4  | Corner presets MUST resolve `start` and `end` against the writing direction of the region's own context: `top-start` is the top-left corner in left-to-right and the top-right corner in right-to-left. `fill`, `top`, `bottom`, and `center` are symmetric and do not change with direction.                                                                                                                                                                                                                                                                     | `design:bidirectionality/DR3`                               | settled            |
+| FR5  | Open placement MUST measure `x` from the surface's left edge and `y` from its top edge in every writing direction, and MUST NOT mirror in right-to-left. The region's own content follows the ambient direction.                                                                                                                                                                                                                                                                                                                                                  | `design:bidirectionality/DR5`                               | settled            |
+| FR6  | Open coordinates and sizes MUST be clamped into 0–1 before placement. A non-finite coordinate MUST resolve to 0, and a non-finite size MUST resolve to omitted.                                                                                                                                                                                                                                                                                                                                                                                                   | Invalid-value behavior                                      | settled            |
+| FR7  | Open placement puts the region's top-left corner at (`x`, `y`) (`component:Overlay/DEC-6`). On an axis with a size, the region MUST be exactly that fraction of the surface, extending right or down, and MUST sit wholly inside it: its start is clamped between 0 and one minus the size. On an axis without a size, the region MUST fit its content starting at the coordinate, and any overhang past the container's edge is clipped, not shifted inward.                                                                                                     | `component:Overlay/DEC-5`                                   | settled            |
+| FR8  | When the surface changes size, every region MUST keep its spot: presets by their insets, open placement by its fractional position and size, without a re-render.                                                                                                                                                                                                                                                                                                                                                                                                 | `component:Overlay/DEC-1`                                   | settled            |
+| FR9  | A region MUST appear, hide, and become inert with the overlay content that contains it, following Overlay's `showOn` and `isOpen`, and MUST inherit the scrim's media theme. It adds no visibility rule of its own.                                                                                                                                                                                                                                                                                                                                               | Overlay's existing reveal behavior                          | settled            |
+| FR10 | A placed region MUST paint above the fill surface's in-flow overlay content, including positioned in-flow content written after it, and a later placed region MUST paint above an earlier one. A placed region inside a wrapper that forms a stacking context is ordered only among that wrapper's content. An Overlay or `useOverlay` container with a placed region anywhere inside it MUST own an isolated stacking context; a container with no region inside it keeps its stacking unchanged. A placed region MUST NOT take part in the scrim's flow layout. | Absolute positioning within the surface; `spec:AST-027/FR2` | settled            |
+| FR11 | Overlay and `OverlayRegion` MUST NOT move, drag, or resize a region, and MUST NOT attach pointer, keyboard, or gesture handlers to it. A region moves only when its caller passes a new `position`.                                                                                                                                                                                                                                                                                                                                                               | `component:Overlay/DEC-3`                                   | settled            |
+
+### Allowed variation
+
+- **AV1 — Content.** Any content may sit in a region; on an open region each
+  axis is sized or content-sized independently (FR7).
+- **AV2 — Surface size and shape.** The surface may be any size or aspect ratio,
+  and may change size at any time (FR8).
+- **AV3 — Mixed content.** In-flow overlay content, preset regions, and open
+  regions may share one surface (FR10).
+
+### Representative states
+
+| State                                                    | Required invariant                                                                                        | Allowed variation  |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------ |
+| Two captions, `top` and `bottom` presets                 | Each spans the inset width at its edge, like Overlay's own strips.                                        | Caption text.      |
+| `top-start` badge, left-to-right and right-to-left       | Top-left corner in left-to-right; top-right corner in right-to-left.                                      | Badge content.     |
+| Open sized caption near the right edge                   | Box is the given fraction of the image and stays wholly inside, flush with that edge.                     | Which edge.        |
+| Open content-sized pin                                   | Pin starts at its point and extends right and down; overhang past the container is clipped.               | Pin content.       |
+| Open region, right-to-left page                          | Same spot on the media as left-to-right; the region's text reads right-to-left.                           | Writing direction. |
+| Surface resized from 640px to 320px wide                 | Every region keeps its spot, with no re-render.                                                           | Any surface size.  |
+| Region in an Overlay's `children` or outside any Overlay | Is not placed: its content flows where it stands, and it warns once in development.                       | Location.          |
+| Region in a `position="bottom"` Overlay                  | Is not placed: its content flows in the strip like other strip content, and it warns once in development. | Strip content.     |
+| `showOn="hover"` overlay at rest                         | Regions are hidden with the rest of the overlay content.                                                  | Reveal mode.       |
+
+### Transformation and precedence order
+
+- **ORD1 — Placement.** Resolve the reference box (FR1, FR2) → for a preset,
+  place it in the content inset and resolve start/end against direction (FR3,
+  FR4); for open placement, clamp values (FR6) and resolve each axis as sized or
+  content-sized in physical space (FR5, FR7) → express the result as insets and
+  fractions of the box (FR8). Styling inputs compose after placement in the order
+  `architecture:public-component-api/INV6` gives; a caller who overrides inset or
+  size properties owns the result.
+
+### Performance and resources
+
+- **PR1 — CSS geometry only.** Placement, clamping, and scaling MUST be achieved
+  with arithmetic on the given values and CSS: no measurement, observer,
+  listener, state, Effect, or extra render pass. The fill-only check adds no
+  measurement, state, or extra render pass.
+
+## Accessibility contract
+
+- **AR1 — Presentation only.** `OverlayRegion` MUST add no role, accessible name,
+  description, focus stop, or text. Its content keeps its own semantics.
+- **AR2 — Source order is reading order.** Assistive technology and keyboard
+  focus follow the regions' source order, not their position on the surface. A
+  caller renders regions in the order a reader should meet them.
+- **AR3 — Movement offers non-drag paths.** Overlay's documented move pattern
+  for open regions pairs pointer dragging with a single-pointer path that needs
+  no drag, where activating a spot on the media moves the region there, and a
+  keyboard path that moves a region whose content has focus by a fixed step per
+  arrow key, with arrow directions matching the visual axes
+  (`design:bidirectionality/DR6`).
+
+## Design relationships
+
+| Anatomy or state     | Design requirement                                           | Representation authority      | Hierarchy role | Component contract |
+| -------------------- | ------------------------------------------------------------ | ----------------------------- | -------------- | ------------------ |
+| Preset region        | Reads as Overlay's own places, with Overlay's content inset. | Owner direction               | Supporting     | FR3                |
+| Corner preset in RTL | Leading and trailing corners follow reading order.           | `design:bidirectionality/DR3` | Supporting     | FR4                |
+| Open region          | Stays on the same spot of the media at every size.           | Owner direction               | Supporting     | FR7, FR8           |
+| Open region in RTL   | Media is physical content and does not mirror.               | `design:bidirectionality/DR5` | Supporting     | FR5                |
+
+## Family and system relationships
+
+- `design:bidirectionality` owns direction behavior: FR4 applies DR3 to corner
+  presets, FR5 applies DR5 to open placement, and AR3 applies DR6 to movement.
+- `architecture:component-theming-surface/INV4` keeps a non-painting box out of
+  the theme surface: the region is a geometry-only box that paints nothing, so it
+  has no theme target and its content owns its paint.
+- `architecture:public-component-api` owns prop admission and styling-input
+  order; ORD1 applies INV6.
+- `spec:AST-027/FR2` puts the isolation boundary on the surface; FR10 makes the
+  Overlay or `useOverlay` container that holds a region that owner.
+- `spec:AST-017/FR5` classifies this as nonbreaking: it adds a new component,
+  changes no default, and a caller who never renders a region sees no change.
+
+## Verification map
+
+| Contract                      | Verification                                                         | Representative states                                                                                                                             | Mutation or failure expectation                                                                                                                                             | Audit section          |
+| ----------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR1, FR2, FR6, FR11           | `Overlay.test.tsx` region suite                                      | Region in Overlay and `useOverlay` content; in a `bottom` Overlay; outside any Overlay; out-of-range and non-finite input; pointer and key events | Unclamped values, a region outside the scrim, a placed region in a strip or a missing warning, or a region that moves on its own fails.                                     | `audit:Overlay/api`    |
+| FR3, FR4, FR5, FR7, FR8, FR10 | Real-Chromium assertions in the Overlay region story's play function | Every preset; open sized, edge-clamped, and content-sized; resized surface; RTL; a region before a positioned control                             | A region off its spot by more than 0.5px, a corner that does not flip or an open region that does, the in-flow control hit at a region's center, or wrong isolation, fails. | `audit:Overlay/layout` |
+| FR9                           | `Overlay.test.tsx` reveal case with a region                         | `isOpen={false}`                                                                                                                                  | A region outside the scrim, or a closed scrim that is not inert, fails.                                                                                                     | `audit:Overlay/api`    |
+| AR1, AR2                      | `Overlay.test.tsx` DOM check of the region element                   | Text content                                                                                                                                      | Any attribute other than `class` and `style` on the region element, or text it adds, fails.                                                                                 | `audit:Overlay/a11y`   |
+| AR3                           | Region move story's play function                                    | Arrow key and single activation on the media, LTR and RTL                                                                                         | ArrowRight moving a region left, or an activation that does not move the region to the activated spot, fails.                                                               | `audit:Overlay/a11y`   |
+| PR1                           | Source review of `OverlayRegion`                                     | All inputs                                                                                                                                        | A ref read, observer, listener, or Effect added for placement fails review.                                                                                                 | `audit:Overlay/layout` |
+
+## Decision log
+
+<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
+
+### DEC-1 — Several placed items are Overlay regions with one `position` prop
+
+**Reference:** `component:Overlay/DEC-1`
+**Decider:** cixzhang, 2026-10-22
+
+Overlay places one content block, so a surface with several spots needs a child
+that places itself. `OverlayRegion` inside Overlay's content inherits Overlay's
+surface, reveal, and media theme with no new Overlay prop, and one `position`
+prop covers both kinds of spot: a named place or open placement. Sizes live
+inside the open placement object, so a region never carries `width` or `height`
+props whose numbers mean fractions while the same names mean pixels on Card,
+Button, and Grid.
+
+Rejected: an object form of Overlay's own `position`, because it still places
+only one block.
+
+### DEC-2 — Presets reuse Overlay's places and add the center and corners
+
+**Reference:** `component:Overlay/DEC-2`
+**Decider:** cixzhang, 2026-10-22
+
+`fill`, `top`, and `bottom` mean on a region what they mean on Overlay, so a
+builder reads one vocabulary. Static badges and labels need the center and the
+corners, which Overlay's single block cannot hold beside other content. Corners
+use `start` and `end` because a leading badge leads in either direction.
+
+### DEC-3 — Moving a region stays at the callsite
+
+**Reference:** `component:Overlay/DEC-3`
+**Decider:** cixzhang, 2026-10-22
+
+What moving a region means differs by product: whether the position commits on
+release or live, the keyboard step, snapping, which regions move, and what
+happens while a new rendering of the media loads. Overlay therefore never moves
+a region; the caller converts pointer and keyboard input into new fractions
+measured against the region's reference box and passes them back.
+
+Rejected: a drag hook on Overlay, because a shared drag primitive needs its own
+record and more than one caller's needs.
+
+### DEC-4 — Regions belong to fill overlays
+
+**Reference:** `component:Overlay/DEC-4`
+**Decider:** cixzhang, 2026-10-22
+
+A spot on the media is meaningless inside a strip whose height follows its own
+content and which slides in and out. A strip is also the containing block of
+everything inside it, so CSS cannot place a region against the media from
+there. In a strip overlay a region therefore renders its content as ordinary
+strip content and warns in development, so the content stays visible. The
+public type cannot enforce the rule, because regions arrive through `content`.
+The same fallback applies outside any fill host, where there is no surface to
+measure against and nothing to isolate a region's paint order.
+
+Rejected: placing a strip's regions against the container, because escaping the
+strip needs a second rendering layer that duplicates Overlay's reveal.
+
+### DEC-5 — Open sized axes are clamped inside; content-sized axes are not
+
+**Reference:** `component:Overlay/DEC-5`
+**Decider:** cixzhang, 2026-10-22
+
+A sized region can be kept inside the surface with arithmetic on the given
+fractions, so it never spills off the media however far it is moved. Keeping a
+content-sized region inside would require measuring it, which PR1 forbids, so
+the container clips any overhang.
+
+### DEC-6 — Open placement names the region's top-left corner
+
+**Reference:** `component:Overlay/DEC-6`
+**Decider:** cixzhang, 2026-10-22
+
+`x` and `y` are the region's top-left corner, and `width` and `height` extend
+right and down. That matches how servers and editors report boxes (left, top,
+width, height) and how CSS insets read, so a reported box passes through with no
+conversion and is clamped with plain arithmetic.
+
+Rejected: the region's center, because every reported box would need converting.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.