@astryxdesign/core 0.7.2-canary.7462c41 → 0.7.2-canary.7ae39ea

package/dist/DropdownMenu/DropdownMenu.d.ts

@@ -1,6 +1,6 @@
 /**
  * @file DropdownMenu.tsx
- * @input Uses React, StyleX, usePopover, MenuBottomSheet, Button, List,
+ * @input Uses React, StyleX, usePopover, MenuBottomSheet (lazy), Button, List,
  *   useListFocus, and the shared viewport-safe menu-width resolver
  * @output Exports DropdownMenu with caller-selected popover or bottom-sheet
  *   presentation

package/dist/DropdownMenu/DropdownMenu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DropdownMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenu.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"DropdownMenu.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/DropdownMenu.tsx"],"names":[],"mappings":"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"}

package/dist/DropdownMenu/DropdownMenu.js

@@ -4,7 +4,7 @@
 
 /**
  * @file DropdownMenu.tsx
- * @input Uses React, StyleX, usePopover, MenuBottomSheet, Button, List,
+ * @input Uses React, StyleX, usePopover, MenuBottomSheet (lazy), Button, List,
  *   useListFocus, and the shared viewport-safe menu-width resolver
  * @output Exports DropdownMenu with caller-selected popover or bottom-sheet
  *   presentation
@@ -58,8 +58,8 @@ import { resolveMenuWidth } from "./menuWidth.js";
 import "../Layer/layerViewportInset.stylex.js";
 import { layerViewportInset } from "../Layer/layerViewportInset.stylex.js";
 import { useAdaptivePresentation } from "../hooks/useAdaptivePresentation.js";
-import { MenuBottomSheet } from "./MenuBottomSheet.js";
-import { MenuBottomSheetActionList } from "./MenuBottomSheetActionList.js";
+// Loaded on demand: only the bottom-sheet presentation renders the sheet.
+import { MenuBottomSheet, MenuBottomSheetActionList } from "./lazyMenuBottomSheet.js";
 import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
 import "../theme/tokens.stylex.js";
 import { spacingVars, colorVars, radiusVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
@@ -491,12 +491,41 @@ function DropdownMenuBottomSheet({
     if (!isOpen || openModalityRef.current !== 'keyboard') {
       return;
     }
-    const frame = requestAnimationFrame(() => {
-      actionListRef.current?.querySelector('button:not(:disabled), a[href]')?.focus({
-        preventScroll: true
+    const findFirstAction = () => actionListRef.current?.querySelector('button:not(:disabled), a[href]') ?? null;
+    let observer = null;
+    let frame = requestAnimationFrame(() => {
+      const action = findFirstAction();
+      if (action != null) {
+        action.focus({
+          preventScroll: true
+        });
+        return;
+      }
+      // The sheet loads on demand, so a keyboard open can arrive before its
+      // rows exist. Wait for them, then focus a frame later so the sheet's
+      // own open-focus has already run.
+      observer = new MutationObserver(() => {
+        const loaded = findFirstAction();
+        if (loaded == null) {
+          return;
+        }
+        observer?.disconnect();
+        observer = null;
+        frame = requestAnimationFrame(() => {
+          loaded.focus({
+            preventScroll: true
+          });
+        });
+      });
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true
       });
     });
-    return () => cancelAnimationFrame(frame);
+    return () => {
+      cancelAnimationFrame(frame);
+      observer?.disconnect();
+    };
   }, [currentItems, isOpen]);
   useEffect(() => {
     if (!isOpen) {

package/dist/DropdownMenu/lazyMenuBottomSheet.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @file lazyMenuBottomSheet.ts
+ * @input Uses React lazy and Suspense, useIsHydrating, MenuBottomSheet, and
+ *   MenuBottomSheetActionList
+ * @output Exports MenuBottomSheet and MenuBottomSheetActionList wrappers that
+ *   load the touch sheet on first render
+ * @position Internal to DropdownMenu
+ *
+ * The touch sheet (BottomSheet, its gestures, and the touch action list) only
+ * renders for the bottom-sheet presentation. Loading it on demand keeps it out
+ * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
+ * the wrapped component's props and renders nothing until its module loads.
+ *
+ * Neither wrapper renders on the server or in the render that hydrates server
+ * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
+ * leave server markup incomplete and abort hydration. The closed sheet has no
+ * visible markup, so it first renders right after hydration.
+ */
+import { type ComponentProps, type ReactElement } from 'react';
+import type { MenuBottomSheet as EagerMenuBottomSheet } from './MenuBottomSheet';
+import type { MenuBottomSheetActionList as EagerMenuBottomSheetActionList } from './MenuBottomSheetActionList';
+export declare function MenuBottomSheet(props: ComponentProps<typeof EagerMenuBottomSheet>): ReactElement | null;
+export declare function MenuBottomSheetActionList(props: ComponentProps<typeof EagerMenuBottomSheetActionList>): ReactElement | null;
+//# sourceMappingURL=lazyMenuBottomSheet.d.ts.map

package/dist/DropdownMenu/lazyMenuBottomSheet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazyMenuBottomSheet.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/lazyMenuBottomSheet.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,eAAe,IAAI,oBAAoB,EAAC,MAAM,mBAAmB,CAAC;AAC/E,OAAO,KAAK,EAAC,yBAAyB,IAAI,8BAA8B,EAAC,MAAM,6BAA6B,CAAC;AAc7G,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,CAAC,OAAO,oBAAoB,CAAC,GACjD,YAAY,GAAG,IAAI,CASrB;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,cAAc,CAAC,OAAO,8BAA8B,CAAC,GAC3D,YAAY,GAAG,IAAI,CASrB"}

package/dist/DropdownMenu/lazyMenuBottomSheet.js

@@ -0,0 +1,46 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file lazyMenuBottomSheet.ts
+ * @input Uses React lazy and Suspense, useIsHydrating, MenuBottomSheet, and
+ *   MenuBottomSheetActionList
+ * @output Exports MenuBottomSheet and MenuBottomSheetActionList wrappers that
+ *   load the touch sheet on first render
+ * @position Internal to DropdownMenu
+ *
+ * The touch sheet (BottomSheet, its gestures, and the touch action list) only
+ * renders for the bottom-sheet presentation. Loading it on demand keeps it out
+ * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
+ * the wrapped component's props and renders nothing until its module loads.
+ *
+ * Neither wrapper renders on the server or in the render that hydrates server
+ * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
+ * leave server markup incomplete and abort hydration. The closed sheet has no
+ * visible markup, so it first renders right after hydration.
+ */
+import { createElement, lazy, Suspense } from 'react';
+import { useIsHydrating } from "../hooks/useIsHydrating.js";
+const LazyMenuBottomSheet = /*#__PURE__*/lazy(async () => import("./MenuBottomSheet.js").then(module => ({
+  default: module.MenuBottomSheet
+})));
+const LazyMenuBottomSheetActionList = /*#__PURE__*/lazy(async () => import("./MenuBottomSheetActionList.js").then(module => ({
+  default: module.MenuBottomSheetActionList
+})));
+export function MenuBottomSheet(props) {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return /*#__PURE__*/createElement(Suspense, {
+    fallback: null
+  }, /*#__PURE__*/createElement(LazyMenuBottomSheet, props));
+}
+export function MenuBottomSheetActionList(props) {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return /*#__PURE__*/createElement(Suspense, {
+    fallback: null
+  }, /*#__PURE__*/createElement(LazyMenuBottomSheetActionList, props));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.7.2-canary.7462c41",
+  "version": "0.7.2-canary.7ae39ea",
   "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.2-canary.7462c41",
-    "@astryxdesign/cli": "0.7.2-canary.7462c41",
+    "@astryxdesign/a11y-spec": "0.7.2-canary.7ae39ea",
+    "@astryxdesign/cli": "0.7.2-canary.7ae39ea",
     "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
     "@babel/preset-react": "^7.29.7",

package/scripts/agent-doc-state.mjs

@@ -106,6 +106,44 @@ export function isAstryxInitialized(targetDir = process.cwd()) {
   return false;
 }
 
+/**
+ * Does an agent working in `startDir` already have the Astryx prompt in reach?
+ *
+ * Coding agents read the agent docs between the repository root and the folder
+ * they work in. So inside a git repository, init's block in any folder from
+ * `startDir` up to the repository root counts: a workspace package of a
+ * monorepo initialized at its root is set up. Outside a repository only
+ * `startDir` itself is checked, as {@link isAstryxInitialized} does. Both the
+ * per-command nudge and the postinstall nudges ask this.
+ *
+ * @param {string} [startDir=process.cwd()]
+ * @returns {boolean}
+ */
+export function isAstryxPromptInReach(startDir = process.cwd()) {
+  const start = path.resolve(startDir);
+  const repositoryRoot = findRepositoryRoot(start);
+  if (!repositoryRoot) return isAstryxInitialized(start);
+  for (let dir = start; ; dir = path.dirname(dir)) {
+    if (isAstryxInitialized(dir)) return true;
+    if (dir === repositoryRoot) return false;
+  }
+}
+
+/**
+ * The nearest folder at or above `start` that holds `.git` (a folder, or the
+ * file a worktree uses), or null outside a repository.
+ * @param {string} start
+ * @returns {string | null}
+ */
+function findRepositoryRoot(start) {
+  for (let dir = start; ; ) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 /**
  * The one-line next-step both postinstall nudges print. Kept here so layer 1
  * (core) and layer 2 (cli) can never word it differently.

package/scripts/postinstall.mjs

@@ -45,7 +45,7 @@ async function main() {
     contract.shouldNudge({
       scriptPath: HERE,
       npmCommand: process.env.npm_command,
-      isSetUp: contract.isAstryxInitialized(root),
+      isSetUp: contract.isAstryxPromptInReach(root),
     })
   ) {
     process.stdout.write(contract.SETUP_NUDGE);

package/src/Code/Code.doc.mjs

@@ -4,6 +4,7 @@
 export const docs = {
   name: 'Code',
   displayName: 'Code',
+  keywords: ['inlinecode', 'monospace'],
   group: 'Code',
   category: 'Content',
   description:

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -87,6 +87,8 @@ export const docs = {
     'modal',
     'dialog',
     'navigation',
+    'commandmenu',
+    'cmdk',
   ],
   description:
     'Root component. Manages open state, search, keyboard navigation, and composition slots.',

package/src/Drawer/Drawer.doc.mjs

@@ -55,6 +55,7 @@ export const docs = {
     'sidebar',
     'dialog',
     'side drawer',
+    'sidesheet',
   ],
   // No isInline docs-preview prop (the drawer has no inline containment), so
   // this is the overlay preview: closed on load with an open trigger, knobs

package/src/DropdownMenu/DropdownMenu.ssr.test.tsx

@@ -0,0 +1,57 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenu.ssr.test.tsx
+ * @input DropdownMenu server markup and React hydration
+ * @output Proves a bottom-sheet DropdownMenu hydrates without a recoverable
+ *   error while its on-demand sheet has not loaded (spec:AST-013 FR9)
+ * @position SSR acceptance test for DropdownMenu
+ */
+
+import {act} from 'react';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {hydrateRoot} from 'react-dom/client';
+import {renderToString} from 'react-dom/server';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.replaceChildren();
+});
+
+async function serverRenderThenHydrate(): Promise<unknown[]> {
+  // A fresh module graph is a fresh server process: the sheet has not loaded.
+  vi.resetModules();
+  const {DropdownMenu} = await import('./DropdownMenu');
+  const tree = (
+    <DropdownMenu
+      button={{label: 'Actions'}}
+      presentation="bottom-sheet"
+      items={[{label: 'Edit project'}, {label: 'Delete'}]}
+    />
+  );
+  const container = document.createElement('div');
+  container.innerHTML = renderToString(tree);
+  document.body.appendChild(container);
+
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+  const recoverableErrors: unknown[] = [];
+  let root!: ReturnType<typeof hydrateRoot>;
+  await act(async () => {
+    root = hydrateRoot(container, tree, {
+      onRecoverableError: error => recoverableErrors.push(error),
+    });
+  });
+  await act(async () => {
+    root.unmount();
+  });
+  container.remove();
+  return recoverableErrors;
+}
+
+describe('DropdownMenu — SSR', () => {
+  it('hydrates a bottom-sheet menu cleanly on the first renders of a server process', async () => {
+    expect(await serverRenderThenHydrate()).toEqual([]);
+    expect(await serverRenderThenHydrate()).toEqual([]);
+    expect(await serverRenderThenHydrate()).toEqual([]);
+  }, 30000);
+});

package/src/DropdownMenu/DropdownMenu.test.tsx

@@ -9,7 +9,15 @@
  * SYNC: When DropdownMenu.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {
+  describe,
+  it,
+  expect,
+  vi,
+  beforeAll,
+  beforeEach,
+  afterEach,
+} from 'vitest';
 import {readFileSync} from 'node:fs';
 import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
@@ -19,6 +27,7 @@ import {DropdownMenu, type DropdownMenuTriggerProps} from './DropdownMenu';
 import {DropdownMenuItem} from './DropdownMenuItem';
 import {DropdownMenuDivider} from './DropdownMenuDivider';
 import {DropdownMenuGroup} from './DropdownMenuGroup';
+import {warmMenuBottomSheet} from './__tests__/warmMenuBottomSheet';
 import {DropdownMenuSubMenu} from './DropdownMenuSubMenu';
 import {Divider} from '../Divider';
 import {rtlStyles} from '../utils';
@@ -74,6 +83,10 @@ beforeEach(() => {
   };
 });
 
+// The touch sheet is loaded lazily; resolve it once so sheets below render
+// synchronously.
+beforeAll(warmMenuBottomSheet, 20000);
+
 describe('DropdownMenu', () => {
   it('renders trigger button with label', () => {
     render(

package/src/DropdownMenu/DropdownMenu.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file DropdownMenu.tsx
- * @input Uses React, StyleX, usePopover, MenuBottomSheet, Button, List,
+ * @input Uses React, StyleX, usePopover, MenuBottomSheet (lazy), Button, List,
  *   useListFocus, and the shared viewport-safe menu-width resolver
  * @output Exports DropdownMenu with caller-selected popover or bottom-sheet
  *   presentation
@@ -81,8 +81,11 @@ import {
   useAdaptivePresentation,
   type AdaptivePresentation,
 } from '../hooks/useAdaptivePresentation';
-import {MenuBottomSheet} from './MenuBottomSheet';
-import {MenuBottomSheetActionList} from './MenuBottomSheetActionList';
+// Loaded on demand: only the bottom-sheet presentation renders the sheet.
+import {
+  MenuBottomSheet,
+  MenuBottomSheetActionList,
+} from './lazyMenuBottomSheet';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
 import {
@@ -759,12 +762,37 @@ function DropdownMenuBottomSheet({
     if (!isOpen || openModalityRef.current !== 'keyboard') {
       return;
     }
-    const frame = requestAnimationFrame(() => {
-      actionListRef.current
-        ?.querySelector<HTMLElement>('button:not(:disabled), a[href]')
-        ?.focus({preventScroll: true});
+    const findFirstAction = () =>
+      actionListRef.current?.querySelector<HTMLElement>(
+        'button:not(:disabled), a[href]',
+      ) ?? null;
+    let observer: MutationObserver | null = null;
+    let frame = requestAnimationFrame(() => {
+      const action = findFirstAction();
+      if (action != null) {
+        action.focus({preventScroll: true});
+        return;
+      }
+      // The sheet loads on demand, so a keyboard open can arrive before its
+      // rows exist. Wait for them, then focus a frame later so the sheet's
+      // own open-focus has already run.
+      observer = new MutationObserver(() => {
+        const loaded = findFirstAction();
+        if (loaded == null) {
+          return;
+        }
+        observer?.disconnect();
+        observer = null;
+        frame = requestAnimationFrame(() => {
+          loaded.focus({preventScroll: true});
+        });
+      });
+      observer.observe(document.body, {childList: true, subtree: true});
     });
-    return () => cancelAnimationFrame(frame);
+    return () => {
+      cancelAnimationFrame(frame);
+      observer?.disconnect();
+    };
   }, [currentItems, isOpen]);
 
   useEffect(() => {

package/src/DropdownMenu/DropdownMenuLazySheet.test.tsx

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file DropdownMenuLazySheet.test.tsx
+ * @input Uses DropdownMenu, Testing Library, and a held module load
+ * @output Tests DropdownMenu while its on-demand touch sheet is still loading
+ * @position Test file for DropdownMenu
+ *
+ * This file never warms the sheet, and it checks that a popover menu never
+ * requests it: each test holds the sheet modules until it
+ * releases them, so it exercises the path a real page takes while the sheet's
+ * code is still downloading.
+ */
+
+import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
+import {render, screen, waitFor, act} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type {DropdownMenu as DropdownMenuComponent} from './DropdownMenu';
+
+const sheetLoad = vi.hoisted(() => {
+  let release: () => void = () => {};
+  const gate = new Promise<void>(resolve => {
+    release = resolve;
+  });
+  return {gate, release: () => release(), requested: [] as string[]};
+});
+
+vi.mock('./MenuBottomSheet', async importOriginal => {
+  sheetLoad.requested.push('MenuBottomSheet');
+  await sheetLoad.gate;
+  return importOriginal();
+});
+
+vi.mock('./MenuBottomSheetActionList', async importOriginal => {
+  sheetLoad.requested.push('MenuBottomSheetActionList');
+  await sheetLoad.gate;
+  return importOriginal();
+});
+
+let DropdownMenu: typeof DropdownMenuComponent;
+
+// If any module the dropdown loads imported the sheet eagerly, this import
+// would wait on the held sheet and the hook would time out.
+beforeAll(async () => {
+  ({DropdownMenu} = await import('./DropdownMenu'));
+}, 10000);
+
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+  vi.stubGlobal(
+    'matchMedia',
+    vi.fn().mockImplementation((query: string) => ({
+      matches: false,
+      media: query,
+      onchange: null,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  );
+});
+
+describe('DropdownMenu touch sheet loaded on demand', () => {
+  // Runs first: nothing in this file has rendered a sheet yet.
+  it('never loads the sheet for a popover menu', async () => {
+    const user = userEvent.setup();
+    HTMLElement.prototype.showPopover = vi.fn();
+    HTMLElement.prototype.hidePopover = vi.fn();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        items={[{label: 'Edit project'}, {label: 'Delete'}]}
+      />,
+    );
+
+    await user.click(screen.getByRole('button', {name: /Actions/}));
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    });
+
+    // Importing DropdownMenu and opening a popover menu requested neither
+    // sheet module, so no other module the dropdown loads imports it eagerly.
+    expect(sheetLoad.requested).toEqual([]);
+  });
+
+  it('focuses the first action when a keyboard open beats the sheet load', async () => {
+    const user = userEvent.setup();
+    render(
+      <DropdownMenu
+        button={{label: 'Actions'}}
+        presentation="bottom-sheet"
+        items={[{label: 'Edit project'}, {label: 'Delete'}]}
+      />,
+    );
+
+    const trigger = screen.getByRole('button', {name: /Actions/});
+    trigger.focus();
+    await user.keyboard('{Enter}');
+    // The open has committed, but the sheet's code has not arrived yet.
+    await act(async () => {
+      await new Promise(resolve => setTimeout(resolve, 50));
+    });
+    expect(screen.queryByRole('button', {name: 'Edit project'})).toBeNull();
+
+    await act(async () => {
+      sheetLoad.release();
+    });
+
+    await waitFor(
+      () =>
+        expect(
+          screen.getByRole('button', {name: 'Edit project'}),
+        ).toHaveFocus(),
+      {timeout: 15000},
+    );
+  }, 20000);
+});

package/src/DropdownMenu/__tests__/warmMenuBottomSheet.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file warmMenuBottomSheet.tsx
+ * @input Uses DropdownMenu and Testing Library
+ * @output Exports warmMenuBottomSheet, a test helper that resolves the lazily
+ *   loaded touch sheet once
+ * @position Test-only helper for suites that open a DropdownMenu bottom sheet
+ *
+ * DropdownMenu loads its touch sheet with React.lazy, so the first sheet
+ * renders a tick after it opens. Opening one up front caches the resolved
+ * modules on the lazy components, and every later sheet renders
+ * synchronously. Call it from `beforeAll`.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {DropdownMenu} from '../DropdownMenu';
+
+export async function warmMenuBottomSheet(): Promise<void> {
+  const {showModal, close} = HTMLDialogElement.prototype;
+  HTMLDialogElement.prototype.showModal = function (this: HTMLDialogElement) {
+    this.setAttribute('open', '');
+  };
+  HTMLDialogElement.prototype.close = function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  };
+  try {
+    render(
+      <DropdownMenu
+        button={{label: 'Warm'}}
+        presentation="bottom-sheet"
+        isMenuOpen
+        items={[{label: 'Warm item'}]}
+      />,
+    );
+    // A cold import transforms the sheet's module graph; allow for it.
+    await screen.findByText('Warm item', undefined, {timeout: 15000});
+  } finally {
+    cleanup();
+    HTMLDialogElement.prototype.showModal = showModal;
+    HTMLDialogElement.prototype.close = close;
+  }
+}

package/src/DropdownMenu/lazyMenuBottomSheet.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file lazyMenuBottomSheet.ts
+ * @input Uses React lazy and Suspense, useIsHydrating, MenuBottomSheet, and
+ *   MenuBottomSheetActionList
+ * @output Exports MenuBottomSheet and MenuBottomSheetActionList wrappers that
+ *   load the touch sheet on first render
+ * @position Internal to DropdownMenu
+ *
+ * The touch sheet (BottomSheet, its gestures, and the touch action list) only
+ * renders for the bottom-sheet presentation. Loading it on demand keeps it out
+ * of pages whose dropdowns only open as anchored popovers. Each wrapper keeps
+ * the wrapped component's props and renders nothing until its module loads.
+ *
+ * Neither wrapper renders on the server or in the render that hydrates server
+ * HTML (spec:AST-013 FR9): a lazy component that has not loaded yet would
+ * leave server markup incomplete and abort hydration. The closed sheet has no
+ * visible markup, so it first renders right after hydration.
+ */
+
+import {
+  createElement,
+  lazy,
+  Suspense,
+  type ComponentProps,
+  type ReactElement,
+} from 'react';
+import {useIsHydrating} from '../hooks/useIsHydrating';
+import type {MenuBottomSheet as EagerMenuBottomSheet} from './MenuBottomSheet';
+import type {MenuBottomSheetActionList as EagerMenuBottomSheetActionList} from './MenuBottomSheetActionList';
+
+const LazyMenuBottomSheet = lazy(async () =>
+  import('./MenuBottomSheet').then(module => ({
+    default: module.MenuBottomSheet,
+  })),
+);
+
+const LazyMenuBottomSheetActionList = lazy(async () =>
+  import('./MenuBottomSheetActionList').then(module => ({
+    default: module.MenuBottomSheetActionList,
+  })),
+);
+
+export function MenuBottomSheet(
+  props: ComponentProps<typeof EagerMenuBottomSheet>,
+): ReactElement | null {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return createElement(
+    Suspense,
+    {fallback: null},
+    createElement(LazyMenuBottomSheet, props),
+  );
+}
+
+export function MenuBottomSheetActionList(
+  props: ComponentProps<typeof EagerMenuBottomSheetActionList>,
+): ReactElement | null {
+  if (useIsHydrating()) {
+    return null;
+  }
+  return createElement(
+    Suspense,
+    {fallback: null},
+    createElement(LazyMenuBottomSheetActionList, props),
+  );
+}

package/src/Icon/Icon.doc.mjs

@@ -23,6 +23,42 @@ export const docs = {
     'pictogram',
     'graphic',
     'vector',
+    'arrow',
+    'chevron',
+    'caret',
+    'checkmark',
+    'cross',
+    'gear',
+    'cog',
+    'broom',
+    'sparkle',
+    'sparkles',
+    'star',
+    'heart',
+    'bell',
+    'trash',
+    'pencil',
+    'magnifyingglass',
+    'paperclip',
+    'house',
+    'flame',
+    'rocket',
+    'lightning',
+    'bolt',
+    'globe',
+    'sun',
+    'moon',
+    'bookmark',
+    'thumbsup',
+    'smiley',
+    'emoji',
+    'lock',
+    'eye',
+    'cloud',
+    'hourglass',
+    'trophy',
+    'gift',
+    'camera',
   ],
   playground: {
     // `icon` is required and its type can't be auto-generated, so the

package/src/Layout/LayoutHeader.doc.mjs

@@ -6,6 +6,11 @@ export const docs = {
   name: 'LayoutHeader',
   subComponentOf: 'Layout',
   displayName: 'Layout Header',
+  keywords: [
+    'pageheader',
+    'appheader',
+    'header',
+  ],
   isHiddenFromOverview: true,
   description: 'Top bar for page titles, app bars, and toolbars.',
   playground: {

package/src/MetadataList/MetadataList.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   displayName: 'Metadata List',
   group: 'MetadataList',
   category: 'Table & List',
-  keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary"],
+  keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary","descriptionlist","descriptions"],
   theming: {
     targets: [
       {

package/src/MoreMenu/MoreMenu.test.tsx

@@ -9,11 +9,15 @@
  * SYNC: When MoreMenu.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeAll, beforeEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MoreMenu} from './MoreMenu';
 import {DropdownMenu} from '../DropdownMenu/DropdownMenu';
+import {warmMenuBottomSheet} from '../DropdownMenu/__tests__/warmMenuBottomSheet';
+
+// DropdownMenu's touch sheet is loaded lazily; resolve it once up front.
+beforeAll(warmMenuBottomSheet, 20000);
 
 // Mock showPopover and hidePopover methods since they're not implemented in jsdom
 beforeEach(() => {

package/src/ProgressBar/ProgressBar.doc.mjs

@@ -53,6 +53,7 @@ export const docs = {
     'determinate',
     'indeterminate',
     'meter',
+    'linearprogress',
   ],
   props: [
     {

package/src/Resizable/useResizable.doc.mjs

@@ -14,6 +14,8 @@ export const docs = {
     'sidebar',
     'divider',
     'splitter',
+    'splitpane',
+    'resizablepanels',
   ],
   params: [
     {

package/src/ScrollableArea/ScrollableArea.doc.mjs

@@ -5,7 +5,7 @@ export const docs = {
   name: 'ScrollableArea',
   displayName: 'Scrollable Area',
   category: 'Layout',
-  keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed'],
+  keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed', 'scrollarea', 'scrollview'],
   usage: {
     description: 'Provides a native scroll viewport and a real observed content box. The viewport enters the tab order only while a requested logical axis is effectively scrollable, and containment applies only to effective axes.',
     bestPractices: [

package/src/Spinner/Spinner.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'Spinner',
   displayName: 'Spinner',
   category: 'Feedback & Status',
-  keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate"],
+  keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate","circularprogress"],
   props: [
     {
       name: 'size',

package/src/Timestamp/Timestamp.doc.mjs

@@ -6,7 +6,7 @@ export const docs = {
   name: 'Timestamp',
   displayName: 'Timestamp',
   category: 'Content',
-  keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration'],
+  keywords: ['date', 'time', 'datetime', 'relative', 'ago', 'clock', 'format', 'duration', 'relativetime'],
   playground: {
     // `value` is required but has no semantic default, so the properties-tab
     // preview fell back to the literal string "value" — which

package/src/ToggleButton/ToggleButtonGroup.doc.mjs

@@ -6,6 +6,10 @@ export const docs = {
   name: 'ToggleButtonGroup',
   subComponentOf: 'ToggleButton',
   displayName: 'Toggle Button Group',
+  keywords: [
+    'togglegroup',
+    'buttontogglegroup',
+  ],
   description: 'Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.',
   props: [
     {

package/src/postinstall.test.mjs

@@ -11,12 +11,15 @@
  */
 
 import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {spawnSync} from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
 // Core's own package-local contract copy — what actually runs at install time.
 import {
   isAstryxInitialized,
+  isAstryxPromptInReach,
   shouldNudge,
   AGENT_DOC_PATHS,
   INIT_MARKERS,
@@ -98,6 +101,49 @@ describe('core postinstall — one authoritative source, no drift', () => {
     write('AGENTS.md', `# doc\n${MARKER}\nbody`);
     expect(isAstryxInitialized(tmp)).toBe(cliLeaf.isAstryxInitialized(tmp));
   });
+
+  it('agrees with the CLI leaf on a monorepo package', () => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('AGENTS.md', MARKER);
+    write('packages/app/package.json', '{"name":"app"}');
+    const app = path.join(tmp, 'packages/app');
+    expect(isAstryxPromptInReach(app)).toBe(true);
+    expect(isAstryxPromptInReach(app)).toBe(cliLeaf.isAstryxPromptInReach(app));
+  });
+});
+
+// Install time, end to end: core's real script and its contract copy, installed
+// under a monorepo's node_modules, run the way npm runs them for a package.
+describe('core postinstall — inside a monorepo package', () => {
+  const CORE = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const install = () => {
+    const installed = path.join(tmp, 'node_modules/@astryxdesign/core/scripts');
+    fs.mkdirSync(installed, {recursive: true});
+    for (const file of ['postinstall.mjs', 'agent-doc-state.mjs']) {
+      fs.copyFileSync(path.join(CORE, 'scripts', file), path.join(installed, file));
+    }
+    return spawnSync(process.execPath, [path.join(installed, 'postinstall.mjs')], {
+      env: {...process.env, INIT_CWD: path.join(tmp, 'packages/app'), npm_command: 'install'},
+      encoding: 'utf8',
+    });
+  };
+  beforeEach(() => {
+    fs.mkdirSync(path.join(tmp, '.git'));
+    write('packages/app/package.json', '{"name":"app"}');
+  });
+
+  it('stays quiet when init ran at the repository root', () => {
+    write('AGENTS.md', MARKER);
+    const r = install();
+    expect(r.status).toBe(0);
+    expect(r.stdout).toBe('');
+  });
+
+  it('still nudges when no folder up to the repository root ran init', () => {
+    const r = install();
+    expect(r.status).toBe(0);
+    expect(r.stdout).toMatch(/finish setup and install the Astryx agent prompt/);
+  });
 });
 
 describe('core postinstall — shouldNudge', () => {