@flamingo-stack/openframe-frontend-core 0.0.510 → 0.0.511-snapshot.20260804140004

package/src/components/shared/doc-search/__tests__/resolve-search-result-action.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, it } from 'vitest'
+import { makeComposeContentUrl } from '../../../../utils/content-href'
+import type { SearchResult } from '../../../ui/search-input'
+import { resolveSearchResultAction } from '../resolve-search-result-action'
+
+const HUB = 'https://www.flamingo.run'
+
+/** A RAG row for a guide the hub owns, shaped like `mapDocSearchResults` emits. */
+const guideRow: SearchResult = {
+  id: 'onboarding-guides/deploy-first-device',
+  title: 'Deploy your first device',
+  path: 'onboarding-guides/deploy-first-device',
+  metadata: {
+    documentType: 'onboarding_guide',
+    externalUrl: `${HUB}/onboarding-guides/deploy-first-device`,
+    sourceRepo: 'onboarding-guides',
+    id: 'guide-123',
+    targetPlatform: 'openframe',
+  },
+}
+
+/** The OpenFrame Help Center seam: the two hosted types live under
+ *  `/help-center/...`, list-filter types deep-link with `?search=<id>`. */
+const helpCenterCompose = makeComposeContentUrl({
+  hostedTypes: new Set(['onboarding_guide', 'product_release']),
+  contentOrigin: HUB,
+  suffixes: {
+    onboarding_guide: 'help-center/onboarding-guides',
+    product_release: 'help-center/releases',
+    blog_post: 'blog',
+  },
+  overrides: {
+    delivery_item: (id) => ({ href: `/help-center/bug-fixes?search=${id}`, targetPlatform: null }),
+  },
+})
+
+describe('resolveSearchResultAction — composeContentUrl seam', () => {
+  it('no seam wired → the RAG externalUrl verbatim (legacy behavior)', () => {
+    expect(resolveSearchResultAction(guideRow, 'openframe')).toEqual({
+      kind: 'navigate-same-tab',
+      href: `${HUB}/onboarding-guides/deploy-first-device`,
+    })
+  })
+
+  it('hosted type → the host in-app route, slug recovered from externalUrl', () => {
+    expect(
+      resolveSearchResultAction(guideRow, 'openframe', 'host', helpCenterCompose),
+    ).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/onboarding-guides/deploy-first-device',
+    })
+  })
+
+  it('relative composed href stays same-tab even in embed mode', () => {
+    // `decideNewTab` forces new-tab under embed; an in-app path must not be
+    // handed to window.open — the short-circuit runs before that decision.
+    expect(
+      resolveSearchResultAction(guideRow, 'openframe', 'embed', helpCenterCompose),
+    ).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/onboarding-guides/deploy-first-device',
+    })
+  })
+
+  it('override type → the host deep-link, primary key as identifier', () => {
+    const row: SearchResult = {
+      id: 'delivery-1',
+      title: 'Fix the thing',
+      metadata: {
+        documentType: 'delivery_item',
+        externalUrl: `${HUB}/bug-fixes-and-enhancements?search=abc123`,
+        sourceRepo: 'clickup-delivery',
+        id: 'abc123',
+      },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-same-tab',
+      href: '/help-center/bug-fixes?search=abc123',
+    })
+  })
+
+  it('non-hosted type → the seam returns externalUrl verbatim, opens out', () => {
+    const row: SearchResult = {
+      id: 'blog-1',
+      title: 'Hello',
+      metadata: {
+        documentType: 'blog_post',
+        externalUrl: `${HUB}/blog/hello`,
+        sourceRepo: 'blog-posts',
+        id: 'blog-1',
+        targetPlatform: 'flamingo',
+      },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-new-tab',
+      href: `${HUB}/blog/hello`,
+    })
+  })
+
+  it('row without documentType → seam skipped, externalUrl verbatim', () => {
+    const row: SearchResult = {
+      id: 'x',
+      title: 'Untyped',
+      metadata: { externalUrl: `${HUB}/somewhere`, targetPlatform: 'openframe' },
+    }
+    expect(resolveSearchResultAction(row, 'openframe', 'host', helpCenterCompose)).toEqual({
+      kind: 'navigate-same-tab',
+      href: `${HUB}/somewhere`,
+    })
+  })
+
+  it('no externalUrl → unchanged ask-ai / route / noop fallbacks', () => {
+    expect(
+      resolveSearchResultAction(
+        {
+          id: 'cap-1',
+          title: 'Cap Table',
+          metadata: { documentType: 'cap_table', sourceRepo: 'financial-cap-table', id: 'row-9' },
+        },
+        'company-hub',
+        'host',
+        helpCenterCompose,
+      ),
+    ).toEqual({
+      kind: 'ask-ai',
+      detail: {
+        source: 'company-hub',
+        ref: { type: 'cap_table', id: 'row-9', title: 'Cap Table', url: null },
+      },
+    })
+
+    expect(
+      resolveSearchResultAction(
+        { id: 'doc', title: 'Doc', path: 'repo/architecture/api.md' },
+        'openframe',
+        'host',
+        helpCenterCompose,
+      ),
+    ).toEqual({ kind: 'route', path: 'repo/architecture/api.md' })
+
+    expect(
+      resolveSearchResultAction({ id: 'empty', title: 'Empty' }, 'openframe', 'host', helpCenterCompose),
+    ).toEqual({ kind: 'noop' })
+  })
+})

package/src/components/shared/doc-search/resolve-search-result-action.ts

@@ -3,8 +3,9 @@
  * Returns one of five typed actions so the caller is a single switch.
  *
  * Resolution order:
- *  1. `externalUrl` present → use `decideNewTab` to choose same-tab vs
- *     new-tab against the row's `targetPlatform`.
+ *  1. `externalUrl` present → resolve the href through the host's
+ *     `composeContentUrl` seam (when wired), then use `decideNewTab` to
+ *     choose same-tab vs new-tab against the resolved `targetPlatform`.
  *  2. Row has `id` + `sourceRepo` + `documentType` → synth an Ask-AI
  *     action (entity drill-in via primary key, no URL).
  *  3. Row has only `path` → legacy navigation fallback.
@@ -16,8 +17,16 @@
 
 import type { SearchResult } from '../../ui/search-input'
 import type { ChatRef } from '../../chat/chat-ref.types'
+import type { ComposeContentUrl } from '../../../utils/content-href'
 import { decideNewTab } from '../../chat/utils/decide-new-tab'
 
+/** True for `https://…` and protocol-relative `//…`. A composed href that is
+ *  NOT absolute is an in-app route the host claimed via `hostedTypes` /
+ *  `overrides`. */
+function isAbsoluteHref(href: string): boolean {
+  return /^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(href)
+}
+
 export type SearchResultAction =
   | { kind: 'navigate-same-tab'; href: string }
   | { kind: 'navigate-new-tab'; href: string }
@@ -29,29 +38,56 @@ export function resolveSearchResultAction(
   result: SearchResult,
   source: string,
   runtimeMode?: 'host' | 'embed',
+  /** The host's unified content-href seam (`runtime.composeContentUrl`).
+   *  When wired, an entity row's RAG `externalUrl` is re-resolved through it,
+   *  so a type the host serves in-app (`hostedTypes`) or deep-links itself
+   *  (`overrides`) lands on the SAME href the catalog cards and chat cards
+   *  use. Omitted → the legacy verbatim-`externalUrl` behavior. */
+  composeContentUrl?: ComposeContentUrl,
 ): SearchResultAction {
   const meta = result.metadata ?? {}
   const externalUrl = meta.externalUrl as string | undefined
+  const rowId = meta.id as string | undefined
+  const sourceRepo = meta.sourceRepo as string | undefined
+  const documentType = meta.documentType as string | undefined
   if (externalUrl) {
+    const targetPlatform = meta.targetPlatform as string | null | undefined
+    // Unified content-href seam — the same call `resolveSourceRowCTA` makes
+    // for chat rows. Hosted types relativize the slug out of `externalUrl`;
+    // everything else comes back verbatim, so an unwired host (or a row with
+    // no `documentType`) keeps today's behavior byte-for-byte.
+    const composed =
+      composeContentUrl && documentType
+        ? composeContentUrl({
+            type: documentType,
+            identifier: rowId ?? '',
+            externalUrl,
+            targetPlatform: targetPlatform ?? null,
+          })
+        : null
+    const href = composed?.href || externalUrl
+    // A RELATIVE composed href means the host claimed this row as in-app.
+    // Short-circuit BEFORE `decideNewTab`: in embed mode that helper forces
+    // new-tab unconditionally, which would fire `window.open()` on a path
+    // that only resolves inside this app.
+    if (composed && !isAbsoluteHref(href)) {
+      return { kind: 'navigate-same-tab', href }
+    }
     // Same pure helper `useNavLink` and `useUnifiedNav` call — single
     // decision rule across cards, chips, and autocomplete rows. Thread
     // the caller's `source` as `currentSource` so the platform-vs-
     // platform comparison matches the hub's pre-migration behavior.
-    const targetPlatform = meta.targetPlatform as string | null | undefined
     const isNewTab = decideNewTab({
-      href: externalUrl,
-      targetPlatform,
+      href,
+      targetPlatform: composed ? composed.targetPlatform : targetPlatform,
       surface: 'useUnifiedNav',
       runtimeMode,
       currentSource: source,
     })
     return isNewTab
-      ? { kind: 'navigate-new-tab', href: externalUrl }
-      : { kind: 'navigate-same-tab', href: externalUrl }
+      ? { kind: 'navigate-new-tab', href }
+      : { kind: 'navigate-same-tab', href }
   }
-  const rowId = meta.id as string | undefined
-  const sourceRepo = meta.sourceRepo as string | undefined
-  const documentType = meta.documentType as string | undefined
   if (rowId && sourceRepo && documentType) {
     return {
       kind: 'ask-ai',

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