@astryxdesign/core 0.1.0 → 0.1.1-canary.080d887

package/src/Chat/ChatLayoutScrollButton.tsx

@@ -90,6 +90,12 @@ const styles = stylex.create({
     whiteSpace: 'nowrap',
     paddingInline: spacingVars['--spacing-2'],
   },
+  // When a label is shown, the icon sits on the leading edge and the text on
+  // the trailing edge. Symmetric padding leaves the text cramped against the
+  // pill's rounded edge, so give the trailing side extra breathing room.
+  buttonWithLabel: {
+    paddingInlineEnd: spacingVars['--spacing-3'],
+  },
 });
 
 // =============================================================================
@@ -130,7 +136,7 @@ export function ChatLayoutScrollButton({
           variant="ghost"
           size="md"
           onClick={onClick}
-          xstyle={styles.button}>
+          xstyle={[styles.button, label ? styles.buttonWithLabel : null]}>
           {label ?? undefined}
         </Button>
       </div>

package/src/Collapsible/useCollapsible.doc.mjs

@@ -38,7 +38,7 @@ export const docs = {
   usage: {
     description: 'Reusable hook that encapsulates the collapsible state machine. Supports three modes: group-controlled (inside CollapsibleGroup), controlled (isOpen + onOpenChange), and uncontrolled (self-managed with defaultIsOpen). Used internally by Card and Section.',
     bestPractices: [
-      {guidance: true, description: 'Use the hook directly when building custom collapsible components that need XDS collapsible behavior without Collapsible wrapper.'},
+      {guidance: true, description: 'Use the hook directly when building custom collapsible components that need Astryx collapsible behavior without Collapsible wrapper.'},
       {guidance: true, description: 'For accordion behavior, wrap items in CollapsibleGroup and pass unique value props.'},
       {guidance: false, description: 'Implement your own open/close state when useCollapsible already provides it; the hook handles group coordination automatically.'},
     ],
@@ -64,7 +64,7 @@ export const docsDense = {
   usage: {
     description: 'Encapsulates collapsible state machine. 3 modes: group-controlled (inside CollapsibleGroup), controlled (isOpen + onOpenChange), uncontrolled (self-managed w/ defaultIsOpen). Used internally by Card + Section.',
     bestPractices: [
-      {guidance: true, description: 'Use directly when building custom collapsible components needing XDS collapsible behavior w/o Collapsible wrapper.'},
+      {guidance: true, description: 'Use directly when building custom collapsible components needing Astryx collapsible behavior w/o Collapsible wrapper.'},
       {guidance: true, description: 'For accordion behavior, wrap items in CollapsibleGroup + pass unique value props.'},
       {guidance: false, description: 'Implement your own open/close state when useCollapsible already provides it; hook handles group coordination automatically.'},
     ],

package/src/ContextMenu/ContextMenu.tsx

@@ -36,7 +36,7 @@ import React, {
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {useLayer} from '../Layer/useLayer';
-import {renderXDSDropdownItems} from '../DropdownMenu/renderXDSDropdownItems';
+import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
 import {
   DropdownMenuContext,
   type DropdownMenuContextValue,
@@ -278,7 +278,7 @@ export function ContextMenu({
   );
 
   const resolvedMenuContent =
-    props.items !== undefined ? renderXDSDropdownItems(items) : menuContent;
+    props.items !== undefined ? renderDropdownItems(items) : menuContent;
 
   return (
     <>

package/src/DateInput/DateInput.test.tsx

@@ -21,19 +21,13 @@ describe('DateInput', () => {
 
   it('renders with placeholder', () => {
     render(
-      <DateInput
-        label="Date"
-        onChange={() => {}}
-        placeholder="Pick a date"
-      />,
+      <DateInput label="Date" onChange={() => {}} placeholder="Pick a date" />,
     );
     expect(screen.getByPlaceholderText('Pick a date')).toBeInTheDocument();
   });
 
   it('displays formatted date when value is provided', () => {
-    render(
-      <DateInput label="Date" value="2026-01-25" onChange={() => {}} />,
-    );
+    render(<DateInput label="Date" value="2026-01-25" onChange={() => {}} />);
     expect(screen.getByDisplayValue('January 25, 2026')).toBeInTheDocument();
   });
 
@@ -118,9 +112,7 @@ describe('DateInput', () => {
 
   it('reverts to previous value on blur when input is invalid', async () => {
     const onChange = vi.fn();
-    render(
-      <DateInput label="Date" value="2026-01-25" onChange={onChange} />,
-    );
+    render(<DateInput label="Date" value="2026-01-25" onChange={onChange} />);
 
     const input = screen.getByRole('combobox');
     fireEvent.change(input, {target: {value: 'not a date'}});
@@ -299,9 +291,7 @@ describe('DateInput', () => {
   // --- P1: Tab order: calendar button first, then input ---
 
   it('renders calendar button before input in DOM order', () => {
-    const {container} = render(
-      <DateInput label="Date" onChange={() => {}} />,
-    );
+    const {container} = render(<DateInput label="Date" onChange={() => {}} />);
     const input = container.querySelector('input');
     const button = container.querySelector('button');
     // Calendar button should come before input in the DOM
@@ -389,9 +379,7 @@ describe('DateInput', () => {
 
   it('calls onChange with undefined when input is cleared and blurred', () => {
     const onChange = vi.fn();
-    render(
-      <DateInput label="Date" value="2026-01-25" onChange={onChange} />,
-    );
+    render(<DateInput label="Date" value="2026-01-25" onChange={onChange} />);
 
     const input = screen.getByRole('combobox');
     fireEvent.change(input, {target: {value: ''}});
@@ -476,9 +464,7 @@ describe('DateInput', () => {
     });
 
     it('does not show clear button when hasClear is false', () => {
-      render(
-        <DateInput label="Date" value="2026-01-15" onChange={() => {}} />,
-      );
+      render(<DateInput label="Date" value="2026-01-15" onChange={() => {}} />);
       expect(
         screen.queryByRole('button', {name: 'Clear Date'}),
       ).not.toBeInTheDocument();
@@ -514,6 +500,68 @@ describe('DateInput', () => {
     });
   });
 
+  // --- Regression: in-progress / leading-zero input must not crash ---
+
+  describe('incomplete typed input', () => {
+    it('does not crash or fire onChange when first digit typed is 0', () => {
+      const onChange = vi.fn();
+      render(<DateInput label="Date" onChange={onChange} />);
+
+      const input = screen.getByRole('combobox');
+      // Typing a leading "0" (e.g. starting "01" for January) must be treated
+      // as incomplete input, not coerced into an (invalid) date that crashes.
+      expect(() =>
+        fireEvent.change(input, {target: {value: '0'}}),
+      ).not.toThrow();
+
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('0');
+    });
+
+    it('does not crash or fire onChange when first digit typed is 1', () => {
+      const onChange = vi.fn();
+      render(<DateInput label="Date" onChange={onChange} />);
+
+      const input = screen.getByRole('combobox');
+      expect(() =>
+        fireEvent.change(input, {target: {value: '1'}}),
+      ).not.toThrow();
+
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('1');
+    });
+
+    it('does not crash while progressively typing a numeric date', () => {
+      const onChange = vi.fn();
+      render(<DateInput label="Date" onChange={onChange} />);
+
+      const input = screen.getByRole('combobox');
+      // Simulate keystroke-by-keystroke entry of "01/15/2026". The leading
+      // single-digit keystrokes must not crash (the original bug).
+      for (const partial of ['0', '01', '01/', '01/1', '01/15', '01/15/']) {
+        expect(() =>
+          fireEvent.change(input, {target: {value: partial}}),
+        ).not.toThrow();
+      }
+
+      // Completing the date commits it without error.
+      expect(() =>
+        fireEvent.change(input, {target: {value: '01/15/2026'}}),
+      ).not.toThrow();
+      expect(onChange).toHaveBeenCalledWith('2026-01-15');
+    });
+
+    it('does not crash on blur after typing an incomplete value', () => {
+      const onChange = vi.fn();
+      render(<DateInput label="Date" onChange={onChange} />);
+
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: '0'}});
+      expect(() => fireEvent.blur(input)).not.toThrow();
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+
   describe('external value changes', () => {
     it('clears pending input when value changes externally', () => {
       const onChange = vi.fn();

package/src/Divider/Divider.doc.mjs

@@ -108,7 +108,7 @@ export const docsZh = {
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'visual separator w/ optional label, using XDS design tokens',
+  description: 'visual separator w/ optional label, using Astryx design tokens',
   usage: {
     description: 'A visual separator that divides content into distinct sections. Use to create clear boundaries between groups of related content, or to demarcate interactive regions within a layout.',
     bestPractices: [

package/src/DropdownMenu/DropdownMenu.tsx

@@ -37,7 +37,7 @@ import {Button, type ButtonProps} from '../Button';
 import {Icon} from '../Icon';
 import type {IconType} from '../Icon';
 
-import {renderXDSDropdownItems} from './renderXDSDropdownItems';
+import {renderDropdownItems} from './renderDropdownItems';
 import {
   DropdownMenuContext,
   type DropdownMenuContextValue,
@@ -366,7 +366,7 @@ export function DropdownMenu({
 
   // Resolve menu content: data-driven items become components
   const menuContent =
-    props.items !== undefined ? renderXDSDropdownItems(items) : children;
+    props.items !== undefined ? renderDropdownItems(items) : children;
 
   return (
     <>

package/src/DropdownMenu/{renderXDSDropdownItems.tsx → renderDropdownItems.tsx}

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file renderXDSDropdownItems.tsx
+ * @file renderDropdownItems.tsx
  * @output Converts data-driven menu items into DropdownMenuItem components
  * @position Utility; used by DropdownMenu to unify data-driven and compound paths
  */
@@ -49,7 +49,7 @@ function getSectionKey(section: DropdownMenuSection, index: number): string {
  * Converts data-driven items into DropdownMenuItem components,
  * so both modes share the same rendering and keyboard navigation path.
  */
-export function renderXDSDropdownItems(
+export function renderDropdownItems(
   items: DropdownMenuOption[],
 ): ReactNode {
   const elements: ReactNode[] = [];

package/src/EmptyState/EmptyState.test.tsx

@@ -45,11 +45,13 @@ describe('EmptyState', () => {
       />,
     );
     expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
+    // Description renders as <div> (never <p>) so block content composes safely.
+    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
   });
 
   it('does not render description when not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(container.querySelector('p')).not.toBeInTheDocument();
+    render(<EmptyState title="No results" />);
+    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
   });
 
   it('renders with icon', () => {

package/src/EmptyState/EmptyState.tsx

@@ -174,13 +174,17 @@ export function EmptyState({
           title,
         )}
         {description != null && (
-          <p
+          // Rendered as <div> (not <p>): description accepts ReactNode and a
+          // <p> cannot legally contain block children, which causes hydration
+          // mismatches. The StyleX style sets margin: 0, so appearance is
+          // unchanged.
+          <div
             {...stylex.props(
               styles.description,
               isCompact && styles.descriptionCompact,
             )}>
             {description}
-          </p>
+          </div>
         )}
       </div>
       {actions != null && (

package/src/FormLayout/FormLayout.doc.mjs

@@ -20,7 +20,7 @@ export const docs = {
       name: 'children',
       type: 'ReactNode',
       description:
-        'Form fields to arrange. Accepts XDS inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
+        'Form fields to arrange. Accepts Astryx inputs (TextInput, Selector, etc.) and Field-wrapped custom controls.',
     },
     {
       name: 'xstyle',
@@ -68,7 +68,7 @@ export const docsZh = {
       name: 'children',
       type: 'ReactNode',
       description:
-        '要排列的表单字段。接受 XDS 输入组件（TextInput、Selector 等）和 Field 包装的自定义控件。',
+        '要排列的表单字段。接受 Astryx 输入组件（TextInput、Selector 等）和 Field 包装的自定义控件。',
     },
     {
       name: 'xstyle',
@@ -122,7 +122,7 @@ export const docsDense = {
   },
   propDescriptions: {
     direction: 'Field arrangement. Vertical stacks top-to-bottom, horizontal arranges left-to-right w/ equal flex-grow, horizontal-labels uses CSS Grid w/ labels left of inputs (collapses <=480px).',
-    children: 'Form fields to arrange. Accepts XDS inputs + Field-wrapped custom controls.',
+    children: 'Form fields to arrange. Accepts Astryx inputs + Field-wrapped custom controls.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
   },
 };

package/src/HoverCard/HoverCard.doc.mjs

@@ -108,6 +108,7 @@ export const docs = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
     anatomy: [
       {name: 'Trigger', required: true, description: 'The element that opens the hover card on hover or focus: a button, link, or inline text.'},
@@ -216,6 +217,7 @@ export const docsZh = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead.' },
     ],
   },
 };
@@ -233,6 +235,7 @@ export const docsDense = {
       { guidance: false, description: 'Place critical actions or required information inside a hover card; users may miss content that only appears on hover.' },
       { guidance: false, description: 'Use a hover card when a simple Tooltip or Popover would suffice.' },
       { guidance: false, description: 'Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.' },
+      { guidance: false, description: 'Nest a block-content HoverCard directly inside phrasing-only contexts (<p>, <label>, heading); it renders inline so block content is invalid HTML there. Wrap surrounding text in a block element instead.' },
     ],
   },
   components: [

package/src/HoverCard/HoverCard.test.tsx

@@ -10,7 +10,10 @@
  */
 
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent, waitFor} from '@testing-library/react';
+import {render, screen, fireEvent, waitFor, act} from '@testing-library/react';
+import {renderToString} from 'react-dom/server';
+import {hydrateRoot} from 'react-dom/client';
+import {StrictMode} from 'react';
 import {HoverCard} from './HoverCard';
 
 // Store original matches to restore later
@@ -73,6 +76,31 @@ describe('HoverCard', () => {
     expect(paragraph?.querySelector('div')).toBeNull();
   });
 
+  it('renders the floating layer with inline-safe markup (no block elements in a paragraph)', () => {
+    // HoverCard renders its floating layer inline (no portal), so the layer
+    // must be phrasing content to stay valid — and stay put on hydration —
+    // inside a <p>. Assert the layer popover element is a <span> and that the
+    // paragraph contains no <div> descendants at all.
+    const {container} = render(
+      <p>
+        Before{' '}
+        <HoverCard content={<span>Card content</span>}>
+          <a href="#trigger">Trigger</a>
+        </HoverCard>{' '}
+        after
+      </p>,
+    );
+
+    const paragraph = container.querySelector('p');
+    const layer = screen.getByText('Card content').closest('[popover]');
+
+    expect(layer).not.toBeNull();
+    expect(layer?.tagName).toBe('SPAN');
+    // The whole layer subtree lives inside the paragraph with no block boxes.
+    expect(paragraph?.contains(layer as Node)).toBe(true);
+    expect(paragraph?.querySelector('div')).toBeNull();
+  });
+
   it('does not show content initially', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
@@ -84,7 +112,7 @@ describe('HoverCard', () => {
     expect(content).toBeInTheDocument();
   });
 
-  it('applies the theme body font to the portaled layer', () => {
+  it('applies the theme body font to the floating layer', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
@@ -370,4 +398,152 @@ describe('HoverCard', () => {
       expect(onOpenChange).not.toHaveBeenCalledWith(true);
     });
   });
+
+  describe('SSR / hydration', () => {
+    // Regression coverage for the hydration mismatch (#3107). The floating
+    // layer used to be portaled into document.body behind a
+    // `typeof document !== 'undefined'` gate: the server rendered nothing while
+    // the first client render emitted the portal, so the two trees disagreed.
+    //
+    // The layer is now rendered inline as inline-safe phrasing markup (a
+    // `<span popover>`), identically on the server and the client, so there is
+    // nothing for hydration to mismatch.
+
+    it('renders the floating layer in server markup (no document gate)', () => {
+      const html = renderToString(
+        <HoverCard content={<span>Card content</span>}>
+          <button type="button">Trigger</button>
+        </HoverCard>,
+      );
+
+      // The popover element is present in the server output...
+      expect(html).toContain('popover="manual"');
+      expect(html).toContain('Card content');
+      // ...and it is a <span> (inline-safe), not a <div>.
+      expect(html).toMatch(/<span[^>]*popover="manual"/);
+    });
+
+    it('keeps the floating layer inline-safe in server markup inside a paragraph', () => {
+      const html = renderToString(
+        <p>
+          Before{' '}
+          <HoverCard content={<span>Card content</span>}>
+            <a href="#trigger">Trigger</a>
+          </HoverCard>{' '}
+          after
+        </p>,
+      );
+
+      // No <div> is emitted inside the paragraph — the layer and its wrappers
+      // are all phrasing content, so the server string is valid <p> markup that
+      // the browser parser will not reparent (which would itself desync
+      // hydration).
+      expect(html).not.toContain('<div');
+      expect(html).toMatch(/<span[^>]*popover="manual"/);
+    });
+
+    it('server markup matches the first client render (no hydration mismatch)', async () => {
+      const tree = (
+        <StrictMode>
+          <p>
+            Glossary:{' '}
+            <HoverCard content={<span>Definition</span>}>
+              <a href="#term">term</a>
+            </HoverCard>
+            .
+          </p>
+        </StrictMode>
+      );
+
+      const serverHTML = renderToString(tree);
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      // Capture any hydration diagnostics. React reports hydration mismatches
+      // both through console.error and through onRecoverableError.
+      const consoleErrorSpy = 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);
+          },
+        });
+      });
+
+      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      );
+
+      expect(hydrationErrors).toEqual([]);
+      expect(recoverableErrors).toEqual([]);
+
+      await act(async () => {
+        root.unmount();
+      });
+      consoleErrorSpy.mockRestore();
+      container.remove();
+    });
+
+    it('hydrates a default-open hover card without a mismatch', async () => {
+      vi.mocked(HTMLElement.prototype.showPopover).mockClear();
+
+      const tree = (
+        <HoverCard content={<span>Default open</span>} isDefaultOpen>
+          <button type="button">Trigger</button>
+        </HoverCard>
+      );
+
+      const serverHTML = renderToString(tree);
+      // isDefaultOpen must not leak the open state into SSR markup — the open
+      // call happens in an effect after hydration, so the server output is the
+      // same closed markup the first client render produces.
+      expect(serverHTML).toContain('popover="manual"');
+
+      const container = document.createElement('div');
+      container.innerHTML = serverHTML;
+      document.body.appendChild(container);
+
+      const consoleErrorSpy = 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);
+          },
+        });
+      });
+
+      const hydrationErrors = consoleErrorSpy.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      );
+      expect(hydrationErrors).toEqual([]);
+      expect(recoverableErrors).toEqual([]);
+
+      // The card opens after hydration via the mount effect.
+      await waitFor(() => {
+        expect(HTMLElement.prototype.showPopover).toHaveBeenCalled();
+      });
+
+      await act(async () => {
+        root.unmount();
+      });
+      consoleErrorSpy.mockRestore();
+      container.remove();
+    });
+  });
 });

package/src/HoverCard/HoverCard.tsx

@@ -4,9 +4,9 @@
 
 /**
  * @file HoverCard.tsx
- * @input Uses React, ReactDOM createPortal, useHoverCard hook
+ * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and portals floating layer
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
@@ -15,13 +15,7 @@
  * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
  */
 
-import React, {
-  useCallback,
-  useRef,
-  type ReactElement,
-  type ReactNode,
-} from 'react';
-import {createPortal} from 'react-dom';
+import {useCallback, useRef, type ReactElement, type ReactNode} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import * as stylex from '@stylexjs/stylex';
 import {useHoverCard, type HoverCardFocusTrigger} from './useHoverCard';
@@ -245,13 +239,23 @@ export function HoverCard({
     };
   }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
 
-  const renderedHoverCard =
-    typeof document !== 'undefined'
-      ? createPortal(
-          hoverCard.renderHoverCard(content, {xstyle, className, style}),
-          document.body,
-        )
-      : null;
+  // Render the floating layer inline, in the same place on the server and the
+  // client. The layer is a `popover` element opened via the Popover API, so the
+  // browser promotes it to the top layer when shown — that already escapes
+  // ancestor clipping, stacking, and transform containing-block traps, and CSS
+  // anchor positioning resolves the trigger reference regardless of where the
+  // element sits in the DOM, so no portal is needed to "escape" layout.
+  //
+  // The layer renders as inline-safe phrasing markup (a `<span>`, see
+  // useHoverCard), which stays put inside a `<p>` instead of being reparented
+  // by the HTML parser. That keeps the server markup and the first client
+  // render identical, so there is no hydration mismatch — and it preserves the
+  // inline-safety guarantee (no block elements injected into a paragraph).
+  const renderedHoverCard = hoverCard.renderHoverCard(content, {
+    xstyle,
+    className,
+    style,
+  });
 
   // For text-only children: use inline span with ref on wrapper
   if (textOnly) {

package/src/HoverCard/useHoverCard.tsx

@@ -58,8 +58,12 @@ const styles = stylex.create({
     marginInlineStart: spacingVars['--spacing-1'],
     marginInlineEnd: spacingVars['--spacing-1'],
   },
-  // Content wrapper for padding and mouse events
+  // Content wrapper for padding and mouse events.
+  // `display: block` keeps the wrapper a block box even though it renders as a
+  // `span` (the layer uses inline-safe phrasing markup so it is valid inside a
+  // paragraph and produces identical server/client markup).
   content: {
+    display: 'block',
     paddingBlockStart: spacingVars['--spacing-3'],
     paddingBlockEnd: spacingVars['--spacing-3'],
     paddingInlineStart: spacingVars['--spacing-3'],
@@ -234,9 +238,7 @@ function isFocusable(element: HTMLElement): boolean {
  * {hoverCard.renderHoverCard(<ProfileCard user={user} />)}
  * ```
  */
-export function useHoverCard(
-  options: HoverCardOptions = {},
-): HoverCardReturn {
+export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
   const {
     placement = 'above',
     alignment = 'center',
@@ -454,14 +456,14 @@ export function useHoverCard(
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
         xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // Render the layer as inline-safe phrasing markup so HoverCard stays
+        // valid (and hydration-stable) inside inline contexts like a `<p>`.
+        as: 'span' as const,
       };
 
       return layer.render(
-        <div
-          {...mergeProps(
-            themeProps('hovercard'),
-            stylex.props(styles.content),
-          )}
+        <span
+          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();
@@ -502,7 +504,7 @@ export function useHoverCard(
             scheduleHide();
           }}>
           {children}
-        </div>,
+        </span>,
         renderProps,
       );
     },