cursedbelt 5.14.0 → 5.15.2

package/src/react/components/Popover.tsx

@@ -1,14 +1,38 @@
 import * as RPopover from '@radix-ui/react-popover';
-import type { ReactNode } from 'react';
+import { type ReactNode, useCallback, useMemo, useRef, useState } from 'react';
+import { useOutsidePress } from '../hooks/useOutsidePress.js';
 import { cn } from '../lib/cn.js';
+import { useFloatingContainer } from '../lib/floatingContainer.js';
 import {
   FLOATING_ANIMATION,
   FLOATING_COLLISION_PADDING,
   FLOATING_CONTENT_BASE,
 } from '../lib/floatingStyles.js';
 
+/**
+ * A point to open a popover at, for a panel that has no trigger of its own — a context
+ * menu at the pointer, or a menu one control opens for another.
+ */
+export interface PopoverPoint {
+  x: number;
+  y: number;
+  /**
+   * The control this was opened from, when there is one. A press on it is never
+   * "outside": its own `onClick` decides whether the press opens or shuts, so a menu
+   * button toggles instead of closing on pointerdown and reopening on click.
+   */
+  trigger?: Element | null;
+}
+
 export interface PopoverProps {
-  trigger: ReactNode;
+  /** The control that opens it. Omit it and pass {@link PopoverProps.anchor} instead. */
+  trigger?: ReactNode;
+  /**
+   * Position the panel against this instead of a trigger: an element, or a point.
+   * With no `open` prop, the panel is open exactly while this is non-null, and
+   * `onOpenChange(false)` is the caller's cue to clear it.
+   */
+  anchor?: Element | PopoverPoint | null;
   children: ReactNode;
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -17,19 +41,58 @@ export interface PopoverProps {
   sideOffset?: number;
   /** Width of the popover panel. Default: auto (sized to content). */
   width?: string | number;
-  /** Show the little arrow pointing at the trigger. Default true. */
+  /** Show the little arrow pointing at the trigger. Default true (false when `unstyled`). */
   arrow?: boolean;
   className?: string;
+  /**
+   * Drop the belt's surface — border, background, shadow, padding, arrow — and keep only
+   * the behaviour: positioning, collision flipping, and closing on a tap or click outside,
+   * on Escape and on focus leaving. For a panel that belongs to its own visual language
+   * (a video player's controls over the picture); `className` then carries the look.
+   */
+  unstyled?: boolean;
+  /**
+   * A press outside ONLY closes the panel, and never also lands on what is under it —
+   * the way a native menu behaves. Right for a menu over something a stray tap would
+   * change (a playing video). Default false: the press closes the panel AND reaches its
+   * target, which is right for a panel beside a form.
+   */
+  modal?: boolean;
+  /**
+   * Render in place rather than in a portal. The portal already follows the full-screen
+   * element (see `floatingContainer.ts`), so this is for a panel that must scroll or
+   * clip with its container. Default true.
+   */
+  portal?: boolean;
+  /** Move focus into the panel when it opens. Default true; false keeps it on the trigger. */
+  autoFocus?: boolean;
+  /** Accessible name of the panel, when no heading inside it names it. */
+  label?: string;
+  /** ARIA role of the panel. Default `dialog` (Radix's). */
+  role?: 'dialog' | 'menu' | 'listbox';
+}
+
+function isPoint(anchor: Element | PopoverPoint): anchor is PopoverPoint {
+  return typeof (anchor as PopoverPoint).x === 'number' && !('getBoundingClientRect' in anchor);
 }
 
 /**
- * Portal-based popover on Radix Popover. General-purpose anchored panel — never
- * clipped by overflow ancestors, auto-flips + shifts to stay on-screen. Use for
- * confirmations, color/date pickers, inline editors, and grouped item pickers.
- * For action menus use {@link DropdownMenu}; for field help use {@link InfoHint}.
+ * THE anchored floating panel of the fleet, on Radix Popover. Never clipped by overflow
+ * ancestors, auto-flips and shifts to stay on screen, and — the reason it must be the one
+ * everybody uses — **it closes when you tap or click anywhere else**, on Escape, and when
+ * focus leaves it, on a phone exactly as on a desktop.
+ *
+ * 🔴 Owner report, 2026-09-27, on an iPhone: flix's subtitle menu, and music's folder
+ * menu, stayed open after tapping away. Each was a hand-rolled `{open && <div
+ * className="absolute …">}` with no outside-press handling at all, so the bug was in every
+ * copy on every screen. The guardrail `no-raw-popover` now flags that shape in every app.
+ *
+ * Use for menus, pickers, confirmations and inline editors. For an action list prefer
+ * {@link DropdownMenu} (keyboard roving built in); for field help use {@link InfoHint}.
  */
 export function Popover({
   trigger,
+  anchor,
   children,
   open,
   onOpenChange,
@@ -37,25 +100,111 @@ export function Popover({
   side = 'bottom',
   sideOffset = 4,
   width,
-  arrow = true,
+  arrow,
   className,
+  unstyled = false,
+  modal = false,
+  portal = true,
+  autoFocus = true,
+  label,
+  role,
 }: PopoverProps) {
+  const container = useFloatingContainer();
+  const showArrow = arrow ?? !unstyled;
+
+  // A point becomes a zero-size virtual element — what Radix's popper measures.
+  const virtualRef = useMemo(() => {
+    if (!anchor) return null;
+    const measure = isPoint(anchor)
+      ? () => new DOMRect(anchor.x, anchor.y, 0, 0)
+      : () => anchor.getBoundingClientRect();
+    return { current: { getBoundingClientRect: measure } };
+  }, [anchor]);
+  const anchorTrigger = anchor ? (isPoint(anchor) ? anchor.trigger : anchor) : null;
+
+  // Always controlled underneath, so the outside-press fallback below can close an
+  // uncontrolled popover too.
+  const [ownOpen, setOwnOpen] = useState(false);
+  const isOpen = open ?? (anchor !== undefined ? anchor !== null : ownOpen);
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (open === undefined && anchor === undefined) setOwnOpen(next);
+      onOpenChange?.(next);
+    },
+    [open, anchor, onOpenChange],
+  );
+
+  /*
+   * 🔴 Radix's own outside-press dismissal is not enough on its own. `@radix-ui/react-popover`
+   * (1.1.23) defers it to the `click` after the pointerdown and then SKIPS it when any
+   * outside handler stopped that click's propagation ("the interaction was intercepted") —
+   * and a video surface, a card or a row routinely does, so a tap on exactly the things
+   * most likely to be under a menu left it open. `useOutsidePress` listens in the capture
+   * phase, before anything can stop it; when Radix has already closed the panel, its second
+   * close is a no-op. Escape and `modal` stay Radix's.
+   */
+  // Typed as Radix types its Trigger; with `asChild` it is whatever element `trigger` is.
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const pressInside = useOutsidePress({
+    open: isOpen,
+    onDismiss: () => setOpen(false),
+    inside: [triggerRef, anchorTrigger],
+    escape: false,
+    // Under `modal` the page is inert and an iPhone sends no click for a tap on it — see
+    // `decideOn` in useOutsidePress.
+    decideOn: modal ? 'pointerdown' : 'click',
+  });
+
+  const content = (
+    <RPopover.Content
+      align={align}
+      side={side}
+      sideOffset={sideOffset}
+      collisionPadding={FLOATING_COLLISION_PADDING}
+      style={width != null ? { width } : undefined}
+      aria-label={label}
+      // Spread, never `role={role}`: Radix spreads our props over its own `role: "dialog"`,
+      // so an explicit `undefined` would erase the panel's role rather than keep the default.
+      {...(role ? { role } : {})}
+      onOpenAutoFocus={autoFocus ? undefined : (event) => event.preventDefault()}
+      onInteractOutside={(event) => {
+        // The anchor's own control decides open/shut with its click — see PopoverPoint.
+        if (anchorTrigger?.contains(event.target as Node)) event.preventDefault();
+      }}
+      // React-tree capture: a press on a nested layer this panel portalled (a Select's
+      // list, a sub-menu) is INSIDE even though the DOM puts it elsewhere.
+      onClickCapture={pressInside.onClickCapture}
+      onPointerDownCapture={pressInside.onPointerDownCapture}
+      className={cn(
+        unstyled
+          ? 'z-[var(--z-popover)] outline-none'
+          : cn(FLOATING_CONTENT_BASE, 'p-3'),
+        FLOATING_ANIMATION,
+        className,
+      )}
+    >
+      {children}
+      {showArrow && <RPopover.Arrow className='fill-border' />}
+    </RPopover.Content>
+  );
+
   return (
-    <RPopover.Root open={open} onOpenChange={onOpenChange}>
-      <RPopover.Trigger asChild>{trigger}</RPopover.Trigger>
-      <RPopover.Portal>
-        <RPopover.Content
-          align={align}
-          side={side}
-          sideOffset={sideOffset}
-          collisionPadding={FLOATING_COLLISION_PADDING}
-          style={width != null ? { width } : undefined}
-          className={cn(FLOATING_CONTENT_BASE, FLOATING_ANIMATION, 'p-3', className)}
-        >
-          {children}
-          {arrow && <RPopover.Arrow className='fill-border' />}
-        </RPopover.Content>
-      </RPopover.Portal>
+    <RPopover.Root open={isOpen} onOpenChange={setOpen} modal={modal}>
+      {virtualRef ? <RPopover.Anchor virtualRef={virtualRef} /> : null}
+      {trigger !== undefined ? (
+        <RPopover.Trigger asChild ref={triggerRef}>
+          {trigger}
+        </RPopover.Trigger>
+      ) : null}
+      {portal ? <RPopover.Portal container={container}>{content}</RPopover.Portal> : content}
     </RPopover.Root>
   );
 }
+
+/**
+ * Wrap a control inside a {@link Popover}'s panel so pressing it also closes the panel —
+ * for an uncontrolled popover whose items should dismiss it.
+ */
+export function PopoverClose({ children }: { children: ReactNode }) {
+  return <RPopover.Close asChild>{children}</RPopover.Close>;
+}

package/src/react/components/SelectField.tsx

@@ -2,6 +2,7 @@ import * as RSelect from '@radix-ui/react-select';
 import { Check, ChevronDown, ChevronUp } from 'lucide-react';
 import type { ReactNode } from 'react';
 import { cn } from '../lib/cn.js';
+import { useFloatingContainer } from '../lib/floatingContainer.js';
 import { type ControlSize, fieldControlClass } from '../lib/field.js';
 import {
   FLOATING_ANIMATION,
@@ -94,6 +95,7 @@ export function SelectField({
   const allGroups: SelectGroup[] =
     groups.length > 0 ? groups : options.length > 0 ? [{ options }] : [];
   const empty = allGroups.every((group) => group.options.length === 0);
+  const container = useFloatingContainer();
 
   return (
     <RSelect.Root
@@ -120,7 +122,7 @@ export function SelectField({
           <ChevronDown className='size-4 shrink-0 opacity-50' />
         </RSelect.Icon>
       </RSelect.Trigger>
-      <RSelect.Portal>
+      <RSelect.Portal container={container}>
         <RSelect.Content
           position='popper'
           sideOffset={4}

package/src/react/components/TooltipImpl.tsx

@@ -2,6 +2,7 @@ import * as RTooltip from '@radix-ui/react-tooltip';
 import { cloneElement, isValidElement, useEffect, useRef, useState } from 'react';
 import { useHasHover } from '../hooks/useHasHover.js';
 import { cn } from '../lib/cn.js';
+import { useFloatingContainer } from '../lib/floatingContainer.js';
 import { FLOATING_COLLISION_PADDING } from '../lib/floatingStyles.js';
 import { HOVER_HINT_DELAY_MS, HOVER_HINT_INSTANT_MS } from '../lib/hoverIntent.js';
 import type { TooltipArm, TooltipProps } from './Tooltip.js';
@@ -40,6 +41,7 @@ export default function TooltipImpl({
   arm,
 }: TooltipImplProps) {
   const hasHover = useHasHover();
+  const container = useFloatingContainer();
   const [open, setOpen] = useState(false);
   const resolvedSide = placement ?? side ?? 'top';
   const triggerRef = useRef<HTMLElement | null>(null);
@@ -212,7 +214,7 @@ export default function TooltipImpl({
   }, [disabled]);
 
   const bubble = (
-    <RTooltip.Portal>
+    <RTooltip.Portal container={container}>
       <RTooltip.Content
         data-cb-tooltip=''
         side={resolvedSide}

package/src/react/hooks/useOutsidePress.spec.tsx

@@ -0,0 +1,112 @@
+import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { type ButtonHTMLAttributes, type Ref, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { useOutsidePress } from './useOutsidePress.js';
+
+afterEach(cleanup);
+
+/** The fixtures' plain control — Popover has to work with ANY trigger element. */
+function B(props: ButtonHTMLAttributes<HTMLButtonElement> & { ref?: Ref<HTMLButtonElement> }) {
+  return (
+    <button
+      // guardrails-ignore no-raw-action-button: a spec fixture — the point is that the
+      // behaviour holds for whatever element an app hands it.
+      type='button'
+      {...props}
+    />
+  );
+}
+
+/**
+ * The shape music's folder tree has (2026-09-27): a panel that is always rendered and only
+ * becomes an overlay when a toggle says so — so it cannot be a Popover, and needs the same
+ * tap-away behaviour anyway.
+ */
+function Panel({ modal = false, onRow = () => {} }: { modal?: boolean; onRow?: () => void }) {
+  const [open, setOpen] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const toggleRef = useRef<HTMLButtonElement>(null);
+  const [nested, setNested] = useState(false);
+  const inside = useOutsidePress({
+    open,
+    onDismiss: () => setOpen(false),
+    inside: [panelRef, toggleRef],
+    modal,
+  });
+  return (
+    <div role='dialog' aria-label='page modal'>
+      <B onClick={onRow}>
+        row
+      </B>
+      <B ref={toggleRef} onClick={() => setOpen((was) => !was)}>
+        folders
+      </B>
+      <div ref={panelRef} {...inside} data-open={open} data-testid='panel'>
+        <B onClick={() => setNested(true)}>
+          open nested
+        </B>
+        {nested
+          ? createPortal(
+              <div role='menu'>
+                <B>nested item</B>
+              </div>,
+              document.body,
+            )
+          : null}
+      </div>
+    </div>
+  );
+}
+
+const isOpen = () => screen.getByTestId('panel').dataset.open === 'true';
+const press = async (el: Element) => {
+  fireEvent.click(el);
+  await act(() => new Promise((r) => setTimeout(r, 5)));
+};
+
+describe('useOutsidePress', () => {
+  test('a press anywhere else closes it — even inside the dialog the panel itself lives in', async () => {
+    render(<Panel />);
+    await press(screen.getByRole('button', { name: 'folders' }));
+    expect(isOpen()).toBe(true);
+    await press(screen.getByRole('button', { name: 'row' }));
+    expect(isOpen()).toBe(false);
+  });
+
+  test('the toggle toggles, rather than shutting and reopening', async () => {
+    render(<Panel />);
+    const toggle = screen.getByRole('button', { name: 'folders' });
+    await press(toggle);
+    await press(toggle);
+    expect(isOpen()).toBe(false);
+  });
+
+  test('a press inside, or on a layer the panel portalled, keeps it open', async () => {
+    render(<Panel />);
+    await press(screen.getByRole('button', { name: 'folders' }));
+    await press(screen.getByRole('button', { name: 'open nested' }));
+    expect(isOpen()).toBe(true);
+    await press(screen.getByRole('button', { name: 'nested item' }));
+    expect(isOpen()).toBe(true);
+  });
+
+  test('Escape closes it', async () => {
+    render(<Panel />);
+    await press(screen.getByRole('button', { name: 'folders' }));
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(isOpen()).toBe(false);
+  });
+
+  test('modal: the tap that closes it does not also reach the row under it', async () => {
+    const onRow = mock(() => {});
+    render(<Panel modal onRow={onRow} />);
+    await press(screen.getByRole('button', { name: 'folders' }));
+    await press(screen.getByRole('button', { name: 'row' }));
+    expect(isOpen()).toBe(false);
+    expect(onRow).not.toHaveBeenCalled();
+    // Closed, the row works again.
+    await press(screen.getByRole('button', { name: 'row' }));
+    expect(onRow).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/hooks/useOutsidePress.ts

@@ -0,0 +1,159 @@
+import { useEffect, useRef } from 'react';
+
+type InsideTarget = { current: Element | null } | Element | null | undefined;
+
+export interface UseOutsidePressOptions {
+  /** Only listens while true. */
+  open: boolean;
+  /** Called once per press outside (and on Escape, unless `escape` is false). */
+  onDismiss: () => void;
+  /**
+   * What counts as inside: the panel, and the control that toggles it — a press on the
+   * toggle is left to its own `onClick`, so it toggles instead of shutting and reopening.
+   */
+  inside?: readonly InsideTarget[];
+  /** Also dismiss on Escape. Default true. */
+  escape?: boolean;
+  /**
+   * The outside press ONLY dismisses and never also reaches what is under it — the way a
+   * native menu behaves. For a panel laid over something a stray tap would change (a list
+   * whose rows play on tap). Default false.
+   */
+  modal?: boolean;
+  /**
+   * Decide on the `pointerdown` rather than the `click`. Only for a panel that has made the
+   * page under it inert (`Popover`'s `modal`, which sets `pointer-events: none` on body).
+   *
+   * 🔴 Measured 2026-09-27 in Playwright's iPhone 15 WebKit: with the page inert, a tap
+   * outside hits `<html>`, which iOS does not consider clickable, so NO `click` is ever
+   * sent — the menu stayed open under the owner's finger, exactly as reported. Deciding on
+   * the pointerdown closes it; the `click` that same press may still produce is swallowed,
+   * or it would land on whatever the closed menu uncovered (the picture, which pauses).
+   */
+  decideOn?: 'click' | 'pointerdown';
+}
+
+/** A floating layer another component portalled — a press there belongs to that layer. */
+const FLOATING_LAYER =
+  '[data-radix-popper-content-wrapper],[role="dialog"],[role="alertdialog"],[role="menu"],[role="listbox"]';
+
+function resolve(target: InsideTarget): Element | null {
+  return (target && 'current' in target ? target.current : target) ?? null;
+}
+
+/**
+ * Close a panel when the reader presses anywhere else — the ONE implementation of it in the
+ * fleet. `Popover` uses it; use it directly only for a panel that cannot be a `Popover`: a
+ * sheet, or a panel that is always rendered and only BECOMES an overlay at one width.
+ *
+ * 🔴 Owner report, 2026-09-27, on an iPhone: menus that stayed open after tapping away.
+ * Three things make an outside-press handler right, and every hand-rolled one got at least
+ * one wrong:
+ *
+ *  · **`click`, in the CAPTURE phase on `document`.** Capture runs before any handler can
+ *    `stopPropagation()`, and a tap on a video surface, a card or a row routinely does —
+ *    Radix Popover's own dismissal is skipped in exactly that case, which is why `Popover`
+ *    needs this too. `click` rather than `pointerdown`, so a finger that lands outside to
+ *    SCROLL does not close the panel: a scroll never produces a click.
+ *  · **decided after the event has finished dispatching**, so a press inside the panel's
+ *    React tree — a nested layer it portalled elsewhere in the DOM — is seen as inside
+ *    (spread the returned props on the panel), and a press on another floating layer (a
+ *    menu or dialog opened from the panel) belongs to that layer.
+ *  · **the toggle is inside**, or pressing an open menu's own button shuts it and reopens
+ *    it a frame later — the "menu that ignores the second press" desk hit on 2026-09-07.
+ */
+export function useOutsidePress({
+  open,
+  onDismiss,
+  inside = [],
+  escape: closeOnEscape = true,
+  modal = false,
+  decideOn = 'click',
+}: UseOutsidePressOptions): { onClickCapture: () => void; onPointerDownCapture: () => void } {
+  const pressInsideRef = useRef(false);
+  // Latest values without re-subscribing on every render — a listener torn down mid-gesture
+  // would miss the very click it exists for.
+  const latest = useRef({ onDismiss, inside, modal });
+  latest.current = { onDismiss, inside, modal };
+
+  useEffect(() => {
+    if (!open) return;
+    const timers = new Set<ReturnType<typeof setTimeout>>();
+    const isInside = (node: Node) =>
+      latest.current.inside.some((target) => Boolean(resolve(target)?.contains(node)));
+    /**
+     * A press on a floating layer that does NOT hold this panel's own controls — a menu or
+     * dialog opened FROM the panel — belongs to that layer. A layer that does hold them (the
+     * Modal this popover was opened inside) is just the page, and a press there is outside.
+     */
+    const onAnotherLayer = (node: Node) => {
+      const layer = node instanceof Element ? node.closest(FLOATING_LAYER) : node.parentElement?.closest(FLOATING_LAYER);
+      if (!layer?.isConnected) return false;
+      return !latest.current.inside.some((target) => {
+        const element = resolve(target);
+        return element ? layer.contains(element) : false;
+      });
+    };
+
+    /** Decide once the event has finished dispatching — see the header. */
+    const decideLater = (target: Node | null) => {
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        if (pressInsideRef.current || !target) return;
+        if (isInside(target)) return;
+        if (onAnotherLayer(target)) return;
+        latest.current.onDismiss();
+      }, 0);
+      timers.add(timer);
+    };
+    const outside = (target: Node | null) => Boolean(target) && !isInside(target as Node) && !onAnotherLayer(target as Node);
+
+    // `pointerdown` mode: the click the same press produces is not a second decision — it is
+    // swallowed, until the next press or a second later, whichever comes first.
+    let swallowUntil = 0;
+    const onPointerDown = (event: PointerEvent) => {
+      pressInsideRef.current = false;
+      swallowUntil = 0;
+      const target = event.target instanceof Node ? event.target : null;
+      if (outside(target)) swallowUntil = Date.now() + 1000;
+      decideLater(target);
+    };
+    const onClick = (event: MouseEvent) => {
+      const target = event.target instanceof Node ? event.target : null;
+      if (decideOn === 'pointerdown') {
+        if (Date.now() < swallowUntil) {
+          swallowUntil = 0;
+          event.preventDefault();
+          event.stopPropagation();
+        }
+        return;
+      }
+      pressInsideRef.current = false;
+      if (latest.current.modal && outside(target)) {
+        // Decidable now for a DOM-inside press; a React-tree-inside press would have been
+        // swallowed too, so a modal panel's portalled layers must live inside `inside`.
+        event.preventDefault();
+        event.stopPropagation();
+      }
+      decideLater(target);
+    };
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') latest.current.onDismiss();
+    };
+
+    document.addEventListener('click', onClick, true);
+    if (decideOn === 'pointerdown') document.addEventListener('pointerdown', onPointerDown, true);
+    if (closeOnEscape) document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('click', onClick, true);
+      document.removeEventListener('pointerdown', onPointerDown, true);
+      document.removeEventListener('keydown', onKeyDown);
+      for (const timer of timers) clearTimeout(timer);
+    };
+  }, [open, closeOnEscape, decideOn]);
+
+  const markInside = () => {
+    pressInsideRef.current = true;
+  };
+  return { onClickCapture: markInside, onPointerDownCapture: markInside };
+}

package/src/react/icons.spec.ts

@@ -42,3 +42,22 @@ describe('DynamicIcon fallback', () => {
     expect(container.innerHTML).toBe('');
   });
 });
+
+describe('DynamicIcon with no iconMap', () => {
+  // 🔴 vault rendered `<DynamicIcon token="unlock" />` with no map, and every token fell to the
+  // letter fallback — "U W S" in its header where three icons belonged (2026-09-28).
+  test('draws the default icon, never the letter fallback', () => {
+    for (const token of ['unlock', 'wand', 'settings', 'search'] as const) {
+      const { container } = render(DynamicIcon({ token }));
+      expect(container.querySelector('[data-icon]'), `${token} fell back to a letter`).toBeNull();
+      expect(container.querySelector('svg'), `${token} drew no icon`).not.toBeNull();
+    }
+  });
+
+  test('an explicit map that lacks the token still falls back to its letter', () => {
+    const icons = createIconMapRegistry();
+    icons.clear();
+    const { container } = render(DynamicIcon({ token: 'settings', iconMap: icons }));
+    expect(container.querySelector('[data-icon="settings"]')?.textContent).toBe('s');
+  });
+});

package/src/react/icons.tsx

@@ -232,7 +232,11 @@ export function createIconMapRegistry(): IconMapRegistry {
 
 export interface DynamicIconProps {
   token?: IconToken;
-  /** The icon map to resolve `token` against — typically `runtime.icons`. */
+  /**
+   * The icon map to resolve `token` against — typically `runtime.icons`. Omitted, the token
+   * resolves against `defaultIconMap`, so a plain `<DynamicIcon token="settings" />` draws the
+   * settings icon.
+   */
   iconMap?: IconMapRegistry | null;
   className?: string;
 }
@@ -249,12 +253,18 @@ export interface DynamicIconProps {
  * element and visually overflows into neighboring content instead of
  * respecting the icon's slot.
  *
- * The `iconMap` is typically the `runtime.icons` registry from the host shell —
- * pass it explicitly so this component stays framework/runtime-agnostic.
+ * The `iconMap` is typically the `runtime.icons` registry from the host shell.
+ *
+ * 🔴 Omitted, it is `defaultIconMap` — NOT "nothing registered". Until 5.15.1 a missing
+ * `iconMap` resolved every token to the letter fallback, so vault's header, which renders
+ * `<DynamicIcon token="unlock" />` and its neighbours with no map, painted the letters
+ * "U W S" where its lock, generator and settings icons belonged, on every screen, from the
+ * day it adopted the component. A registry that was never passed is not a registry that was
+ * cleared; only an explicit map may leave a token unresolved.
  */
 export function DynamicIcon({ token, iconMap, className }: DynamicIconProps) {
   if (!token) return null;
-  const Icon = iconMap?.get(token);
+  const Icon = iconMap ? iconMap.get(token) : defaultIconMap[token];
   if (!Icon)
     return (
       <Tooltip content={token}>

package/src/react/index.ts

@@ -429,7 +429,7 @@ export {
 export { PathText, type PathTextProps } from './components/PathText.js';
 export { TruncatedText, type TruncatedTextProps } from './components/TruncatedText.js';
 export { PluginCard, type PluginCardProps } from './components/PluginCard.js';
-export { Popover, type PopoverProps } from './components/Popover.js';
+export { Popover, PopoverClose, type PopoverPoint, type PopoverProps } from './components/Popover.js';
 export {
   Progress,
   type ProgressProps,
@@ -659,6 +659,7 @@ export {
   useDragReorder,
 } from './hooks/useDragReorder.js';
 export { useEscapeKey } from './hooks/useEscapeKey.js';
+export { type UseOutsidePressOptions, useOutsidePress } from './hooks/useOutsidePress.js';
 export { useHasHover } from './hooks/useHasHover.js';
 export { useKeyboardInset } from './hooks/useKeyboardInset.js';
 export { useKeyDown } from './hooks/useKeyDown.js';

package/src/react/lib/floatingContainer.ts

@@ -0,0 +1,42 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Where a portalled floating panel (Popover, DropdownMenu) mounts: the element that is
+ * full screen right now, or `document.body` when nothing is.
+ *
+ * 🔴 While an element is full screen the browser paints ONLY that element's subtree. A
+ * panel portalled to `document.body` is still in the DOM, still focusable and still
+ * "open" — and invisible. That is why every video player in the fleet hand-rolled its
+ * own in-place menu instead of using the belt's (flix's subtitle, audio and speed menus;
+ * the belt's own CanvasVideoPlayer speed menu), and a hand-rolled menu is the one that
+ * forgets to close when you tap away from it (owner report, 2026-09-27, on an iPhone).
+ * Following the full-screen element is what lets those menus be the shared one.
+ *
+ * Returns `undefined` for "the default" (Radix portals to body) so a page that never goes
+ * full screen renders exactly what it did before this existed.
+ */
+export function fullscreenElement(): Element | null {
+  if (typeof document === 'undefined') return null;
+  const doc = document as Document & { webkitFullscreenElement?: Element | null };
+  return doc.fullscreenElement ?? doc.webkitFullscreenElement ?? null;
+}
+
+const EVENTS = ['fullscreenchange', 'webkitfullscreenchange'] as const;
+
+function subscribe(onChange: () => void): () => void {
+  for (const name of EVENTS) document.addEventListener(name, onChange);
+  return () => {
+    for (const name of EVENTS) document.removeEventListener(name, onChange);
+  };
+}
+
+/** The portal container for a floating panel — see {@link fullscreenElement}. */
+export function useFloatingContainer(): Element | undefined {
+  return (
+    useSyncExternalStore(
+      subscribe,
+      fullscreenElement,
+      () => null,
+    ) ?? undefined
+  );
+}