@plannotator/ui 0.54.0 → 0.56.0

package/components/ImageLightbox.tsx

@@ -9,13 +9,16 @@ import { CommentPopover, type CommentAskAIHandler } from './CommentPopover';
 import { ImagePeek, type ImagePeekHandle, type ImagePeekRow } from './ImagePeek';
 import { RegionBoxLayer, RegionToolStrip, regionOf, type RegionBoxItem } from './ImageRegions';
 import { ImageZoomStage, type ImageZoomStageHandle, type WheelHintGate, type ZoomDraw, type ZoomMode } from './ImageZoomStage';
-import type { NaturalBox, ZoomSize, ZoomViewport } from './imageZoom';
+import { canPanToward, type NaturalBox, type ZoomSize, type ZoomViewport } from './imageZoom';
 import { useIsMobile } from '../hooks/useIsMobile';
+import { useSwipeStep } from '../hooks/useSwipeStep';
 
 /** One image of a document, for the lightbox's stepping (`images`). */
 export interface LightboxImage {
   src: string;
   alt: string;
+  /** What the viewer calls the image (a picture choice: "B · Quiet hover menu"). Absent: the file name its src names. */
+  name?: string;
   /** The heading the image sits under ("Options"), for "2 of 4 · in “Options”" and the peek's rows. */
   section?: string | null;
   /**
@@ -70,10 +73,12 @@ function isTextField(el: EventTarget | null): boolean {
 }
 
 /**
- * The file name an image's src names: the `path` a host route carries
- * (`/api/image?path=…`), else the URL's last segment, else the alt text.
+ * What the viewer calls an image: its `name` when the host gave one, else the
+ * file name its src names (the `path` a host route carries,
+ * `/api/image?path=…`, else the URL's last segment), else the alt text.
  */
-export function lightboxImageName(image: Pick<LightboxImage, 'src' | 'alt'>): string {
+export function lightboxImageName(image: Pick<LightboxImage, 'src' | 'alt' | 'name'>): string {
+  if (image.name) return image.name;
   try {
     const base = typeof window !== 'undefined' && /^https?:/.test(window.location.href) ? window.location.href : 'http://localhost/';
     const url = new URL(image.src, base);
@@ -162,7 +167,15 @@ export const ImageLightbox: React.FC<{
   images?: readonly LightboxImage[];
   /** Comments on part of an image (#2100). Additive: absent, no region tools. */
   regions?: LightboxRegionComments;
-}> = ({ src, alt, onClose, images, regions }) => {
+  /**
+   * A touch screen's swipe through `images` (`useSwipeStep`, the Inbox
+   * phone viewer's, approval "inbox-image-swipe"): the image follows the
+   * finger and steps past a third of the width or on a flick, a zoomed image
+   * pans to its edge first, and a drag down at Fit closes. Additive: absent,
+   * no swipe.
+   */
+  swipe?: boolean;
+}> = ({ src, alt, onClose, images, regions, swipe }) => {
   const overlayRef = useRef<HTMLDivElement>(null);
   const onCloseRef = useRef(onClose);
   onCloseRef.current = onClose;
@@ -389,6 +402,47 @@ export const ImageLightbox: React.FC<{
   }, [index]);
   const stepRef = useRef(step);
   stepRef.current = step;
+  // A touch screen's swipe (`swipe`): heard on the image area, which stays put (so a finger that comes back while the
+  // last step is still sliding is heard), and only the picture follows the finger (`swipeTrackRef`), not the region
+  // strip over it. A box being drawn, Region, or the peek keep the touch. One image alone: a drag down still closes.
+  const swipeAreaRef = useRef<HTMLDivElement>(null);
+  const swipeTrackRef = useRef<HTMLDivElement>(null);
+  /** The zoom stage, inside the track that follows the finger with `swipe`; without it, as before (no wrapper). */
+  const tracked = (stage: React.ReactNode) =>
+    swipe ? (
+      <div ref={swipeTrackRef} className="absolute inset-0" data-lightbox-track="">
+        {stage}
+      </div>
+    ) : (
+      stage
+    );
+  const dimsRef = useRef(dims);
+  dimsRef.current = dims;
+  const zoomModeRef = useRef(zoomMode);
+  zoomModeRef.current = zoomMode;
+  useSwipeStep(framed ? swipeAreaRef : overlayRef, {
+    enabled: !!swipe && !(canDraw && tool === 'region') && !peekOpen && !drawerOpen,
+    canStep: (dir) => stepping && index + dir >= 0 && index + dir < (list?.length ?? 0),
+    move: () => [swipeTrackRef.current],
+    onStep: (dir) => stepRef.current(dir),
+    wouldAsk: () => pending !== null,
+    keeps: (dir) => !stepping || canPanToward(stageRef.current?.visibleBox() ?? null, dimsRef.current?.width ?? 0, dir),
+    dismiss: {
+      can: () => {
+        if (zoomModeRef.current !== 'fit') return false;
+        const box = stageRef.current?.visibleBox() ?? null;
+        return box === null || box.y <= 1;
+      },
+      onDismiss: () => onCloseRef.current(),
+      onProgress: (share) => {
+        const overlay = overlayRef.current;
+        if (!overlay) return;
+        // The framed viewer's page colour, or the one-image overlay's dark veil, fades with the drag.
+        const veil = framed ? `color-mix(in oklch, var(--background) ${Math.round((1 - share) * 100)}%, transparent)` : `rgb(0 0 0 / ${(0.8 * (1 - share)).toFixed(3)})`;
+        overlay.style.backgroundColor = share > 0 ? veil : '';
+      },
+    },
+  });
   const steppingRef = useRef(stepping);
   steppingRef.current = stepping;
   const peekOpenRef = useRef(peekOpen);
@@ -531,22 +585,24 @@ export const ImageLightbox: React.FC<{
         data-image-lightbox=""
         className="fixed inset-0 z-[200] bg-black/80 text-white backdrop-blur-sm outline-none"
       >
-        <ImageZoomStage
-          ref={stageRef}
-          key={src}
-          src={src}
-          alt={alt}
-          label={alt ? `Image: ${alt}` : 'Image'}
-          mode={zoomMode}
-          onModeChange={setZoomMode}
-          inset={{ x: 0.9, y: 0.85 }}
-          onBackgroundTap={onClose}
-          className="absolute inset-0"
-          imageClassName="shadow-2xl"
-          radius={8}
-          stageAttributes={{ 'data-lightbox-stage': zoomMode }}
-          wheelHint={wheelHint}
-        />
+        {tracked(
+          <ImageZoomStage
+            ref={stageRef}
+            key={src}
+            src={src}
+            alt={alt}
+            label={alt ? `Image: ${alt}` : 'Image'}
+            mode={zoomMode}
+            onModeChange={setZoomMode}
+            inset={{ x: 0.9, y: 0.85 }}
+            onBackgroundTap={onClose}
+            className="absolute inset-0"
+            imageClassName="shadow-2xl"
+            radius={8}
+            stageAttributes={{ 'data-lightbox-stage': zoomMode }}
+            wheelHint={wheelHint}
+          />
+        )}
         {alt && (
           <div className="pointer-events-none absolute inset-x-0 bottom-[2.5vh] mx-auto max-w-[90vw] truncate text-center text-sm text-white/70">{alt}</div>
         )}
@@ -711,48 +767,50 @@ export const ImageLightbox: React.FC<{
                 </svg>
               </button>
             )}
-            <div className="relative min-h-0 min-w-0 flex-1 self-stretch">
-              <ImageZoomStage
-                ref={stageRef}
-                key={`${index}:${current.src}`}
-                src={current.src}
-                alt={current.alt}
-                label={`Image: ${name}`}
-                description={drawing ? 'Region: drag to draw a box and comment on it. Or frame the spot with Actual size and the scroll keys, then press Enter to comment on what is on screen.' : undefined}
-                mode={zoomMode}
-                onModeChange={setZoomMode}
-                onScaleChange={setScale}
-                onImageLoad={setDims}
-                // A single image keeps #2067's tap beside the image to close
-                // (its click swallowed so the page beneath never gets it), in
-                // Move only: in Region a press there may start a box.
-                onBackgroundTap={!stepping && !drawing ? onClose : undefined}
-                onViewChange={regionsOn ? (v, stage, eased) => setView({ view: v, stage, eased }) : undefined}
-                drawing={drawing}
-                onDraw={drawing ? onDraw : undefined}
-                className="absolute inset-0"
-                imageClassName="shadow-xl"
-                stageAttributes={{ 'data-lightbox-stage': zoomMode, ...(regionsOn ? { 'data-region-tool-active': tool } : {}) }}
-                wheelHint={wheelHint}
-              >
-                {regionsOn && (
-                  <RegionBoxLayer
-                    view={view?.view ?? null}
-                    stage={view?.stage ?? null}
-                    eased={view?.eased ?? false}
-                    regions={boxes}
-                    selectedId={selectedId}
-                    draft={draft}
-                    pending={pending ? { box: pending, n: pendingNumber } : null}
-                    interactive={!drawing}
-                    onPick={(id) => {
-                      setDrawerOpen(true);
-                      setSelectedId(id);
-                    }}
-                    pendingRef={setPendingEl}
-                  />
-                )}
-              </ImageZoomStage>
+            <div ref={swipeAreaRef} className="relative min-h-0 min-w-0 flex-1 self-stretch" data-lightbox-swipe={swipe ? '' : undefined}>
+              {tracked(
+                <ImageZoomStage
+                  ref={stageRef}
+                  key={`${index}:${current.src}`}
+                  src={current.src}
+                  alt={current.alt}
+                  label={`Image: ${name}`}
+                  description={drawing ? 'Region: drag to draw a box and comment on it. Or frame the spot with Actual size and the scroll keys, then press Enter to comment on what is on screen.' : undefined}
+                  mode={zoomMode}
+                  onModeChange={setZoomMode}
+                  onScaleChange={setScale}
+                  onImageLoad={setDims}
+                  // A single image keeps #2067's tap beside the image to close
+                  // (its click swallowed so the page beneath never gets it), in
+                  // Move only: in Region a press there may start a box.
+                  onBackgroundTap={!stepping && !drawing ? onClose : undefined}
+                  onViewChange={regionsOn ? (v, stage, eased) => setView({ view: v, stage, eased }) : undefined}
+                  drawing={drawing}
+                  onDraw={drawing ? onDraw : undefined}
+                  className="absolute inset-0"
+                  imageClassName="shadow-xl"
+                  stageAttributes={{ 'data-lightbox-stage': zoomMode, ...(regionsOn ? { 'data-region-tool-active': tool } : {}) }}
+                  wheelHint={wheelHint}
+                >
+                  {regionsOn && (
+                    <RegionBoxLayer
+                      view={view?.view ?? null}
+                      stage={view?.stage ?? null}
+                      eased={view?.eased ?? false}
+                      regions={boxes}
+                      selectedId={selectedId}
+                      draft={draft}
+                      pending={pending ? { box: pending, n: pendingNumber } : null}
+                      interactive={!drawing}
+                      onPick={(id) => {
+                        setDrawerOpen(true);
+                        setSelectedId(id);
+                      }}
+                      pendingRef={setPendingEl}
+                    />
+                  )}
+                </ImageZoomStage>
+              )}
               {strip && (
                 <div className={`pointer-events-none absolute inset-x-0 z-[3] flex justify-center ${phone ? 'bottom-2.5' : 'top-2.5'}`}>{strip}</div>
               )}

package/components/ImageZoomStage.tsx

@@ -23,6 +23,7 @@ import {
   zoomLimits,
   type FitAxis,
   type NaturalBox,
+  type ZoomClear,
   type ZoomInset,
   type ZoomSize,
   type ZoomViewport,
@@ -165,7 +166,11 @@ function prefersReducedMotion(): boolean {
  * (Fit fills the width or height, the smallest scale stays the whole
  * image), `padding` (Fit leaves that many pixels on every side), `overlay`
  * (drawn over the image in the same transform, e.g. a marked-up copy, so it
- * stays aligned at any zoom), and `onImageLoad` / `onImageError`.
+ * stays aligned at any zoom), `clear` (rows the host floats things over: Fit
+ * and the pan's limits work between them, the image still slides under them
+ * when zoomed, and those rows still take the fingers), and `onImageLoad` /
+ * `onImageError`. `clear` and Region mode do not go together: `children` and
+ * `onViewChange` speak of the stage without it.
  *
  * Region comments (#2100) add three more, also optional: `drawing` (a
  * primary press and drag draws a box, reported through `onDraw` in the
@@ -188,6 +193,8 @@ export const ImageZoomStage = forwardRef<ImageZoomStageHandle, {
   padding?: number;
   /** Which way Fit fits (default: the whole image). */
   fitAxis?: FitAxis;
+  /** Rows at the stage's top and bottom that the host floats things over (default: none). */
+  clear?: ZoomClear;
   /** Drawn over the image at its own size, in the image's transform. */
   overlay?: React.ReactNode;
   /** The image's own size, once it has loaded. */
@@ -216,7 +223,7 @@ export const ImageZoomStage = forwardRef<ImageZoomStageHandle, {
   children?: React.ReactNode;
   /** The "⌘ + scroll to zoom" hint's gate, shared across the viewer's stages; `false` turns the hint off. Absent: once per stage. */
   wheelHint?: WheelHintGate | false;
-}>(function ImageZoomStage({ src, alt, mode, onModeChange, onScaleChange, inset, padding, fitAxis, overlay, onImageLoad, onImageError, onBackgroundTap, className, imageClassName, radius = 6, stageAttributes, label, description, drawing = false, onDraw, onViewChange, children, wheelHint }, ref) {
+}>(function ImageZoomStage({ src, alt, mode, onModeChange, onScaleChange, inset, padding, fitAxis, clear, overlay, onImageLoad, onImageError, onBackgroundTap, className, imageClassName, radius = 6, stageAttributes, label, description, drawing = false, onDraw, onViewChange, children, wheelHint }, ref) {
   const stageRef = useRef<HTMLDivElement>(null);
   const imgRef = useRef<HTMLImageElement>(null);
   const [dims, setDims] = useState<ZoomSize | null>(null);
@@ -230,6 +237,10 @@ export const ImageZoomStage = forwardRef<ImageZoomStageHandle, {
   paddingRef.current = padding;
   const axisRef = useRef<FitAxis>(fitAxis ?? 'contain');
   axisRef.current = fitAxis ?? 'contain';
+  const clearTop = clear?.top ?? 0;
+  const clearBottom = clear?.bottom ?? 0;
+  const clearRef = useRef({ top: clearTop, bottom: clearBottom });
+  clearRef.current = { top: clearTop, bottom: clearBottom };
   const overlayRef = useRef<HTMLDivElement | null>(null);
   const dimsRef = useRef<ZoomSize | null>(null);
   const boxRef = useRef<StageBox | null>(null);
@@ -291,7 +302,9 @@ export const ImageZoomStage = forwardRef<ImageZoomStageHandle, {
     const stage = stageRef.current;
     if (!stage) return null;
     const r = stage.getBoundingClientRect();
-    boxRef.current = { width: r.width, height: r.height, left: r.left, top: r.top };
+    // The box every viewport is worked out in: the stage between the clear rows, its corner where the viewport's 0, 0 is drawn (`paint`).
+    const { top, bottom } = clearRef.current;
+    boxRef.current = { width: r.width, height: r.height - top - bottom, left: r.left, top: r.top + top };
     return boxRef.current;
   }, []);
 
@@ -304,7 +317,7 @@ export const ImageZoomStage = forwardRef<ImageZoomStageHandle, {
   const paint = useCallback(
     (el: HTMLElement, view: ZoomViewport, animate: boolean) => {
       el.style.transition = animate && !prefersReducedMotion() ? 'transform 180ms cubic-bezier(0.2, 0, 0, 1)' : 'none';
-      el.style.transform = `translate(${view.x}px, ${view.y}px) scale(${view.scale})`;
+      el.style.transform = `translate(${view.x}px, ${view.y + clearRef.current.top}px) scale(${view.scale})`;
       el.style.borderRadius = `${radius / view.scale}px`;
     },
     [radius],
@@ -376,6 +389,21 @@ export const ImageZoomStage = forwardRef<ImageZoomStageHandle, {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [padding, fitAxis, measure, applyMode, apply]);
 
+  // The host's clear rows changed (what floats came or went): Fit eases to the new space, anything else stays where it is on screen, within it.
+  const clearShape = useRef({ top: clearTop, bottom: clearBottom });
+  useLayoutEffect(() => {
+    const movedBy = clearShape.current.top - clearTop;
+    if (movedBy === 0 && clearShape.current.bottom === clearBottom) return;
+    clearShape.current = { top: clearTop, bottom: clearBottom };
+    measure();
+    if (!ready() || !viewRef.current) return;
+    if (modeRef.current === 'fit') return applyMode('fit', true);
+    const kept = clampViewport({ ...viewRef.current, y: viewRef.current.y + movedBy }, dimsRef.current!, boxRef.current!, limits());
+    if (modeRef.current === 'zoom') gesture(kept);
+    else apply(kept);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [clearTop, clearBottom, measure, applyMode, apply]);
+
   // The image's own size, once it has loaded (or at once when it was cached).
   useEffect(() => {
     const img = imgRef.current;

package/components/InlineMarkdown.tsx

@@ -1,9 +1,8 @@
-import React, { useState, useRef, useCallback, useEffect, useMemo } from "react";
-import { createPortal } from "react-dom";
+import React, { useState, useMemo } from "react";
 import { isCodeFilePath, isCodeFilePathStrict, CODE_PATH_BARE_REGEX, parseCodePath } from "@plannotator/core/code-file";
 import { findCrossRepoRef, forgeRefLinks, matchCrossRepoRef, type CrossRepoRef } from "@plannotator/core/forge-refs";
-import { ensureHighlight, highlightToHtml } from "../utils/codeHighlight";
-import { useFenceTheme } from "../hooks/useFenceTheme";
+import { CodeSnippetPreview } from "./CodeSnippetPreview";
+import { useHoverPreview } from "../hooks/useHoverPreview";
 import { transformPlainText } from "../utils/inlineTransforms";
 import { hasLinkedDocExtension } from "../utils/markdownExtensions";
 import { getImageSrc } from "./ImageThumbnail";
@@ -77,101 +76,6 @@ function gateCodePath(
   }
 }
 
-function extToLanguage(filepath: string): string | undefined {
-  const ext = filepath.split('.').pop()?.toLowerCase();
-  const map: Record<string, string> = {
-    ts: 'typescript', tsx: 'typescript', js: 'javascript', jsx: 'javascript',
-    py: 'python', rb: 'ruby', rs: 'rust', go: 'go', java: 'java',
-    css: 'css', scss: 'scss', json: 'json', yml: 'yaml', yaml: 'yaml',
-    sql: 'sql', sh: 'bash', bash: 'bash', zsh: 'bash', md: 'markdown',
-    html: 'html', xml: 'xml', toml: 'toml', swift: 'swift', kt: 'kotlin',
-  };
-  return ext ? map[ext] : undefined;
-}
-
-const CodeSnippetPreview: React.FC<{
-  anchorEl: HTMLElement | null;
-  contents: string;
-  filepath: string;
-  line: number;
-  lineEnd?: number;
-  onMouseEnter?: () => void;
-  onMouseLeave?: () => void;
-}> = ({ anchorEl, contents, filepath, line, lineEnd, onMouseEnter, onMouseLeave }) => {
-  const allLines = contents.split('\n');
-  const start = Math.max(0, line - 1);
-  const end = Math.min(allLines.length, (lineEnd ?? line));
-  const snippet = allLines.slice(start, end).join('\n');
-
-  const fenceTheme = useFenceTheme();
-  // Bumped once the grammar is attached, to re-run the memo below with the
-  // highlighter warm. Until then the snippet renders as plain text — no
-  // auto-detection, and an unknown extension simply stays plain.
-  const [highlighterGeneration, setHighlighterGeneration] = useState(0);
-  const lang = extToLanguage(filepath);
-
-  useEffect(() => {
-    if (!lang) return;
-    let cancelled = false;
-    void ensureHighlight(lang, fenceTheme).then((ok) => {
-      if (ok && !cancelled) setHighlighterGeneration((n) => n + 1);
-    });
-    return () => { cancelled = true; };
-  }, [lang, fenceTheme]);
-
-  const highlightedLines = useMemo(() => {
-    // Highlight the snippet as one unit so multi-line constructs (block
-    // comments, template literals) tokenise correctly, then split back into
-    // rows: the highlighter joins lines with "\n" and never emits one inside a
-    // span, so the split is exact.
-    const html = lang ? highlightToHtml(snippet, lang, fenceTheme) : null;
-    if (html !== null) return html.split('\n');
-    return snippet.split('\n').map(line =>
-      line.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;'));
-    // highlighterGeneration is the "grammar just became available" signal.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [snippet, lang, fenceTheme, highlighterGeneration]);
-
-  if (!anchorEl) return null;
-
-  const rect = anchorEl.getBoundingClientRect();
-  const spaceBelow = window.innerHeight - rect.bottom;
-  const showAbove = spaceBelow < 200 && rect.top > spaceBelow;
-  const top = showAbove ? undefined : rect.bottom + 4;
-  const bottom = showAbove ? window.innerHeight - rect.top + 4 : undefined;
-  const left = Math.max(8, Math.min(rect.left, window.innerWidth - 520));
-
-  return createPortal(
-    <div
-      className="fixed z-[9999] rounded-lg border border-border bg-card shadow-xl flex flex-col"
-      style={{ top, bottom, left, maxWidth: 'min(600px, 90vw)', maxHeight: '300px' }}
-      onMouseEnter={onMouseEnter}
-      onMouseLeave={onMouseLeave}
-    >
-      <div className="px-3 py-1.5 border-b border-border/50 text-[10px] text-muted-foreground font-mono flex items-center justify-between gap-4 flex-shrink-0">
-        <span>{filepath.split('/').pop()}</span>
-        <span className="opacity-60">{lineEnd && lineEnd !== line ? `lines ${line}–${lineEnd}` : `line ${line}`}</span>
-      </div>
-      <div className="code-snippet-preview overflow-auto text-[12px] leading-5 min-h-0" style={{ padding: 0, background: 'var(--code-bg, #1e293b)' }}>
-        <table className="border-collapse w-full">
-          <tbody>
-            {snippet.split('\n').map((_, i) => (
-              <tr key={start + i} className="hover:bg-white/5">
-                <td className="select-none text-muted-foreground/40 text-right pr-3 pl-3 py-0 align-top font-mono w-8 whitespace-nowrap" style={{ userSelect: 'none' }}>{start + i + 1}</td>
-                <td
-                  className="font-mono pr-3 py-0 whitespace-pre"
-                  dangerouslySetInnerHTML={{ __html: highlightedLines[i] ?? '' }}
-                />
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
-    </div>,
-    document.body,
-  );
-};
-
 const CodeFileLink: React.FC<{
   candidate: string;
   display: string;
@@ -181,57 +85,16 @@ const CodeFileLink: React.FC<{
   const validation = useCodePathValidation();
   const gate = gateCodePath(candidate, validation);
   const [pickerOpen, setPickerOpen] = useState(false);
-  const [hoverPreview, setHoverPreview] = useState<{ contents: string; filepath: string } | null>(null);
-  const hoverPreviewRef = useRef(hoverPreview);
-  hoverPreviewRef.current = hoverPreview;
-  const anchorRef = useRef<HTMLElement | null>(null);
-  const showTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const hideTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const parsed = parseCodePath(candidate);
   const hasLineRef = parsed.line != null;
-
-  const cancelHide = useCallback(() => {
-    if (hideTimerRef.current) { clearTimeout(hideTimerRef.current); hideTimerRef.current = null; }
-  }, []);
-
-  const scheduleHide = useCallback(() => {
-    cancelHide();
-    hideTimerRef.current = setTimeout(() => {
-      setHoverPreview(null);
-    }, 200);
-  }, [cancelHide]);
-
-  const handleMouseEnter = useCallback(() => {
-    if (!hasLineRef || gate.render === 'plain') return;
-    cancelHide();
-    if (hoverPreviewRef.current) return;
-    showTimerRef.current = setTimeout(async () => {
-      try {
-        const data = await docPreviewFetcher(candidate, baseDir);
-        if (data?.contents) setHoverPreview({ contents: data.contents, filepath: data.filepath ?? candidate });
-      } catch {}
-    }, 150);
-  }, [candidate, hasLineRef, gate.render, cancelHide, baseDir]);
-
-  const handleMouseLeave = useCallback(() => {
-    if (showTimerRef.current) { clearTimeout(showTimerRef.current); showTimerRef.current = null; }
-    scheduleHide();
-  }, [scheduleHide]);
-
-  const handlePreviewEnter = useCallback(() => {
-    cancelHide();
-  }, [cancelHide]);
-
-  const handlePreviewLeave = useCallback(() => {
-    scheduleHide();
-  }, [scheduleHide]);
-
-  useEffect(() => {
-    return () => {
-      if (showTimerRef.current) clearTimeout(showTimerRef.current);
-      if (hideTimerRef.current) clearTimeout(hideTimerRef.current);
-    };
-  }, []);
+  const hover = useHoverPreview<{ contents: string; filepath: string }>(async () => {
+    const data = await docPreviewFetcher(candidate, baseDir);
+    return data?.contents ? { contents: data.contents, filepath: data.filepath ?? candidate } : null;
+  }, hasLineRef && gate.render !== 'plain');
+  const hoverPreview = hover.preview;
+  const anchorRef = hover.anchorRef;
+  const handleMouseEnter = hover.onEnter;
+  const handleMouseLeave = hover.onLeave;
 
   if (gate.render === 'plain') {
     return (
@@ -280,8 +143,7 @@ const CodeFileLink: React.FC<{
           filepath={hoverPreview.filepath}
           line={parsed.line!}
           lineEnd={parsed.lineEnd}
-          onMouseEnter={handlePreviewEnter}
-          onMouseLeave={handlePreviewLeave}
+          {...hover.previewHandlers}
         />
       )}
       {pickerOpen && isAmbiguous && (
@@ -350,6 +212,9 @@ function canRenderSpacedDollarMath(tex: string): boolean {
   const trimmed = normalizeMathTex(tex);
   if (!trimmed) return false;
   if (!/^\s|\s$/.test(tex)) return true;
+  // Padding must be symmetric (`$ y $`). In `$write-better on the copy, and $`
+  // the closing `$` is really the opener of the next `$skill` token.
+  if (/^\s/.test(tex) !== /\s$/.test(tex)) return false;
   return (
     /\\[a-zA-Z]+/.test(trimmed) ||
     /[=^_{}+\-*/<>|]/.test(trimmed) ||