@teaflask/assistant 0.0.0 → 0.3.0

package/src/components/primitives/cx.ts

@@ -0,0 +1,5 @@
+// Class-name joiner for the primitives layer — the package deliberately
+// carries no styling dependencies.
+export function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(" ");
+}

package/src/components/primitives/dialog.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  type DialogHTMLAttributes,
+  type MouseEvent,
+  type PointerEvent,
+  type SyntheticEvent,
+} from "react";
+
+import { focusAutofocusTarget } from "./autofocus.js";
+import { cx } from "./cx.js";
+
+// The primitives-layer overlay: a controlled modal on the native <dialog>.
+// showModal() is what buys the whole overlay contract for free — top-layer
+// paint above every host stacking context, an inert page behind (a real
+// focus trap), Esc via `cancel`, and focus returned to the opener on
+// close() — while the element stays where React rendered it, so host
+// `--tf-*` variables and `data-tf-theme` keep inheriting exactly as they
+// do into in-flow surfaces. A portal would break that inheritance; the
+// top layer never does.
+
+interface TfDialogProps extends Omit<
+  DialogHTMLAttributes<HTMLDialogElement>,
+  "open"
+> {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function TfDialog({
+  open,
+  onOpenChange,
+  className,
+  children,
+  onPointerDown: onHostPointerDown,
+  ...props
+}: TfDialogProps) {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+
+  // The `open` prop stays authoritative: native closes are reported up,
+  // never applied locally, and this effect is the only writer.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog === null) {
+      return;
+    }
+    if (open && !dialog.open) {
+      dialog.showModal();
+      // The composer marks itself with data-tf-autofocus; without a mark
+      // the native behavior (first focusable) stands.
+      focusAutofocusTarget(dialog, () => dialog.open);
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open]);
+
+  // Esc. Cancelled so the close happens through the controlled cycle.
+  const closeFromCancel = useCallback(
+    (event: SyntheticEvent<HTMLDialogElement>) => {
+      event.preventDefault();
+      onOpenChange(false);
+    },
+    [onOpenChange],
+  );
+
+  // Safety net for a native close that skipped `cancel` (a
+  // method="dialog" form, or a browser force-closing on repeated Esc).
+  const closeFromNativeClose = useCallback(() => {
+    onOpenChange(false);
+  }, [onOpenChange]);
+
+  // With zero own padding, the only place a press lands on the dialog
+  // element itself is the ::backdrop. The click alone can't be trusted:
+  // it dispatches on the common ancestor of pointerdown and pointerup,
+  // so a text selection that starts in content and releases past the
+  // panel edge also "clicks" the dialog — only a press that BEGAN on the
+  // backdrop counts.
+  //
+  // Composed, not overridden: the spread below lands after every handler
+  // on the element, so a caller passing its own onPointerDown (the sheet's
+  // drag) would silently take this one's place and with it click-to-close.
+  const pressBeganOnBackdropRef = useRef(false);
+  const trackPressOrigin = useCallback(
+    (event: PointerEvent<HTMLDialogElement>) => {
+      pressBeganOnBackdropRef.current = event.target === event.currentTarget;
+      onHostPointerDown?.(event);
+    },
+    [onHostPointerDown],
+  );
+  const closeFromBackdropClick = useCallback(
+    (event: MouseEvent<HTMLDialogElement>) => {
+      if (
+        event.target === event.currentTarget &&
+        pressBeganOnBackdropRef.current
+      ) {
+        onOpenChange(false);
+      }
+    },
+    [onOpenChange],
+  );
+
+  return (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions, jsx-a11y/click-events-have-key-events -- backdrop click-to-close; keyboard users close via Esc (the native cancel event)
+    <dialog
+      ref={dialogRef}
+      // `hidden` restates the UA's closed-dialog display so the open:flex
+      // override can't leak onto the closed-but-mounted element. The
+      // important marker's collision rationale is historical: it guarded
+      // against a host build re-declaring `.hidden` after this element's
+      // `open:flex` — with the tf: prefix no host build can generate a
+      // colliding name. Kept as ordering insurance between the sheet's
+      // own tf:hidden and tf:open:flex rules, immune to any future
+      // intra-sheet order or specificity drift.
+      className={cx("tf:hidden tf:p-0 tf:open:flex!", className)}
+      onCancel={closeFromCancel}
+      onClose={closeFromNativeClose}
+      onPointerDown={trackPressOrigin}
+      onClick={closeFromBackdropClick}
+      {...props}
+    >
+      {children}
+    </dialog>
+  );
+}

package/src/components/primitives/disclosure.tsx

@@ -0,0 +1,190 @@
+"use client";
+
+import { createContext, useContext, useState, type ReactNode } from "react";
+
+import { cx } from "./cx.js";
+
+// A dependency-free collapsible on native <details>/<summary> — the
+// package ships no Radix. Consumers place their own trailing affordance
+// (the chevron, or a spinner while work is in flight) in the summary.
+// `framed` is the standing bordered form; `bare` keeps only the
+// mechanics (marker hiding, cursor, focus ring) and hands every visual
+// decision to the caller — the form composed surfaces like the tool
+// rows build their own chrome on.
+
+type DisclosureVariant = "framed" | "bare";
+
+interface DisclosureProps {
+  summary: ReactNode;
+  children: ReactNode;
+  variant?: DisclosureVariant;
+  /** true opens the disclosure and re-opens it on every VALUE change
+   *  back to true (React re-writes the attribute only when the prop
+   *  value changes — see the nativeOpen comment below — so a visitor's
+   *  collapse of a held-open details sticks until the next flip);
+   *  undefined leaves it native — pass `condition || undefined` so the
+   *  true→undefined transition auto-collapses once, then hands toggling
+   *  back to the visitor. */
+  open?: boolean;
+  className?: string;
+  summaryClassName?: string;
+  bodyClassName?: string;
+  /** data-* identity hooks spread onto the <details> root (the tool
+   *  row's data-tf-tool-call-id, which the approval banner's
+   *  Show-request affordance resolves). Undefined for every other
+   *  consumer — zero DOM change where unused. */
+  rootDataAttributes?: Record<`data-${string}`, string>;
+}
+
+interface DisclosureVisualState {
+  open: boolean;
+  summaryActive: boolean;
+}
+
+const DisclosureVisualStateContext =
+  createContext<DisclosureVisualState | null>(null);
+
+/** The disclosure's DOM-backed visual state, for summary content that
+ *  renders differently open vs closed (the fold headline's collapsed
+ *  step label — the same mirror the chevron rotates on). Only readable
+ *  INSIDE the summary: the provider deliberately wraps the summary
+ *  children alone, and the read is the DOM's `open` (see the nativeOpen
+ *  comment below), never the prop — a visitor can collapse a force-opened
+ *  details while the prop still reads true. Null outside any Disclosure
+ *  summary. */
+export function useDisclosureVisualState(): DisclosureVisualState | null {
+  return useContext(DisclosureVisualStateContext);
+}
+
+export function Disclosure({
+  summary,
+  children,
+  variant = "framed",
+  open,
+  className,
+  summaryClassName,
+  bodyClassName,
+  rootDataAttributes,
+}: DisclosureProps) {
+  // The package cannot rely on a consuming application's Tailwind scan to
+  // emit selectors for arbitrary parent states such as
+  // `[summary:hover_&]` or `[[open]>summary_&]`. Keep the native details as
+  // the source of truth, mirror only the two visual facts the chevron
+  // needs, and hand them to the summary's affordance through context.
+  // This makes the behavior identical in the package fixture and in a host
+  // that consumes only the built JavaScript.
+  const [nativeOpen, setNativeOpen] = useState(open === true);
+  const [summaryActive, setSummaryActive] = useState(false);
+
+  return (
+    // No `group` class here on purpose: a group variant on a nestable
+    // disclosure matches ANY open ancestor (see DisclosureChevron below),
+    // so the hook stays unwired rather than inviting the next consumer
+    // to re-create the nested-chevron bug. Anchor on [open]>summary.
+    <details
+      {...rootDataAttributes}
+      open={open}
+      onToggle={(event) => {
+        setNativeOpen(event.currentTarget.open);
+      }}
+      className={cx(
+        variant === "framed" && "tf:rounded-tf tf:border",
+        className,
+      )}
+    >
+      <summary
+        onMouseEnter={() => {
+          setSummaryActive(true);
+        }}
+        onMouseLeave={() => {
+          setSummaryActive(false);
+        }}
+        onFocus={() => {
+          setSummaryActive(true);
+        }}
+        onBlur={() => {
+          setSummaryActive(false);
+        }}
+        className={cx(
+          "tf:cursor-pointer tf:list-none tf:select-none tf:[&::-webkit-details-marker]:hidden",
+          "tf:focus-visible:outline-2 tf:focus-visible:outline-offset-2 tf:focus-visible:outline-tf-ring",
+          variant === "framed" &&
+            "tf:flex tf:items-center tf:gap-2 tf:px-3 tf:py-1.5 tf:text-tf-label",
+          summaryClassName,
+        )}
+      >
+        <DisclosureVisualStateContext.Provider
+          // nativeOpen ALONE, never `open === true || nativeOpen`: React
+          // re-writes the open attribute only when the prop VALUE changes,
+          // so after a visitor collapses a force-opened details the DOM is
+          // closed while the prop still reads true — the [open]>summary
+          // selector this mirror replaced always read the DOM, and so must
+          // the mirror. nativeOpen is seeded from the prop at mount and a
+          // later undefined→true flip lands through onToggle.
+          value={{ open: nativeOpen, summaryActive }}
+        >
+          {summary}
+        </DisclosureVisualStateContext.Provider>
+      </summary>
+      <div
+        className={cx(
+          variant === "framed" && "tf:border-t tf:px-3 tf:py-2",
+          bodyClassName,
+        )}
+      >
+        {children}
+      </div>
+    </details>
+  );
+}
+
+// Rotates when its OWN Disclosure is open. Not the group-open hook:
+// every Tailwind group variant (named or not) compiles to an
+// ancestor-matching selector, so inside a nested Disclosure — a tool
+// row inside an open fold — the outer open details would keep an inner
+// chevron rotated forever. The [open]>summary anchor can't leak across
+// nesting levels, because a chevron's only <summary> ancestor is its
+// own (a details' body is never inside another details' summary).
+// The framed variant hides the native marker, so summaries that carry no
+// other trailing affordance MUST place this — a markerless summary reads
+// as an inert box, invisible as a control.
+export function DisclosureChevron({
+  revealOnInteraction = false,
+}: {
+  /** Keep quiet summaries free of permanent arrow furniture. Keyboard
+   *  focus mirrors hover so the disclosure never loses its affordance
+   *  for non-pointer navigation. */
+  revealOnInteraction?: boolean;
+} = {}) {
+  const visualState = useContext(DisclosureVisualStateContext);
+  const isOpen = visualState?.open === true;
+  const visible =
+    !revealOnInteraction || isOpen || visualState?.summaryActive === true;
+
+  return (
+    <svg
+      viewBox="0 0 16 16"
+      aria-hidden="true"
+      data-tf-disclosure-chevron=""
+      data-tf-disclosure-chevron-visible={visible ? "" : undefined}
+      data-tf-disclosure-chevron-open={isOpen ? "" : undefined}
+      opacity={revealOnInteraction ? (visible ? 1 : 0) : 1}
+      className={cx(
+        "tf:size-3.5 tf:shrink-0 tf:text-tf-muted-foreground",
+        isOpen ? "tf:rotate-90" : "tf:rotate-0",
+        revealOnInteraction
+          ? "tf:transition-[opacity,transform]"
+          : "tf:transition-transform",
+      )}
+    >
+      <path
+        d="M6 4l4 4-4 4"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}

package/src/components/primitives/file-input.tsx

@@ -0,0 +1,37 @@
+"use client";
+
+import { forwardRef } from "react";
+import type { ChangeEvent } from "react";
+
+// The package's one file control: a visually hidden native input a
+// visible button drives via ref (the shell ImageRow pattern). Hidden
+// rather than styled — a native file control cannot wear the register,
+// so the affordance is always a TfButton and this is its mechanism.
+// forwardRef rather than ref-as-prop: the peer range admits React 18.3,
+// where a function component receives no ref through props.
+
+export const TfFileInput = forwardRef<
+  HTMLInputElement,
+  {
+    accept?: string;
+    multiple?: boolean;
+    onPickFiles: (files: FileList | null) => void;
+  }
+>(function TfFileInput({ accept, multiple = false, onPickFiles }, ref) {
+  return (
+    <input
+      ref={ref}
+      type="file"
+      accept={accept}
+      multiple={multiple}
+      className="tf:sr-only"
+      tabIndex={-1}
+      aria-hidden="true"
+      onChange={(event: ChangeEvent<HTMLInputElement>) => {
+        onPickFiles(event.target.files);
+        // Clearing lets the same file re-fire a change event.
+        event.target.value = "";
+      }}
+    />
+  );
+});

package/src/components/primitives/floating-panel.tsx

@@ -0,0 +1,295 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  type KeyboardEvent,
+  type ReactNode,
+  type RefObject,
+  type ToggleEvent,
+} from "react";
+
+import { useLatestRef } from "../use-latest-ref.js";
+import { focusAutofocusTarget } from "./autofocus.js";
+import { cx } from "./cx.js";
+import { useDockReflow } from "./use-dock-reflow.js";
+import { useSwipeDismiss } from "./use-swipe-dismiss.js";
+
+// The primitives-layer NON-MODAL floating surface: a corner-anchored
+// panel on popover="manual" — the one primitive that buys top-layer
+// paint WITHOUT modality: the page stays interactive (no inert, no
+// trap, no focus steal, no light dismiss), the panel paints above every
+// host stacking context with zero z-index, in place in React's tree
+// (host `--tf-*`/`data-tf-theme` inherit), inside a shadow root too.
+// Rejected: position:fixed + z-index (a transformed host ancestor
+// re-parents it) and non-modal dialog.show() (steals focus). Without
+// popover support the panel never opens. Of the modal contract: inert
+// page and focus trap dropped (usable beside the host IS the feature);
+// Esc re-implemented panel-scoped; focus-on-open opt-in via
+// data-tf-autofocus and only for the visitor's own open (focusOnOpen);
+// focus return only while focus is still inside; no
+// backdrop close, no scroll lock; top-layer order is promotion order.
+// A hide the panel did not initiate (a modal's hide-all-popovers, a
+// host hidePopover()) is a YIELD, not a close: `open` stays true and
+// the panel returns when the way clears, without touching focus.
+// Deferred: software-keyboard handling and scroll-aware swipe arbitration.
+// The decision in full, alternatives included: docs/floating-panel.md.
+
+type FloatingPanelCorner = "bottom-right" | "bottom-left";
+type FloatingPanelDock = "floating" | "sidebar";
+
+interface TfFloatingPanelProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** The viewport corner the panel anchors to. The companion sits in the
+   * same corner; its clearance is the consumer's className. */
+  corner?: FloatingPanelCorner;
+  /** Where the panel lives: the floating corner card (default), or the
+   * full-height sidebar docked flush to the right edge with the host
+   * page pushed aside. The sidebar ignores `corner` — right-edge only. */
+  dock?: FloatingPanelDock;
+  "aria-label": string;
+  /** The open is the visitor's own gesture, so the content's
+   *  data-tf-autofocus mark may take the caret; read as of the open. */
+  focusOnOpen: boolean;
+  className?: string;
+  children: ReactNode;
+}
+
+/** Where focus actually is, from the panel's own tree: getRootNode(),
+ * never the document, which retargets activeElement to the shadow HOST
+ * inside the script-tag distribution — the contains() guard would always
+ * fail and the captured opener would be the host. */
+function _activeElementNear(panel: HTMLElement): Element | null {
+  const root = panel.getRootNode();
+  return root instanceof Document || root instanceof ShadowRoot
+    ? root.activeElement
+    : null;
+}
+
+/** Restores focus to the remembered opener, but only when the close is
+ * taking focus away from the user — i.e. focus still lives inside the
+ * panel. A user who opened the panel and moved on keeps their place. */
+function _returnFocusToOpener(
+  panel: HTMLElement,
+  opener: Element | null,
+): void {
+  if (!panel.contains(_activeElementNear(panel))) {
+    return;
+  }
+  if (opener instanceof HTMLElement && opener.isConnected) {
+    opener.focus();
+  }
+}
+
+export function TfFloatingPanel({
+  open,
+  onOpenChange,
+  corner = "bottom-right",
+  dock = "floating",
+  focusOnOpen,
+  className,
+  children,
+  ...props
+}: TfFloatingPanelProps) {
+  const panelRef = useRef<HTMLDivElement>(null);
+  const parkOnForcedHide = usePopoverPresence(panelRef, open, focusOnOpen);
+
+  // Esc closes the surface it is pressed in, and nothing else: scoped to
+  // keydowns that reach the panel, stopped so one keystroke does one thing.
+  const closeFromEscape = useCallback(
+    (event: KeyboardEvent<HTMLDivElement>) => {
+      if (event.key !== "Escape" || event.defaultPrevented) {
+        return;
+      }
+      event.stopPropagation();
+      onOpenChange(false);
+    },
+    [onOpenChange],
+  );
+
+  const dismiss = useCallback(() => {
+    onOpenChange(false);
+  }, [onOpenChange]);
+  // Downward swipe on the grab region dismisses — confined to the handle
+  // because the content scrolls the same axis. Docked, the gesture is
+  // off: a full-height pane reads as page furniture, and furniture that
+  // flies away under a drag reads as breakage.
+  const swipe = useSwipeDismiss({
+    axis: "y",
+    direction: 1,
+    open,
+    enabled: dock === "floating",
+    onDismiss: dismiss,
+    handleSelector: "[data-tf-swipe-handle]",
+  });
+
+  useDockReflow(panelRef, dock);
+
+  return (
+    // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- the keydown is the panel's own Esc-to-close; the pointer handlers are the handle's swipe. Keyboard users close via Esc.
+    <div
+      ref={panelRef}
+      popover="manual"
+      role="dialog"
+      data-tf-assistant=""
+      data-tf-floating-panel={corner}
+      data-tf-panel-dock={dock}
+      // Glass is earned by floating over the host's pixels; the docked
+      // pane pushes the page aside and stays opaque Graphite.
+      data-tf-glass={dock === "floating" ? "" : undefined}
+      onToggle={parkOnForcedHide}
+      onKeyDown={closeFromEscape}
+      onPointerDown={swipe.onPointerDown}
+      onPointerMove={swipe.onPointerMove}
+      onPointerUp={swipe.onPointerUp}
+      onPointerCancel={swipe.onPointerCancel}
+      onClickCapture={swipe.onClickCapture}
+      className={cx(
+        // `hidden` restates the UA's closed-popover display and is the
+        // whole display without popover support; the important marker is
+        // ordering insurance between tf:hidden and tf:open:flex.
+        "tf:m-0 tf:hidden tf:p-0 tf:open:flex!",
+        "tf:flex-col tf:overflow-hidden tf:text-tf-foreground",
+        dock === "sidebar"
+          ? // Flush full-height, edge to edge, never an inset column: the
+            // Portal Lift rule inverted — no shadow, square corners, a
+            // hairline left border (in styles.css, not a border-l utility:
+            // border utilities ride an @property registration Chromium honours
+            // only in document sheets; this must paint everywhere). A fixed 26rem
+            // on ultrawide too — a pane, not a proportion; max-w guards an
+            // inflated host rem. left-auto is load-bearing: the UA popover
+            // style is inset:0, and left+right 0 resolves to the LEFT edge in LTR.
+            "tf:inset-y-0 tf:right-0 tf:left-auto tf:h-dvh tf:w-104 tf:max-w-[calc(100vw-2rem)] tf:rounded-none tf:bg-tf-background tf:shadow-none"
+          : cx(
+              // A floating corner card, never flush: the viewport-edge margins
+              // signal "the page is still there". Compose-window proportions
+              // (~44vw): the 24rem floor is the phone card, 46rem caps the
+              // ultrawide so the panel stays a card, never a pane.
+              "tf:inset-auto tf:bottom-4 tf:w-[clamp(24rem,44vw,46rem)] tf:max-w-[calc(100vw-2rem)]",
+              // Fixed height under viewport-relative caps so the panel never
+              // jumps between empty and busy: ~68dvh is the compose-window
+              // register, 52rem stops tall monitors growing a tower, and the
+              // 6rem headroom term keeps the software-keyboard behavior.
+              "tf:h-[min(68dvh,52rem,calc(100dvh-6rem))]",
+              // The floating-surface chrome comes from the liquid-glass
+              // material (data-tf-glass, styles.css). The 24px corner is the
+              // panel step of the radius ladder (the composer slab wears the
+              // same literal), not derived from --tf-radius so a host's
+              // control-radius theme can't unround the surface.
+              "tf:rounded-3xl tf:border",
+              corner === "bottom-left" ? "tf:left-4" : "tf:right-4",
+            ),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/**
+ * The popover discipline: `open` shows and hides the top-layer panel
+ * (focus captured on a gesture's open, returned on close), a hide the
+ * panel did not initiate parks it, and the way-is-clear watcher restores
+ * it. Returns the toggle handler that detects the forced hide.
+ */
+function usePopoverPresence(
+  panelRef: RefObject<HTMLDivElement | null>,
+  open: boolean,
+  focusOnOpen: boolean,
+): (event: ToggleEvent<HTMLDivElement>) => void {
+  const openerRef = useRef<Element | null>(null);
+  const focusOnOpenRef = useLatestRef(focusOnOpen);
+  // Parked by a modal (or a meddling host script): hidden while `open`
+  // still says true, waiting for the way to clear. A ref, not state:
+  // nothing rendered depends on it and the watcher reads it live.
+  const yieldedRef = useRef(false);
+
+  // The `open` prop stays authoritative: external hides are parked or
+  // reported, never applied locally, and this effect is the only writer.
+  // Inert is written here for the whole not-open stretch, not rendered:
+  // inert={!open} would commit before this effect and blur the focused
+  // descendant, so the focus return's "still inside" check could never
+  // pass. On open it lifts BEFORE showPopover(); on close it lands after.
+  useEffect(() => {
+    const panel = panelRef.current;
+    if (panel === null) {
+      return;
+    }
+    if (open) {
+      panel.removeAttribute("inert");
+    }
+    if (typeof panel.showPopover === "function") {
+      const showing = panel.matches(":popover-open");
+      if (open && !showing && !yieldedRef.current) {
+        openerRef.current = _activeElementNear(panel);
+        panel.showPopover();
+        if (focusOnOpenRef.current) {
+          focusAutofocusTarget(panel, () => panel.matches(":popover-open"));
+        }
+      } else if (!open) {
+        if (showing) {
+          // Before hidePopover(), while "focus is still inside" is still
+          // observable.
+          _returnFocusToOpener(panel, openerRef.current);
+          panel.hidePopover();
+        }
+        yieldedRef.current = false;
+      }
+    }
+    if (!open) {
+      panel.setAttribute("inert", "");
+    }
+  }, [panelRef, open, focusOnOpenRef]);
+
+  // The yield detector. Our own hide only ever runs with `open` already
+  // false, so a closed-toggle arriving while `open` is true was forced
+  // from outside — a modal's hide-all-popovers, or a host script.
+  const parkOnForcedHide = useCallback(
+    (event: ToggleEvent<HTMLDivElement>) => {
+      if (event.newState === "closed" && open) {
+        yieldedRef.current = true;
+      }
+    },
+    [open],
+  );
+
+  // The way-is-clear watcher, listening for the whole open stretch and
+  // acting only while parked. `close` doesn't bubble, so the document
+  // hears it in the capture phase; fullscreen exits hide popovers through
+  // the same spec step. Restoration never touches focus.
+  useEffect(() => {
+    const panel = panelRef.current;
+    if (!open || panel === null || typeof panel.showPopover !== "function") {
+      return;
+    }
+    const doc = panel.ownerDocument;
+    const restoreWhenClear = () => {
+      // fullscreenchange fires on the way IN too, and entering fullscreen
+      // is itself a popover-hiding step — without the fullscreenElement
+      // check this would pop the panel over the fullscreen element.
+      if (
+        !yieldedRef.current ||
+        doc.querySelector("dialog:modal") !== null ||
+        doc.fullscreenElement !== null
+      ) {
+        return;
+      }
+      if (!panel.matches(":popover-open")) {
+        panel.showPopover();
+      }
+      yieldedRef.current = false;
+    };
+    doc.addEventListener("close", restoreWhenClear, true);
+    doc.addEventListener("fullscreenchange", restoreWhenClear);
+    return () => {
+      doc.removeEventListener("close", restoreWhenClear, true);
+      doc.removeEventListener("fullscreenchange", restoreWhenClear);
+    };
+  }, [panelRef, open]);
+
+  return parkOnForcedHide;
+}

package/src/components/primitives/kbd.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+import type { ComponentPropsWithoutRef } from "react";
+
+import { cx } from "./cx.js";
+
+// A key cap: the question panel's ↑ ↓ ↵ hints at the right edge of the
+// active answer row. Hairline on a transparent ground (so it sits on the
+// emphasis wash in light and dark alike), the badge step, the control
+// radius — an instrument marking, never a decoration — and always
+// aria-hidden at the call site: the hint duplicates what the radiogroup's
+// description already tells assistive tech, so it must not be read twice.
+// Never wraps: a two-token cap ("Ctrl ↵") must stay one line inside its
+// 20px height. Geist Sans, not mono: the visual spec keeps the mono face
+// for code alone; the glyphs themselves are icons at the call site,
+// because a host font cannot be trusted to carry U+21B5.
+
+// WithoutRef on purpose: a plain function component cannot forward a ref
+// under React 18.3, so admitting one in the props type would type-check a
+// silent no-op (tests/ref-prop-surface.test.ts holds the line).
+export function Kbd({ className, ...props }: ComponentPropsWithoutRef<"kbd">) {
+  return (
+    <kbd
+      className={cx(
+        "tf:inline-flex tf:h-5 tf:min-w-5 tf:items-center tf:justify-center tf:gap-0.5 tf:rounded-tf",
+        "tf:border tf:border-tf-input tf:bg-tf-transparent tf:px-1 tf:font-tf-sans tf:text-xs",
+        "tf:leading-none tf:whitespace-nowrap tf:text-tf-muted-foreground",
+        className,
+      )}
+      {...props}
+    />
+  );
+}