@plannotator/ui 0.36.0 → 0.38.0

package/components/Viewer.tsx

@@ -1,3 +1,4 @@
+import { generateId } from '../utils/generateId';
 import React, { useRef, useState, useEffect, useMemo, forwardRef, useImperativeHandle, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import { AnnotationType, type Block, type Annotation, type EditorMode, type InputMethod, type ImageAttachment, type ActionsLabelMode } from '../types';
@@ -44,7 +45,7 @@ import { MermaidBlock } from './MermaidBlock';
 import { isGraphvizLanguage, isMermaidLanguage } from './diagramLanguages';
 import { getIdentity } from '../utils/identity';
 import { type QuickLabel } from '../utils/quickLabels';
-import { DocBadges, type LinkedDocBadgeInfo } from './DocBadges';
+import { DocBadges, type DocBadgesProps, type LinkedDocBadgeInfo } from './DocBadges';
 import { PinpointOverlay } from './PinpointOverlay';
 import { usePinpoint } from '../hooks/usePinpoint';
 import { useAnnotationHighlighter } from '../hooks/useAnnotationHighlighter';
@@ -58,8 +59,24 @@ import {
 } from '../hooks/useScrollViewport';
 import { decodeAnchorHash } from '../utils/anchors';
 import { VimModeOverlay } from './VimModeOverlay';
+import { AnnotationToolstrip } from './AnnotationToolstrip';
+import {
+  resolveCompactHeaderGeometry,
+  snapCompactHeaderWidth,
+} from './compactHeaderLayout';
+
+/** Typed controls required for Viewer's opt-in, in-flow annotation header. */
+export interface ViewerAnnotationHeaderConfig {
+  /** Persist and apply a Select or Pinpoint input-method change. */
+  readonly onInputMethodChange: (method: InputMethod) => void;
+  /** Persist and apply an annotation-mode change. */
+  readonly onModeChange: (mode: EditorMode) => void;
+  /** Omit Quick Label without changing or coercing the current mode. */
+  readonly hideQuickLabel?: boolean;
+}
 
-interface ViewerProps {
+/** Public properties for the Markdown document Viewer. */
+export interface ViewerProps {
   blocks: Block[];
   markdown: string;
   frontmatter?: Frontmatter | null;
@@ -75,6 +92,14 @@ interface ViewerProps {
   onRemoveGlobalAttachment?: (path: string) => void;
   repoInfo?: { display: string; branch?: string; host?: string } | null;
   stickyActions?: boolean;
+  /**
+   * Render compact annotation controls and the existing document actions in
+   * one measured, in-flow header owned by Viewer. The header reserves its
+   * responsive height before document content and follows `stickyActions`.
+   * Omit this prop to retain the legacy floating action bar exactly. Read-only
+   * viewers suppress the annotation header rather than expose dead controls.
+   */
+  annotationHeader?: ViewerAnnotationHeaderConfig;
   /** Render the plan as a floating card on a grid background (shadow/border/padding). Default false. */
   gridEnabled?: boolean;
   onOpenLinkedDoc?: (path: string) => void;
@@ -189,6 +214,118 @@ const FrontmatterCard: React.FC<{ frontmatter: Frontmatter }> = ({ frontmatter }
   );
 };
 
+interface ViewerDocumentHeaderProps {
+  readonly config: ViewerAnnotationHeaderConfig;
+  readonly inputMethod: InputMethod;
+  readonly mode: EditorMode;
+  readonly taterMode: boolean;
+  readonly sticky: boolean;
+  readonly stuck: boolean;
+  readonly sentinelRef: React.RefObject<HTMLDivElement | null>;
+  readonly badges: Omit<DocBadgesProps, 'layout'>;
+  readonly actions: React.ReactNode;
+}
+
+/** Viewer-owned header that keeps leading controls and trailing actions in one flow. */
+const ViewerDocumentHeader: React.FC<ViewerDocumentHeaderProps> = ({
+  config,
+  inputMethod,
+  mode,
+  taterMode,
+  sticky,
+  stuck,
+  sentinelRef,
+  badges,
+  actions,
+}) => {
+  const headerRef = useRef<HTMLDivElement>(null);
+  const actionsRef = useRef<HTMLDivElement>(null);
+  const [headerWidth, setHeaderWidth] = useState(0);
+  const [actionsWidth, setActionsWidth] = useState(0);
+
+  useEffect(() => {
+    const header = headerRef.current;
+    if (!header) return;
+    const observer = new ResizeObserver(([entry]) => {
+      const next = snapCompactHeaderWidth(entry.contentRect.width);
+      setHeaderWidth((current) => current === next ? current : next);
+    });
+    observer.observe(header);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    const actionCluster = actionsRef.current;
+    if (!actionCluster) return;
+    const observer = new ResizeObserver(([entry]) => {
+      const next = snapCompactHeaderWidth(entry.contentRect.width);
+      setActionsWidth((current) => current === next ? current : next);
+    });
+    observer.observe(actionCluster);
+    return () => observer.disconnect();
+  }, []);
+
+  const geometry = resolveCompactHeaderGeometry({
+    containerWidth: headerWidth,
+    trailingWidth: actionsWidth,
+    leadingInset: 0,
+  });
+  const narrow = geometry.layout === 'narrow';
+  const iconOnly = geometry.layout !== 'wide';
+
+  return (
+    <>
+      {sticky && <div ref={sentinelRef} className="h-0 w-0" aria-hidden="true" />}
+      <div
+        ref={headerRef}
+        data-annotation-exclude
+        data-print-hide
+        data-viewer-document-header
+        data-header-layout={geometry.layout}
+        className={`annotation-exclude ${sticky ? 'sticky top-3' : 'relative'} z-40 mb-3 md:mb-4 rounded-lg transition-colors duration-150 ${
+          stuck ? 'bg-card/95 backdrop-blur-sm shadow-sm' : ''
+        }`}
+      >
+        <div className={`flex min-w-0 ${
+          narrow
+            ? 'flex-col items-stretch gap-2'
+            : 'flex-row items-start justify-between gap-4'
+        }`}>
+          <div
+            data-viewer-annotation-controls
+            className={`inline-flex min-w-0 flex-wrap items-center gap-x-3 gap-y-1 py-1 md:py-2 ${
+              narrow ? 'w-full' : 'flex-1'
+            }`}
+          >
+            <div className="flex-shrink-0">
+              <AnnotationToolstrip
+                inputMethod={inputMethod}
+                onInputMethodChange={config.onInputMethodChange}
+                mode={mode}
+                onModeChange={config.onModeChange}
+                taterMode={taterMode}
+                hideQuickLabel={config.hideQuickLabel}
+                compact
+                iconOnly={iconOnly}
+              />
+            </div>
+            <DocBadges layout="header" {...badges} />
+          </div>
+          <div
+            ref={actionsRef}
+            data-sticky-actions
+            className={`flex flex-shrink-0 items-start gap-1 rounded-lg p-1 md:gap-2 md:p-2 ${
+              narrow ? 'self-end' : ''
+            }`}
+          >
+            {actions}
+          </div>
+        </div>
+      </div>
+    </>
+  );
+};
+
 /**
  * Render and annotate a parsed Markdown document.
  *
@@ -211,6 +348,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   onRemoveGlobalAttachment,
   repoInfo,
   stickyActions = true,
+  annotationHeader,
   gridEnabled = false,
   planDiffStats,
   isPlanDiffActive,
@@ -242,6 +380,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   vimHudKeyPanelEnabled = true,
   onVimHudKeyPanelChange,
 }, ref) => {
+  const viewerAnnotationHeader = readOnly ? undefined : annotationHeader;
+  const hasViewerAnnotationHeader = viewerAnnotationHeader !== undefined;
   const [copied, setCopied] = useState(false);
   const [lightbox, setLightbox] = useState<{ src: string; alt: string } | null>(null);
   const [locationHash, setLocationHash] = useState(() => window.location.hash);
@@ -271,6 +411,10 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   const docBadgesRef = useRef<HTMLDivElement | null>(null);
   const [badgeClearance, setBadgeClearance] = useState(0);
   useEffect(() => {
+    if (hasViewerAnnotationHeader) {
+      setBadgeClearance(0);
+      return;
+    }
     const el = docBadgesRef.current;
     const article = containerRef.current;
     if (!el || !article) { setBadgeClearance(0); return; }
@@ -284,7 +428,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     ro.observe(el);
     window.addEventListener('resize', measure);
     return () => { ro.disconnect(); window.removeEventListener('resize', measure); };
-  }, [repoInfo, hasPreviousVersion, showDemoBadge, linkedDocInfo, archiveInfo, sourceInfo, planDiffStats, openInAppPath]);
+  }, [hasViewerAnnotationHeader, repoInfo, hasPreviousVersion, showDemoBadge, linkedDocInfo, archiveInfo, sourceInfo, planDiffStats, openInAppPath]);
 
   // Per-doc heading slug map with dedup — computed once per blocks array so
   // anchor ids stay stable across re-renders and duplicate heading texts get
@@ -605,14 +749,18 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   // The IntersectionObserver root must be the actual scroll element — the
   // OverlayScrollArea viewport — not the <main> host, which doesn't scroll.
   useEffect(() => {
-    if (!stickyActions || !stickySentinelRef.current || !scrollViewport) return;
+    if (!stickyActions) {
+      setIsStuck(false);
+      return;
+    }
+    if (!stickySentinelRef.current || !scrollViewport) return;
     const observer = new IntersectionObserver(
       ([entry]) => setIsStuck(!entry.isIntersecting),
       { root: getScrollViewportIntersectionRoot(scrollViewport), threshold: 0 }
     );
     observer.observe(stickySentinelRef.current);
     return () => observer.disconnect();
-  }, [stickyActions, scrollViewport]);
+  }, [hasViewerAnnotationHeader, stickyActions, scrollViewport]);
 
   useEffect(() => {
     const handleHashChange = () => {
@@ -634,12 +782,15 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     const target = document.getElementById(anchor);
     if (!target || !container.contains(target)) return false;
 
-    const stickyActionsEl = container.querySelector<HTMLElement>('[data-sticky-actions]');
-    const stickyTop = stickyActionsEl
-      ? Number.parseFloat(window.getComputedStyle(stickyActionsEl).top || '0') || 0
+    const documentHeader = stickyActions
+      ? container.querySelector<HTMLElement>('[data-viewer-document-header]')
+        ?? container.querySelector<HTMLElement>('[data-sticky-actions]')
+      : null;
+    const stickyTop = documentHeader
+      ? Number.parseFloat(window.getComputedStyle(documentHeader).top || '0') || 0
       : 0;
-    const headerOffset = stickyActionsEl
-      ? stickyActionsEl.getBoundingClientRect().height + stickyTop
+    const headerOffset = documentHeader
+      ? documentHeader.getBoundingClientRect().height + stickyTop
       : 0;
     const containerRect = getScrollViewportRect(scrollViewport);
     const targetRect = target.getBoundingClientRect();
@@ -651,7 +802,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
       behavior: 'smooth',
     });
     return true;
-  }, [scrollViewport]);
+  }, [scrollViewport, stickyActions]);
 
   useEffect(() => {
     if (!scrollViewport || !locationHash || lastAutoScrolledHashRef.current === locationHash) return;
@@ -758,7 +909,10 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
 
     if (viewerCommentPopover.isGlobal) {
       const newAnnotation: Annotation = {
-        id: `global-${Date.now()}`,
+        // randomUUID, not Date.now(): two comments minted in the same
+        // millisecond (paste + submit, or a concurrent external write)
+        // would collide on a timestamp id.
+        id: generateId('global'),
         blockId: '',
         startOffset: 0,
         endOffset: 0,
@@ -788,6 +942,82 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
 
   const codePathValidation = useValidatedCodePaths(markdown, codePathBaseDir, disableCodePathValidation);
 
+  const documentActions = (
+    <>
+      {messagePickerInfo && (
+        <button
+          onClick={messagePickerInfo.onOpen}
+          className="flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground bg-muted/50 hover:bg-muted rounded-md transition-colors"
+          title="Pick a different message to annotate"
+        >
+          <MessagesIcon />
+          {actionsLabelMode === 'full' && (
+            <span>Message {messagePickerInfo.current} of {messagePickerInfo.total}</span>
+          )}
+          {actionsLabelMode === 'short' && (
+            <span>{messagePickerInfo.current}/{messagePickerInfo.total}</span>
+          )}
+        </button>
+      )}
+
+      {!readOnly && onAddGlobalAttachment && onRemoveGlobalAttachment && (
+        <AttachmentsButton
+          images={globalAttachments}
+          onAdd={onAddGlobalAttachment}
+          onRemove={onRemoveGlobalAttachment}
+          variant="toolbar"
+          hideLabel={actionsLabelMode === 'icon'}
+        />
+      )}
+
+      {!readOnly && (
+        <button
+          ref={globalCommentButtonRef}
+          onClick={() => {
+            const anchorEl = globalCommentButtonRef.current;
+            if (!anchorEl) return;
+            setViewerCommentPopover({
+              anchorEl,
+              contextText: '',
+              isGlobal: true,
+            });
+          }}
+          className="flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground bg-muted/50 hover:bg-muted rounded-md transition-colors"
+          title="Add global comment"
+        >
+          <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+            <path strokeLinecap="round" strokeLinejoin="round" d="M12 21a9.004 9.004 0 008.716-6.747M12 21a9.004 9.004 0 01-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 017.843 4.582M12 3a8.997 8.997 0 00-7.843 4.582m15.686 0A11.953 11.953 0 0112 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0121 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0112 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 013 12c0-1.605.42-3.113 1.157-4.418" />
+          </svg>
+          {actionsLabelMode === 'full' && <span>Global comment</span>}
+          {actionsLabelMode === 'short' && <span>Comment</span>}
+        </button>
+      )}
+
+      <button
+        onClick={handleCopyPlan}
+        className="flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground bg-muted/50 hover:bg-muted rounded-md transition-colors"
+        title={copied ? 'Copied!' : copyLabel || (linkedDocInfo ? 'Copy file' : 'Copy plan')}
+      >
+        {copied ? (
+          <>
+            <svg className="w-3.5 h-3.5 text-success" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+            </svg>
+            Copied!
+          </>
+        ) : (
+          <>
+            <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
+            </svg>
+            {actionsLabelMode === 'full' && <span>{copyLabel || (linkedDocInfo ? 'Copy file' : 'Copy plan')}</span>}
+            {actionsLabelMode === 'short' && <span>Copy</span>}
+          </>
+        )}
+      </button>
+    </>
+  );
+
   return (
     <CodePathValidationContext.Provider value={codePathValidation}>
     <div className="relative z-50 w-full" style={maxWidth === null ? undefined : { maxWidth: maxWidth ?? 832 }}>
@@ -810,8 +1040,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
           ...(vimModeActive ? { outline: 'none' } : {}),
         } as React.CSSProperties}
       >
-        {/* Repo info + plan diff badge + demo badge + linked doc badge + archive badge - top left */}
-        {(repoInfo || hasPreviousVersion || showDemoBadge || linkedDocInfo || archiveInfo || sourceInfo || openInAppPath) && (
+        {/* Legacy badge placement remains byte-for-byte opt-out behavior. */}
+        {!viewerAnnotationHeader && (repoInfo || hasPreviousVersion || showDemoBadge || linkedDocInfo || archiveInfo || sourceInfo || openInAppPath) && (
           <div ref={docBadgesRef} data-print-hide className={`absolute top-3 md:top-4 ${gridEnabled ? 'left-3 md:left-5' : 'left-0'}`}>
             <DocBadges
               layout="column"
@@ -831,88 +1061,40 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
           </div>
         )}
 
-        {/* Clearance so document content starts below the (absolute) badge cluster
-            when it outgrows the card's top padding — see the measuring effect above. */}
-        {badgeClearance > 0 && <div data-print-hide style={{ height: badgeClearance }} aria-hidden="true" />}
-
-        {/* Sentinel for sticky detection */}
-        {stickyActions && <div ref={stickySentinelRef} className="h-0 w-0 float-right" aria-hidden="true" />}
-
-        {/* Header buttons - top right */}
-        <div data-print-hide data-sticky-actions className={`${stickyActions ? 'sticky top-3' : ''} z-30 float-right flex items-start gap-1 md:gap-2 rounded-lg p-1 md:p-2 transition-colors duration-150 ${isStuck ? 'bg-card/95 backdrop-blur-sm shadow-sm' : ''} ${gridEnabled ? '-mr-3 md:-mr-5 lg:-mr-7 xl:-mr-9' : '-mr-1 md:-mr-2'} mt-6 md:-mt-5 lg:-mt-7 xl:-mt-9`}>
-          {messagePickerInfo && (
-            <button
-              onClick={messagePickerInfo.onOpen}
-              className="flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground bg-muted/50 hover:bg-muted rounded-md transition-colors"
-              title="Pick a different message to annotate"
-            >
-              <MessagesIcon />
-              {actionsLabelMode === 'full' && (
-                <span>Message {messagePickerInfo.current} of {messagePickerInfo.total}</span>
-              )}
-              {actionsLabelMode === 'short' && (
-                <span>{messagePickerInfo.current}/{messagePickerInfo.total}</span>
-              )}
-            </button>
-          )}
-
-          {/* Attachments button */}
-          {!readOnly && onAddGlobalAttachment && onRemoveGlobalAttachment && (
-            <AttachmentsButton
-              images={globalAttachments}
-              onAdd={onAddGlobalAttachment}
-              onRemove={onRemoveGlobalAttachment}
-              variant="toolbar"
-              hideLabel={actionsLabelMode === 'icon'}
-            />
-          )}
-
-          {/* <span className="md:hidden">Comment</span><span className="hidden md:inline">Global comment</span> button */}
-          {!readOnly && (
-          <button
-            ref={globalCommentButtonRef}
-            onClick={() => {
-              setViewerCommentPopover({
-                anchorEl: globalCommentButtonRef.current!,
-                contextText: '',
-                isGlobal: true,
-              });
+        {viewerAnnotationHeader ? (
+          <ViewerDocumentHeader
+            config={viewerAnnotationHeader}
+            inputMethod={inputMethod}
+            mode={mode}
+            taterMode={taterMode}
+            sticky={stickyActions}
+            stuck={isStuck}
+            sentinelRef={stickySentinelRef}
+            badges={{
+              repoInfo,
+              planDiffStats,
+              isPlanDiffActive,
+              hasPreviousVersion,
+              onPlanDiffToggle,
+              planDiffBaselineLabel,
+              planDiffBaselineTooltip,
+              showDemoBadge,
+              archiveInfo,
+              linkedDocInfo,
+              sourceInfo,
+              openInAppPath,
             }}
-            className="flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground bg-muted/50 hover:bg-muted rounded-md transition-colors"
-            title="Add global comment"
-          >
-            <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-              <path strokeLinecap="round" strokeLinejoin="round" d="M12 21a9.004 9.004 0 008.716-6.747M12 21a9.004 9.004 0 01-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 017.843 4.582M12 3a8.997 8.997 0 00-7.843 4.582m15.686 0A11.953 11.953 0 0112 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0121 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0112 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 013 12c0-1.605.42-3.113 1.157-4.418" />
-            </svg>
-            {actionsLabelMode === 'full' && <span>Global comment</span>}
-            {actionsLabelMode === 'short' && <span>Comment</span>}
-          </button>
-          )}
-
-          {/* Copy plan/file button */}
-          <button
-            onClick={handleCopyPlan}
-            className="flex items-center gap-1.5 px-2.5 py-1.5 text-xs font-medium text-muted-foreground hover:text-foreground bg-muted/50 hover:bg-muted rounded-md transition-colors"
-            title={copied ? 'Copied!' : copyLabel || (linkedDocInfo ? 'Copy file' : 'Copy plan')}
-          >
-            {copied ? (
-              <>
-                <svg className="w-3.5 h-3.5 text-success" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
-                </svg>
-                Copied!
-              </>
-            ) : (
-              <>
-                <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M8 16H6a2 2 0 01-2-2V6a2 2 0 012-2h8a2 2 0 012 2v2m-6 12h8a2 2 0 002-2v-8a2 2 0 00-2-2h-8a2 2 0 00-2 2v8a2 2 0 002 2z" />
-                </svg>
-                {actionsLabelMode === 'full' && <span>{copyLabel || (linkedDocInfo ? 'Copy file' : 'Copy plan')}</span>}
-                {actionsLabelMode === 'short' && <span>Copy</span>}
-              </>
-            )}
-          </button>
-        </div>
+            actions={documentActions}
+          />
+        ) : (
+          <>
+            {badgeClearance > 0 && <div data-print-hide style={{ height: badgeClearance }} aria-hidden="true" />}
+            {stickyActions && <div ref={stickySentinelRef} className="h-0 w-0 float-right" aria-hidden="true" />}
+            <div data-print-hide data-sticky-actions className={`${stickyActions ? 'sticky top-3' : ''} z-30 float-right flex items-start gap-1 md:gap-2 rounded-lg p-1 md:p-2 transition-colors duration-150 ${isStuck ? 'bg-card/95 backdrop-blur-sm shadow-sm' : ''} ${gridEnabled ? '-mr-3 md:-mr-5 lg:-mr-7 xl:-mr-9' : '-mr-1 md:-mr-2'} mt-6 md:-mt-5 lg:-mt-7 xl:-mt-9`}>
+              {documentActions}
+            </div>
+          </>
+        )}
         {frontmatter && <><div className="clear-right md:hidden" /><FrontmatterCard frontmatter={frontmatter} /></>}
         {!frontmatter && blocks.length > 0 && blocks[0].type !== 'heading' && <div className="mt-4" />}
         {groupBlocks(blocks).map(group =>

package/components/VimTargetReticle.tsx

@@ -194,7 +194,7 @@ export function VimTargetReticle({
         ? getScrollViewportRect(scrollViewport).top
         : containerRect.top;
       const stickyBottom = container
-        .querySelector<HTMLElement>('[data-sticky-actions]')
+        .querySelector<HTMLElement>('[data-viewer-document-header], [data-sticky-actions]')
         ?.getBoundingClientRect()
         .bottom;
       setPosition(relativePosition(

package/components/blocks/AlertBlock.tsx

@@ -1,6 +1,8 @@
 import React from 'react';
 import type { AlertKind } from '../../types';
 import { renderProseBody } from './proseBody';
+import { InlineMarkdown } from '../InlineMarkdown';
+import { parseAlertTitleLine } from '../../utils/alertTitle';
 
 interface AlertBlockProps {
   blockId: string;
@@ -22,6 +24,25 @@ const TITLE: Record<AlertKind, string> = {
   important: 'Important',
 };
 
+/**
+ * Host seam: resolve a named icon from a title line's `<!-- icon: name -->`
+ * comment to a React node. Default: null for every name, so the alert keeps
+ * the type's own icon exactly as today. A host that ships an icon set (the
+ * package deliberately bundles none) registers a renderer once at startup.
+ * Returning null for an unknown name falls back to the type's icon.
+ */
+export type AlertIconRenderer = (name: string) => React.ReactNode | null;
+
+let alertIconRenderer: AlertIconRenderer | null = null;
+
+export function setAlertIconRenderer(renderer: AlertIconRenderer | null): void {
+  alertIconRenderer = renderer;
+}
+
+export function resetAlertIconRenderer(): void {
+  alertIconRenderer = null;
+}
+
 const Icon: React.FC<{ kind: AlertKind }> = ({ kind }) => {
   const common = { viewBox: '0 0 16 16', width: '16', height: '16', fill: 'currentColor', 'aria-hidden': true as const };
   switch (kind) {
@@ -41,6 +62,19 @@ const Icon: React.FC<{ kind: AlertKind }> = ({ kind }) => {
 export const AlertBlock: React.FC<AlertBlockProps> = ({
   blockId, kind, body, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, githubRepo, onNavigateAnchor,
 }) => {
+  const proseProps = { imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, onNavigateAnchor, githubRepo };
+
+  // A bold-only first line (optionally led by one emoji, optionally trailed by
+  // an `<!-- icon: name -->` comment) is the alert's title and rides the icon
+  // row in place of the type word; the emoji, or a host-resolved named icon,
+  // takes the icon slot. See utils/alertTitle for the exact grammar. A body
+  // with no such line renders exactly as before.
+  const titleLine = parseAlertTitleLine(body);
+  const hostIcon = titleLine?.icon && alertIconRenderer ? alertIconRenderer(titleLine.icon) : null;
+  const icon = titleLine?.emoji
+    ? <span aria-hidden="true" className="alert-emoji text-base leading-none">{titleLine.emoji}</span>
+    : hostIcon ?? <Icon kind={kind} />;
+
   return (
     <div
       className={`alert alert-${kind} my-4 pl-4 pr-3 py-2 border-l-[3px]`}
@@ -48,11 +82,24 @@ export const AlertBlock: React.FC<AlertBlockProps> = ({
       data-block-type="alert"
       data-alert-kind={kind}
     >
-      <div className="alert-title flex items-center gap-2 font-semibold mb-1">
-        <Icon kind={kind} />
-        <span>{TITLE[kind]}</span>
+      <div
+        className="alert-title flex items-center gap-2 font-semibold mb-1"
+        aria-label={titleLine?.title ? `${TITLE[kind]}: ${titleLine.title}` : undefined}
+      >
+        {icon}
+        <span>
+          {titleLine?.title
+            ? <InlineMarkdown text={titleLine.title} {...proseProps} />
+            : TITLE[kind]}
+        </span>
       </div>
-      {renderProseBody({ body, imageBaseDir, onImageClick, onOpenLinkedDoc, onOpenCodeFile, onNavigateAnchor, githubRepo })}
+      {titleLine
+        ? (titleLine.rest.trim()
+            // Indent the body by the icon's width plus the row gap so it starts
+            // at the title's left edge (16px icon + 8px gap = pl-6).
+            ? <div className="alert-body pl-6">{renderProseBody({ body: titleLine.rest, ...proseProps })}</div>
+            : null)
+        : renderProseBody({ body, ...proseProps })}
     </div>
   );
 };

package/components/compactHeaderLayout.ts

@@ -0,0 +1,52 @@
+/** Responsive presentation chosen for a measured compact document header. */
+export type CompactHeaderLayout = 'wide' | 'tight' | 'narrow';
+
+/** Measurements used to place a compact leading lane beside trailing actions. */
+export interface CompactHeaderMeasurements {
+  /** Measured width of the full header container. */
+  readonly containerWidth: number;
+  /** Measured width occupied by the trailing action cluster. */
+  readonly trailingWidth: number;
+  /** Leading inset that is unavailable to the compact controls. */
+  readonly leadingInset: number;
+}
+
+/** Resolved responsive geometry for a compact document header. */
+export interface CompactHeaderGeometry {
+  /** Pixels available to the leading controls after actions and spacing. */
+  readonly availableForLeading: number;
+  /** Whether controls keep labels, become icon-only, or stack. */
+  readonly layout: CompactHeaderLayout;
+  /** Whether both required measurements have arrived. */
+  readonly measured: boolean;
+}
+
+const GRID_SIZE = 16;
+const CLUSTER_GAP = 16;
+const WIDE_LEADING_WIDTH = 460;
+const MIN_LEADING_WIDTH = 300;
+
+/**
+ * Quantize a ResizeObserver width to avoid rendering for every dragged pixel.
+ * Floors toward the more conservative responsive layout.
+ */
+export function snapCompactHeaderWidth(width: number): number {
+  return Math.floor(width / GRID_SIZE) * GRID_SIZE;
+}
+
+/** Resolve the shared wide, tight, and narrow compact-header states. */
+export function resolveCompactHeaderGeometry({
+  containerWidth,
+  trailingWidth,
+  leadingInset,
+}: CompactHeaderMeasurements): CompactHeaderGeometry {
+  const measured = containerWidth > 0 && trailingWidth > 0;
+  const availableForLeading = containerWidth - leadingInset - trailingWidth - CLUSTER_GAP;
+  const layout = !measured || availableForLeading >= WIDE_LEADING_WIDTH
+    ? 'wide'
+    : availableForLeading >= MIN_LEADING_WIDTH
+      ? 'tight'
+      : 'narrow';
+
+  return { availableForLeading, layout, measured };
+}

package/config/reviewView.ts

@@ -56,6 +56,7 @@ export function getPersistedReviewPanelView(): 'sections' | 'tree' | undefined {
 
 export type ReviewDefaultDiffType =
   | 'since-base'
+  | 'local-vs-remote'
   | 'uncommitted'
   | 'unstaged'
   | 'staged'