@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.511

package/src/components/shared/doc-search/use-doc-search.ts

@@ -26,6 +26,16 @@
  * Everything else (debounce, `useChatRuntime` for embed-mode short-
  * circuit, embed-shim router, the action-resolver + result-mapper) is
  * now lib-resident.
+ *
+ * ## Result hrefs go through the content-href seam
+ *
+ * A row's href is NOT the RAG `externalUrl` verbatim any more: when the
+ * host wires `runtime.composeContentUrl` (or passes `composeContentUrl`
+ * here), the row is re-resolved through it — the SAME seam the catalog
+ * cards and the chat entity cards use. So a host that serves onboarding
+ * guides at `/help-center/onboarding-guides/<slug>` gets that path from
+ * the dropdown too, instead of bouncing the user to the canonical hub
+ * URL. Unwired hosts keep the verbatim-`externalUrl` behavior.
  */
 
 import { useState, useEffect, useCallback } from 'react'
@@ -39,6 +49,7 @@ import {
   stripSameOriginToPath,
   NEW_TAB_FEATURES,
 } from '../../chat/utils/chat-nav-resolution'
+import type { ComposeContentUrl } from '../../../utils/content-href'
 import type { DocSearchResult } from './types'
 import { mapDocSearchResults } from './map-doc-search-results'
 import { resolveSearchResultAction } from './resolve-search-result-action'
@@ -72,6 +83,12 @@ export interface UseDocSearchConfig {
    *  (the hub's reverse-proxy route). Embedders with a different
    *  path can override. */
   searchEndpoint?: string
+  /** Optional content-href seam override. Same fall-back chain as
+   *  `searchEndpoint`: prop → `runtime.composeContentUrl` → none. Wired,
+   *  it makes a result row honor the host's `hostedTypes` / `overrides`
+   *  instead of navigating to the RAG's canonical hub URL — so a row
+   *  lands where the catalog card for the same entity lands. */
+  composeContentUrl?: ComposeContentUrl
 }
 
 export function useDocSearch(config: UseDocSearchConfig) {
@@ -82,6 +99,7 @@ export function useDocSearch(config: UseDocSearchConfig) {
     tableIds,
     onInPageSwap,
     searchEndpoint,
+    composeContentUrl,
   } = config
   const tableIdsKey = tableIds && tableIds.length > 0 ? tableIds.join(',') : ''
 
@@ -94,6 +112,11 @@ export function useDocSearch(config: UseDocSearchConfig) {
   const runtime = useChatRuntime()
   const resolvedSearchEndpoint =
     searchEndpoint ?? runtime?.endpoints.docsSearchUrl ?? '/api/docs/search'
+  // Content-href seam, same prop → runtime → none chain. Threading it into
+  // `resolveSearchResultAction` is what makes the dropdown obey the host's
+  // route map; without it the row navigates to the RAG's canonical hub URL
+  // even when the host serves that content in-app under a different path.
+  const resolvedComposeContentUrl = composeContentUrl ?? runtime?.composeContentUrl
 
   const [query, setQuery] = useState('')
   const [results, setResults] = useState<SearchResult[]>([])
@@ -172,6 +195,7 @@ export function useDocSearch(config: UseDocSearchConfig) {
         result,
         source,
         runtime?.navigation.mode,
+        resolvedComposeContentUrl,
       )
       // Modifier / non-primary mouse click → force new tab regardless of
       // same-tab/new-tab decision. The dropdown row is a `<div>`, not an
@@ -188,19 +212,6 @@ export function useDocSearch(config: UseDocSearchConfig) {
           (typeof modifiers.button === 'number' && modifiers.button !== 0))
       switch (action.kind) {
         case 'navigate-same-tab': {
-          // Embed-mode short-circuit — autocomplete row clicked while
-          // the chat panel is hosted inside an embedding app.
-          if (runtime?.navigation.mode === 'embed') {
-            setKeepOpen(true)
-            const targetPlatform =
-              (result.metadata?.targetPlatform as string | null | undefined) ?? null
-            resolveExternalNavigation({
-              href: action.href,
-              targetPlatform,
-              runtime,
-            }).open()
-            return
-          }
           if (wantsNewTab) {
             setKeepOpen(true)
             window.open(action.href, '_blank', NEW_TAB_FEATURES)
@@ -226,6 +237,23 @@ export function useDocSearch(config: UseDocSearchConfig) {
           // product-hub) — open in a new tab. Keep dropdown open so the
           // user can pick another result without re-searching.
           setKeepOpen(true)
+          // Embed-mode short-circuit — the row was clicked while the panel is
+          // hosted inside an embedding app, so absolutize against the
+          // embedder-supplied content origin and honor its `openExternal`
+          // override. Not the only path an embed host takes: a composed
+          // RELATIVE href resolves to `navigate-same-tab` above and never
+          // reaches `decideNewTab`, which is what lets an embedder keep its
+          // own in-app routes in-app.
+          if (runtime?.navigation.mode === 'embed') {
+            const targetPlatform =
+              (result.metadata?.targetPlatform as string | null | undefined) ?? null
+            resolveExternalNavigation({
+              href: action.href,
+              targetPlatform,
+              runtime,
+            }).open()
+            return
+          }
           window.open(action.href, '_blank', NEW_TAB_FEATURES)
           return
         case 'ask-ai':
@@ -249,7 +277,15 @@ export function useDocSearch(config: UseDocSearchConfig) {
           return
       }
     },
-    [onNavigate, source, baseRoute, router, onInPageSwap, runtime],
+    [
+      onNavigate,
+      source,
+      baseRoute,
+      router,
+      onInPageSwap,
+      runtime,
+      resolvedComposeContentUrl,
+    ],
   )
 
   // Reset keepOpen when query changes.

package/src/components/ui/__tests__/overlay-open-registry.test.tsx

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest'
+import { render, act } from '@testing-library/react'
+import { useState } from 'react'
+import {
+  OverlayOpenRegistryProvider,
+  useReportOverlayOpen,
+} from '../overlay-open-registry'
+
+/** Stand-in for `ActionsMenuDropdown` — reports its open state, renders nothing. */
+function Overlay({ open }: { open: boolean }) {
+  useReportOverlayOpen(open)
+  return null
+}
+
+describe('OverlayOpenRegistry', () => {
+  it('fires only on 0 → 1 and 1 → 0, not per overlay', () => {
+    const onOpenChange = vi.fn()
+    function Harness({ a, b }: { a: boolean; b: boolean }) {
+      return (
+        <OverlayOpenRegistryProvider onOpenChange={onOpenChange}>
+          <Overlay open={a} />
+          <Overlay open={b} />
+        </OverlayOpenRegistryProvider>
+      )
+    }
+    const { rerender } = render(<Harness a={false} b={false} />)
+    expect(onOpenChange).not.toHaveBeenCalled()
+
+    rerender(<Harness a b={false} />)
+    expect(onOpenChange.mock.calls).toEqual([[true]])
+
+    // Second overlay opens while the first is still open — no new signal.
+    rerender(<Harness a b />)
+    expect(onOpenChange.mock.calls).toEqual([[true]])
+
+    // First closes, one still open — still no signal.
+    rerender(<Harness a={false} b />)
+    expect(onOpenChange.mock.calls).toEqual([[true]])
+
+    rerender(<Harness a={false} b={false} />)
+    expect(onOpenChange.mock.calls).toEqual([[true], [false]])
+  })
+
+  it('releases when an open overlay unmounts', () => {
+    const onOpenChange = vi.fn()
+    function Harness({ mounted }: { mounted: boolean }) {
+      return (
+        <OverlayOpenRegistryProvider onOpenChange={onOpenChange}>
+          {mounted ? <Overlay open /> : null}
+        </OverlayOpenRegistryProvider>
+      )
+    }
+    const { rerender } = render(<Harness mounted />)
+    expect(onOpenChange.mock.calls).toEqual([[true]])
+    rerender(<Harness mounted={false} />)
+    expect(onOpenChange.mock.calls).toEqual([[true], [false]])
+  })
+
+  it('is inert without a provider — no throw, no crash', () => {
+    expect(() => render(<Overlay open />)).not.toThrow()
+  })
+
+  it('a stable context value keeps overlays from re-rendering on count changes', () => {
+    const renderSpy = vi.fn()
+    function CountingOverlay({ open }: { open: boolean }) {
+      renderSpy()
+      useReportOverlayOpen(open)
+      return null
+    }
+    let bump: (() => void) | undefined
+    function Harness() {
+      const [, setTick] = useState(0)
+      bump = () => setTick((t) => t + 1)
+      return (
+        <OverlayOpenRegistryProvider>
+          <CountingOverlay open={false} />
+        </OverlayOpenRegistryProvider>
+      )
+    }
+    render(<Harness />)
+    const before = renderSpy.mock.calls.length
+    act(() => bump?.())
+    // One re-render from the parent's own state, not extra churn from context.
+    expect(renderSpy.mock.calls.length).toBe(before + 1)
+  })
+})

package/src/components/ui/actions-menu.tsx

@@ -13,6 +13,16 @@ import {
 	DropdownMenuContent,
 	DropdownMenuTrigger,
 } from "./dropdown-menu";
+import {
+	COLLISION_PADDING_PX,
+	useCollisionBoundary,
+	usePortalContainer,
+} from "./portal-container";
+import { useReportOverlayOpen } from "./overlay-open-registry";
+
+/** Trigger movement (px) that counts as "the user scrolled away" rather than
+ *  touch-momentum jitter or the sub-pixel settle right after opening. */
+const SCROLL_DISMISS_THRESHOLD_PX = 12;
 
 export interface ActionsMenuItemIconAction {
 	icon: React.ReactNode;
@@ -126,6 +136,10 @@ const SecondaryAction: React.FC<{ action: ActionsMenuItemIconAction }> = ({ acti
 };
 
 const MenuItem: React.FC<MenuItemProps> = ({ item, onItemClick }) => {
+	// Submenus below portal + collide against the OWNING surface, matching the
+	// root menu (`DropdownMenuContent`). Read unconditionally — hooks first.
+	const portalContainer = usePortalContainer();
+	const collisionBoundary = useCollisionBoundary();
 	const activate = useCallback(() => {
 		if (item.disabled) return;
 		if (item.type === "checkbox") {
@@ -265,9 +279,14 @@ const MenuItem: React.FC<MenuItemProps> = ({ item, onItemClick }) => {
 					>
 						{rowContent}
 					</DropdownMenuPrimitive.SubTrigger>
-					<DropdownMenuPrimitive.Portal>
+					<DropdownMenuPrimitive.Portal container={portalContainer ?? undefined}>
 						<DropdownMenuPrimitive.SubContent
 							sideOffset={4}
+							// Confine flip/shift (and the available-height this menu sizes
+							// itself by) to the owning surface — see `useCollisionBoundary`.
+							collisionBoundary={collisionBoundary ?? undefined}
+							collisionPadding={collisionBoundary ? COLLISION_PADDING_PX : undefined}
+							hideWhenDetached
 							className="z-[1500] min-w-[256px] max-h-[var(--radix-popper-available-height)] bg-ods-bg border border-ods-border rounded-md shadow-xl overflow-y-auto p-0"
 						>
 							{item.submenu.map((subItem, index) => (
@@ -377,6 +396,50 @@ export const ActionsMenuDropdown: React.FC<ActionsMenuDropdownProps> = ({
 		onChange: onOpenChange,
 	});
 
+	// Tell the surrounding surface an overlay is open, so it can stop moving
+	// the ground under it (the chat thread suspends its follow-the-bottom
+	// auto-scroll — see `OverlayOpenRegistryProvider`). Inert without a
+	// provider, so menus elsewhere are unaffected.
+	useReportOverlayOpen(open);
+
+	// Dismiss once the USER scrolls the trigger away.
+	//
+	// Two different situations, two different answers. Content moving on its own
+	// (a streaming reply) is handled above by suspending the auto-scroll — the
+	// menu must survive that, nobody asked for it to close. A deliberate scroll
+	// is the opposite: the reader left, and an anchored menu would ride along
+	// until it hovers over unrelated chrome. `hideWhenDetached` only kicks in
+	// once the trigger is FULLY clipped, so a half-scrolled trigger still drags
+	// a visible menu across the header.
+	//
+	// Scoped deliberately:
+	//   • only scrolls of containers that actually contain the trigger — a
+	//     scroll in a neighbouring column is none of our business;
+	//   • only past `SCROLL_DISMISS_THRESHOLD_PX` of movement, so touch
+	//     momentum and the ~1px settle after opening don't close the menu the
+	//     user is reaching for.
+	const triggerRef = React.useRef<HTMLButtonElement | null>(null);
+	React.useEffect(() => {
+		if (!open) return;
+		if (typeof document === "undefined") return;
+		const trigger = triggerRef.current;
+		if (!trigger) return;
+		const anchorTop = trigger.getBoundingClientRect().top;
+		const onScroll = (event: Event) => {
+			const target = event.target as Node | null;
+			// `document` fires for the page scroll and contains everything.
+			const scrolledTheTrigger =
+				target === document ||
+				(target instanceof Node && target.contains(trigger));
+			if (!scrolledTheTrigger) return;
+			const moved = Math.abs(trigger.getBoundingClientRect().top - anchorTop);
+			if (moved > SCROLL_DISMISS_THRESHOLD_PX) setOpen(false);
+		};
+		document.addEventListener("scroll", onScroll, { capture: true, passive: true });
+		return () =>
+			document.removeEventListener("scroll", onScroll, { capture: true });
+	}, [open, setOpen]);
+
 	const handleItemClick = useCallback(
 		(item: ActionsMenuItem) => {
 			onItemClick?.(item);
@@ -393,7 +456,7 @@ export const ActionsMenuDropdown: React.FC<ActionsMenuDropdownProps> = ({
 
 	return (
 		<DropdownMenu open={open} onOpenChange={setOpen} modal={false}>
-			<DropdownMenuTrigger asChild>
+			<DropdownMenuTrigger asChild ref={triggerRef}>
 				{customTrigger ?? (
 					<Button
 						variant="outline"

package/src/components/ui/dropdown-menu.tsx

@@ -5,7 +5,11 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu"
 import { Check, ChevronRight, Circle } from "lucide-react"
 
 import { cn } from "../../utils/cn"
-import { usePortalContainer } from "./portal-container"
+import {
+  COLLISION_PADDING_PX,
+  useCollisionBoundary,
+  usePortalContainer,
+} from "./portal-container"
 
 const DropdownMenu = DropdownMenuPrimitive.Root
 
@@ -44,31 +48,77 @@ DropdownMenuSubTrigger.displayName =
 const DropdownMenuSubContent = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.SubContent>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>
->(({ className, ...props }, ref) => (
-  <DropdownMenuPrimitive.SubContent
-    ref={ref}
-    className={cn(
-      "z-50 min-w-[8rem] overflow-hidden rounded-md border border-ods-border bg-ods-card p-1 text-ods-text-primary shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
-      className
-    )}
-    {...props}
-  />
-))
+>(({ className, collisionBoundary, collisionPadding, hideWhenDetached, ...props }, ref) => {
+  // Same container as the root content — `DropdownMenuContent` portals, and a
+  // submenu left un-portaled inherits whatever clipping/stacking context its
+  // parent sits in instead of the one the host published. (The hand-rolled
+  // submenu in `actions-menu` already portals; this keeps the shared primitive
+  // consistent with both.)
+  const container = usePortalContainer()
+  // Same boundary as the root content — a submenu must not escape the surface
+  // its parent menu is confined to.
+  const boundary = useCollisionBoundary()
+  const resolvedBoundary = collisionBoundary ?? boundary ?? undefined
+  return (
+  <DropdownMenuPrimitive.Portal container={container ?? undefined}>
+    <DropdownMenuPrimitive.SubContent
+      ref={ref}
+      collisionBoundary={resolvedBoundary}
+      collisionPadding={collisionPadding ?? (resolvedBoundary ? COLLISION_PADDING_PX : undefined)}
+      // Only defaulted ON where a boundary was published (i.e. inside a panel
+      // that owns its menus) — see `DropdownMenuContent`.
+      hideWhenDetached={hideWhenDetached ?? (resolvedBoundary ? true : undefined)}
+      className={cn(
+        "z-50 min-w-[8rem] overflow-hidden rounded-md border border-ods-border bg-ods-card p-1 text-ods-text-primary shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        className
+      )}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+  )
+})
 DropdownMenuSubContent.displayName =
   DropdownMenuPrimitive.SubContent.displayName
 
 const DropdownMenuContent = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
->(({ className, sideOffset = 4, ...props }, ref) => {
+>(({
+  className,
+  sideOffset = 4,
+  collisionBoundary,
+  collisionPadding,
+  hideWhenDetached,
+  ...props
+}, ref) => {
   // Portal into the active container (e.g. a drawer) so the menu inherits its
   // stacking context; falls back to `document.body` when none is provided.
   const container = usePortalContainer()
+  // Keep flip/shift inside the surface that owns the menu. Without this Radix
+  // collides against the VIEWPORT, so a menu opened near the top of the chat
+  // panel grows upward past the panel and lands over the app header. An
+  // explicit prop still wins; no provider → viewport, Radix's own default.
+  const boundary = useCollisionBoundary()
+  const resolvedBoundary = collisionBoundary ?? boundary ?? undefined
   return (
   <DropdownMenuPrimitive.Portal container={container ?? undefined}>
     <DropdownMenuPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}
+      collisionBoundary={resolvedBoundary}
+      collisionPadding={collisionPadding ?? (resolvedBoundary ? COLLISION_PADDING_PX : undefined)}
+      // A menu tracks its trigger for as long as it is open. When the trigger
+      // scrolls out of its clipping ancestor — a chat card carried away by the
+      // thread's auto-scroll while the menu is open — Radix keeps the menu
+      // pinned to that off-screen anchor, so it slides to the surface edge and
+      // reads as a detached popup floating over unrelated chrome.
+      // `hideWhenDetached` makes it disappear with its trigger instead.
+      //
+      // Defaulted ON only where a boundary was published. This is a SHARED
+      // primitive: flipping it on globally would change dismissal behavior for
+      // every dropdown in every consumer, and the detached-popup problem it
+      // solves is specific to a menu living inside a scrolling panel.
+      hideWhenDetached={hideWhenDetached ?? (resolvedBoundary ? true : undefined)}
       className={cn(
         "z-50 min-w-[8rem] overflow-hidden rounded-md border border-ods-border bg-ods-card p-1 text-ods-text-primary shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className

package/src/components/ui/markdown/base-components.tsx

@@ -21,6 +21,11 @@ import {
   useHeadingId,
 } from './heading-ids';
 import { slugifyHeadingText } from '../../../utils/markdown-heading-id';
+import {
+  getHashTargetElement,
+  navigateSamePageHash,
+  HUB_HEADER_OFFSET_PX,
+} from '../../../utils/same-page-hash-nav';
 
 /**
  * True when an image `src` is worth rendering. Shared by the base `img` and
@@ -284,12 +289,33 @@ export function buildBaseComponents({
         );
       }
 
+      // In-page anchor. Doc TOCs are authored against GitHub's slugger
+      // (`## 📚 Table of Contents` → `#-table-of-contents`) while our heading
+      // ids trim the emoji's leftover hyphen, so the raw href resolves to
+      // nothing and the browser silently ignores the click. Resolve through
+      // `getHashTargetElement` — the same resolver deep links use — then hand
+      // the real id to the canonical hash-nav helper, which also lands the
+      // heading BELOW the sticky header instead of under it, matching how the
+      // "On this page" rail scrolls.
+      const isInPageAnchor = typeof href === 'string' && href.startsWith('#') && href.length > 1;
+      const handleAnchorClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+        // Let modifier / non-primary clicks keep their native behavior.
+        if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+        const target = getHashTargetElement(href.slice(1));
+        // Nothing matched anywhere in the document → leave the browser's
+        // default alone rather than swallowing a click that isn't ours.
+        if (!target?.id) return;
+        e.preventDefault();
+        navigateSamePageHash(`#${target.id}`, { headerOffset: HUB_HEADER_OFFSET_PX });
+      };
+
       return (
         <a
           href={href}
           className={`text-ods-accent no-underline relative transition-colors duration-200 hover:after:w-full after:content-[''] after:absolute after:w-0 after:h-0.5 after:-bottom-0.5 after:left-0 after:bg-ods-accent after:transition-all after:duration-300 ${linkClassName || ''}`}
           target={href?.startsWith('http') ? '_blank' : undefined}
           rel={href?.startsWith('http') ? 'noopener noreferrer' : undefined}
+          onClick={isInPageAnchor ? handleAnchorClick : undefined}
         >
           {children}
         </a>

package/src/components/ui/overlay-open-registry.tsx

@@ -0,0 +1,99 @@
+'use client'
+
+/**
+ * A surface-scoped count of overlays (⋯ menus, popovers) currently open INSIDE
+ * that surface, so the surface can suspend behaviour that would move the ground
+ * under them.
+ *
+ * ## Why
+ *
+ * An open menu stays anchored to its trigger. In a chat thread the ground moves
+ * on its own: a streaming reply grows the transcript and the auto-scroll follows
+ * the bottom, carrying the trigger — and its menu — upward until the menu is
+ * pinned to an off-screen anchor at the panel edge, visually detached from the
+ * card it belongs to.
+ *
+ * The honest fix is not to dismiss the menu on every scroll event (that breaks
+ * touch, where momentum scrolling fires constantly) but to stop pulling the
+ * ground: while an overlay is open the thread stops chasing the bottom, exactly
+ * how ChatGPT/Claude stop chasing once you interact with the transcript. When
+ * the overlay closes, the thread catches up if it was at the bottom before.
+ *
+ * ## Wiring
+ *
+ * Surface: wrap the region in `<OverlayOpenRegistryProvider onOpenChange={…}>`.
+ * Overlay: call `useReportOverlayOpen(open)`. No provider → the hook is inert,
+ * so overlays outside such a surface behave exactly as before.
+ */
+
+import * as React from 'react'
+
+export interface OverlayOpenRegistry {
+  /** Register one open overlay; call the returned fn to release it. */
+  acquire: () => () => void
+}
+
+export const OverlayOpenRegistryContext =
+  React.createContext<OverlayOpenRegistry | null>(null)
+
+/** Read the surrounding registry (or `null` when there is no provider). */
+export function useOverlayOpenRegistry(): OverlayOpenRegistry | null {
+  return React.useContext(OverlayOpenRegistryContext)
+}
+
+/**
+ * Report this overlay's open state to the surrounding surface. Safe to call
+ * unconditionally — with no provider it does nothing.
+ */
+export function useReportOverlayOpen(open: boolean): void {
+  const registry = useOverlayOpenRegistry()
+  React.useEffect(() => {
+    if (!open || !registry) return
+    return registry.acquire()
+  }, [open, registry])
+}
+
+export interface OverlayOpenRegistryProviderProps {
+  /** Fires on 0 → 1 and 1 → 0 transitions only, not on every acquire. */
+  onOpenChange?: (hasOpenOverlay: boolean) => void
+  children: React.ReactNode
+}
+
+/**
+ * Owns the count for one surface. The context value is referentially stable, so
+ * mounting this provider does not re-render overlays when the count changes —
+ * only the surface's own `onOpenChange` callback fires.
+ */
+export function OverlayOpenRegistryProvider({
+  onOpenChange,
+  children,
+}: OverlayOpenRegistryProviderProps) {
+  const countRef = React.useRef(0)
+  const onOpenChangeRef = React.useRef(onOpenChange)
+  onOpenChangeRef.current = onOpenChange
+
+  const registry = React.useMemo<OverlayOpenRegistry>(
+    () => ({
+      acquire: () => {
+        countRef.current += 1
+        if (countRef.current === 1) onOpenChangeRef.current?.(true)
+        let released = false
+        return () => {
+          // Guard against a double release (StrictMode double-invokes effect
+          // cleanups in development) driving the count negative.
+          if (released) return
+          released = true
+          countRef.current -= 1
+          if (countRef.current === 0) onOpenChangeRef.current?.(false)
+        }
+      },
+    }),
+    [],
+  )
+
+  return (
+    <OverlayOpenRegistryContext.Provider value={registry}>
+      {children}
+    </OverlayOpenRegistryContext.Provider>
+  )
+}

package/src/components/ui/portal-container.tsx

@@ -26,3 +26,34 @@ export const PortalContainerContext = React.createContext<HTMLElement | null>(
 export function usePortalContainer(): HTMLElement | null {
   return React.useContext(PortalContainerContext)
 }
+
+/**
+ * The element Radix overlays should treat as their COLLISION boundary — the
+ * surface they must stay inside of.
+ *
+ * Separate from {@link PortalContainerContext} on purpose: the portal target is
+ * a `display: contents` node (no box, so it can't be measured), while a
+ * collision boundary must be a real, laid-out element.
+ *
+ * Why it matters: Radix positions overlays `position: fixed` and, by default,
+ * flips/shifts them against the VIEWPORT. A menu opened near the top of a
+ * panel therefore happily grows upward past the panel's edge and lands on top
+ * of the app header — visually detached from the surface it belongs to. Handing
+ * Radix the panel element instead keeps flip/shift (and the
+ * `--radix-popper-available-height` a menu sizes itself by) inside that panel.
+ *
+ * Default `null` → viewport, i.e. Radix's own default, unchanged everywhere a
+ * provider isn't present.
+ */
+export const CollisionBoundaryContext = React.createContext<HTMLElement | null>(
+  null,
+)
+
+/** Read the active collision boundary (or `null` for the viewport). */
+export function useCollisionBoundary(): HTMLElement | null {
+  return React.useContext(CollisionBoundaryContext)
+}
+
+/** Padding (px) kept between an overlay and its boundary edge. Matches the
+ *  panel's own gutter so a shifted menu never sits flush against the edge. */
+export const COLLISION_PADDING_PX = 8