@plannotator/ui 0.54.0 → 0.55.0

package/components/TableOfContents.tsx

@@ -22,6 +22,17 @@ interface TableOfContentsProps {
   linkedDocFilepath?: string | null;
   onLinkedDocBack?: () => void;
   backLabel?: string;
+  /**
+   * The element a click scrolls. Default: the `ScrollViewportProvider`
+   * context's viewport (plan review). A host that draws the list outside the
+   * document's scroll area (the Inbox's comments column) names it here.
+   */
+  scrollViewport?: HTMLElement | null;
+  /**
+   * The deepest heading level listed. Default 3 (plan review's list); the
+   * contents rail's surface (`DocumentContents`) lists 1 to 4, as the rail does.
+   */
+  maxLevel?: number;
 }
 
 // The prototype's TOC is a FLAT list — heading depth is conveyed by indentation
@@ -43,7 +54,7 @@ function flattenToc(items: TocItem[]): TocItem[] {
 // H1 flush + near-full strength, H2/H3 indented and dimmed to muted. Active row
 // is a soft neutral surface tint (not a loud primary fill).
 function itemClasses(level: number, isActive: boolean): string {
-  const indent = level <= 1 ? '' : level === 2 ? 'ml-3' : 'ml-6';
+  const indent = level <= 1 ? '' : level === 2 ? 'ml-3' : level === 3 ? 'ml-6' : 'ml-9';
   const tone = isActive
     ? 'bg-surface-1 text-foreground'
     : level <= 1
@@ -62,6 +73,8 @@ export function TableOfContents({
   linkedDocFilepath,
   onLinkedDocBack,
   backLabel,
+  scrollViewport: scrollViewportProp,
+  maxLevel = 3,
 }: TableOfContentsProps) {
   // Annotation count per section (kept — production feature).
   const annotationCounts = useMemo(
@@ -69,15 +82,16 @@ export function TableOfContents({
     [blocks, annotations]
   );
 
-  // Build the hierarchy (filters to heading levels ≤ 3 and attaches counts),
-  // then flatten to a plain list.
+  // Build the hierarchy (filters to heading levels ≤ maxLevel and attaches
+  // counts), then flatten to a plain list.
   const tocItems = useMemo(
-    () => flattenToc(buildTocHierarchy(blocks, annotationCounts)),
-    [blocks, annotationCounts]
+    () => flattenToc(buildTocHierarchy(blocks, annotationCounts, maxLevel)),
+    [blocks, annotationCounts, maxLevel]
   );
 
   // The real scroll element is the OverlayScrollArea viewport, not <main>.
-  const scrollViewport = useScrollViewport();
+  const contextViewport = useScrollViewport();
+  const scrollViewport = scrollViewportProp === undefined ? contextViewport : scrollViewportProp;
 
   // Smooth scroll-to-heading, accounting for the sticky header.
   const handleNavigate = useCallback(

package/components/Viewer.tsx

@@ -320,6 +320,10 @@ export interface ViewerProps {
   /** A small label over each picture tile's picture (see `QuestionBlock`
    *  `pictureBadge`); absent: none. */
   questionPictureBadge?: (choice: { label: string; image: { alt: string; src: string } }) => string | null;
+  /** A picture tile's zoom, told its question's key and the choice's index (see
+   *  `QuestionBlock` `onZoomChoice`). Absent: the zoom opens the picture
+   *  through `onImageClick`, as before. */
+  onQuestionPictureZoom?: (key: string, index: number, url: string, alt: string) => void;
   /** Makes a question's "Records a decision" tag a toggle button
    *  (`aria-pressed`); a click calls this with the question's key and the
    *  next state, which the host stores and returns from
@@ -833,6 +837,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
   questionContractLines = false,
   questionPictureChoices = true,
   questionPictureBadge,
+  onQuestionPictureZoom,
   onToggleQuestionDecisionRecording,
   onOpenQuestionDecision,
   questionDecisionLocked,
@@ -1329,8 +1334,8 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
     const container = containerRef.current;
     if (!container || !scrollViewport) return false;
 
-    const target = document.getElementById(anchor);
-    if (!target || !container.contains(target)) return false;
+    const target = container.querySelector<HTMLElement>(`#${CSS.escape(anchor)}`);
+    if (!target) return false;
 
     const documentHeader = stickyActions
       ? container.querySelector<HTMLElement>('[data-viewer-document-header]')
@@ -1980,6 +1985,7 @@ export const Viewer = forwardRef<ViewerHandle, ViewerProps>(({
                   questionContractLines={questionContractLines}
                   questionPictureChoices={questionPictureChoices}
                   questionPictureBadge={questionPictureBadge}
+                  onQuestionPictureZoom={onQuestionPictureZoom}
                 />
               );
               // `textComments`: a question card's words are not commented on

package/components/blocks/QuestionBlock.tsx

@@ -271,6 +271,11 @@ export interface QuestionBlockProps {
    *  answer, never read by the parser. Default absent, so every card draws as
    *  before (the Plannotator Inbox's onboarding tour labels its pictures). */
   pictureBadge?: (choice: { label: string; image: { alt: string; src: string } }) => string | null;
+  /** The zoom button on a picture tile, told which question and which choice
+   *  (its index in the question's choices) as well as the picture: a host can
+   *  open a gallery of that question's choices (the Plannotator Inbox's option
+   *  sets). Absent: the zoom calls `onImageClick(url, alt)` as before. */
+  onZoomChoice?: (key: string, index: number, url: string, alt: string) => void;
 }
 
 /** The picture tile's label (`pictureBadge`): a small dark chip over the picture's top-left corner. */
@@ -321,6 +326,7 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
   onNavigateAnchor,
   pictureChoices = true,
   pictureBadge,
+  onZoomChoice,
 }) => {
   const { question, number } = indexed;
   const resolveImage = useImageResolver();
@@ -880,7 +886,11 @@ export const QuestionBlock: React.FC<QuestionBlockProps> = ({
                 name={groupName}
                 readOnly={readOnly}
                 onPick={pick}
-                onZoom={onImageClick}
+                onZoom={
+                  onZoomChoice
+                    ? (url, alt, index) => onZoomChoice(question.key, index, url, alt)
+                    : onImageClick
+                }
                 onPictureError={markPictureFailed}
                 heldTitle={pictureHeldTitle}
                 renderText={inline}
@@ -1121,8 +1131,8 @@ export interface QuestionPictureTilesProps {
   readOnly?: boolean;
   /** The tile's radio or checkbox changed (the picture and the label pick through it). */
   onPick: (label: string, checked: boolean) => void;
-  /** The separate zoom button (absent: no zoom button). Never picks. */
-  onZoom?: (url: string, alt: string) => void;
+  /** The separate zoom button (absent: no zoom button). Never picks. `index`: the choice's place in `choices`. */
+  onZoom?: (url: string, alt: string, index: number) => void;
   onPictureError?: (url: string) => void;
   /** The host's reason a picture is held (its image resolver's `unavailable` title). */
   heldTitle?: (src: string) => string | null;
@@ -1256,7 +1266,7 @@ export const QuestionPictureTiles: React.FC<QuestionPictureTilesProps> = ({
           {shown && onZoom && (
             <button
               type="button"
-              onClick={() => onZoom(shown, alt)}
+              onClick={() => onZoom(shown, alt, index)}
               aria-label={`Zoom: ${alt}`}
               className="annotation-exclude absolute right-1.5 top-1.5 grid h-7 w-7 place-items-center rounded-md bg-background/85 text-foreground shadow-sm ring-1 ring-border/70 before:absolute before:-inset-2 before:content-[''] hover:bg-background focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-primary"
               data-pinpoint-ignore=""

package/components/html-viewer/HtmlViewer.tsx

@@ -148,6 +148,20 @@ const MAX_VIM_COPY_TEXT_LENGTH = 2 * 1024 * 1024;
  */
 export const HTML_VIEWER_SANDBOX = "allow-scripts allow-modals";
 
+/**
+ * The srcdoc frame's `sandbox` attribute: the `sandbox` prop's value as given,
+ * plus `allow-popups` when `hostNavigates` needs it and the value lacks it.
+ * Anything that is not a string (`undefined`, and also `null` from a host's
+ * unset config, which a destructuring default does not catch) becomes
+ * `HTML_VIEWER_SANDBOX`, so the frame always carries a sandbox: React would
+ * drop a `null` attribute and run the page unsandboxed.
+ */
+function srcdocSandbox(sandbox: unknown, hostNavigates: boolean): string {
+  const value = typeof sandbox === "string" ? sandbox : HTML_VIEWER_SANDBOX;
+  if (!hostNavigates || value.split(/\s+/).includes("allow-popups")) return value;
+  return value.trim() ? `${value} allow-popups` : "allow-popups";
+}
+
 /** Default wait for the bridge's `ready` on the `bridgeScriptUrl` path. */
 export const DEFAULT_BRIDGE_READY_TIMEOUT_MS = 5000;
 
@@ -373,6 +387,26 @@ export interface HtmlViewerProps {
    * still pins. Absent → unchanged.
    */
   hostNavigates?: boolean;
+  /**
+   * The srcdoc frame's whole `sandbox` attribute value, for a host whose
+   * documents must not open dialogs: `"allow-scripts"` keeps a shared page's
+   * `alert`, `confirm` and `prompt` from drawing over the host's origin. Used
+   * as given, except that `hostNavigates` still adds `allow-popups`, which it
+   * needs. Never add `allow-same-origin` beside `allow-scripts`: the page
+   * could then remove its own sandbox. Live-app (`src`) mode has no sandbox
+   * and ignores this. Absent, or any non-string such as `null` →
+   * `HTML_VIEWER_SANDBOX` (`"allow-scripts allow-modals"`), unchanged.
+   *
+   * `""` (or only spaces) is kept as given: the strictest frame, with no
+   * scripts, so the annotation bridge never starts and the page cannot be
+   * annotated. It never falls back to the wider default.
+   *
+   * Read when the frame loads a document: browsers apply a changed `sandbox`
+   * only on the frame's next navigation (a new `rawHtml`, for example). To
+   * apply a new value to the document already shown, remount the viewer (for
+   * example, key it on the value).
+   */
+  sandbox?: string;
 }
 
 /**
@@ -429,6 +463,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
       bridgeErrorDisplay = "banner",
       onHostDraft,
       hostNavigates = false,
+      sandbox = HTML_VIEWER_SANDBOX,
     },
     ref,
   ) => {
@@ -1295,7 +1330,7 @@ export const HtmlViewer = forwardRef<ViewerHandle, HtmlViewerProps>(
                 same-origin XHR) and no srcdoc. Srcdoc mode is unchanged. */}
             <iframe
               ref={iframeRef}
-              {...(src ? { src } : { srcDoc: srcdoc, sandbox: HTML_VIEWER_SANDBOX + (hostNavigates ? " allow-popups" : "") })}
+              {...(src ? { src } : { srcDoc: srcdoc, sandbox: srcdocSandbox(sandbox, hostNavigates) })}
               style={{
                 width: "100%",
                 height: fullViewport ? "100%" : `${iframeHeight}px`,

package/components/imageZoom.ts

@@ -147,6 +147,17 @@ export function atFit(view: ZoomViewport, limits: ZoomLimits | number): boolean
   return Math.abs(view.scale - fit) < 1e-3;
 }
 
+/**
+ * Whether the part of an image on screen (`visibleBox`, its own pixels) can
+ * still pan sideways: `1` shows more of its right (the finger moving left),
+ * `-1` more of its left. A swipe that way pans first, and steps once the
+ * image is at its edge (approval "inbox-image-swipe").
+ */
+export function canPanToward(box: Pick<NaturalBox, 'x' | 'w'> | null, naturalWidth: number, dir: 1 | -1): boolean {
+  if (!box || !(naturalWidth > 0)) return false;
+  return dir > 0 ? box.x + box.w < naturalWidth - 1 : box.x > 1;
+}
+
 /** The share of a stage that leaves `padding` CSS pixels on every side (at least a tenth). */
 export function paddingInset(stage: ZoomSize, padding: number): ZoomInset {
   if (!valid(stage) || padding <= 0) return FULL;

package/contents-rail.css

@@ -0,0 +1,337 @@
+/*
+ * @plannotator/ui/contents-rail.css: the document contents rail
+ * (components/MarkdownContentsRail.tsx). Its own stylesheet, NOT part of
+ * theme.css or styles.css: import it OUTSIDE any CSS cascade layer, after the
+ * host's base reset. A layered copy loses to a later unlayered reset (the
+ * marker's margin-inline-start: auto, the tick, title and label paddings and
+ * margins, the depth indents), and the ticks then sit over the prose.
+ *
+ * Moved from the Workspaces app's `ws-markdown-contents-*` rules (approved
+ * 2026-10-03). A stable marker dock sits in the document's existing right
+ * padding without participating in layout. The Contents surface opens to its
+ * LEFT and may overlay the document, never a docked comments column. Pointer
+ * events stay on the real navigation buttons; selection and scrolling remain
+ * untouched. Plain CSS, no Tailwind. Tokens are the host's (Workspaces defines
+ * them all); each has a fallback.
+ */
+@keyframes pn-contents-rail-enter {
+  from {
+    opacity: 0;
+  }
+}
+
+.pn-contents-rail {
+  --pn-contents-dock-width: 36px;
+  --pn-contents-panel-gap: 6px;
+  --pn-contents-panel-width: 256px;
+
+  position: fixed;
+  z-index: 20;
+  translate: 0 -50%;
+  width: calc(
+    var(--pn-contents-dock-width) + var(--pn-contents-panel-gap) + var(--pn-contents-panel-width)
+  );
+  pointer-events: none;
+  animation: pn-contents-rail-enter var(--motion-duration-fast, 120ms)
+    var(--ease-enter, cubic-bezier(0.22, 1, 0.36, 1)) both;
+}
+
+.pn-contents-rail-dock {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: var(--pn-contents-dock-width);
+  pointer-events: none;
+}
+
+/* The floating surface (Workspaces' `floating-surface`: popover fill, no drawn
+ * border, the edge is the hairline ring in the menu shadow). */
+.pn-contents-rail-surface {
+  position: absolute;
+  top: -40px;
+  bottom: -8px;
+  left: 0;
+  width: var(--pn-contents-panel-width);
+  border-radius: var(--geometry-floating-radius, 10px);
+  background: var(--popover);
+  color: var(--popover-foreground);
+  box-shadow: var(
+    --shadow-menu,
+    0 0 0 1px color-mix(in oklch, var(--foreground) 8%, transparent),
+    0 12px 32px -8px color-mix(in oklch, var(--foreground) 22%, transparent)
+  );
+  transform: translateX(4px) scale(0.98);
+  transform-origin: right center;
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* The section eyebrow (Workspaces' EYEBROW: 12 px, weight 500). */
+.pn-contents-rail-title {
+  position: absolute;
+  top: -32px;
+  left: 8px;
+  display: flex;
+  width: calc(var(--pn-contents-panel-width) - 16px);
+  height: 28px;
+  align-items: center;
+  padding-inline: 4px;
+  color: var(--foreground);
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 20px;
+  transform: translateX(4px);
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1);
+}
+
+/* A host's one control at the right of the open panel's title (panelAction). */
+.pn-contents-rail-action {
+  position: absolute;
+  z-index: 2;
+  top: -32px;
+  right: calc(var(--pn-contents-dock-width) + var(--pn-contents-panel-gap) + 8px);
+  display: flex;
+  height: 28px;
+  align-items: center;
+  pointer-events: auto;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-surface,
+.pn-contents-rail[data-revealed] .pn-contents-rail-title {
+  transform: translateX(0) scale(1);
+  opacity: 1;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-title {
+  transition-delay: var(--motion-duration-basic, 150ms), var(--motion-duration-basic, 150ms);
+}
+
+.pn-contents-rail-list {
+  position: relative;
+  z-index: 1;
+  width: 100%;
+  /* The closed rail renders at most ten sampled document spans, so it never
+   * needs an internal scroll position. Shorter maps retain their natural
+   * height and stay centered by the rail's fixed midpoint anchor. */
+  max-height: 160px;
+  overflow-x: hidden;
+  overflow-y: hidden;
+  overscroll-behavior: contain;
+  scrollbar-width: none;
+  touch-action: none;
+  pointer-events: none;
+  transition: max-height var(--motion-duration-basic, 150ms) var(--ease-exit, cubic-bezier(0.4, 0, 0.2, 1));
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-list {
+  max-height: min(62vh, 560px);
+  overflow-y: auto;
+  transition-duration: var(--motion-duration-relaxed, 300ms);
+  transition-timing-function: var(--ease-enter, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+.pn-contents-rail-list::-webkit-scrollbar {
+  display: none;
+}
+
+.pn-contents-rail-marker {
+  --pn-contents-line-width: 26px;
+
+  position: relative;
+  display: flex;
+  width: var(--pn-contents-dock-width);
+  height: 16px;
+  flex-direction: row-reverse;
+  align-items: center;
+  justify-content: flex-start;
+  overflow: hidden;
+  margin-inline-start: auto;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  pointer-events: auto;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-marker {
+  width: 100%;
+  overflow: visible;
+}
+
+.pn-contents-rail-tick {
+  display: flex;
+  width: var(--pn-contents-dock-width);
+  flex: none;
+  align-items: center;
+  justify-content: flex-start;
+  padding-inline-start: 4px;
+}
+
+.pn-contents-rail-line {
+  --marker-progress: 0;
+
+  display: block;
+  width: var(--pn-contents-line-width);
+  height: 2px;
+  transform: scaleX(calc(0.6154 + 0.3846 * var(--marker-progress)));
+  transform-origin: left center;
+  background: var(--muted-foreground);
+  opacity: 0.4;
+  pointer-events: none;
+  transition: none;
+}
+
+/* The frequently scanned closed map updates immediately. The local lens is
+ * motion reserved for the explicitly opened Contents state. */
+.pn-contents-rail[data-revealed] .pn-contents-rail-line {
+  transition:
+    transform var(--motion-duration-basic, 150ms)
+      linear(0, 0.398 10%, 0.682 20%, 0.843 30%, 0.925 40%, 0.972 50%, 1.004 60%, 1.008 70%, 1.003 80%, 1),
+    opacity var(--motion-duration-basic, 150ms) ease,
+    background-color var(--motion-duration-basic, 150ms) ease;
+}
+
+/* H1:H2 is 12px:10px with the shorter line inset 2px toward the document, at
+ * a deliberately longer scale, then the same step for H3 and H4. */
+.pn-contents-rail-marker[data-level="2"] {
+  --pn-contents-line-width: 22px;
+}
+
+.pn-contents-rail-marker[data-level="3"] {
+  --pn-contents-line-width: 18px;
+}
+
+.pn-contents-rail-marker[data-level="4"] {
+  --pn-contents-line-width: 14px;
+}
+
+.pn-contents-rail-marker[data-current] .pn-contents-rail-line {
+  background: var(--primary);
+  opacity: 0.68;
+}
+
+.pn-contents-rail-marker[data-highlighted] .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible .pn-contents-rail-line {
+  --marker-progress: 1;
+  background: var(--foreground);
+  opacity: 1;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.7;
+  opacity: 0.78;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.4;
+  opacity: 0.58;
+}
+
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker[data-highlighted]) .pn-contents-rail-line,
+.pn-contents-rail-marker:has(+ .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker:focus-visible) .pn-contents-rail-line,
+.pn-contents-rail-marker[data-highlighted] + .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line,
+.pn-contents-rail-marker:focus-visible + .pn-contents-rail-marker + .pn-contents-rail-marker + .pn-contents-rail-marker .pn-contents-rail-line {
+  --marker-progress: 0.2;
+  opacity: 0.46;
+}
+
+.pn-contents-rail-label {
+  display: block;
+  width: calc(var(--pn-contents-panel-width) - 16px);
+  height: 16px;
+  min-width: 0;
+  flex: none;
+  overflow: hidden;
+  margin-inline-end: calc(var(--pn-contents-panel-gap) + 8px);
+  padding-inline: 4px;
+  border-radius: var(--geometry-structure-radius, 4px);
+  background: transparent;
+  color: var(--muted-foreground);
+  font-size: inherit;
+  font-weight: 400;
+  line-height: 16px;
+  text-align: left;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  opacity: 0;
+  transform: translateX(-4px);
+  pointer-events: none;
+  transition:
+    opacity var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    transform var(--motion-duration-basic, 150ms) cubic-bezier(0.23, 1, 0.32, 1),
+    color var(--motion-duration-fast, 120ms) ease,
+    background-color var(--motion-duration-fast, 120ms) ease;
+}
+
+.pn-contents-rail-marker[data-depth="1"] .pn-contents-rail-label {
+  padding-inline-start: 16px;
+}
+
+.pn-contents-rail-marker[data-depth="2"] .pn-contents-rail-label {
+  padding-inline-start: 28px;
+}
+
+.pn-contents-rail-marker[data-depth="3"] .pn-contents-rail-label {
+  padding-inline-start: 40px;
+}
+
+.pn-contents-rail[data-revealed] .pn-contents-rail-label {
+  opacity: 1;
+  transform: translateX(0);
+  transition-delay: var(--motion-duration-basic, 150ms), var(--motion-duration-basic, 150ms), 0ms, 0ms;
+}
+
+.pn-contents-rail-marker[data-current] .pn-contents-rail-label {
+  color: var(--foreground);
+}
+
+.pn-contents-rail-marker[data-highlighted] .pn-contents-rail-label,
+.pn-contents-rail-marker:focus-visible .pn-contents-rail-label {
+  background: var(--surface-hover, color-mix(in oklch, var(--foreground) 6%, transparent));
+  color: var(--foreground);
+}
+
+.pn-contents-rail:focus-within .pn-contents-rail-surface,
+.pn-contents-rail:focus-within .pn-contents-rail-title,
+.pn-contents-rail:focus-within .pn-contents-rail-label,
+.pn-contents-rail:focus-within .pn-contents-rail-list {
+  transition-duration: 0ms;
+  transition-delay: 0ms;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pn-contents-rail {
+    animation: none;
+  }
+  .pn-contents-rail-line {
+    transition: none;
+  }
+  .pn-contents-rail-surface,
+  .pn-contents-rail-title,
+  .pn-contents-rail-label,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-surface,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-title,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-label {
+    transform: none;
+    transition: opacity var(--motion-duration-fast, 120ms) ease;
+    transition-delay: 0ms;
+  }
+  .pn-contents-rail-list,
+  .pn-contents-rail[data-revealed] .pn-contents-rail-list {
+    transition: none;
+  }
+}

package/hooks/useHeadingScrollSpy.ts

@@ -0,0 +1,77 @@
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { activeHeadingBinding, bindHeadings, type HeadingBinding } from '../utils/headingScrollSpy';
+
+/**
+ * The block id of the heading being read in `scrollViewport`, by the contents
+ * rail's own scroll math (utils/headingScrollSpy): cached heading tops, read
+ * on every scroll frame, the last heading at the document's end. For a
+ * Contents list on the rail's surface (`DocumentContents`), so the two never
+ * disagree. Plan review's list keeps `useActiveSection`.
+ *
+ * Reads at once on mount (a sheet opened mid-document marks the section being
+ * read on its first paint), and re-binds when the document's elements change
+ * (an edit can replace the headings and keep their count) or resize. Before
+ * any heading is drawn the answer stays what it was.
+ */
+export function useHeadingScrollSpy(
+  scrollViewport: HTMLElement | null,
+  blockIds: readonly string[],
+): string | null {
+  const idsKey = blockIds.join('\n');
+  // Stable while the ids are the same, whatever array the caller passes.
+  const ids = useMemo(() => (idsKey === '' ? [] : idsKey.split('\n')), [idsKey]);
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const bindingsRef = useRef<readonly HeadingBinding[]>([]);
+
+  const refresh = useCallback(() => {
+    if (scrollViewport === null) return;
+    const binding = activeHeadingBinding(bindingsRef.current, scrollViewport);
+    if (binding !== null) setActiveIndex(binding.itemIndex);
+  }, [scrollViewport]);
+
+  useLayoutEffect(() => {
+    setActiveIndex(null);
+    bindingsRef.current = [];
+    if (scrollViewport === null || ids.length === 0) return;
+    const rebind = () => {
+      bindingsRef.current = bindHeadings(scrollViewport, ids);
+      refresh();
+    };
+    rebind();
+
+    let scrollFrame: number | null = null;
+    const onScroll = () => {
+      if (scrollFrame !== null) return;
+      scrollFrame = requestAnimationFrame(() => {
+        scrollFrame = null;
+        refresh();
+      });
+    };
+    let bindFrame: number | null = null;
+    const scheduleRebind = () => {
+      if (bindFrame !== null) cancelAnimationFrame(bindFrame);
+      bindFrame = requestAnimationFrame(() => {
+        bindFrame = null;
+        rebind();
+      });
+    };
+    scrollViewport.addEventListener('scroll', onScroll, { passive: true });
+    window.addEventListener('resize', scheduleRebind);
+    const resizeObserver =
+      typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(scheduleRebind);
+    resizeObserver?.observe(scrollViewport);
+    const mutationObserver =
+      typeof MutationObserver === 'undefined' ? null : new MutationObserver(scheduleRebind);
+    mutationObserver?.observe(scrollViewport, { childList: true, subtree: true });
+    return () => {
+      if (scrollFrame !== null) cancelAnimationFrame(scrollFrame);
+      if (bindFrame !== null) cancelAnimationFrame(bindFrame);
+      scrollViewport.removeEventListener('scroll', onScroll);
+      window.removeEventListener('resize', scheduleRebind);
+      resizeObserver?.disconnect();
+      mutationObserver?.disconnect();
+    };
+  }, [ids, refresh, scrollViewport]);
+
+  return activeIndex === null ? null : (ids[activeIndex] ?? null);
+}