@plannotator/ui 0.36.0 → 0.38.0

package/HANDOFF.md

@@ -94,6 +94,7 @@ Pass any subset of these to `configurePlannotatorUI({ ... })`. Anything omitted
 | `loadSettingsFromBackend` | `boolean` | After install, re-hydrate settings from your `storageBackend` | off |
 | `mathRendererLoader` | `() => Promise<MathRenderer>` | How KaTeX is loaded when no renderer is registered before the first math node renders (see "Lazy renderers and eager entries"). Once registered, the package default is never called, not even as a fallback after a rejected load, and `resetMathRenderer()` keeps the registration (0.34.0); a default load already in flight at registration still fills the slot (pre-existing, see `setMathRendererLoader`), so register before the first math render | `utils/math-default-loader`'s `import('katex')`, JS only; CSS stays yours |
 | `identityGenerator` | `() => string` | The synchronous generator behind the default "tater" display name when no `identityProvider` is installed | A built-in 16 x 16 word pool of the same `adjective-noun-tater` shape; Plannotator registers the full dictionary via `utils/identity-tater` |
+| `alertIconRenderer` | `(name: string) => ReactNode | null` | The icon rendered for a GitHub alert whose title line carries `<!-- icon: name -->` (0.38.0; grammar in `utils/alertTitle`). Called only for a title line with an icon comment and no leading emoji; a null return falls back to the type icon | `null` for every name: the type's own icon, the package bundles no icon set |
 
 ### Interface details worth knowing
 
@@ -190,13 +191,13 @@ We deliberately did **not** restructure the exports map in this PR (move-don't-r
 | `utils/parser` (`parseMarkdownToBlocks`, `exportAnnotations`) | Pure — no backend. |
 | `components/BlockRenderer` + the block components it renders (`TableBlock`, `HtmlBlock`, `Callout`, `MermaidBlock`, `MathBlock`, …) | Pure rendering. |
 | `components/InlineMarkdown` | Code-file hover previews route through the `docPreviewFetcher` seam. Wiki-link rendering takes the sync `resolveLinkedDoc` prop (live labels + deleted-doc treatment; see "Wiki-link seams (0.27.0)"). |
-| `components/Viewer` | The full annotatable document. Required props: `markdown` and `taterMode` (pass `false`). **Pass `disableCodePathValidation` unless you implement `/api/doc/exists`** — code-path validation is a prop-level opt-out, not a `configure` seam. |
+| `components/Viewer` | The full annotatable document. Required props: `markdown` and `taterMode` (pass `false`). **Pass `disableCodePathValidation` unless you implement `/api/doc/exists`** — code-path validation is a prop-level opt-out, not a `configure` seam. `annotationHeader={{ onInputMethodChange, onModeChange, hideQuickLabel? }}` opts into one Viewer-owned, in-flow header containing the compact annotation controls and existing document actions. It reserves its measured responsive height, preserves all document badges, and follows `stickyActions` as one unit; omit it for the legacy action bar. Compact mode contains no help link. `hideQuickLabel` still requires the host to clamp restored mode state away from `'quickLabel'`. A host-owned scroll element must be supplied through `ScrollViewportProvider` (`hooks/useScrollViewport`) so stuck chrome and anchor clearance use the real scroller. |
 | `components/MarkdownEditor` | Theme-bridging wrapper over `@plannotator/markdown-editor`. Takes CM6 extensions via the `extensions` prop (captured ONCE per `documentId` — see "Wiki-link seams (0.27.0)") and re-exports `wikiLinks`, `embedPicker`, `embedSlashItem`, `planEmbedInsert`, and their public types. |
 | `components/MarkdownDiff` | Theme-bridging wrapper over `@plannotator/markdown-editor`'s frozen two-revision diff. Same shim pattern as `components/MarkdownEditor` (ThemeProvider bridge, `extensions` passthrough, grid card chrome); never editable. See "Frozen markdown diff (0.28.0)". |
 | `components/CommentPopover` | Anchor capture + comment entry. Ask-AI UI renders only if you pass `onAskAI`. |
 | `components/AnnotationPanel` | Renders from your annotation state; no fetches of its own. |
 | `components/AnnotationToolstrip` | The annotation mode toolstrip (Select / Pinpoint / Markup / Comment / Redline / Label). **Pass `showHelpLink={false}` in a host** — the default help modal embeds Plannotator's own YouTube walkthroughs. `hideQuickLabel` omits only the Label button (`StickyHeaderLane` forwards it, so the pinned scroll header matches); it hides the control, it does **not** clamp the mode — keep host mode state out of `'quickLabel'` (including preferences restored through `utils/editorMode`, which accepts it from storage) or text selection silently opens the quick-label picker with no visible cause. `hideInputMethodSwitch` likewise omits the pinpoint/drag switch. *(Blessed in 0.35.0.)* |
-| `components/StickyHeaderLane` | The measured compact toolstrip + badge lane aligned beside `Viewer`'s `[data-sticky-actions]` cluster. Defaults remain hidden/inert at rest and visible only while stuck, including the incumbent hidden chrome during its fade. `visibility="always"` exposes the zero-height, absolutely positioned lane at rest without sticky chrome or document padding; the host must reserve a clear header-height region so its controls do not cover or intercept document content. `sticky={false}` uses normal-flow positioning, creates no intersection observer, and scrolls away; pass the same value to `Viewer.stickyActions` and pair it with `visibility="always"` because the default stuck-only visibility would otherwise stay hidden. The measured Viewer-actions width is intentionally retained because both clusters still share the lane at rest. Wide active-label, tight icon-only, and narrow stacked fallbacks remain measurement-driven, and `hideQuickLabel` still forwards to the compact toolstrip. |
+| `components/StickyHeaderLane` | The backward-compatible standalone ghost lane used by Plannotator beside Viewer's legacy action bar. Defaults remain hidden/inert at rest and visible only while stuck, including the incumbent hidden chrome during its fade. Its `visibility="always"` mode remains a zero-height overlay and therefore requires host-owned clearance. New hosts that need a visible in-flow header should use `Viewer.annotationHeader` instead; it owns both clusters and their clearance. **The `visibility="always"` / `sticky={false}` pair is soft-deprecated as of 0.37.0**: it shipped in 0.36.0, its one intended consumer moved to `Viewer.annotationHeader` before adopting it, and it has no known consumers. It is retained for compatibility and still tested, but do not build new integrations on it. `sticky={false}` uses normal-flow positioning, creates no intersection observer, and must be paired with `visibility="always"`. Wide active-label, tight icon-only, and narrow stacked fallbacks remain measurement-driven, and `hideQuickLabel` still forwards to the compact toolstrip. |
 | `components/ThemeProvider` | Color-mode context. |
 | `theme-modes` (`THEME_MODES`, `Mode`) | The supported Light/Dark/System catalog and mode type. `Mode` also remains exported from `components/ThemeProvider` for compatibility with existing consumers. |
 | `components/ImageThumbnail` / `getImageSrc` | Routes through `imageSrcResolver`. |
@@ -237,6 +238,7 @@ Don't import these in a host. Each hits hardcoded Plannotator endpoints:
 - `utils/sharing` — Plannotator's public paste service (share-URL feature).
 - `hooks/useUpdateCheck`, `components/MenuVersionSection`, `components/PlanHeaderMenu` — Plannotator release checks.
 - `utils/planAgentInstructions`, `utils/reviewAgentInstructions` — generate agent instructions that curl Plannotator's local API.
+- `components/DecisionControl`, `utils/decisionSpec`, `hooks/useDismissablePopover` — session decision chrome for Plannotator's own approve/deny/exit endpoints (a host's session decisions are its own outcomes against its own backend).
 
 If Workspaces ever wants one of these surfaces, the path is the same as everything else: add a seam to the module in a Plannotator PR, don't fork the component.
 
@@ -676,8 +678,8 @@ Additive only, but required: `@plannotator/ui` 0.32.0 imports the new `@plannota
 
 ## Publishing & versioning
 
-- The current pair is `@plannotator/ui` `0.35.2` on `@plannotator/core` `0.25.1`. Core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`; UI 0.35.2 pins that corrected core exactly. The UI behavior remains the `hideQuickLabel` seam introduced in 0.35.0.
-- Recent pairs, for the consumer's install matrix: ui 0.31.0 on core 0.24.0 (lockstep), ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2 on core 0.25.1. Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export.
+- The current pair is `@plannotator/ui` `0.38.0` on `@plannotator/core` `0.25.1`. UI 0.38.0 also renders a GitHub alert's bold-only first body line as its title on the icon row (an emoji on that line becomes the icon; `<!-- icon: name -->` is stripped and resolved through the new `alertIconRenderer` seam, null by default; grammar in `utils/alertTitle`, importable by a host editor so it writes the bytes the reader parses; a fenced code block inside an alert body still renders as text, deferred because nesting a `CodeBlock` inside a block interacts with the positional annotation anchors and needs its own design). UI 0.38.0 carries the whole unified decision-control stack: the internal primitives (`DecisionControl`, `utils/decisionSpec`, `hooks/useDismissablePopover` — not host-supported surface, see the unsupported list; `useDismissablePopover` also replaced the hand-rolled dismissal inside `ActionMenu`/`ApproveDropdown`, both likewise unsupported) plus one blessed-barrel addition: `decisionControlShortcuts` on `@plannotator/ui/shortcuts` (pure scope data, fetch-free, same contract as the other scopes). The removal of `ToolbarButtons`' platform-mode `muted` prop is internal — `ToolbarButtons` is not host-supported surface. UI 0.37.0 added the Viewer-owned document-header seam (a new public API, hence the minor bump; 0.36.1 was reserved for it but never published) while retaining the `hideQuickLabel` and `StickyHeaderLane` seams from the 0.35.x and 0.36.0 releases; core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`, and UI pins that corrected core exactly.
+- Recent pairs, for the consumer's install matrix: ui 0.32.0 on core 0.25.0 (lockstep, `html-anchor`), ui 0.33.0 and ui 0.34.0 on core 0.25.0 (ui only), and ui 0.35.2, ui 0.36.0, ui 0.37.0, and ui 0.38.0 on core 0.25.1 (0.36.1 was never published). Do not consume ui 0.35.0 externally because its published manifest contains `workspace:*`; do not consume ui 0.35.1 because its exact core 0.25.0 dependency lacks the `annotation-threads` export.
 - When both packages change, **publish `core` first**: ui 0.32.0 imports the `@plannotator/core/html-anchor` subpath, which no earlier published core (0.24.0 and before) has, just as ui 0.29.0 needed core 0.23.0 for `@plannotator/core/annotatable`. Bump core, update UI's exact core dependency to the same new version, and run `bun install` so `bun.lock` records the new workspace versions before packing either package.
 - The HTML annotation seams also changed the guides.show viewer **stylesheet** (five utility rules from `HtmlSurfaceControls`; the viewer JS is unchanged), so `packages/core/guide-viewer-manifest.ts` now pins a CSS hash that exists on guides.show only after the deploy workflow has published this build's `/v1/` assets. A guide exported from this build before that deploy would pin a stylesheet the host does not serve yet: **deploy guides.show before any release that ships this manifest.**
 - UI declares the already published core version exactly in its source manifest. Do not replace it with `workspace:*`: direct publication can preserve that protocol and make the package impossible to install outside this repository. Bun links the local core workspace whenever its version matches the exact dependency. Before publishing, run `bun run --cwd packages/ui smoke:package`; it checks the source and packed manifests, required tarball subpaths, local Bun linking, and a real pnpm install in an external temporary consumer. When both packages change, publish **`core` first, then `ui`**.

package/README.md

@@ -30,6 +30,7 @@ configurePlannotatorUI({
   webmcp,                      // browser-agent (WebMCP) provider policy: { enabled, namePrefix }
   mathRendererLoader,          // how KaTeX loads when no renderer is registered before first math render
   identityGenerator,           // sync generator behind the default "tater" name (no identityProvider)
+  alertIconRenderer,           // (name) => ReactNode | null for a GitHub alert title line's <!-- icon: name --> (default: null, the type's icon)
 });
 ```
 
@@ -160,6 +161,61 @@ behavior: hidden and inert at rest, then visible with card chrome once stuck.
   wrapper width and the measured action-cluster width. `hideQuickLabel` is still
   forwarded to the compact toolstrip.
 
+#### Viewer-owned document header
+
+Use `Viewer.annotationHeader` when the compact annotation controls must be
+visible at rest. Viewer then owns one in-flow header containing those controls
+on the left and its existing Global comment / Copy actions on the right:
+
+```tsx
+<Viewer
+  mode={mode}
+  inputMethod={inputMethod}
+  stickyActions={stickyActions}
+  annotationHeader={{
+    onInputMethodChange: setInputMethod,
+    onModeChange: setMode,
+    hideQuickLabel: true,
+  }}
+  // ...the existing Viewer props
+/>
+```
+
+The trailing action cluster keeps full-width labels unless you also pass
+`actionsLabelMode` (`'full' | 'short' | 'icon'`); the header measures the real
+cluster either way, so omitting it costs earlier stacking on narrow columns,
+never breakage.
+
+The header reserves its real responsive height before document content. It
+keeps active labels in the wide layout, switches the compact toolstrip to
+icons in the tight layout, and stacks the two clusters when narrow or wrapped.
+All Viewer badge context moves into the same measured header. With
+`stickyActions={true}` the complete header pins and gains the existing stuck
+chrome; with `false` it remains in flow and scrolls away. The complete header
+has `data-print-hide`, so it contributes no print layout.
+
+As with Viewer's legacy sticky actions and anchor navigation, hosts with a
+custom scroll element must wrap Viewer in `ScrollViewportProvider` from
+`@plannotator/ui/hooks/useScrollViewport` and pass that actual scroll element.
+Without the provider, CSS page stickiness can still apply, but Viewer cannot
+observe the host scroller to add stuck chrome or calculate anchor clearance.
+
+The header reuses Viewer's `[data-sticky-actions]` cluster, so host CSS that
+restyled that selector for the legacy floating bar (negative margins are the
+common case) applies inside the header too and pulls the action cluster out of
+its row. Scope such rules away from the header, e.g.
+`[data-viewer-document-header] [data-sticky-actions] { margin-top: 0; margin-right: 0; }`.
+
+The config is intentionally typed rather than a React-node slot. Viewer reuses
+its existing `mode`, `inputMethod`, and `taterMode`; the config supplies only
+the state-change callbacks and optional `hideQuickLabel`. Compact toolstrips
+never render the Plannotator help modal. Hiding Quick Label does not clamp the
+mode, so hosts must still prevent stored `'quickLabel'` state from reaching
+Viewer. Omit `annotationHeader` to preserve the legacy floating action bar
+exactly. The standalone `StickyHeaderLane` remains supported for Plannotator's
+hidden-at-rest ghost lane, but its always-visible mode is an overlay and is not
+the in-flow host integration.
+
 ### WebMCP provider (`@plannotator/ui/webmcp`; 0.32.0)
 
 The engine that lets a browser-integrated agent (Chrome/Edge WebMCP, `document.modelContext`) call in-page tools on a document surface. Feature-detected once; a browser without the API sees no registration, no DOM, no network, no timers. Seam: `configurePlannotatorUI({ webmcp: { enabled, namePrefix } })`, default enabled with the `plannotator.` prefix; pass `enabled: false` to keep a host page tool-free, or your own prefix to namespace the tools beside your own. There is deliberately no confirmation seam: the catalog is read-and-comment only (no approve / submit / close tools), and the agent may only edit or remove comments stamped `source: "browser-agent"`.
@@ -195,7 +251,7 @@ npm install @plannotator/ui @plannotator/core
 - `@plannotator/core` — pure utils + types, zero deps, browser-safe (CI enforces no `node:` imports). Published.
 - `@plannotator/ui` — React components/hooks + theme + `configure()`. Depends on an exact published `@plannotator/core` version. Published.
 - `@plannotator/shared`, `@plannotator/ai` — stay private to the monorepo; `shared` re-exports `core`'s modules via shims so Plannotator's internals are untouched.
-- Currently `@plannotator/ui` 0.35.2 depends exactly on `@plannotator/core` 0.25.1. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
+- Currently `@plannotator/ui` 0.38.0 depends exactly on `@plannotator/core` 0.25.1. `core` is bumped only when something under `packages/core` changes, so `ui` can advance alone. Keep the published core version exact in `packages/ui/package.json`; do not use a `workspace:` protocol there, because a directly published manifest must remain installable outside this monorepo. Bun still links the matching local workspace during development. When both packages change, publish `core` first, then build and publish the UI tarball. See HANDOFF.md "Publishing & versioning" for the verification command.
 
 ## The one rule
 

package/components/ActionMenu.tsx

@@ -1,4 +1,5 @@
-import React, { useEffect, useRef, useState } from 'react';
+import React, { useCallback, useRef, useState } from 'react';
+import { useDismissablePopover } from '../hooks/useDismissablePopover';
 
 interface ActionMenuProps {
   className?: string;
@@ -21,28 +22,15 @@ export const ActionMenu: React.FC<ActionMenuProps> = ({
   const [isOpen, setIsOpen] = useState(false);
   const menuRef = useRef<HTMLDivElement>(null);
 
-  useEffect(() => {
-    if (!isOpen) return;
-
-    const handlePointerDown = (event: PointerEvent) => {
-      if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
-        setIsOpen(false);
-      }
-    };
-
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        setIsOpen(false);
-      }
-    };
-
-    document.addEventListener('pointerdown', handlePointerDown);
-    document.addEventListener('keydown', handleKeyDown);
-    return () => {
-      document.removeEventListener('pointerdown', handlePointerDown);
-      document.removeEventListener('keydown', handleKeyDown);
-    };
-  }, [isOpen]);
+  // Shared dismissal (outside pointerdown + Escape). The hook consumes the
+  // dismissing Escape, so closing an open Options menu no longer also runs
+  // the host app's own Escape ladder — one Escape, one rung.
+  const dismiss = useCallback(() => setIsOpen(false), []);
+  useDismissablePopover({
+    enabled: isOpen,
+    ref: menuRef,
+    onDismiss: dismiss,
+  });
 
   return (
     <div ref={menuRef} className={className ? `relative ${className}` : 'relative'}>
@@ -53,6 +41,7 @@ export const ActionMenu: React.FC<ActionMenuProps> = ({
 
       {isOpen && (
         <div
+          data-pn-dismissable-popover="true"
           className={panelClassName ?? `absolute top-full right-0 mt-1 ${panelWidth === 'wide' ? 'w-64' : 'w-56'} rounded-lg border border-border bg-popover py-1 shadow-xl z-[70]`}
         >
           {children({ closeMenu: () => setIsOpen(false) })}
@@ -69,6 +58,12 @@ interface ActionMenuItemProps {
   subtitle?: string;
   badge?: React.ReactNode;
   disabled?: boolean;
+  /** ARIA menu semantics for hosts that render a real `role="menu"` popover
+   *  (DecisionControl). Default undefined so existing consumers are unchanged. */
+  role?: 'menuitem';
+  /** Appended to the row's classes (e.g. a tone token). Default undefined so
+   *  existing consumers are byte-identical. */
+  className?: string;
 }
 
 export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
@@ -78,13 +73,16 @@ export const ActionMenuItem: React.FC<ActionMenuItemProps> = ({
   subtitle,
   badge,
   disabled = false,
+  role,
+  className,
 }) => (
   <button
     data-pn-touch-target
     type="button"
     onClick={onClick}
     disabled={disabled}
-    className="flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-45 disabled:hover:bg-transparent"
+    role={role}
+    className={`flex w-full items-center gap-2 px-3 py-2 text-left text-xs transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-45 disabled:hover:bg-transparent${className ? ` ${className}` : ''}`}
   >
     <span className="text-muted-foreground">{icon}</span>
     {subtitle ? (

package/components/AnnotationToolbar.tsx

@@ -179,8 +179,9 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   const isCentered = position.left !== undefined;
   const translateX = isCentered ? ' translateX(-50%)' : '';
 
-  const style: React.CSSProperties = {
+  const style: React.CSSProperties & { '--pn-annotation-toolbar-anchor-x'?: string } = {
     top: position.top,
+    '--pn-annotation-toolbar-anchor-x': isCentered ? `${position.left}px` : undefined,
     ...(isCentered
       ? { left: position.left, transform: 'translateX(-50%)' }
       : { right: position.right }),
@@ -192,6 +193,7 @@ export const AnnotationToolbar: React.FC<AnnotationToolbarProps> = ({
   return createPortal(
     <div
       ref={toolbarRef}
+      data-pn-annotation-toolbar-centered={isCentered ? 'true' : undefined}
       className="annotation-toolbar fixed z-[100] bg-popover border border-border rounded-lg shadow-2xl"
       style={style}
       onMouseDown={(e) => e.stopPropagation()}

package/components/ApproveDropdown.tsx

@@ -1,5 +1,6 @@
-import React, { useState, useRef, useEffect } from 'react';
+import React, { useState, useRef, useCallback } from 'react';
 import type { Agent } from '../hooks/useAgents';
+import { useDismissablePopover } from '../hooks/useDismissablePopover';
 import { getAgentSwitchSettings, saveAgentSwitchSettings, type AgentSwitchSettings } from '../utils/agentSwitch';
 
 interface ApproveDropdownProps {
@@ -40,22 +41,15 @@ export const ApproveDropdown: React.FC<ApproveDropdownProps> = ({
   const [isOpen, setIsOpen] = useState(false);
   const dropdownRef = useRef<HTMLDivElement>(null);
 
-  useEffect(() => {
-    const handleClickOutside = (event: PointerEvent) => {
-      if (dropdownRef.current && !dropdownRef.current.contains(event.target as Node)) {
-        setIsOpen(false);
-      }
-    };
-    const handleEscape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') setIsOpen(false);
-    };
-    document.addEventListener('pointerdown', handleClickOutside);
-    document.addEventListener('keydown', handleEscape);
-    return () => {
-      document.removeEventListener('pointerdown', handleClickOutside);
-      document.removeEventListener('keydown', handleEscape);
-    };
-  }, []);
+  // Shared dismissal (outside pointerdown + Escape), active only while open —
+  // the old always-on listeners were no-ops when closed. The hook consumes the
+  // dismissing Escape so it cannot double as a host-ladder Escape.
+  const dismiss = useCallback(() => setIsOpen(false), []);
+  useDismissablePopover({
+    enabled: isOpen,
+    ref: dropdownRef,
+    onDismiss: dismiss,
+  });
 
   const handleSelect = (newSetting: AgentSwitchSettings) => {
     setSetting(newSetting);
@@ -120,7 +114,10 @@ export const ApproveDropdown: React.FC<ApproveDropdownProps> = ({
 
       {/* Dropdown */}
       {isOpen && (
-        <div className="absolute right-0 top-full mt-1 w-52 rounded-lg border border-border bg-popover shadow-xl z-[70] overflow-hidden py-1">
+        <div
+          data-pn-dismissable-popover="true"
+          className="absolute right-0 top-full mt-1 w-52 rounded-lg border border-border bg-popover shadow-xl z-[70] overflow-hidden py-1"
+        >
           <div className="px-3 py-1.5 text-[10px] uppercase tracking-wider text-muted-foreground/70 font-medium">
             Switch to agent
           </div>

package/components/CommentPopover.tsx

@@ -529,6 +529,7 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
     hasUnsavedContent ||
     (allowEmptySubmit && initialText.trim().length > 0);
   const canAskAI = !!onAskAI && !askAIDisabled && text.trim().length > 0;
+  const showsSkillMenu = skillAc.menu !== null;
 
   // Shared by both footers. Disabled once anything is typed or attached so a
   // click can never discard a draft; with content present, Save is the path.
@@ -570,7 +571,9 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           aria-modal="true"
           aria-label={isGlobal ? 'Global comment' : 'Comment'}
           tabIndex={-1}
-          className="relative w-full max-w-xl max-h-full min-h-0 bg-popover border border-border rounded-xl shadow-2xl flex flex-col overflow-hidden"
+          className={`relative w-full max-w-xl max-h-full min-h-0 bg-popover border border-border rounded-xl shadow-2xl flex flex-col ${
+            showsSkillMenu ? 'overflow-visible' : 'overflow-hidden'
+          }`}
           style={{
             animation: 'comment-dialog-in 0.15s ease-out',
           }}
@@ -617,7 +620,9 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
           {chipsRow}
 
           {/* Textarea */}
-          <div className="relative px-4 py-3 min-h-0 flex-1 overflow-y-auto">
+          <div className={`relative px-4 py-3 min-h-0 flex-1 ${
+            showsSkillMenu ? 'overflow-visible' : 'overflow-y-auto'
+          }`}>
             {skillAc.menu && (
               <SkillReferenceMenu
                 id={skillListboxId}
@@ -713,14 +718,14 @@ export const CommentPopover: React.FC<CommentPopoverProps> = ({
             left: dragPosition.left,
             width: position.width,
             maxHeight: visibleBounds.height,
-            overflowY: 'auto',
+            overflowY: showsSkillMenu ? 'visible' : 'auto',
           }
         : {
             top: position.top,
             left: position.left,
             width: position.width,
             maxHeight: position.maxHeight,
-            overflowY: 'auto',
+            overflowY: showsSkillMenu ? 'visible' : 'auto',
             ...(position.flipAbove ? { transform: 'translateY(-100%)' } : {}),
             animation: position.flipAbove
               ? 'comment-popover-in-above 0.15s ease-out'