@astryxdesign/core 0.7.2-canary.a5c7e4a → 0.7.2-canary.b4b905b

package/dist/Layer/useLayer.d.ts.map

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

package/dist/Layer/useLayer.js

@@ -464,8 +464,14 @@ function useLayerImplementation(options) {
         // hosted away from its trigger then still takes its sequential focus
         // order (and its popover nesting) from the trigger rather than from
         // its own DOM position. Browsers without the option ignore it.
+        // `source` is declared as an `HTMLElement`. A caller-rendered icon
+        // trigger is an `SVGElement`, whose dictionary conversion throws
+        // before the popover opens. Omitting the option for it still anchors
+        // the layer, because positioning reads the anchor-name pair, and only
+        // gives up the invoker's focus order.
+        const trigger = triggerRef.current instanceof HTMLElement ? triggerRef.current : undefined;
         popover.showPopover({
-          source: triggerRef.current ?? undefined
+          source: trigger
         });
       });
     } else {

package/dist/hooks/useEntryAnimation.d.ts

@@ -4,7 +4,8 @@ export type EntryAnimationPreset = 'slideDown' | 'slideUp' | 'fadeIn' | 'scaleIn
  * Returns a StyleX style for animating an element on mount.
  *
  * Only animates when the element is dynamically inserted after the initial
- * page paint. Elements rendered on page load are not animated.
+ * page paint. Elements rendered on page load, including server-rendered
+ * elements while they hydrate, are not animated.
  *
  * @example
  * ```

package/dist/hooks/useEntryAnimation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useEntryAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntryAnimation.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAoFnD,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GACX,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAEd;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAkC,GACzC,YAAY,GAAG,IAAI,CAGrB"}
+{"version":3,"file":"useEntryAnimation.d.ts","sourceRoot":"","sources":["../../src/hooks/useEntryAnimation.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAgFnD,MAAM,MAAM,oBAAoB,GAC9B,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,GAAE,oBAAkC,GACzC,YAAY,GAAG,IAAI,CAMrB"}

package/dist/hooks/useEntryAnimation.js

@@ -4,28 +4,26 @@
 
 /**
  * @file useEntryAnimation.ts
- * @input Uses React, StyleX, theme tokens
+ * @input Uses React, StyleX, theme tokens, useIsHydrating
  * @output Exports useEntryAnimation hook for mount-only entry animations
  * @position Hook utility; consumed by FieldStatus and available to consumers
  *
  * Provides entry animations for conditionally rendered elements.
  * Only animates when the element is dynamically mounted after the initial
  * page paint — statically rendered elements on page load are not animated.
+ * Server-rendered elements hydrate without the entry style and never play it
+ * (spec:AST-013 FR13).
  */
 import { useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { durationVars, easeVars, spacingVars } from "../theme/tokens.stylex.js";
+import { useIsHydrating } from "./useIsHydrating.js";
 
-// Track whether the initial page paint has completed.
-// Elements rendered on page load should not animate;
-// only dynamically inserted ones should.
-//
-// NOTE: This module is marked 'use client' so it never runs on the server.
-// If the directive is removed, this flag will always be false during SSR,
-// and useState(() => initialPaintComplete) will capture false — meaning
-// animations won't run after hydration. Keep 'use client' or add an
-// effect-based fallback if SSR support is needed.
+// Track whether the initial page paint has completed, so elements a
+// client-only root renders on page load do not animate; only dynamically
+// inserted ones should. Server-rendered elements are covered by
+// useIsHydrating instead: hydration can run after this flag turns true.
 let initialPaintComplete = false;
 if (typeof window !== 'undefined') {
   requestAnimationFrame(() => {
@@ -70,7 +68,8 @@ const styles = {
  * Returns a StyleX style for animating an element on mount.
  *
  * Only animates when the element is dynamically inserted after the initial
- * page paint. Elements rendered on page load are not animated.
+ * page paint. Elements rendered on page load, including server-rendered
+ * elements while they hydrate, are not animated.
  *
  * @example
  * ```
@@ -79,6 +78,9 @@ const styles = {
  * ```
  */
 export function useEntryAnimation(preset = 'slideDown') {
-  const [animate] = useState(() => initialPaintComplete);
+  const isHydrating = useIsHydrating();
+  // Captured once: a hydrated element must not start animating when React
+  // re-renders it with the client snapshot after hydration.
+  const [animate] = useState(() => !isHydrating && initialPaintComplete);
   return animate ? styles[preset] : null;
 }

package/dist/hooks/useIsHydrating.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Returns `true` during server render and during the client render that
+ * hydrates server HTML; `false` in every other client render.
+ */
+export declare function useIsHydrating(): boolean;
+//# sourceMappingURL=useIsHydrating.d.ts.map

package/dist/hooks/useIsHydrating.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsHydrating.d.ts","sourceRoot":"","sources":["../../src/hooks/useIsHydrating.ts"],"names":[],"mappings":"AAwBA;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAExC"}

package/dist/hooks/useIsHydrating.js

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIsHydrating.ts
+ * @input Uses React useSyncExternalStore
+ * @output Exports useIsHydrating (internal; not re-exported from hooks/index.ts)
+ * @position Internal utility; read by useEntryAnimation so markup that
+ *   hydrates server HTML matches the server (spec:AST-013 FR9, FR13)
+ *
+ * React renders with the server snapshot on the server and again in the
+ * client render that hydrates server HTML, then re-renders with the client
+ * snapshot. Code that must render the server's markup while hydrating reads
+ * this instead of a first-paint flag, timer, animation frame, or mount Effect.
+ */
+import { useSyncExternalStore } from 'react';
+
+// Nothing ever changes, so there is nothing to subscribe to.
+const subscribe = () => () => {};
+const getSnapshot = () => false;
+const getServerSnapshot = () => true;
+
+/**
+ * Returns `true` during server render and during the client render that
+ * hydrates server HTML; `false` in every other client render.
+ */
+export function useIsHydrating() {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/package.json

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

package/src/Layer/useLayer.tsx

@@ -762,7 +762,16 @@ function useLayerImplementation(
         // hosted away from its trigger then still takes its sequential focus
         // order (and its popover nesting) from the trigger rather than from
         // its own DOM position. Browsers without the option ignore it.
-        popover.showPopover({source: triggerRef.current ?? undefined});
+        // `source` is declared as an `HTMLElement`. A caller-rendered icon
+        // trigger is an `SVGElement`, whose dictionary conversion throws
+        // before the popover opens. Omitting the option for it still anchors
+        // the layer, because positioning reads the anchor-name pair, and only
+        // gives up the invoker's focus order.
+        const trigger =
+          triggerRef.current instanceof HTMLElement
+            ? triggerRef.current
+            : undefined;
+        popover.showPopover({source: trigger});
       });
     } else {
       popover.style.display = 'block';

package/src/Tooltip/Tooltip.test.tsx

@@ -183,6 +183,37 @@ describe('Tooltip', () => {
     });
   });
 
+  describe('icon-only trigger', () => {
+    // A rendered icon is an SVGElement, and ShowPopoverOptions.source is
+    // declared as an HTMLElement. Handing the icon to showPopover throws
+    // during dictionary conversion, before the popover opens, so the hint
+    // never appeared. (#7226)
+    it('opens an icon trigger without passing an SVGElement as the source', async () => {
+      const showSpy = vi.mocked(HTMLElement.prototype.showPopover);
+      showSpy.mockClear();
+
+      render(
+        <Tooltip content="Shared memory" isDefaultOpen>
+          <svg data-testid="icon" aria-hidden="true" />
+        </Tooltip>,
+      );
+
+      await waitFor(() => {
+        expect(showSpy).toHaveBeenCalled();
+      });
+
+      const [options] = showSpy.mock.calls[0];
+      // Compared as a boolean on purpose: a plain `toBeUndefined` failure makes
+      // the diff printer walk the SVGElement, which it cannot inspect.
+      expect(options?.source === undefined).toBe(true);
+
+      // The icon is still the trigger the ARIA tooltip pattern is wired to.
+      expect(screen.getByTestId('icon').getAttribute('aria-describedby')).toBe(
+        screen.getByRole('tooltip', {hidden: true}).id,
+      );
+    });
+  });
+
   describe('WCAG 1.4.13 — content on hover or focus', () => {
     it('dismisses on Escape while visible (dismissible)', async () => {
       const onOpenChange = vi.fn();

package/src/hooks/useEntryAnimation.doc.mjs

@@ -18,12 +18,12 @@ export const docs = {
     {
       name: 'entryStyle',
       type: 'StyleXStyles | null',
-      description: 'A StyleX style object for the entry animation, or null if the element was rendered on initial page load (no animation needed).',
+      description: 'A StyleX style object for the entry animation, or null if the element was rendered on initial page load or hydrated from server HTML (no animation needed).',
     },
   ],
   usage: {
     description:
-      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Requires "use client"; does not support SSR.',
+      'Returns a StyleX style for animating an element on mount. Only animates when the element is dynamically inserted after the initial page paint; elements rendered on page load are not animated. Uses Astryx motion tokens (duration, easing) for consistent animation timing. Server-rendered elements hydrate without the entry style and never animate; elements mounted after hydration animate.',
     bestPractices: [
       { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, or expanding sections.' },
       { guidance: true, description: 'Spread the returned style into stylex.props() alongside other styles.' },
@@ -39,7 +39,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+    'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Server-rendered elements hydrate without entry style, never animate; elements mounted after hydration animate.',
   paramDescriptions: {
     preset: 'animation preset applied on mount.',
   },
@@ -48,7 +48,7 @@ export const docsDense = {
   },
   usage: {
     description:
-      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Requires "use client"; does not support SSR.',
+      'Returns StyleX style for animating element on mount. Only animates when element dynamically inserted after initial page paint; elements rendered on page load not animated. Uses Astryx motion tokens (duration, easing) for consistent timing. Server-rendered elements hydrate without entry style, never animate; elements mounted after hydration animate.',
     bestPractices: [
       { guidance: true, description: 'Use for conditionally rendered elements like validation messages, toasts, expanding sections.' },
       { guidance: true, description: 'Spread returned style into stylex.props() alongside other styles.' },

package/src/hooks/useEntryAnimation.ssr.test.tsx

@@ -0,0 +1,143 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useEntryAnimation.ssr.test.tsx
+ * @input FieldStatus server markup, React hydration, and client mounts
+ * @output Proves server-rendered entry-animated elements hydrate without mismatches
+ * @position SSR acceptance test for useEntryAnimation
+ */
+
+import {act, useState} from 'react';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {createRoot, hydrateRoot} from 'react-dom/client';
+import {renderToString} from 'react-dom/server';
+
+// Each test imports a fresh copy of FieldStatus with the hook's first-frame
+// callback held back, so server markup renders before the page "paints" (as on
+// a real server) and `paint()` then runs that frame.
+async function importFieldStatus() {
+  const frames: FrameRequestCallback[] = [];
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+    frames.push(callback),
+  );
+  vi.resetModules();
+  const {FieldStatus} = await import('../FieldStatus');
+  vi.unstubAllGlobals();
+  const paint = () => {
+    frames.splice(0).forEach(callback => callback(performance.now()));
+  };
+  return {FieldStatus, paint};
+}
+
+function mountServerHTML(html: string): HTMLDivElement {
+  const container = document.createElement('div');
+  container.innerHTML = html;
+  document.body.appendChild(container);
+  return container;
+}
+
+function classesOf(element: Element | null): string[] {
+  return (element?.getAttribute('class') ?? '').split(/\s+/).filter(Boolean);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+  document.body.replaceChildren();
+});
+
+describe('useEntryAnimation — SSR', () => {
+  it('hydrates server-rendered FieldStatus after the first paint without a mismatch', async () => {
+    const {FieldStatus, paint} = await importFieldStatus();
+    const tree = <FieldStatus type="error" message="x" />;
+    const serverHTML = renderToString(tree);
+    const container = mountServerHTML(serverHTML);
+    const serverClassName = container.firstElementChild?.className;
+    paint();
+
+    const consoleError = 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),
+      });
+    });
+
+    expect(
+      consoleError.mock.calls.filter(call =>
+        String(call[0] ?? '')
+          .toLowerCase()
+          .includes('hydrat'),
+      ),
+    ).toEqual([]);
+    expect(recoverableErrors).toEqual([]);
+    expect(container.firstElementChild?.className).toBe(serverClassName);
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('still animates a client-only mount after the first paint', async () => {
+    const {FieldStatus, paint} = await importFieldStatus();
+    const staticClasses = classesOf(
+      mountServerHTML(renderToString(<FieldStatus type="error" message="x" />))
+        .firstElementChild,
+    );
+    paint();
+
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    await act(async () => {
+      root.render(<FieldStatus type="error" message="x" />);
+    });
+
+    const clientClasses = classesOf(container.firstElementChild);
+    expect(clientClasses).toEqual(expect.arrayContaining(staticClasses));
+    expect(clientClasses.length).toBeGreaterThan(staticClasses.length);
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('animates a FieldStatus mounted after hydration', async () => {
+    const {FieldStatus, paint} = await importFieldStatus();
+    let showSecond!: () => void;
+    function Form() {
+      const [second, setSecond] = useState(false);
+      showSecond = () => setSecond(true);
+      return (
+        <>
+          <FieldStatus type="error" message="first" />
+          {second ? <FieldStatus type="error" message="second" /> : null}
+        </>
+      );
+    }
+    const container = mountServerHTML(renderToString(<Form />));
+    const staticClasses = classesOf(container.firstElementChild);
+    paint();
+
+    let root!: ReturnType<typeof hydrateRoot>;
+    await act(async () => {
+      root = hydrateRoot(container, <Form />);
+    });
+    await act(async () => {
+      showSecond();
+    });
+
+    const mounted = container.children[1] ?? null;
+    expect(mounted).toHaveTextContent('second');
+    const mountedClasses = classesOf(mounted);
+    expect(mountedClasses).toEqual(expect.arrayContaining(staticClasses));
+    expect(mountedClasses.length).toBeGreaterThan(staticClasses.length);
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+});

package/src/hooks/useEntryAnimation.ts

@@ -3,29 +3,27 @@
 'use client';
 /**
  * @file useEntryAnimation.ts
- * @input Uses React, StyleX, theme tokens
+ * @input Uses React, StyleX, theme tokens, useIsHydrating
  * @output Exports useEntryAnimation hook for mount-only entry animations
  * @position Hook utility; consumed by FieldStatus and available to consumers
  *
  * Provides entry animations for conditionally rendered elements.
  * Only animates when the element is dynamically mounted after the initial
  * page paint — statically rendered elements on page load are not animated.
+ * Server-rendered elements hydrate without the entry style and never play it
+ * (spec:AST-013 FR13).
  */
 
 import {useState} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {durationVars, easeVars, spacingVars} from '../theme/tokens.stylex';
+import {useIsHydrating} from './useIsHydrating';
 
-// Track whether the initial page paint has completed.
-// Elements rendered on page load should not animate;
-// only dynamically inserted ones should.
-//
-// NOTE: This module is marked 'use client' so it never runs on the server.
-// If the directive is removed, this flag will always be false during SSR,
-// and useState(() => initialPaintComplete) will capture false — meaning
-// animations won't run after hydration. Keep 'use client' or add an
-// effect-based fallback if SSR support is needed.
+// Track whether the initial page paint has completed, so elements a
+// client-only root renders on page load do not animate; only dynamically
+// inserted ones should. Server-rendered elements are covered by
+// useIsHydrating instead: hydration can run after this flag turns true.
 let initialPaintComplete = false;
 if (typeof window !== 'undefined') {
   requestAnimationFrame(() => {
@@ -99,16 +97,14 @@ const styles = stylex.create({
 });
 
 export type EntryAnimationPreset =
-  | 'slideDown'
-  | 'slideUp'
-  | 'fadeIn'
-  | 'scaleIn';
+  'slideDown' | 'slideUp' | 'fadeIn' | 'scaleIn';
 
 /**
  * Returns a StyleX style for animating an element on mount.
  *
  * Only animates when the element is dynamically inserted after the initial
- * page paint. Elements rendered on page load are not animated.
+ * page paint. Elements rendered on page load, including server-rendered
+ * elements while they hydrate, are not animated.
  *
  * @example
  * ```
@@ -119,6 +115,9 @@ export type EntryAnimationPreset =
 export function useEntryAnimation(
   preset: EntryAnimationPreset = 'slideDown',
 ): StyleXStyles | null {
-  const [animate] = useState(() => initialPaintComplete);
+  const isHydrating = useIsHydrating();
+  // Captured once: a hydrated element must not start animating when React
+  // re-renders it with the client snapshot after hydration.
+  const [animate] = useState(() => !isHydrating && initialPaintComplete);
   return animate ? styles[preset] : null;
 }

package/src/hooks/useIsHydrating.test.tsx

@@ -0,0 +1,70 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useIsHydrating.test.tsx
+ * @input useIsHydrating, React server render, hydration, and client roots
+ * @output Proves the hook is true only on the server and while hydrating
+ * @position Unit test for the internal hydration-state utility
+ */
+
+import {act, useState} from 'react';
+import {afterEach, describe, expect, it} from 'vitest';
+import {createRoot, hydrateRoot} from 'react-dom/client';
+import {renderToString} from 'react-dom/server';
+import {useIsHydrating} from './useIsHydrating';
+
+const seen: boolean[] = [];
+
+function Probe() {
+  const isHydrating = useIsHydrating();
+  seen.push(isHydrating);
+  return <span data-hydrating={String(isHydrating)} />;
+}
+
+afterEach(() => {
+  seen.length = 0;
+  document.body.replaceChildren();
+});
+
+describe('useIsHydrating', () => {
+  it('is true on the server', () => {
+    expect(renderToString(<Probe />)).toContain('data-hydrating="true"');
+  });
+
+  it('is true while hydrating, then false after hydration', async () => {
+    const container = document.createElement('div');
+    container.innerHTML = renderToString(<Probe />);
+    document.body.appendChild(container);
+    seen.length = 0;
+
+    let root!: ReturnType<typeof hydrateRoot>;
+    await act(async () => {
+      root = hydrateRoot(container, <Probe />);
+    });
+
+    expect(seen[0]).toBe(true);
+    expect(seen.at(-1)).toBe(false);
+    expect(container.querySelector('span')).toHaveAttribute(
+      'data-hydrating',
+      'false',
+    );
+    await act(async () => root.unmount());
+  });
+
+  it('is false in a client-only root and for elements mounted after hydration', async () => {
+    let show!: () => void;
+    function Later() {
+      const [isShown, setIsShown] = useState(false);
+      show = () => setIsShown(true);
+      return isShown ? <Probe /> : null;
+    }
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const root = createRoot(container);
+    await act(async () => root.render(<Later />));
+    await act(async () => show());
+
+    expect(seen).toEqual([false]);
+    await act(async () => root.unmount());
+  });
+});

package/src/hooks/useIsHydrating.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIsHydrating.ts
+ * @input Uses React useSyncExternalStore
+ * @output Exports useIsHydrating (internal; not re-exported from hooks/index.ts)
+ * @position Internal utility; read by useEntryAnimation so markup that
+ *   hydrates server HTML matches the server (spec:AST-013 FR9, FR13)
+ *
+ * React renders with the server snapshot on the server and again in the
+ * client render that hydrates server HTML, then re-renders with the client
+ * snapshot. Code that must render the server's markup while hydrating reads
+ * this instead of a first-paint flag, timer, animation frame, or mount Effect.
+ */
+
+import {useSyncExternalStore} from 'react';
+
+// Nothing ever changes, so there is nothing to subscribe to.
+const subscribe = () => () => {};
+const getSnapshot = () => false;
+const getServerSnapshot = () => true;
+
+/**
+ * Returns `true` during server render and during the client render that
+ * hydrates server HTML; `false` in every other client render.
+ */
+export function useIsHydrating(): boolean {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}