Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
88.1 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file useLayer.tsx
 * @input Uses React hooks, Popover API (its `beforetoggle`/`toggle` events through the popoverOperations ledger), CSS anchor positioning, owned DOM boundaries, shared text/provider boundaries
 * @output Exports the public useLayer hook plus internal trigger helpers.
 * @position Core layer utility; used by useHoverCard, useTooltip, etc.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Layer/useLayer.doc.mjs
 * - /packages/core/src/Layer/useLayer.test.tsx
 * - /packages/core/src/Layer/index.ts
 */

import React, {
  useCallback,
  useEffect,
  useId,
  useMemo,
  useRef,
  useState,
  useSyncExternalStore,
  type ReactNode,
  type RefCallback,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {StyleXStyles} from '@stylexjs/stylex';
import {createPortal} from 'react-dom';
import {LayerContentBoundary} from './layerScopedContext';
import {layerClickBoundary} from './layerClickBoundary';
import {addAnchorName, readAnchorNames, removeAnchorName} from './anchorName';
import {
  claimContextMenuPress,
  currentGesture,
  currentGestureHasClicked,
} from './gestureCounter';
import {resolveLayerPortalTarget} from './layerHost';
import {layerTextReset} from './layerTextReset.stylex';
import {layerStructureReset} from './layerStructureReset.stylex';
import {layerViewportInset} from './layerViewportInset.stylex';
import {keyboardLiftStyle, useLayerKeyboardClearance} from './LayerTouch';
import {LAYER_ANCHORED_ATTRIBUTE} from './layerKeyboardClearance';
import {settledBox} from './settledBox';
import {layerInsetProperties} from './layerInset';
import {
  LAYER_CLEARANCE_PROPERTY,
  ensureSlideRules,
  anchorClearAlignment,
  getAnchorClearFallbacks,
  slideRuleName,
} from './layerSlideRules';
import {
  afterPopoverOperations,
  isBrowserHideInFlight,
  isPopoverOperationInFlight,
  observeBrowserHide,
  runPopoverOperation,
} from './popoverOperations';
import {preserveAnimations} from './preserveAnimations';
import {useLayerContext} from './LayerContext';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {overlayPaddingReset} from '../Layout/overlayPaddingReset.stylex';
import {observeResize} from '../utils/sharedResizeObserver';
import {observeMutations} from '../utils/sharedMutationObserver';
import {containsAlongFlatTree, parentAcrossShadow} from '../utils/flatTree';
import {isShadowRoot} from '../utils/nodeType';
import {subscribeInput} from '../utils/inputStream';

const styles = stylex.create({
  // The software keyboard's block-size cap, on the layer's own element. Every
  // layer sets it, an uncapped one to a limit no viewport cap reaches. So a
  // layer nested in a capped one does not inherit the outer cap. The surfaces
  // inside a layer read it through `layerViewportInset.maxBlockSize`. The cap
  // also writes the overflow a capped surface takes. Popover's surface reads
  // it, so it scrolls from the commit that caps it. Beside them, the
  // keyboard's inset from the viewport's bottom lets a layer that places
  // itself slide above the keyboard. The inset keeps its largest value until
  // the layer closes, so that layer stays put as the keyboard goes. Every
  // layer sets it, `initial` until a keyboard is up, so a nested layer does
  // not inherit it. All three are private runtime state, never set by an app
  // or a theme.
  // SYNC: the properties are LAYER_KEYBOARD_CAP_PROPERTY,
  // LAYER_KEYBOARD_OVERFLOW_PROPERTY and LAYER_KEYBOARD_INSET_PROPERTY
  // (useLayerKeyboardClearance.ts).
  keyboardCap: (cap: string, overflow: 'auto' | 'visible', inset: string) => ({
    '--_layer-keyboard-max-block-size': cap,
    '--_layer-keyboard-overflow': overflow,
    '--_layer-keyboard-inset-block-end': inset,
  }),
  // A layer that keeps its anchor clear scrolls only once its content
  // overflows the box it was given. A layer that fits has no scroll range, so
  // a wheel over it scrolls the page. Nothing contains the scroll, so a tall
  // layer chains to the page at its end.
  scrollsOnOverflow: {
    overflowY: 'auto',
  },
  // Base reset for all layers
  base: {
    marginBlockStart: 0,
    marginBlockEnd: 0,
    marginInlineStart: 0,
    marginInlineEnd: 0,
    paddingBlockStart: 0,
    paddingBlockEnd: 0,
    paddingInlineStart: 0,
    paddingInlineEnd: 0,
    borderWidth: 0,
    borderStyle: 'none',
    overflow: 'visible',
    // Override browser default [popover] background (canvas color)
    backgroundColor: 'transparent',
  },
  // Fixed positioning mode
  fixed: {
    position: 'fixed',
  },
  // Margins on the placement axis: the anchor clearance on the edge facing
  // the anchor, the viewport gutter on the far edge (spec:AST-059 FR1, FR6).
  // The margin box is what must fit a position option and what the browser's
  // overflow shift keeps inside the viewport, so a layer that would end
  // inside the gutter — or under a declared bar — does not fit there and the
  // next option is tried. A flip tactic swaps the two values with the area,
  // so the clearance stays on the anchor side and the gutter on the far side
  // (#4803); for the same reason the gutter is one value for both edges, the
  // larger of the two block gutters.
  placementBelow: (offset: string) => ({
    marginBlockStart: offset,
    marginBlockEnd: layerViewportInset.gutterBlock,
  }),
  placementAbove: (offset: string) => ({
    marginBlockStart: layerViewportInset.gutterBlock,
    marginBlockEnd: offset,
  }),
  placementEnd: (offset: string) => ({
    marginInlineStart: offset,
    marginInlineEnd: layerViewportInset.gutterInline,
  }),
  placementStart: (offset: string) => ({
    marginInlineStart: layerViewportInset.gutterInline,
    marginInlineEnd: offset,
  }),
  // Flush against the anchor (no offset): only the far-edge gutter.
  farBelow: {marginBlockEnd: layerViewportInset.gutterBlock},
  farAbove: {marginBlockStart: layerViewportInset.gutterBlock},
  farEnd: {marginInlineEnd: layerViewportInset.gutterInline},
  farStart: {marginInlineStart: layerViewportInset.gutterInline},
  // The viewport inset (spec:AST-059 FR1–FR3). Every anchor-mode layer is
  // capped to the viewport minus both gutters on both axes and keeps the
  // runtime's gutter from the far viewport edge of its alignment axis as a
  // margin (the placement-axis gutter rides the placement margins above).
  // The cap is on the layer box itself: content wider than the viewport
  // overflows inside the layer, where the composing component decides
  // whether it scrolls or clips; the box never leaves the viewport.
  // Each constant is wrapped in `calc()` so both declarations ship (see
  // layerViewportInset).
  viewportFit: {
    boxSizing: 'border-box',
    maxInlineSize: stylex.firstThatWorks(
      `calc(${layerViewportInset.maxInlineSize})`,
      `calc(${layerViewportInset.maxInlineSizeFallback})`,
    ),
    maxBlockSize: stylex.firstThatWorks(
      `calc(${layerViewportInset.maxBlockSize})`,
      `calc(${layerViewportInset.maxBlockSizeFallback})`,
    ),
  },
  // Alignment-axis gutter (spec:AST-059 FR1): a margin on the far viewport
  // edge of the alignment axis — one on the anchor-facing edge would push an
  // aligned layer off its anchor — or both edges for a centered layer. The
  // flip tactic mirrors it with the area. The slide options carry both
  // (see layerSlideRules.ts).
  gutterInlineEnd: {
    marginInlineEnd: stylex.firstThatWorks(
      `calc(${layerViewportInset.gutterInline})`,
      `calc(${layerViewportInset.gutterInlineFallback})`,
    ),
  },
  gutterInlineStart: {
    marginInlineStart: stylex.firstThatWorks(
      `calc(${layerViewportInset.gutterInline})`,
      `calc(${layerViewportInset.gutterInlineFallback})`,
    ),
  },
  gutterBlockEnd: {
    marginBlockEnd: stylex.firstThatWorks(
      `calc(${layerViewportInset.gutterBlock})`,
      `calc(${layerViewportInset.gutterBlockFallback})`,
    ),
  },
  gutterBlockStart: {
    marginBlockStart: stylex.firstThatWorks(
      `calc(${layerViewportInset.gutterBlock})`,
      `calc(${layerViewportInset.gutterBlockFallback})`,
    ),
  },
});

/**
 * Props for a control that sits on the trigger but must not dismiss the layer.
 */
interface KeepLayerOpenProps {
  onPointerDown: React.PointerEventHandler<HTMLElement>;
  /**
   * Capture phase, so spreading these props never collides with the control's
   * own `onClick`.
   */
  onClickCapture: React.MouseEventHandler<HTMLElement>;
}

/**
 * Position placement relative to anchor.
 * Logical: start/end resolve against the popover's own inherited direction
 * via CSS (RTL contexts mirror automatically, no JS involved).
 */
export type LayerPlacement = 'above' | 'below' | 'start' | 'end';

/**
 * Alignment along the placement axis
 */
export type LayerAlignment = 'start' | 'center' | 'end';

/**
 * Render props for context mode (anchor positioning)
 */
export interface ContextRenderProps {
  /**
   * Who authors the layer's position styles.
   *
   * `'anchor'` (default): the hook derives CSS anchor-positioning styles —
   * `position-area` and `position-try-fallbacks` — from the logical
   * `placement`/`alignment`.
   *
   * `'custom'`: the consumer authors its own position styles via `style`
   * (e.g. explicit `anchor()` insets or an `anchor-size()` cover). The hook
   * keeps the popover behavior and the `position-anchor` wiring but emits no
   * placement-derived styles, so direction handling becomes the consumer's
   * responsibility. `placement`/`alignment` are ignored.
   *
   * @default 'anchor'
   */
  positioning?: 'anchor' | 'custom';
  /**
   * Logical placement relative to the anchor. Ignored when `positioning`
   * is `'custom'`.
   */
  placement?: LayerPlacement;
  /**
   * Alignment along the placement axis. Ignored when `positioning`
   * is `'custom'`.
   */
  alignment?: LayerAlignment;
  /**
   * Clearance between the layer and its anchor, as a CSS length (a number is
   * treated as `px`). Applied along the placement axis and flip-safe, so the
   * gap survives a `position-try-fallbacks` flip to the opposite side.
   *
   * Layers sit flush by default: the hook zeroes the UA margins so anchor
   * positioning has a clean box, and clearance is a deliberate choice per
   * surface. `var(--spacing-1)` is the system's standard clearance.
   *
   * Ignored when `positioning` is `'custom'` — that mode owns its own insets.
   *
   * @default 0
   */
  offset?: number | string;
  /**
   * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
   * consumers complete the ARIA pattern and gives test tooling a stable,
   * non-hashed selector for the layer.
   */
  role?: string;
  /**
   * Accessible name applied to the popover container via `aria-label`.
   * Pair with `role` so layers with a named role (e.g. `'dialog'`) expose a
   * proper name to assistive technology.
   */
  'aria-label'?: string;
  /**
   * StyleX styles for the popover container.
   */
  xstyle?: StyleXStyles;
  /**
   * Additional CSS class name(s) for the popover container.
   * Use with themeProps() for theme targeting when reflecting visual props.
   */
  className?: string;
  /**
   * Inline styles for the popover container.
   * Merged after StyleX and anchor positioning styles.
   */
  style?: React.CSSProperties;
  /**
   * HTML tag to render the popover container as.
   *
   * Defaults to `'div'`. Context layers render an inert `<template>` marker at
   * the JSX position. The marker's parent is checked before the requested
   * container mounts there or portals outside ancestors that cannot safely
   * contain it. The marker remains available to detect a new parent if the
   * render call moves. With `lazyMount`, the first check waits until `show()`.
   *
   * @default 'div'
   */
  as?: 'div' | 'span';
  /**
   * Pointer-enter handler attached to the popover container itself. Lets a
   * consumer keep a hover-driven layer open while the pointer is over the
   * surface (e.g. Tooltip/HoverCard "hoverable" behavior — WCAG 1.4.13).
   */
  onMouseEnter?: React.MouseEventHandler<HTMLElement>;
  /**
   * Pointer-leave handler attached to the popover container itself.
   */
  onMouseLeave?: React.MouseEventHandler<HTMLElement>;
}

/**
 * Render props for fixed mode (manual coordinates)
 */
export interface FixedRenderProps {
  x: number;
  y: number;
  /**
   * StyleX styles for the popover container.
   */
  xstyle?: StyleXStyles;
  /**
   * Additional CSS class name(s) for the popover container.
   * Use with themeProps() for theme targeting when reflecting visual props.
   */
  className?: string;
  /**
   * Inline styles for the popover container.
   * Merged after StyleX and position styles.
   */
  style?: React.CSSProperties;
}

/**
 * Base options shared by both modes
 */
interface BaseLayerOptions {
  /**
   * Callback fired when layer is shown.
   * Wrap in useCallback for stable identity.
   */
  onShow?: () => void;

  /**
   * Callback fired when layer is hidden.
   * Wrap in useCallback for stable identity.
   */
  onHide?: () => void;

  /**
   * Whether clicking outside should dismiss the layer.
   * When true, uses popover="auto" for native light-dismiss behavior.
   * @default false
   */
  lightDismiss?: boolean;
}

/**
 * Options for context mode (CSS anchor positioning)
 */
export interface ContextLayerOptions extends BaseLayerOptions {
  mode: 'context';
  /**
   * Defer mounting the final layer and resolving its inline/portal position
   * until `show()` is requested. Hiding unmounts it while the inert marker
   * remains at the JSX position. Use this when rich content must never enter
   * an unsafe ancestor, even briefly, and does not need to exist while closed.
   *
   * @default false
   */
  lazyMount?: boolean;
}

/**
 * Options for fixed mode (manual positioning)
 */
export interface FixedLayerOptions extends BaseLayerOptions {
  mode: 'fixed';
}

/**
 * Return type for context mode
 */
export interface ContextLayerReturn {
  /**
   * Ref to attach to trigger element.
   * While the layer is shown, and until its exit animation ends, the trigger
   * carries the layer's CSS anchor name.
   */
  ref: RefCallback<HTMLElement>;

  /**
   * The CSS anchor name to use for positioning.
   * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
   * Set it only while the layer is shown or its exit animation runs.
   */
  anchorId: string;

  /**
   * Show the layer
   */
  show: () => void;

  /**
   * Hide the layer
   */
  hide: () => void;

  /**
   * Whether the layer is currently open
   */
  isOpen: boolean;

  /**
   * Unique ID for aria-describedby
   */
  id: string;

  /**
   * Render function for layer content.
   * Pass placement and alignment for anchor positioning.
   */
  render: (children: ReactNode, props?: ContextRenderProps) => ReactNode;
}

/**
 * Return type for fixed mode
 */
export interface FixedLayerReturn {
  /**
   * Ref is undefined in fixed mode (no anchor element needed)
   */
  ref: undefined;

  /**
   * Show the layer
   */
  show: () => void;

  /**
   * Hide the layer
   */
  hide: () => void;

  /**
   * Whether the layer is currently open
   */
  isOpen: boolean;

  /**
   * Unique ID for aria-describedby
   */
  id: string;

  /**
   * Render function for layer content.
   * Pass x and y coordinates for fixed positioning.
   */
  render: (children: ReactNode, props: FixedRenderProps) => ReactNode;
}

interface InternalLayerFields {
  wasJustDismissed: () => boolean;
}

/**
 * Context-mode options a core component may pass through `useLayerInternal`;
 * not part of the public `useLayer` options.
 */
interface InternalContextLayerOptions extends ContextLayerOptions {
  /**
   * The layer must never settle over its anchor (spec:AST-059 FR4). When the
   * standard fallback list settles it over its anchor, it switches to its
   * anchor-clear list: beside the trigger, then whichever block side is
   * roomier, sized to its room. For a hover-summoned layer, which the hover on
   * its trigger keeps open.
   */
  keepsAnchorClear?: boolean;
  /**
   * With `lazyMount`, the layer stays mounted once its first `show()` mounted
   * it: hiding leaves it in place, so its close plays out and every later
   * `show()` opens it at once. A layer never shown still mounts only its inert
   * marker. For a component with many triggers that each own a layer (a
   * context menu on every table cell).
   */
  keepsMountAfterShow?: boolean;
  /**
   * Runs as the layer starts to close, while the browser still shows it: in
   * its `beforetoggle` to closed. A close that plays out after the layer is
   * hidden starts here.
   */
  onCloseStart?: () => void;
}

type InternalContextLayerReturn = ContextLayerReturn & InternalLayerFields;
type InternalFixedLayerReturn = FixedLayerReturn & InternalLayerFields;

function toCssLength(value: number | string): string {
  return typeof value === 'number' ? `${value}px` : value;
}

/**
 * Make the engine choose a shown layer's position option afresh: a browser
 * keeps a laid-out layer on the option it last used until the layer stops
 * being rendered, so the layer is taken out of rendering for one forced
 * layout and restored, in the same task. No frame paints in between and the
 * popover stays open, so no toggle event fires and focus and hover are
 * untouched. Every CSS animation and transition of the layer and its content
 * is put back in the state it was in (`preserveAnimations`).
 */
function placeAfresh(layer: HTMLElement): void {
  preserveAnimations(layer, () => {
    const display = layer.style.display;
    layer.style.display = 'none';
    layer.getBoundingClientRect();
    layer.style.display = display;
  });
}

/**
 * Whether an animation is running and ends on its own. A paused or idle
 * animation does not end by itself. An animation with an infinite end time
 * never ends. Waiting on either holds the layer for good.
 */
function endsOnItsOwn(animation: Animation): boolean {
  return (
    animation.playState === 'running' &&
    animation.effect?.getComputedTiming().endTime !== Infinity
  );
}

/**
 * The finite animations still running on `layer` and its content. A layer
 * that fades out keeps running them after the browser hides it, and it stays
 * placed against its anchor until they end.
 */
function exitAnimations(layer: HTMLElement | null): Animation[] {
  if (layer == null || typeof layer.getAnimations !== 'function') {
    return [];
  }
  return layer.getAnimations({subtree: true}).filter(endsOnItsOwn);
}

/**
 * Whether the closed state's transition keeps `layer` shown after it hides.
 * Only a discrete `display` transition holds a hidden layer shown, until it
 * ends. Read it while the layer is closed: the close takes its values from
 * the closed state's style.
 */
function closeTransitionKeepsShown(layer: HTMLElement): boolean {
  const style = layer.ownerDocument.defaultView?.getComputedStyle(layer);
  if (style == null) {
    return false;
  }
  const list = (name: string) =>
    style
      .getPropertyValue(name)
      .split(',')
      .map(value => value.trim());
  const behaviors = list('transition-behavior');
  const durations = list('transition-duration').map(parseFloat);
  const delays = list('transition-delay').map(parseFloat);
  return list('transition-property').some((name, index) => {
    const behavior = behaviors[index % behaviors.length];
    const duration = durations[index % durations.length] || 0;
    const delay = delays[index % delays.length] || 0;
    return (
      (name === 'all' || name === 'display') &&
      behavior === 'allow-discrete' &&
      duration + Math.max(0, delay) > 0
    );
  });
}

/** The keyframe animations that `layer`'s style declares, or `none`. */
function animationNames(layer: HTMLElement): string {
  const style = layer.ownerDocument.defaultView?.getComputedStyle(layer);
  return style?.getPropertyValue('animation-name').trim() || 'none';
}

/**
 * Whether the standard list has failed a layer that must keep its anchor
 * clear: its box covers the anchor or, while the anchor is in view, leaves the
 * viewport on the block axis. Only a box that overlaps the anchor counts; a
 * layer flush against it does not.
 */
function failsAnchor(layer: HTMLElement, anchor: HTMLElement): boolean {
  const a = anchor.getBoundingClientRect();
  const l = settledBox(layer);
  if (l.width <= 0 || l.height <= 0) {
    return false;
  }
  const covers =
    l.left < a.right &&
    a.left < l.right &&
    l.top < a.bottom &&
    a.top < l.bottom;
  // The viewport's block extent, as the layer's anchor positioning sees it.
  const viewportBlock = layer.ownerDocument.documentElement.clientHeight;
  const anchorInView = a.bottom > 0 && a.top < viewportBlock;
  return covers || (anchorInView && (l.top < 0 || l.bottom > viewportBlock));
}

/**
 * For a layer that must never settle over its anchor (spec:AST-059 FR4). Every
 * option of its one combined fallback list keeps it clear of its anchor, and
 * the engine picks one. Where the box still covers the anchor or, while the
 * anchor is in view, leaves the viewport on the block axis, the layer is
 * placed afresh (`placeAfresh`) from that list. The runtime calls this in the
 * same task as every show and remount, and while the layer is open whenever
 * its size, its content's size, its anchor's size or the viewport changes;
 * each of those reads lands before the next frame paints. It also runs once
 * in the first frame painted after a scroll of the anchor stops
 * (`observeScrollStop`), because during a scroll the browser does not choose
 * an option again. Nothing watches an anchor that moves without resizing, so
 * the layer never jumps to another side mid-scroll.
 */
function keepAnchorClear(layer: HTMLElement, anchor: HTMLElement | null): void {
  if (anchor && failsAnchor(layer, anchor)) {
    placeAfresh(layer);
  }
}

/**
 * How long a scroll must stay still, in ms, to count as stopped where the
 * browser does not fire `scrollend`.
 */
const SCROLL_STILL_MS = 150;

/**
 * The shadow roots along `node`'s flat-tree path. `scroll` and `scrollend`
 * are not composed, so a scroll inside a shadow tree reaches its shadow root
 * but not the window.
 */
function shadowRootsAbove(node: Node): ShadowRoot[] {
  const roots: ShadowRoot[] = [];
  for (
    let current: Node | null = node;
    current;
    current = parentAcrossShadow(current)
  ) {
    const root = current.getRootNode();
    if (isShadowRoot(root) && !roots.includes(root)) {
      roots.push(root);
    }
  }
  return roots;
}

/**
 * Calls `onStop` once each time a scroll of the page or of an ancestor of
 * `anchor` stops, in the first frame painted after it stops. During a scroll,
 * Chromium does not choose a layer's position option again, so the layer is
 * checked once the scroll stops. A scroll stops at `scrollend`; where the
 * browser does not fire it, a scroll stops after `SCROLL_STILL_MS` with no
 * `scroll` event. A scroll that starts again before the check cancels it. No
 * handler reads layout.
 */
function observeScrollStop(
  view: Window,
  anchor: HTMLElement,
  onStop: () => void,
): () => void {
  let frame: number | null = null;
  let timer: number | null = null;
  const cancel = () => {
    if (frame !== null) {
      view.cancelAnimationFrame(frame);
      frame = null;
    }
    if (timer !== null) {
      view.clearTimeout(timer);
      timer = null;
    }
  };
  // At `scrollend`, and in the frame after it, Chromium still reads the
  // anchored layer at its position before the scroll. After one painted
  // frame it reads the position the scroll gave it.
  const callAfterNextPaint = () => {
    cancel();
    frame = view.requestAnimationFrame(() => {
      frame = null;
      timer = view.setTimeout(() => {
        timer = null;
        frame = view.requestAnimationFrame(() => {
          frame = null;
          onStop();
        });
      });
    });
  };
  const firesScrollEnd =
    (view as {onscrollend?: unknown}).onscrollend !== undefined;
  const isAnchorScroll = (event: Event) =>
    containsAlongFlatTree(event.target as Node, anchor);
  const onScroll = (event: Event) => {
    if (!isAnchorScroll(event)) {
      return;
    }
    cancel();
    if (!firesScrollEnd) {
      timer = view.setTimeout(() => {
        timer = null;
        callAfterNextPaint();
      }, SCROLL_STILL_MS);
    }
  };
  const onScrollEnd = (event: Event) => {
    if (isAnchorScroll(event)) {
      callAfterNextPaint();
    }
  };
  const unsubscribes = [subscribeInput(view, 'scroll', onScroll)];
  if (firesScrollEnd) {
    unsubscribes.push(subscribeInput(view, 'scrollend', onScrollEnd));
  }
  const listening = {capture: true, passive: true};
  const shadowRoots = shadowRootsAbove(anchor);
  for (const shadowRoot of shadowRoots) {
    shadowRoot.addEventListener('scroll', onScroll, listening);
    if (firesScrollEnd) {
      shadowRoot.addEventListener('scrollend', onScrollEnd, listening);
    }
  }
  return () => {
    for (const unsubscribe of unsubscribes) {
      unsubscribe();
    }
    for (const shadowRoot of shadowRoots) {
      shadowRoot.removeEventListener('scroll', onScroll, listening);
      shadowRoot.removeEventListener('scrollend', onScrollEnd, listening);
    }
    cancel();
  };
}

/**
 * Watch an open layer that keeps its anchor clear, and its anchor, for every
 * change that can re-settle the layer over the anchor (spec:AST-059 FR4, FR8):
 * the layer, its content or the anchor resizing (ResizeObserver, before
 * paint), the viewport resizing (before paint), and a scroll of the anchor
 * stopping (`observeScrollStop`, in the first frame painted after it). Each
 * calls `keepAnchorClear` for this layer and anchor while `isCurrent` says
 * they are still the live pair. Returns the function that removes every
 * observer and listener it added.
 */
function observeAnchorClearance(
  layer: HTMLElement,
  anchor: HTMLElement,
  isCurrent: () => boolean,
): () => void {
  const view = layer.ownerDocument.defaultView;
  if (!view) {
    return () => {};
  }
  const reread = () => {
    if (isCurrent()) {
      keepAnchorClear(layer, anchor);
    }
  };
  let observer: ResizeObserver | null = null;
  if (typeof ResizeObserver !== 'undefined') {
    observer = new ResizeObserver(reread);
    observer.observe(layer);
    for (const child of Array.from(layer.children)) {
      observer.observe(child);
    }
    observer.observe(anchor);
  }
  view.addEventListener('resize', reread);
  const stopObservingScrollStop = observeScrollStop(view, anchor, reread);
  return () => {
    observer?.disconnect();
    stopObservingScrollStop();
    view.removeEventListener('resize', reread);
  };
}

/** Whether `element` is shown as a popover (`:popover-open`). */
function isShownAsPopover(element: HTMLElement): boolean {
  try {
    return element.matches(':popover-open');
  } catch {
    // An engine without the pseudo-class has no popovers to be shown as.
    return false;
  }
}

/**
 * Whether `anchor` is a valid CSS anchor right now: it has a layout box, and
 * any `<dialog>` it sits in is showing, as a modal (`open`) or as a popover
 * (a non-modal `Drawer` is shown with `showPopover()` and never `open`).
 * `Dialog` displays its element during render but only calls `showModal()` in
 * a later Effect, so in that window the trigger already has a box while the
 * dialog is not yet in the top layer; opening a layer then paints it before
 * the dialog is modal.
 */
function isAnchorReady(anchor: HTMLElement): boolean {
  // No layout box at all: `display: none`, or inside a closed `<dialog>`. An
  // element that renders but is empty (an inline `<span>` with no content, such
  // as a ContextMenu's cursor anchor in a shadow root without Astryx's styles)
  // still has one 0x0 client rect and is a valid anchor.
  if (anchor.getClientRects().length === 0) {
    return false;
  }
  const dialog = anchor.closest('dialog');
  return dialog == null || dialog.open || isShownAsPopover(dialog);
}

/**
 * Calls `onReady` one frame later, once every running animation that ends on
 * its own, on the document timeline, on `anchor` or an ancestor, has finished.
 * Calls it synchronously if `document.getAnimations` does not exist (jsdom).
 * Returns a cancel function.
 *
 * `getBoundingClientRect()` reflects an ancestor's CSS transform, so an
 * anchor sitting inside a running entry animation — Dialog's own
 * scale/translate enter transition, e.g. — keeps reporting a different box
 * every frame for as long as that animation runs, even though a
 * `ResizeObserver` sees no size change at all (a transform never changes the
 * anchor's own layout box). Anchoring a layer to the trigger's box mid
 * transition, rather than the one it settles into, has produced a CSS
 * anchor-positioning resolution that never gets revisited once the trigger
 * stops moving: the layer is stranded at its unanchored fallback position
 * for the rest of that open.
 *
 * The check itself waits one frame before reading `document.getAnimations()`:
 * a CSS animation just triggered by a `display`/class change (exactly what
 * unhides a Dialog's content) is not yet in that list in the same task —
 * measured directly, not assumed — so checking synchronously would always see
 * zero animations and defeat the whole guard. One frame is enough for the UA
 * to have started it.
 *
 * The wait skips an animation that never ends by itself: a paused one, an
 * infinite one such as `StatusDot`'s pulse, and a scroll- or view-driven one.
 * `Animation.finished` never resolves for these, so waiting on them would
 * block a layer that anchors to them from ever opening.
 */

function waitForAncestorAnimations(
  anchor: HTMLElement,
  onReady: () => void,
): () => void {
  if (typeof document.getAnimations !== 'function') {
    onReady();
    return () => {};
  }
  let cancelled = false;
  const handle = requestAnimationFrame(() => {
    if (cancelled) {
      return;
    }
    const running = document.getAnimations().filter(animation => {
      const target =
        animation.effect instanceof KeyframeEffect
          ? animation.effect.target
          : null;
      if (
        !(target instanceof Node) ||
        !(target === anchor || target.contains(anchor))
      ) {
        return false;
      }
      // A scroll- or view-driven animation finishes only when the person
      // scrolls to the end of its range, so it is not a settle to wait on.
      if (animation.timeline !== document.timeline) {
        return false;
      }
      return endsOnItsOwn(animation);
    });
    if (running.length === 0) {
      onReady();
      return;
    }
    void Promise.all(
      running.map(async animation => animation.finished.catch(() => {})),
    ).then(() => {
      if (!cancelled) {
        onReady();
      }
    });
  });
  return () => {
    cancelled = true;
    cancelAnimationFrame(handle);
  };
}

interface ContextLayerMount {
  /** Null means the marker's parent is safe and the layer stays inline. */
  portalTarget: HTMLElement | null;
  /**
   * Logical writing context lost when moving outside an unsafe ancestor, or
   * null until it is read. A closed layer mounted ahead of its first show
   * reads it in `show()`, before the layer opens: reading computed style for
   * every closed layer on mount forces a style recalculation per layer.
   */
  portalStyle: React.CSSProperties | null;
}

/**
 * Where a context layer is hosted, published to the one component that
 * renders it. The hook resolves the mount from the marker's parent once the
 * marker is in the DOM, and the slot below subscribes to it, so the render
 * that places the layer re-renders the slot alone: the hook's host (a
 * Tooltip, a Popover, a menu) and everything under it render once on mount.
 */
interface ContextLayerMountStore {
  readonly get: () => ContextLayerMount | null;
  readonly set: (mount: ContextLayerMount | null) => void;
  readonly subscribe: (onChange: () => void) => () => void;
}

function createContextLayerMountStore(): ContextLayerMountStore {
  let mount: ContextLayerMount | null = null;
  const listeners = new Set<() => void>();
  return {
    get: () => mount,
    set: next => {
      if (next === mount) {
        return;
      }
      mount = next;
      for (const listener of listeners) {
        listener();
      }
    },
    subscribe: onChange => {
      listeners.add(onChange);
      return () => {
        listeners.delete(onChange);
      };
    },
  };
}

const readNoMount = (): ContextLayerMount | null => null;

/**
 * The marker and, once the hook has resolved where it goes, the layer. The
 * server and the hydrating render carry the marker alone, so block content
 * never enters server markup inside `<p>` and its kin; the mount arrives from
 * the marker's ref callback, and only this component re-renders to place the
 * layer.
 */
function ContextLayerSlot({
  mountStore,
  renderLayer,
  sentinelRef,
}: {
  readonly mountStore: ContextLayerMountStore;
  readonly renderLayer: (mount: ContextLayerMount) => ReactNode;
  readonly sentinelRef: RefCallback<HTMLTemplateElement>;
}) {
  const mount = useSyncExternalStore(
    mountStore.subscribe,
    mountStore.get,
    readNoMount,
  );
  // Keep the marker mounted after resolving the layer. Apart from giving
  // us the real JSX parent on first show, this lets its ref report when a
  // persistent hook's render call moves to a different host.
  const sentinel = <template ref={sentinelRef} />;
  if (mount === null) {
    return <>{sentinel}</>;
  }
  const layer = renderLayer(mount);
  return (
    <>
      {sentinel}
      {mount.portalTarget ? createPortal(layer, mount.portalTarget) : layer}
    </>
  );
}

function readPortalWritingContext(
  element: HTMLElement,
  portalTarget: HTMLElement,
): React.CSSProperties {
  const view = element.ownerDocument.defaultView;
  if (!view) {
    return {};
  }
  const sourceStyle = view.getComputedStyle(element);
  const targetStyle = view.getComputedStyle(portalTarget);

  // Do not snapshot custom properties here. The portal target is the closest
  // safe ancestor, so theme variables continue to inherit and update there.
  // These two properties can be set on the unsafe chain itself and directly
  // affect the logical anchor-positioning keywords used by the layer. Only
  // override values the portal would actually lose; matching values should
  // keep inheriting from the target so later direction changes remain live.
  return {
    ...(sourceStyle.direction !== targetStyle.direction && {
      direction: sourceStyle.direction as React.CSSProperties['direction'],
    }),
    ...(sourceStyle.writingMode !== targetStyle.writingMode && {
      writingMode:
        sourceStyle.writingMode as React.CSSProperties['writingMode'],
    }),
  };
}

/**
 * Map logical placement/alignment to a CSS position-area value.
 *
 * Uses the self-* logical keyword family: the inline axis resolves against
 * the popover's own direction (inherited inline or preserved when portaled),
 * so it mirrors in RTL without placement-specific JS. The block axis is
 * direction-neutral but must come from the same keyword family — mixing
 * physical `top` with `self-inline-*` produces an invalid position-area
 * (computes to `none`, which pins the popover to the viewport corner because
 * styles.base zeroes the UA margins).
 *
 * Note the plain logical family (`inline-start`, no `self-`) is NOT a
 * substitute: it resolves against the containing block — the page root for
 * a top-layer popover — so it ignores `direction` set on a subtree, which
 * is exactly #3389's repro.
 */
function getPositionArea(
  placement: LayerPlacement = 'above',
  alignment: LayerAlignment = 'center',
): string {
  if (placement === 'above' || placement === 'below') {
    const block = placement === 'above' ? 'self-block-start' : 'self-block-end';
    if (alignment === 'start') {
      return `${block} span-self-inline-end`;
    }
    if (alignment === 'end') {
      return `${block} span-self-inline-start`;
    }
    return block; // center
  }

  const inline =
    placement === 'start' ? 'self-inline-start' : 'self-inline-end';
  if (alignment === 'start') {
    return `${inline} span-self-block-end`;
  }
  if (alignment === 'end') {
    return `${inline} span-self-block-start`;
  }
  return inline; // center
}

/**
 * Compute the `position-try-fallbacks` list for a placement/alignment pair
 * (spec:AST-059 FR4).
 *
 * Flips first; they mirror the placement-axis margins (clearance and gutter)
 * and the alignment-axis gutter with the area. Then the slide: named
 * `@position-try` options whose area spans the whole alignment axis
 * (`layerSlideRules.ts`), same side of the trigger first, opposite side
 * second. Flips alone cannot rescue a layer wider than the room on either
 * side of its trigger — every flipped option overflows the alignment axis
 * too, and the browser keeps the base option, so the layer never moves to the
 * side of the trigger that has room on the placement axis (#3671 for centered
 * layers, where a flip maps center → center). A slide option fits wherever
 * the layer fits the viewport; its anchor-center alignment plus the browser's
 * overflow shift keep the layer's margin box — and so the gutter on both
 * edges — inside the viewport. Centered layers keep their one-sided spans
 * ahead of the full span so they slide the least distance first.
 */
export function getPositionTryFallbacks(
  placement: LayerPlacement = 'above',
  alignment: LayerAlignment = 'center',
): string {
  const flips = 'flip-block, flip-inline, flip-block flip-inline';
  const slides = `${slideRuleName(placement, alignment, 'same')}, ${slideRuleName(placement, alignment, 'opposite')}`;

  if (alignment !== 'center') {
    return `${flips}, ${slides}`;
  }

  if (placement === 'above' || placement === 'below') {
    const [same, opposite] =
      placement === 'above' ? ['top', 'bottom'] : ['bottom', 'top'];
    return `${flips}, ${same} span-left, ${same} span-right, ${opposite} span-left, ${opposite} span-right, ${slides}`;
  }

  const [same, opposite] =
    placement === 'start' ? ['left', 'right'] : ['right', 'left'];
  return `${flips}, ${same} span-top, ${same} span-bottom, ${opposite} span-top, ${opposite} span-bottom, ${slides}`;
}

/**
 * The self-alignment an aligned layer uses while its anchor is out of view
 * (spec:AST-059 FR5). A position-area box that overflows the room beside its
 * anchor is shifted by default to stay inside the viewport — the slide an
 * aligned layer relies on when it fits on neither side (FR4). Once the anchor
 * has left the viewport that shift would pin the layer into the narrowest
 * strip at the edge, so the alignment is pinned `unsafe` toward the anchor
 * instead and the layer holds the position its flips give it. `self-*`
 * keywords resolve against the layer's own direction, matching the `self-*`
 * position-area family; the flip tactics swap start/end with the area.
 *
 * Centered layers already slide through their span fallbacks and are
 * unchanged; a visible anchor keeps the browser's default alignment.
 */
export function getSelfAlignment(
  placement: LayerPlacement,
  alignment: LayerAlignment,
  isAnchorInView: boolean,
): React.CSSProperties {
  if (isAnchorInView || alignment === 'center') {
    return {};
  }
  const edge = alignment === 'start' ? 'unsafe self-start' : 'unsafe self-end';
  return placement === 'above' || placement === 'below'
    ? {justifySelf: edge}
    : {alignSelf: edge};
}

/**
 * The gutter styles for a placement/alignment pair: the far viewport edge of
 * the alignment axis, or both edges when centered (spec:AST-059 FR1).
 */
function getGutterStyles(
  placement: LayerPlacement,
  alignment: LayerAlignment,
): ReadonlyArray<StyleXStyles> {
  if (placement === 'above' || placement === 'below') {
    if (alignment === 'start') {
      return [styles.gutterInlineEnd];
    }
    if (alignment === 'end') {
      return [styles.gutterInlineStart];
    }
    return [styles.gutterInlineStart, styles.gutterInlineEnd];
  }
  if (alignment === 'start') {
    return [styles.gutterBlockEnd];
  }
  if (alignment === 'end') {
    return [styles.gutterBlockStart];
  }
  return [styles.gutterBlockStart, styles.gutterBlockEnd];
}

/**
 * Internal props for controls that sit beside an open layer. This stays out of
 * the public useLayer/usePopover return types until the input family adopts it.
 */
export function useKeepLayerOpenProps(
  id: string,
  isOpen: boolean,
): KeepLayerOpenProps {
  const isOpenRef = useRef(isOpen);
  isOpenRef.current = isOpen;

  return useMemo(
    () => ({
      onPointerDown: (event: React.PointerEvent<HTMLElement>) => {
        if (!isOpenRef.current) {
          return;
        }
        // The browser reads the invoker relationship at both ends of the press.
        const control = event.currentTarget;
        const doc = control.ownerDocument;
        control.setAttribute('popovertarget', id);
        const onPressEnd = () => {
          doc.removeEventListener('pointerup', onPressEnd);
          doc.removeEventListener('pointercancel', onPressEnd);
          // Light dismiss runs as the pointerup default action after listeners.
          doc.defaultView?.setTimeout(() => {
            control.removeAttribute('popovertarget');
          }, 0);
        };
        doc.addEventListener('pointerup', onPressEnd);
        doc.addEventListener('pointercancel', onPressEnd);
      },
      onClickCapture: (event: React.MouseEvent<HTMLElement>) => {
        const control = event.currentTarget;
        if (control.hasAttribute('popovertarget')) {
          // Being an invoker would otherwise toggle the layer shut.
          event.preventDefault();
          control.removeAttribute('popovertarget');
        }
      },
    }),
    [id],
  );
}

/**
 * Core layer hook that handles popover behavior and positioning.
 *
 * Supports two positioning modes with type-safe render props:
 * - `context`: CSS anchor positioning relative to a trigger element
 * - `fixed`: Fixed positioning at specified coordinates
 *
 * @example
 * ```
 * const layer = useLayer({ mode: 'context' });
 * <button ref={layer.ref}>Trigger</button>
 * {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
 * ```
 */
function useLayerImplementation(
  options: InternalContextLayerOptions | FixedLayerOptions,
): InternalContextLayerReturn | InternalFixedLayerReturn {
  const {mode, onShow, onHide, lightDismiss = false} = options;
  const lazyMount = mode === 'context' ? (options.lazyMount ?? false) : false;
  const keepsMountAfterShow =
    lazyMount && mode === 'context'
      ? (options.keepsMountAfterShow ?? false)
      : false;
  const keepsAnchorClear =
    mode === 'context' ? (options.keepsAnchorClear ?? false) : false;
  const onCloseStartRef = useRef<(() => void) | undefined>(undefined);
  onCloseStartRef.current =
    mode === 'context' ? options.onCloseStart : undefined;
  const id = useId();
  const anchorId = `--astryx-layer-${id.replace(/:/g, '')}`;

  const [isOpen, setIsOpen] = useState(false);
  // Whether the anchor is inside the viewport (spec:AST-059 FR5). The slide
  // fallback is withdrawn while it is not, so an aligned layer holds its
  // position and size instead of chasing an anchor nobody can see.
  const [isAnchorInView, setIsAnchorInView] = useState(true);
  // Mirror so the pre-paint read commits nothing when the answer is unchanged.
  const isAnchorInViewRef = useRef(true);
  const updateAnchorInView = useCallback((inView: boolean) => {
    if (isAnchorInViewRef.current !== inView) {
      isAnchorInViewRef.current = inView;
      setIsAnchorInView(inView);
    }
  }, []);
  // The inset the app declared on LayerProvider (FR6). Read through context
  // and written inline on the layer, so a corrective portal cannot escape it
  // and no measurement is needed to apply it.
  const layerContext = useLayerContext();
  const declaredInset = layerContext?.inset;
  const popoverRef = useRef<HTMLElement | null>(null);
  // The DOM element on which the current logical open state was applied.
  // A portal target change replaces the popover element; retaining the old
  // reference lets the ref callback recognize and reopen its replacement.
  const openedPopoverRef = useRef<HTMLElement | null>(null);
  const triggerRef = useRef<HTMLElement | null>(null);
  // A detach (contextRef(null)) still in its transient window — cancelled if
  // the same element reattaches before the microtask runs, applied
  // (removing the anchor name) otherwise. See contextRef below.
  const pendingTriggerDetachRef = useRef<{
    element: HTMLElement;
    cancelled: boolean;
  } | null>(null);
  // Context layers place a persistent inert marker at their real JSX position.
  // Its parent tells us whether the final layer can stay inline or needs a
  // corrective portal, including after the render call moves.
  const sentinelRef = useRef<HTMLTemplateElement | null>(null);
  const contextMountRef = useRef<ContextLayerMount | null>(null);
  // The resolved mount reaches the slot through this store, never through
  // state on this hook, so placing the layer renders the slot alone. The
  // generation counts mounts that REPLACE a resolved one (a render call that
  // moved to another host): the layer element is recreated then, and the
  // effects below that bind to it re-run.
  const [mountStore] = useState(createContextLayerMountStore);
  const [mountGeneration, setMountGeneration] = useState(0);
  // A show() that cannot run yet is remembered here and replayed: one that
  // arrives before the final layer mounts runs when its popover ref attaches;
  // one that arrives while another popover is mid show/hide runs once that
  // operation has unwound. hide() forgets it either way.
  const pendingShowRef = useRef(false);

  // Ref mirrors isOpen for synchronous reads inside show/hide.
  // State drives re-renders; the ref lets the imperative calls avoid
  // stale-closure reads of the previous isOpen value.
  const isOpenRef = useRef(false);

  // The exit of the layer that closed last, while it still paints. Its
  // trigger stays an anchor until it ends, also when the trigger attaches
  // again during it. Null once it has ended.
  const exitRef = useRef<object | null>(null);

  // Read at the last show, from the closed state's style.
  const closeKeepsShownRef = useRef(false);

  // A closed trigger is no anchor, once the layer stops painting. A show
  // during the exit keeps the name, and so does a later exit.
  const releaseAnchor = useCallback(
    (layer: HTMLElement | null) => {
      const exit = {};
      exitRef.current = exit;
      const release = () => {
        if (exitRef.current !== exit) {
          return;
        }
        exitRef.current = null;
        const trigger = triggerRef.current;
        if (!isOpenRef.current && trigger != null) {
          removeAnchorName(trigger, anchorId);
        }
      };
      // The animation read lays out the page between the writes of the close.
      // Skip it when the layer stops painting as it hides.
      const running = closeKeepsShownRef.current ? exitAnimations(layer) : [];
      if (running.length === 0) {
        release();
        return;
      }
      void Promise.all(
        running.map(async animation =>
          animation.finished.catch(() => undefined),
        ),
      ).then(release);
    },
    [anchorId],
  );

  // The gesture during which the browser last closed this layer on its own.
  // Read through wasJustDismissed by triggers deciding whether a click is
  // theirs to act on.
  const dismissedByGestureRef = useRef<number | null>(null);
  const forgetDismissalRef = useRef<(() => void) | null>(null);

  const wasJustDismissed = useCallback(() => {
    const gesture = currentGesture();
    return dismissedByGestureRef.current === gesture;
  }, []);

  /**
   * Asks the browser to show the popover. Returns false when the browser
   * refused with an `InvalidStateError` while a hide it runs itself is still
   * in flight (the ledger counts it from `beforetoggle`); the caller then
   * replays the show once that hide has ended. Any other failure, and a
   * refusal outside such a hide, reaches the caller: a replay runs outside
   * the hide, so one that fails is not caught here.
   */
  const showPopoverElement = useCallback((popover: HTMLElement): boolean => {
    // Finding infra-4: the Popover API is unsupported on Safari <17 and
    // Firefox <125. On those browsers `showPopover` does not exist, so fall
    // back to plain visibility instead of throwing.
    if (typeof popover.showPopover === 'function') {
      const doc = popover.ownerDocument;
      const duringBrowserHide = isBrowserHideInFlight(doc);
      try {
        runPopoverOperation(doc, () => {
          // The trigger is passed as the popover's invoker `source`: a layer
          // 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.
          // The check asks the trigger's own window: an HTML trigger rendered
          // into another document (an iframe, a Picture-in-Picture window) is
          // not an instance of this window's `HTMLElement`, and keeps its
          // source.
          const trigger = triggerRef.current;
          const triggerView = trigger?.ownerDocument.defaultView;
          popover.showPopover({
            source:
              triggerView != null && trigger instanceof triggerView.HTMLElement
                ? trigger
                : undefined,
          });
        });
      } catch (error) {
        // The name, not the constructor: a popover in another document throws
        // that document's `DOMException`.
        if (
          duringBrowserHide &&
          (error as {name?: unknown} | null)?.name === 'InvalidStateError'
        ) {
          return false;
        }
        throw error;
      }
    } else {
      popover.style.display = 'block';
    }
    openedPopoverRef.current = popover;
    return true;
  }, []);

  const isCurrentContextPopover = useCallback(
    (popover: HTMLElement): boolean => {
      if (mode !== 'context') {
        return true;
      }
      const mount = contextMountRef.current;
      if (mount === null) {
        return false;
      }
      const expectedParent =
        mount.portalTarget ?? sentinelRef.current?.parentElement ?? null;
      return popover.parentElement === expectedParent;
    },
    [mode],
  );

  const requestContextMount = useCallback(() => {
    if (mode !== 'context') {
      return;
    }

    const sentinel = sentinelRef.current;
    const inlineParent = sentinel?.parentElement ?? null;
    if (!sentinel || !inlineParent) {
      return;
    }

    // The slide options' `@position-try` rules (FR4) are installed in the
    // layer's document before its first paint, here where the mount resolves:
    // the marker's arrival is the one event every mount has, whether the
    // render call mounts with its host or later. One sheet serves every layer.
    ensureSlideRules(sentinel.ownerDocument);

    const portalTarget = resolveLayerPortalTarget(inlineParent);
    // A mount for a layer that is opening or open reads its writing context
    // now; a closed layer's waits for its first show.
    const opening = pendingShowRef.current || isOpenRef.current;
    const mount: ContextLayerMount = {
      portalTarget,
      portalStyle:
        portalTarget == null
          ? {}
          : opening
            ? readPortalWritingContext(sentinel, portalTarget)
            : null,
    };
    const replaced = contextMountRef.current !== null;
    contextMountRef.current = mount;
    mountStore.set(mount);
    if (replaced) {
      setMountGeneration(generation => generation + 1);
    }
  }, [mode, mountStore]);

  // Reads the writing context a closed layer's mount deferred, before the
  // layer opens. It is written on the popover at once, so the first open frame
  // already has it (layer-runtime INV12), and published to the slot, whose
  // render writes the same values. A value the caller's own `style` sets is
  // already inline and wins, as it does in render.
  const applyDeferredWritingContext = useCallback(
    (popover: HTMLElement) => {
      const mount = contextMountRef.current;
      const sentinel = sentinelRef.current;
      if (
        mount === null ||
        mount.portalTarget === null ||
        mount.portalStyle !== null ||
        sentinel === null
      ) {
        return;
      }
      const portalStyle = readPortalWritingContext(
        sentinel,
        mount.portalTarget,
      );
      if (portalStyle.direction != null && popover.style.direction === '') {
        popover.style.direction = portalStyle.direction;
      }
      if (portalStyle.writingMode != null && popover.style.writingMode === '') {
        popover.style.writingMode = portalStyle.writingMode;
      }
      const next: ContextLayerMount = {...mount, portalStyle};
      contextMountRef.current = next;
      mountStore.set(next);
    },
    [mountStore],
  );

  const clearContextMount = useCallback(() => {
    if (mode !== 'context' || !lazyMount || keepsMountAfterShow) {
      return;
    }
    contextMountRef.current = null;
    mountStore.set(null);
  }, [mode, lazyMount, keepsMountAfterShow, mountStore]);

  const openNow = useCallback(() => {
    // Every caller lands here, so this is where the dismissing press is
    // absorbed: opening now would reopen the popup that same press closed.
    if (wasJustDismissed()) {
      return;
    }
    // A context popover left over until React commits a previous hide must not
    // be reopened. The synchronous mount ref is the source of truth.
    const candidate = popoverRef.current;
    const popover =
      candidate && isCurrentContextPopover(candidate) ? candidate : null;
    if (!popover) {
      pendingShowRef.current = true;
      requestContextMount();
      return;
    }
    if (!isOpenRef.current) {
      const replayWhenSettled = () => {
        pendingShowRef.current = true;
        afterPopoverOperations(popover.ownerDocument, () => {
          if (pendingShowRef.current) {
            pendingShowRef.current = false;
            showRef.current();
          }
        });
      };
      // Another layer's own show or hide is running (typically a hide that is
      // handing focus back to this layer's trigger): the browser would refuse
      // the show, so replay this call once that operation has returned.
      if (isPopoverOperationInFlight(popover.ownerDocument)) {
        replayWhenSettled();
        return;
      }
      // The close takes its values from the closed state's style. Read it
      // before the writes of the show, so the read lays nothing out.
      const closeTransitionHolds = closeTransitionKeepsShown(popover);
      const closedAnimations = animationNames(popover);
      applyDeferredWritingContext(popover);
      // The trigger takes the layer's anchor name in the task that shows the
      // layer, so the layer's first frame is placed against it.
      const anchor = triggerRef.current;
      if (anchor != null) {
        addAnchorName(anchor, anchorId);
      }
      // A hide the browser runs itself (an Escape its close watcher answers)
      // is counted too, from `beforetoggle` until the element's `toggle`, a
      // task after the hide has returned. The show is asked of the browser
      // first, because the browser accepts it once its hide has returned (a
      // light dismiss at pointerup, then this show at the click); only a show
      // it refuses replays once the hide's count has ended.
      if (!showPopoverElement(popover)) {
        // The replay anchors the trigger again; until then it is closed. An
        // exit still running keeps the name.
        if (anchor != null && exitRef.current == null) {
          removeAnchorName(anchor, anchorId);
        }
        replayWhenSettled();
        return;
      }
      // A keyframe animation that only the closed state declares starts at
      // the close, and it can animate `display`. One that both states declare
      // is the entrance, and the hide stops it.
      const closeStartsAnimation =
        closedAnimations !== 'none' &&
        closedAnimations !== animationNames(popover);
      closeKeepsShownRef.current = closeTransitionHolds || closeStartsAnimation;
      if (lightDismiss) {
        claimContextMenuPress(popover);
      }
      if (keepsAnchorClear) {
        keepAnchorClear(popover, triggerRef.current);
      }
      isOpenRef.current = true;
      setIsOpen(true);
      onShow?.();
    }
  }, [
    anchorId,
    onShow,
    keepsAnchorClear,
    lightDismiss,
    requestContextMount,
    applyDeferredWritingContext,
    showPopoverElement,
    isCurrentContextPopover,
    wasJustDismissed,
  ]);

  // A wait for the trigger to get a layout box, started by a show() that
  // found none. Cancelled by the next show()/hide() or by
  // unmount, so a stale wait from a closed-then-reopened layer never fires
  // openNow() after the fact.
  const pendingAnchorWaitRef = useRef<(() => void) | null>(null);
  // The element that wait is observing, so a trigger swapped out underneath it
  // can restart the wait on the new element (see `contextRef`).
  const pendingAnchorElementRef = useRef<HTMLElement | null>(null);

  // The deferred restart `contextRef` queues after a trigger swap. Any
  // show()/hide() or a new wait supersedes it, so a layer that was hidden in
  // the same commit never reopens by itself.
  const pendingRestartRef = useRef<{cancelled: boolean} | null>(null);

  const cancelPendingAnchorWait = useCallback(() => {
    pendingAnchorWaitRef.current?.();
    pendingAnchorWaitRef.current = null;
    pendingAnchorElementRef.current = null;
    if (pendingRestartRef.current) {
      pendingRestartRef.current.cancelled = true;
      pendingRestartRef.current = null;
    }
  }, []);

  // A wait that reached its end: nothing is pending any more, so a later
  // trigger swap must not restart it.
  const finishAnchorWait = useCallback(() => {
    pendingAnchorWaitRef.current = null;
    pendingAnchorElementRef.current = null;
  }, []);

  // A trigger with no layout box (no client rect) is not a valid CSS anchor. Opening against it now resolves the popover to
  // its fallback position (the viewport corner), and unlike a live layout
  // change, that resolution does not get revisited once the trigger later
  // gets a box: the popover is stuck there for the rest of this open.
  //
  // The concrete case this guards: a Dialog mounts its children before it
  // opens (`isOpen` gates only `showModal()`, not rendering), so a context
  // layer with `isDefaultOpen` or a controlled `isOpen={true}` inside one can
  // mount, and show() can run, while the trigger sits inside a `<dialog>`
  // that hasn't gone modal yet and so has no box. Anchor readiness lives here
  // rather than in each caller because this is the one place that already
  // owns the trigger element (`triggerRef`, set by `contextRef` below) and the
  // one place every context-mode show() funnels through.
  const show = useCallback(() => {
    cancelPendingAnchorWait();

    const anchor = mode === 'context' ? triggerRef.current : null;
    if (!anchor) {
      openNow();
      return;
    }
    if (isAnchorReady(anchor)) {
      // A trigger that already has a layout box is a valid anchor: open now, in the
      // same task as the interaction that asked, so a menu still opens on
      // press and not on the next frame. Only a trigger with no layout box has to wait.
      openNow();
      return;
    }
    // No layout engine to wait on (jsdom, an old browser): same fallback
    // sharedResizeObserver.ts uses for the same gap. Skip the wait rather than
    // throw, and open against whatever box is available now. A missing
    // `document.getAnimations` is the signal for "no real layout" here: jsdom
    // reports every box as 0x0 forever, so a ResizeObserver stub that never
    // fires would otherwise hold every layer closed.
    if (
      typeof ResizeObserver === 'undefined' ||
      typeof document.getAnimations !== 'function'
    ) {
      openNow();
      return;
    }
    // The wait is driven by signals, never by polling. Any of them re-reads `isAnchorReady`; the first that
    // finds the anchor ready wins. None resolves against a boxless trigger, so
    // a layer whose container gains layout much later still ends up anchored,
    // not opened against a 0x0 box because a cap gave up first:
    //
    // - ResizeObserver: a block-level trigger gaining a box.
    // - IntersectionObserver: reports a `display: inline` trigger, which
    //   ResizeObserver never delivers an entry for, such as the wrapper
    //   `<span>` of a text-only Tooltip or HoverCard. It also fires
    //   when a hidden ancestor is displayed.
    // - The enclosing `<dialog>`'s `open` attribute and `toggle` event: the
    //   trigger can have a box before the dialog is modal (see
    //   `isAnchorReady`), and a popover-shown dialog never sets `open`.
    //
    // A ResizeObserver stub that fires synchronously (several component tests
    // use one) resolves exactly as fast as it always did. Environments with no
    // real layout ever are excluded before this point.
    const anchorElement: HTMLElement = anchor;
    const dialog = anchor.closest('dialog');
    let cancelSettleWait: () => void = () => {};
    let resolved = false;
    // The shared observers hand back an unsubscribe for this
    // registration only, so the teardown does not touch other observers of the
    // same element.
    let stopResize: () => void = () => {};
    let stopMutations: () => void = () => {};
    const release = () => {
      stopResize();
      intersection?.disconnect();
      stopMutations();
      dialog?.removeEventListener('toggle', check);
    };
    const resolve = () => {
      resolved = true;
      release();
      // Once the box exists, a short settle wait lets an ancestor's running
      // entry animation finish before the layer anchors to it.
      cancelSettleWait = waitForAncestorAnimations(anchor, () => {
        finishAnchorWait();
        openNow();
      });
    };
    function check() {
      if (!resolved && isAnchorReady(anchorElement)) {
        resolve();
      }
    }
    const intersection =
      typeof IntersectionObserver === 'undefined'
        ? null
        : new IntersectionObserver(check);
    stopResize = observeResize(anchor, check);
    if (!resolved) {
      intersection?.observe(anchor);
      if (dialog) {
        stopMutations = observeMutations(
          dialog,
          {attributes: true, attributeFilter: ['open']},
          check,
        );
        dialog.addEventListener('toggle', check);
      }
    } else {
      // The registration itself resolved the wait before its unsubscribe
      // existed, so release it now.
      release();
    }
    pendingAnchorWaitRef.current = () => {
      resolved = true;
      release();
      cancelSettleWait();
    };
    pendingAnchorElementRef.current = anchor;
  }, [mode, openNow, cancelPendingAnchorWait, finishAnchorWait]);

  const hide = useCallback(() => {
    cancelPendingAnchorWait();
    pendingShowRef.current = false;
    if (isOpenRef.current) {
      const el = popoverRef.current;
      // A close that plays out after the layer is hidden starts here, while
      // the browser still shows it. The `beforetoggle` handler below starts
      // the browser's own hides.
      onCloseStartRef.current?.();
      // Clear the open state BEFORE hiding: hidePopover fires `toggle`, and
      // the reconciler below reads this ref to tell the browser's own
      // dismissals from ours.
      openedPopoverRef.current = null;
      isOpenRef.current = false;
      // See finding infra-4 note in `show`: mirror the same guard on hide so
      // unsupported browsers degrade gracefully instead of throwing.
      if (el) {
        if (typeof el.hidePopover === 'function') {
          // Hiding hands focus back to the previously focused element while
          // the browser still counts this popover as hiding; a layer that
          // focus wakes (a tooltip on that element) defers its show until
          // this returns.
          runPopoverOperation(el.ownerDocument, () => {
            el.hidePopover();
          });
        } else {
          el.style.display = 'none';
        }
      }
      setIsOpen(false);
      onHide?.();
    }
    releaseAnchor(popoverRef.current);
    clearContextMount();
  }, [onHide, clearContextMount, releaseAnchor, cancelPendingAnchorWait]);

  // A deferred show() replays through a ref so the queued closure reaches the
  // current callback rather than the one captured when it was queued.
  const showRef = useRef(show);
  showRef.current = show;

  // The open-state geometry observers of a layer that keeps its anchor clear
  // (`observeAnchorClearance`), as their teardown. The open-state layout
  // effect binds them; the trigger callback ref rebinds them when a caller
  // replaces the trigger element while the layer stays open.
  const clearObserversRef = useRef<(() => void) | null>(null);

  // Stable ref for the trigger element (context mode only).
  //
  // A combined ref can call this ref with `null` and then with the same
  // element. Removing `anchor-name` in that gap strands an open layer at its
  // fallback position. So a `null` call removes the name one microtask later,
  // unless the same element attaches again first. A different element takes
  // over at once, and a `null` with nothing after it (an unmount) removes the
  // name.
  const contextRef = useCallback(
    (el: HTMLElement | null) => {
      if (!el) {
        const stale = triggerRef.current;
        if (!stale) {
          return;
        }
        const pending = {element: stale, cancelled: false};
        pendingTriggerDetachRef.current = pending;
        queueMicrotask(() => {
          if (pending.cancelled || triggerRef.current !== stale) {
            return;
          }
          removeAnchorName(stale, anchorId);
          triggerRef.current = null;
          // A real unmount: stop waiting on an element that will never get a
          // box, and release the observers an open layer kept on it.
          if (pendingAnchorElementRef.current === stale) {
            cancelPendingAnchorWait();
          }
          if (keepsAnchorClear && isOpenRef.current) {
            clearObserversRef.current?.();
            clearObserversRef.current = null;
          }
        });
        return;
      }
      // Reattaching the exact element a pending detach targeted: cancel it,
      // the churn never happened as far as the anchor name is concerned.
      if (pendingTriggerDetachRef.current?.element === el) {
        pendingTriggerDetachRef.current.cancelled = true;
        pendingTriggerDetachRef.current = null;
      }
      // Remove only THIS layer's anchor name from the previous element so
      // other layers sharing the same trigger keep their anchors.
      if (triggerRef.current && triggerRef.current !== el) {
        removeAnchorName(triggerRef.current, anchorId);
      }

      // Only a shown layer's trigger is an anchor. WebKit's Linux ports run the
      // transform animation of an element that holds an anchor on the main
      // thread. A busy task would then freeze a surface that moves around a
      // closed trigger.
      if (el && (isOpenRef.current || exitRef.current != null)) {
        addAnchorName(el, anchorId);
      }

      const previous = triggerRef.current;
      triggerRef.current = el;

      // A trigger replaced while the layer is open (React detaches the old
      // node with `null`, then attaches the new one): the old trigger's
      // observers are removed before the new trigger's are added, and
      // binding them reads the new trigger's geometry at once.
      if (keepsAnchorClear && isOpenRef.current && el !== previous) {
        clearObserversRef.current?.();
        clearObserversRef.current = null;
        const layer = popoverRef.current;
        if (layer) {
          clearObserversRef.current = observeAnchorClearance(
            layer,
            el,
            () => popoverRef.current === layer && triggerRef.current === el,
          );
          keepAnchorClear(layer, el);
        }
      }

      // A show() is still waiting for a box on a different trigger: that wait
      // observes the element it started with, so it would never end for this
      // one. Restart it on the new trigger, after the commit that attached it.
      const waitingOn = pendingAnchorElementRef.current;
      if (waitingOn && waitingOn !== el) {
        cancelPendingAnchorWait();
        const restart = {cancelled: false};
        pendingRestartRef.current = restart;
        queueMicrotask(() => {
          if (restart.cancelled) {
            return;
          }
          pendingRestartRef.current = null;
          if (triggerRef.current === el && !isOpenRef.current) {
            showRef.current();
          }
        });
      }
    },
    [anchorId, cancelPendingAnchorWait, keepsAnchorClear],
  );

  // Arm only when the dismissing gesture's click is still ahead of us. Some
  // engines deliver click first; in that order there is nothing left to absorb.
  const rememberDismissal = useCallback((doc: Document) => {
    forgetDismissalRef.current?.();
    if (currentGestureHasClicked()) {
      return;
    }
    dismissedByGestureRef.current = currentGesture();
    const view = doc.defaultView;
    let forgetTimer: number | null = null;
    const forget = () => {
      dismissedByGestureRef.current = null;
      doc.removeEventListener('click', scheduleForget, true);
      if (forgetTimer !== null) {
        view?.clearTimeout(forgetTimer);
        forgetTimer = null;
      }
      if (forgetDismissalRef.current === forget) {
        forgetDismissalRef.current = null;
      }
    };
    const scheduleForget = () => {
      doc.removeEventListener('click', scheduleForget, true);
      // The next task keeps the dismissal armed through React's click handler.
      if (view) {
        forgetTimer = view.setTimeout(() => {
          forgetTimer = null;
          if (forgetDismissalRef.current === forget) {
            forget();
          }
        }, 0);
      } else {
        forget();
      }
    };
    doc.addEventListener('click', scheduleForget, true);
    forgetDismissalRef.current = forget;
  }, []);

  // Syncs the document's capture-phase gesture tracking with this mount.
  // Unmount forgets the layer's dismissal and releases a pending anchor wait.
  useEffect(() => {
    // Install capture-phase gesture tracking before the first interaction.
    currentGesture();
    return () => {
      forgetDismissalRef.current?.();
      pendingAnchorWaitRef.current?.();
    };
  }, []);

  // Reconcile browser-initiated closes (light-dismiss, popover="auto" stack
  // eviction). These are the only cases where the DOM mutates without going
  // through our show/hide — we sync React state back to match.
  //
  // No "open" case: the browser never spontaneously opens a popover. Opens
  // only happen via showPopover() which we always call from show().
  //
  // The isOpenRef guard prevents double-firing: when our hide() already set
  // the ref to false, the subsequent toggle event (which the browser fires
  // as a side-effect of hidePopover) sees false and skips.
  // A hide the browser runs itself (light dismiss, popover="auto" stack
  // eviction, an Escape its close watcher answers) never passes through
  // hide(), so the ledger of popover operations would not know the document
  // is mid-hide, and a layer that the hide's focus restore wakes would ask the
  // browser to show inside it. `beforetoggle` fires synchronously as such a
  // hide starts; the ledger counts the hide from there until the element's
  // own `toggle`, independent of this hook's bindings, which a render inside
  // the hide can replace.
  const handleBeforeToggle = useCallback(
    (e: Event) => {
      const toggleEvent = e as ToggleEvent;
      const el = e.currentTarget as HTMLElement | null;
      if (toggleEvent.newState !== 'closed' || el == null) {
        return;
      }
      if (isOpenRef.current) {
        observeBrowserHide(el);
        onCloseStartRef.current?.();
        // The browser's own close releases the name from its toggle event.
        return;
      }
      // Our hide drops its trigger's anchor name here, inside the hide, so the
      // hide's own layout covers the change. A name dropped after that layout
      // costs one more. A layer that the closed state keeps shown keeps the
      // name until its exit ends.
      const trigger = triggerRef.current;
      if (
        trigger != null &&
        readAnchorNames(trigger).includes(anchorId) &&
        !closeKeepsShownRef.current
      ) {
        exitRef.current = null;
        removeAnchorName(trigger, anchorId);
      }
    },
    [anchorId],
  );

  const handleToggle = useCallback(
    (e: Event) => {
      const toggleEvent = e as ToggleEvent;
      if (toggleEvent.newState === 'closed' && isOpenRef.current) {
        openedPopoverRef.current = null;
        isOpenRef.current = false;
        rememberDismissal(
          (e.currentTarget as HTMLElement | null)?.ownerDocument ?? document,
        );
        releaseAnchor(e.currentTarget as HTMLElement | null);
        setIsOpen(false);
        onHide?.();
        clearContextMount();
      }
    },
    [onHide, clearContextMount, rememberDismissal, releaseAnchor],
  );

  // Ref callback for popover element — sets up the `toggle` listener.
  // Tracks the element + handler currently bound so the listener is removed
  // when the element detaches or when `handleToggle`'s identity changes (a new
  // `onHide` prop), preventing stale-closure listeners from accumulating on the
  // same element (infra-10).
  const listenedElRef = useRef<HTMLElement | null>(null);
  const listenedHandlerRef = useRef<((e: Event) => void) | null>(null);

  const bindToggleListener = useCallback(
    (el: HTMLElement | null, handler: (e: Event) => void) => {
      if (
        listenedElRef.current &&
        listenedHandlerRef.current &&
        (listenedElRef.current !== el || listenedHandlerRef.current !== handler)
      ) {
        listenedElRef.current.removeEventListener(
          'toggle',
          listenedHandlerRef.current,
        );
        listenedElRef.current.removeEventListener(
          'beforetoggle',
          handleBeforeToggle,
        );
        listenedElRef.current = null;
        listenedHandlerRef.current = null;
      }
      if (el && listenedElRef.current !== el) {
        el.addEventListener('toggle', handler);
        el.addEventListener('beforetoggle', handleBeforeToggle);
        listenedElRef.current = el;
        listenedHandlerRef.current = handler;
      }
    },
    [handleBeforeToggle],
  );

  // An anchored layer that would run under the software keyboard keeps its
  // block-start edge and ends clear of the keyboard.
  const {
    cap: keyboardCap,
    lift: keyboardLift,
    inset: keyboardInset,
    followLayerElement,
  } = useLayerKeyboardClearance(isOpen && mode === 'context', popoverRef);

  const popoverRefCallback = useCallback(
    (el: HTMLElement | null) => {
      popoverRef.current = el;
      bindToggleListener(el, handleToggle);
      if (el && pendingShowRef.current) {
        pendingShowRef.current = false;
        show();
      } else if (
        el &&
        isOpenRef.current &&
        openedPopoverRef.current !== el &&
        isCurrentContextPopover(el)
      ) {
        // Changing a portal target remounts the popover. Preserve the logical
        // open state without firing onShow again for the replacement element.
        // A show the browser refused during one of its own hides replays once
        // that hide has ended, for the element still mounted then. The
        // keyboard cap follows the replacement element too.
        followLayerElement();
        if (showPopoverElement(el)) {
          if (keepsAnchorClear) {
            keepAnchorClear(el, triggerRef.current);
          }
        } else {
          afterPopoverOperations(el.ownerDocument, () => {
            const current = popoverRef.current;
            if (
              isOpenRef.current &&
              current === el &&
              openedPopoverRef.current !== el &&
              showPopoverElement(el) &&
              keepsAnchorClear
            ) {
              keepAnchorClear(el, triggerRef.current);
            }
          });
        }
      }
    },
    [
      handleToggle,
      bindToggleListener,
      show,
      showPopoverElement,
      isCurrentContextPopover,
      keepsAnchorClear,
      followLayerElement,
    ],
  );

  const sentinelRefCallback = useCallback(
    (el: HTMLTemplateElement | null) => {
      sentinelRef.current = el;
      // A layer that keeps its mount re-resolves it too once it has one.
      if (
        el &&
        (!lazyMount ||
          pendingShowRef.current ||
          isOpenRef.current ||
          (keepsMountAfterShow && contextMountRef.current != null))
      ) {
        // The render call may have moved while the hook stayed mounted.
        // Resolve again from the newly attached marker rather than reusing a
        // portal target from its previous JSX position.
        requestContextMount();
      }
    },
    [lazyMount, keepsMountAfterShow, requestContextMount],
  );

  // Re-bind when the handler identity changes while the element stays mounted,
  // and detach on unmount.
  useEffect(() => {
    if (popoverRef.current) {
      bindToggleListener(popoverRef.current, handleToggle);
    }
    return () => {
      if (listenedElRef.current && listenedHandlerRef.current) {
        listenedElRef.current.removeEventListener(
          'toggle',
          listenedHandlerRef.current,
        );
        listenedElRef.current.removeEventListener(
          'beforetoggle',
          handleBeforeToggle,
        );
        listenedElRef.current = null;
        listenedHandlerRef.current = null;
      }
    };
  }, [handleToggle, bindToggleListener, handleBeforeToggle]);

  // Anchor visibility (FR5). The first frame must already be right (FR8), so
  // the opening read is synchronous — a layout effect runs before paint, and a
  // state change inside it re-renders before paint — against the visual
  // viewport. IntersectionObserver then tracks changes while open; with no
  // root it reports against the viewport and through every ancestor clip, so
  // an anchor scrolled out of a panel reads as out of view too.
  useIsomorphicLayoutEffect(() => {
    if (!isOpen || mode !== 'context') {
      return;
    }
    const anchor = triggerRef.current;
    if (!anchor) {
      return;
    }
    const view = anchor.ownerDocument.defaultView;
    if (view) {
      // Edge-adjacent counts as in view, as IntersectionObserver reports it;
      // an engine with no layout (a zero rect) therefore reads as in view too.
      const rect = anchor.getBoundingClientRect();
      const inView =
        rect.bottom >= 0 &&
        rect.right >= 0 &&
        rect.top <= view.innerHeight &&
        rect.left <= view.innerWidth;
      updateAnchorInView(inView);
    }
    if (typeof IntersectionObserver === 'undefined') {
      return;
    }
    const observer = new IntersectionObserver(entries => {
      const latest = entries[entries.length - 1];
      if (latest) {
        updateAnchorInView(latest.isIntersecting);
      }
    });
    observer.observe(anchor);
    return () => observer.disconnect();
  }, [isOpen, mode, updateAnchorInView]);

  // A layer that keeps its anchor clear re-reads its geometry while it
  // is open: content that grows, an anchor that resizes or moves (in layout or
  // by a scroll) or a viewport resize can each re-settle the standard list over the anchor or
  // give the layer a scroll range (`observeAnchorClearance`). The external
  // systems are those browser observers and listeners; this effect binds them
  // while the layer is open and removes them when it closes, unmounts or is
  // remounted by a moved render call (`mountGeneration`). A trigger replaced
  // while open is rebound by the trigger callback ref, so no DOM node enters
  // state.
  useIsomorphicLayoutEffect(() => {
    if (!keepsAnchorClear || !isOpen || mode !== 'context') {
      return;
    }
    const layer = popoverRef.current;
    const anchor = triggerRef.current;
    if (!layer || !anchor) {
      return;
    }
    clearObserversRef.current?.();
    clearObserversRef.current = observeAnchorClearance(
      layer,
      anchor,
      () => popoverRef.current === layer && triggerRef.current === anchor,
    );
    return () => {
      clearObserversRef.current?.();
      clearObserversRef.current = null;
    };
  }, [keepsAnchorClear, isOpen, mode, mountGeneration]);

  // Render function for context mode
  const renderContext = useCallback(
    (children: ReactNode, props?: ContextRenderProps) => {
      const {
        placement = 'above',
        alignment = 'center',
        positioning = 'anchor',
        offset,
        role,
        'aria-label': ariaLabel,
        xstyle,
        className: extraClassName,
        style: extraStyle,
        as: Container = 'div',
        onMouseEnter,
        onMouseLeave,
      } = props || {};

      // CSS anchor positioning (dynamic, not in StyleX)
      const standardFallbacks = getPositionTryFallbacks(placement, alignment);
      // An above or below layer that keeps its anchor clear uses one combined
      // list whose options never overlap the anchor (FR4).
      const clearFallbacks =
        keepsAnchorClear && positioning === 'anchor'
          ? getAnchorClearFallbacks(placement)
          : '';
      const anchorStyle: React.CSSProperties =
        positioning === 'custom'
          ? // Consumer authors its own position styles via `style` — keep
            // only the anchor wiring, derive nothing from placement.
            {positionAnchor: anchorId}
          : {
              positionAnchor: anchorId,
              positionArea: getPositionArea(placement, alignment),
              positionTryFallbacks: clearFallbacks || standardFallbacks,
              ...(clearFallbacks
                ? {alignSelf: anchorClearAlignment(placement)}
                : {}),
              ...getSelfAlignment(placement, alignment, isAnchorInView),
            };

      const clearance = offset ? toCssLength(offset) : null;
      const clearanceProperty: Record<string, string> =
        positioning === 'anchor' && clearance != null
          ? {[LAYER_CLEARANCE_PROPERTY]: clearance}
          : {};
      const offsetStyle =
        positioning !== 'anchor'
          ? null
          : clearance == null
            ? placement === 'above'
              ? styles.farAbove
              : placement === 'below'
                ? styles.farBelow
                : placement === 'start'
                  ? styles.farStart
                  : styles.farEnd
            : placement === 'above'
              ? styles.placementAbove(clearance)
              : placement === 'below'
                ? styles.placementBelow(clearance)
                : placement === 'start'
                  ? styles.placementStart(clearance)
                  : styles.placementEnd(clearance);

      const viewportStyles =
        positioning === 'anchor'
          ? [styles.viewportFit, ...getGutterStyles(placement, alignment)]
          : null;

      const stylexResult = stylex.props(
        layerTextReset.reset,
        layerStructureReset.reset,
        styles.base,
        overlayPaddingReset.reset,
        styles.keyboardCap(
          keyboardCap == null ? '100vh' : `${keyboardCap}px`,
          keyboardCap == null ? 'visible' : 'auto',
          keyboardInset == null ? 'initial' : `${keyboardInset}px`,
        ),
        keepsAnchorClear && styles.scrollsOnOverflow,
        viewportStyles,
        offsetStyle,
        xstyle,
      );
      const combinedClassName = extraClassName
        ? `${extraClassName} ${stylexResult.className ?? ''}`
        : stylexResult.className;

      // The marker gives us the actual JSX parent without mounting arbitrary
      // children there. Safe positions preserve the existing DOM order and
      // cascade; unsafe positions use the nearest corrective portal target.
      // The slot renders the layer once the hook has resolved that mount.
      const renderLayer = (mount: ContextLayerMount) => (
        <Container
          ref={popoverRefCallback}
          id={id}
          // Anchor positioning, as this commit renders it: the software
          // keyboard caps only an anchored layer, and reads this at
          // measurement.
          {...(positioning === 'anchor'
            ? {[LAYER_ANCHORED_ATTRIBUTE]: ''}
            : {})}
          role={role}
          aria-label={ariaLabel}
          popover={lightDismiss ? 'auto' : 'manual'}
          className={combinedClassName}
          style={{
            ...stylexResult.style,
            ...anchorStyle,
            ...keyboardLiftStyle(keyboardLift),
            ...clearanceProperty,
            ...layerInsetProperties(declaredInset),
            ...mount.portalStyle,
            ...extraStyle,
          }}
          onMouseEnter={onMouseEnter}
          onMouseLeave={onMouseLeave}
          // Presses inside the layer do not reach handlers around where it
          // is written.
          {...layerClickBoundary()}>
          <LayerContentBoundary>{children}</LayerContentBoundary>
        </Container>
      );

      return (
        <ContextLayerSlot
          mountStore={mountStore}
          renderLayer={renderLayer}
          sentinelRef={sentinelRefCallback}
        />
      );
    },
    [
      anchorId,
      declaredInset,
      id,
      isAnchorInView,
      keepsAnchorClear,
      keyboardCap,
      keyboardInset,
      keyboardLift,
      lightDismiss,
      mountStore,
      popoverRefCallback,
      sentinelRefCallback,
    ],
  );

  // Render function for fixed mode
  const renderFixed = useCallback(
    (children: ReactNode, props: FixedRenderProps) => {
      const {
        x,
        y,
        xstyle,
        className: extraClassName,
        style: extraStyle,
      } = props;

      // Dynamic position values
      const positionStyle: React.CSSProperties = {
        top: y,
        left: x,
      };

      const stylexResult = stylex.props(
        layerTextReset.reset,
        layerStructureReset.reset,
        styles.base,
        overlayPaddingReset.reset,
        // A fixed layer is never capped; it still sets its own limit so it is
        // not clamped by a capped layer it sits in.
        styles.keyboardCap('100vh', 'visible', 'initial'),
        styles.fixed,
        xstyle,
      );
      const combinedClassName = extraClassName
        ? `${extraClassName} ${stylexResult.className ?? ''}`
        : stylexResult.className;

      return (
        <div
          ref={popoverRefCallback}
          id={id}
          popover={lightDismiss ? 'auto' : 'manual'}
          className={combinedClassName}
          style={{...stylexResult.style, ...positionStyle, ...extraStyle}}
          // Presses inside the layer do not reach handlers around where it
          // is written.
          {...layerClickBoundary()}>
          <LayerContentBoundary>{children}</LayerContentBoundary>
        </div>
      );
    },
    [popoverRefCallback, id, lightDismiss],
  );

  const contextResult = useMemo<InternalContextLayerReturn>(
    () => ({
      ref: contextRef,
      anchorId,
      show,
      hide,
      isOpen,
      wasJustDismissed,
      id,
      render: renderContext,
    }),
    [
      contextRef,
      anchorId,
      show,
      hide,
      isOpen,
      wasJustDismissed,
      id,
      renderContext,
    ],
  );
  const fixedResult = useMemo<InternalFixedLayerReturn>(
    () => ({
      ref: undefined,
      show,
      hide,
      isOpen,
      wasJustDismissed,
      id,
      render: renderFixed,
    }),
    [show, hide, isOpen, wasJustDismissed, id, renderFixed],
  );

  return mode === 'context' ? contextResult : fixedResult;
}

export function useLayer(options: ContextLayerOptions): ContextLayerReturn;
export function useLayer(options: FixedLayerOptions): FixedLayerReturn;
export function useLayer(
  options: ContextLayerOptions | FixedLayerOptions,
): ContextLayerReturn | FixedLayerReturn {
  const internalLayer = useLayerImplementation(options);
  return useMemo(() => {
    const {wasJustDismissed: _, ...layer} = internalLayer;
    return layer;
  }, [internalLayer]);
}

/**
 * @internal Shared with usePopover and useTooltip; not exported from the
 * package barrel.
 */
export function useLayerInternal(
  options: InternalContextLayerOptions,
): InternalContextLayerReturn;
export function useLayerInternal(
  options: FixedLayerOptions,
): InternalFixedLayerReturn;
export function useLayerInternal(
  options: InternalContextLayerOptions | FixedLayerOptions,
): InternalContextLayerReturn | InternalFixedLayerReturn {
  return useLayerImplementation(options);
}