@plannotator/ui 0.35.2 → 0.37.0

package/HANDOFF.md

@@ -190,12 +190,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 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`. |
@@ -675,8 +676,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.37.0` on `@plannotator/core` `0.25.1`. Core 0.25.1 publishes the `annotation-threads` subpath already used by `AnnotationPanel` and `utils/parser`; UI pins that corrected core exactly. UI 0.37.0 adds 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.
+- 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, and ui 0.37.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

@@ -137,6 +137,78 @@ The srcdoc then carries one classic `<script src>` in the exact place the inline
 - **`showHelpLink={false}`** for hosts: the default help modal embeds Plannotator's own video walkthroughs.
 - **`hideInputMethodSwitch`** omits the pinpoint/drag input-method switch.
 
+#### Sticky header lane host props
+
+`components/StickyHeaderLane` is the measured compact companion to `Viewer`'s
+`[data-sticky-actions]` cluster. Its defaults preserve Plannotator's ghost-header
+behavior: hidden and inert at rest, then visible with card chrome once stuck.
+
+- **`visibility="always"`** keeps the existing measured left lane visible and
+  interactive at rest as well as while stuck. Resting lanes have no background,
+  border, backdrop, shadow, or new document padding; stuck lanes retain the
+  incumbent chrome. The lane remains zero-height and absolutely positioned, so
+  the host must reserve a clear header-height region; otherwise its visible
+  controls can cover and intercept interaction with document content below.
+- **`sticky={false}`** uses non-sticky positioning, creates no intersection
+  observer, and scrolls away normally. Pass the same value to
+  `Viewer.stickyActions` so the left lane and right action cluster follow one
+  policy. By itself it leaves the default stuck-only lane permanently hidden;
+  combine it with `visibility="always"` for a visible non-sticky header. The
+  measured Viewer-actions width is still reserved because both clusters share
+  the lane at rest before they scroll away together.
+- Wide, tight icon-only, and narrow stacked layouts continue to derive from the
+  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 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"`.
@@ -172,7 +244,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.37.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/DocBadges.tsx

@@ -3,7 +3,8 @@
  *
  * Extracted from Viewer.tsx so the same markup can render in two places:
  *   - layout="column": original location at the top-left of the plan card (absolute)
- *   - layout="row":   inside the sticky header lane when the user scrolls
+ *   - layout="row":   compact context inside the legacy sticky header lane
+ *   - layout="header": complete context inside Viewer's in-flow shared header
  *
  * In row layout, the demo badge and linked-doc breadcrumb are dropped —
  * everything else is decorative top-of-doc context except the plan-diff
@@ -29,7 +30,7 @@ export interface LinkedDocBadgeInfo {
 }
 
 export interface DocBadgesProps {
-  layout: 'column' | 'row';
+  layout: 'column' | 'row' | 'header';
   repoInfo?: { display: string; branch?: string } | null;
   planDiffStats?: PlanDiffStats | null;
   isPlanDiffActive?: boolean;
@@ -68,6 +69,7 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
   openInAppPath,
 }) => {
   const isRow = layout === 'row';
+  const isHorizontal = layout !== 'column';
   const canOpenInApp =
     !!openInAppPath && !/^https?:\/\//i.test(openInAppPath);
   const openInButton = canOpenInApp ? (
@@ -85,15 +87,16 @@ export const DocBadges: React.FC<DocBadgesProps> = ({
   if (!anything) return null;
 
   // Row layout: single horizontal line. Column layout: stacked rows.
-  const outerClass = isRow
-    ? 'flex flex-row items-center gap-1.5 text-[9px] text-muted-foreground/70 font-mono'
+  const outerClass = isHorizontal
+    ? `flex flex-row items-center gap-1.5 text-[9px] text-muted-foreground/70 font-mono ${layout === 'header' ? 'flex-wrap' : ''}`
     : 'flex flex-col items-start gap-1 text-[9px] text-muted-foreground/50 font-mono';
 
   return (
     <div className={outerClass}>
-      {/* Row layout (sticky lane) omits repo/branch to keep the bar compact —
+      {/* Legacy row layout omits repo/branch to keep the ghost bar compact —
           they'd otherwise push the container wide enough to visually extend
-          under the action buttons. Plan-diff badge still renders below. */}
+          under the action buttons. The Viewer-owned header measures and wraps
+          the complete badge set, so its `header` layout keeps this context. */}
       {repoInfo && !linkedDocInfo && !isRow && (
         <div className="flex items-center gap-1.5">
           <span

package/components/StickyHeaderLane.tsx

@@ -1,11 +1,12 @@
 /**
- * StickyHeaderLane — compact "ghost" header that pins as the user scrolls
+ * StickyHeaderLane — compact "ghost" header that can pin as the user scrolls
  * past the AnnotationToolstrip.
  *
- * At rest (top of doc): invisible, non-interactive. The original toolstrip
- * and badge cluster on the card remain the visible source of truth.
+ * By default, the lane is invisible and non-interactive at rest, leaving the
+ * original toolstrip and badge cluster as the visible source of truth. Hosts
+ * can keep this measured lane visible at rest or let it scroll normally.
  *
- * Layout is driven by two ResizeObserver measurements — the sticky
+ * Layout is driven by two ResizeObserver measurements — the lane
  * wrapper's actual width AND the Viewer action button cluster's actual
  * width — so the bar fits exactly into the space between its left edge
  * and the buttons, with no fixed pixel reserves.
@@ -33,32 +34,20 @@ import {
 } from '../hooks/useScrollViewport';
 import type { EditorMode, InputMethod } from '../types';
 import type { PlanDiffStats } from '../utils/planDiffEngine';
+import {
+  resolveCompactHeaderGeometry,
+  snapCompactHeaderWidth,
+} from './compactHeaderLayout';
 
-// Snap a measured pixel width to a 16px grid. ResizeObserver fires every
-// frame during a drag; without quantization the sticky bar would
-// re-render on every pixel. Hoisted to module scope so the effects
-// (which use [] deps) can't accidentally close over a stale instance.
-// Floor (not round) so wrapper undershoots and actions overshoots — both
-// errors push toward a more cautious layout, avoiding a one-bucket overlap
-// flash right at the 300/460 thresholds during a slow drag.
-const snap = (n: number) => Math.floor(n / 16) * 16;
-
-// Layout geometry — static tuning constants, hoisted alongside `snap`.
-// LEFT_OFFSET: matches the bar's `md:left-5` (20px).
-// GAP: minimum breathing room between the bar's right edge and the
-//      action button cluster's left edge when they share a lane.
-// Two-stage shared-lane shrinkage, mirroring the right side:
-//   WIDE_BAR_WIDTH: full toolstrip (active labels Pinpoint/Markup ~300px)
-//                   + badges (~140px) on a single line.
-//   MIN_BAR_WIDTH:  icon-only toolstrip (~140px) + badges (~140px).
-// Below MIN, even the icon-only bar can't fit beside the (likely also
-// icon-only) action cluster — stack as the final fallback.
+// Matches the bar's `md:left-5` inset. The remaining shared geometry lives
+// in compactHeaderLayout so Viewer-owned and standalone lanes cannot drift.
 const LEFT_OFFSET = 20;
-const GAP = 16;
-const WIDE_BAR_WIDTH = 460;
-const MIN_BAR_WIDTH = 300;
 
-interface StickyHeaderLaneProps {
+/** Controls when the compact header lane is visible and interactive. */
+export type StickyHeaderLaneVisibility = 'stuck' | 'always';
+
+/** Props for the measured compact annotation and document header lane. */
+export interface StickyHeaderLaneProps {
   // Toolstrip state
   inputMethod: InputMethod;
   onInputMethodChange: (method: InputMethod) => void;
@@ -68,6 +57,21 @@ interface StickyHeaderLaneProps {
   /** Omit the Quick Label tool in the compact toolstrip (mirrors AnnotationToolstripProps.hideQuickLabel). */
   hideQuickLabel?: boolean;
 
+  /**
+   * Show the lane only after it sticks, or keep it visible at rest too.
+   * Defaults to `'stuck'`, preserving the incumbent ghost-header behavior.
+   * Hosts using `'always'` must reserve a clear header-height region because
+   * the lane remains zero-height and absolutely positioned over its sibling.
+   */
+  visibility?: StickyHeaderLaneVisibility;
+  /**
+   * Keep the lane pinned while its scroll viewport moves. Pass the same value
+   * to `Viewer.stickyActions` so both measured header lanes share one policy.
+   * Defaults to true. Pair false with `visibility="always"`; the default
+   * stuck-only visibility cannot become visible when stickiness is disabled.
+   */
+  sticky?: boolean;
+
   // Badge state
   repoInfo?: { display: string; branch?: string } | null;
   planDiffStats?: PlanDiffStats | null;
@@ -91,6 +95,7 @@ interface StickyHeaderLaneProps {
   remountToken?: string;
 }
 
+/** Render the shared, measured header lane beside the Viewer's action cluster. */
 export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
   inputMethod,
   onInputMethodChange,
@@ -98,6 +103,8 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
   onModeChange,
   taterMode,
   hideQuickLabel,
+  visibility = 'stuck',
+  sticky = true,
   repoInfo,
   planDiffStats,
   isPlanDiffActive,
@@ -115,28 +122,26 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
   const [wrapperWidth, setWrapperWidth] = useState(0);
   const [actionsWidth, setActionsWidth] = useState(0);
   const scrollViewport = useScrollViewport();
+  const laneIsStuck = sticky && isStuck;
+  const isVisible = visibility === 'always' || laneIsStuck;
+  // Preserve the incumbent ghost lane exactly: its chrome remains mounted
+  // while the whole hidden bar fades out. Only the new always-visible mode
+  // removes chrome at rest for the supported chrome-free presentation.
+  const showChrome = visibility === 'always' ? laneIsStuck : true;
 
-  // Space available for the bar in the shared lane = wrapper width, minus
-  // the bar's left offset, minus the action buttons' measured width, minus
-  // the breathing gap.
-  const availableForBar = wrapperWidth - LEFT_OFFSET - actionsWidth - GAP;
-
-  // Narrow = not enough room in the shared lane for even the icon-only
-  // bar. Falls back to a stacked row below the action buttons.
-  // actionsWidth=0 before measurement is treated as "don't know yet"
-  // (not narrow), so we don't flash the wrong layout on first paint.
-  const measured = wrapperWidth > 0 && actionsWidth > 0;
-  const isNarrow = measured && availableForBar < MIN_BAR_WIDTH;
-  // Tight = shared lane still fits, but only if the toolstrip drops its
-  // active labels and goes icon-only. Lets us stay horizontally aligned
-  // for an extra ~160px of width before stacking.
-  const isToolstripIconOnly =
-    measured && !isNarrow && availableForBar < WIDE_BAR_WIDTH;
+  const headerGeometry = resolveCompactHeaderGeometry({
+    containerWidth: wrapperWidth,
+    trailingWidth: actionsWidth,
+    leadingInset: LEFT_OFFSET,
+  });
+  const availableForBar = headerGeometry.availableForLeading;
+  const isNarrow = headerGeometry.layout === 'narrow';
+  const isToolstripIconOnly = headerGeometry.layout === 'tight';
 
   useEffect(() => {
     if (!wrapperRef.current) return;
     const ro = new ResizeObserver(([entry]) => {
-      const next = snap(entry.contentRect.width);
+      const next = snapCompactHeaderWidth(entry.contentRect.width);
       setWrapperWidth((prev) => (prev === next ? prev : next));
     });
     ro.observe(wrapperRef.current);
@@ -159,7 +164,7 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
     const el = document.querySelector<HTMLElement>('[data-sticky-actions]');
     if (!el) return;
     const ro = new ResizeObserver(([entry]) => {
-      const next = snap(entry.contentRect.width);
+      const next = snapCompactHeaderWidth(entry.contentRect.width);
       setActionsWidth((prev) => (prev === next ? prev : next));
     });
     ro.observe(el);
@@ -175,6 +180,10 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
   // doubles up with the still-visible toolstrip. Root is the OverlayScrollArea
   // viewport from context, NOT <main> (which doesn't actually scroll).
   useEffect(() => {
+    if (!sticky) {
+      setIsStuck(false);
+      return;
+    }
     if (!sentinelRef.current || !scrollViewport) return;
     const observer = new IntersectionObserver(
       ([entry]) => setIsStuck(!entry.isIntersecting),
@@ -186,17 +195,18 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
     );
     observer.observe(sentinelRef.current);
     return () => observer.disconnect();
-  }, [scrollViewport]);
+  }, [scrollViewport, sticky]);
 
   return (
     <>
-      {/* Sentinel — zero-size, rendered in normal flow at the top of the
-          column. When it scrolls out of the OverlayScrollArea viewport,
-          the sticky bar fades in. */}
-      <div ref={sentinelRef} aria-hidden="true" className="h-0 w-0" />
+      {/* Sentinel — present only for sticky positioning. It sits at the top of
+          the column and activates the stuck state after scrolling out of the
+          OverlayScrollArea viewport. */}
+      {sticky && <div ref={sentinelRef} aria-hidden="true" className="h-0 w-0" />}
 
-      {/* Sticky wrapper — zero-height so it never pushes content down. The
-          visible bar is positioned absolutely relative to this wrapper.
+      {/* Zero-height wrapper — sticky by default, relative when sticky is
+          disabled so the absolutely positioned lane scrolls in normal flow.
+          It never pushes document content down.
           The Viewer's outer wrapper uses z-50, so the sticky lane must
           sit above that to paint over the card.
 
@@ -209,8 +219,8 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
       <div
         ref={wrapperRef}
         data-sticky-header-lane="true"
-        className={`sticky z-[60] w-full self-center pointer-events-none ${
-          isNarrow ? 'top-[52px] md:top-[60px]' : 'top-3'
+        className={`${sticky ? 'sticky' : 'relative'} z-[60] w-full self-center pointer-events-none ${
+          sticky ? (isNarrow ? 'top-[52px] md:top-[60px]' : 'top-3') : ''
         }`}
         style={maxWidth == null ? { height: 0 } : { maxWidth, height: 0 }}
       >
@@ -227,11 +237,13 @@ export const StickyHeaderLane: React.FC<StickyHeaderLaneProps> = ({
             is the final safety net so any overflow clips inside the chrome
             rather than leaking out.
 
-            `inert` removes the bar from the tab order when not stuck. */}
+            `inert` removes the bar from the tab order whenever it is hidden. */}
         <div
-          inert={!isStuck || undefined}
-          className={`absolute left-3 md:left-5 top-0 inline-flex flex-wrap items-center gap-x-3 gap-y-1 min-w-0 overflow-hidden rounded-lg py-1 md:py-1.5 bg-card/95 backdrop-blur-sm shadow-sm border border-border/30 motion-reduce:transform-none ${
-            isStuck
+          inert={!isVisible || undefined}
+          className={`absolute left-3 md:left-5 top-0 inline-flex flex-wrap items-center gap-x-3 gap-y-1 min-w-0 overflow-hidden rounded-lg py-1 md:py-1.5 ${
+            showChrome ? 'bg-card/95 backdrop-blur-sm shadow-sm border border-border/30' : ''
+          } motion-reduce:transform-none ${
+            isVisible
               ? 'opacity-100 translate-y-0 pointer-events-auto'
               : 'opacity-0 -translate-y-1 pointer-events-none'
           }`}