@plannotator/ui 0.53.1 → 0.55.0

package/components/InboxAnnouncementDialog.tsx

@@ -0,0 +1,202 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { ArrowUpRight, Play } from 'lucide-react';
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from './ui/dialog';
+
+/**
+ * One-time announcement for the Plannotator Inbox, on plan review, annotate
+ * and code review. Nearly full screen: the Inbox film from plannotator.ai/inbox
+ * fills the top, under it one title, one sentence, "Close" and one link to the
+ * Inbox page.
+ *
+ * Built on the shared dialog (`./ui/dialog`, Base UI): modal, focus trapped,
+ * focus restored on close, the backdrop and Escape close it. Like the other
+ * announcements it swallows Mod+Enter on the capture phase, so a keystroke
+ * aimed at it cannot approve a plan or post a review behind it.
+ *
+ * The film is the marketing page's own file (`apps/marketing/public/assets/
+ * inbox-film.mp4`, 1920x1080, ~14 MB, voice-led), served from
+ * plannotator.ai/assets like the other announcements' footage. It never
+ * autoplays and is `preload="none"`: opening the dialog fetches only the poster
+ * (~120 KB), and the film downloads when the reader presses play. Until then
+ * the frame is the poster with one play button, as on the Inbox page; after
+ * that the native controls take over (sound, seeking, full screen). If the
+ * film cannot load, the frame says so and the rest of the dialog is unchanged.
+ */
+
+/** The Inbox page on plannotator.ai. */
+export const INBOX_PAGE_URL = 'https://plannotator.ai/inbox';
+
+/** Where the marketing deploy publishes `apps/marketing/public/assets/`. */
+const MEDIA_BASE_URL = 'https://plannotator.ai/assets';
+
+export const INBOX_FILM = {
+  mp4: `${MEDIA_BASE_URL}/inbox-film.mp4`,
+  poster: `${MEDIA_BASE_URL}/inbox-film-poster.jpg`,
+} as const;
+
+/** The film is 1920x1080. */
+const FILM_ASPECT = 16 / 9;
+
+/**
+ * The panel's width also follows the viewport height, so on a short window the
+ * film shrinks until film and footer fit instead of scrolling the film away.
+ * 2rem is the overlay's padding, 10rem the footer on a wide panel.
+ */
+const PANEL_WIDTH =
+  `min(1200px, 100%, calc((var(--pn-viewport-height, 100dvh) - 2rem - 10rem) * ${FILM_ASPECT}))`;
+
+interface InboxAnnouncementDialogProps {
+  readonly isOpen: boolean;
+  /**
+   * Marks the announcement seen and closes it. Wired to Close, Escape, the
+   * backdrop and the link to the Inbox page.
+   */
+  readonly onDismiss: () => void;
+}
+
+function Film() {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [started, setStarted] = useState(false);
+  const [failed, setFailed] = useState(false);
+
+  const play = () => {
+    setStarted(true);
+    // A rejected play() (autoplay policy, no media) leaves the native
+    // controls up, which offer play again.
+    void videoRef.current?.play()?.catch(() => {});
+  };
+
+  return (
+    <div className="relative w-full shrink-0 overflow-hidden border-b border-border bg-muted" style={{ aspectRatio: String(FILM_ASPECT) }}>
+      <video
+        ref={videoRef}
+        data-inbox-film
+        poster={INBOX_FILM.poster}
+        controls={started}
+        playsInline
+        preload="none"
+        aria-label="The Plannotator Inbox film"
+        // A source that cannot be fetched errors on <source>; a file that was
+        // fetched but cannot be decoded errors on the element itself.
+        onError={() => setFailed(true)}
+        className="absolute inset-0 h-full w-full bg-muted object-contain"
+      >
+        <source src={INBOX_FILM.mp4} type="video/mp4" onError={() => setFailed(true)} />
+      </video>
+
+      {failed ? (
+        <p
+          data-inbox-film-unavailable
+          className="absolute inset-0 grid place-items-center bg-background/75 px-6 text-center text-sm text-muted-foreground backdrop-blur-sm"
+        >
+          The film could not load. It is also on the Inbox page.
+        </p>
+      ) : !started ? (
+        <button
+          type="button"
+          onClick={play}
+          aria-label="Play the Inbox film"
+          data-inbox-film-play
+          className="group absolute inset-0 grid place-items-center outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary"
+        >
+          <span className="grid size-16 place-items-center rounded-full border border-border/60 bg-background/80 text-foreground shadow-lg backdrop-blur-sm transition-transform motion-reduce:transition-none group-hover:scale-105 sm:size-20">
+            <Play className="ml-1 size-6 fill-current sm:size-7" aria-hidden="true" />
+          </span>
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export function InboxAnnouncementDialog({ isOpen, onDismiss }: InboxAnnouncementDialogProps) {
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const onDismissRef = useRef(onDismiss);
+
+  useEffect(() => {
+    onDismissRef.current = onDismiss;
+  }, [onDismiss]);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // Escape is handled here rather than by the dialog so that no window
+      // handler of the App behind it (close a panel, leave a mode) sees it.
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        event.stopPropagation();
+        onDismissRef.current();
+        return;
+      }
+      // Both apps submit their decision on Mod+Enter from a window-level
+      // handler; swallow it on the capture phase.
+      if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) {
+        event.preventDefault();
+        event.stopPropagation();
+      }
+    };
+    document.addEventListener('keydown', handleKeyDown, true);
+    return () => document.removeEventListener('keydown', handleKeyDown, true);
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  return (
+    <Dialog
+      open
+      onOpenChange={(open) => {
+        if (!open) onDismissRef.current();
+      }}
+    >
+      <DialogContent
+        hideClose
+        initialFocus={closeRef}
+        data-inbox-announcement-dialog
+        backdropClassName="bg-background/90 backdrop-blur-sm"
+        style={{ width: PANEL_WIDTH }}
+        className="max-h-full max-w-none rounded-xl bg-card text-card-foreground shadow-2xl motion-reduce:transition-none"
+      >
+        <Film />
+
+        <div className="flex min-h-0 flex-col gap-5 overflow-y-auto px-5 py-5 sm:flex-row sm:items-end sm:justify-between sm:gap-8 sm:px-7 sm:py-6">
+          <div className="min-w-0">
+            <DialogTitle className="text-balance text-xl font-semibold tracking-tight sm:text-2xl">
+              The Plannotator Inbox
+            </DialogTitle>
+            <DialogDescription className="mt-1.5 max-w-xl text-pretty leading-relaxed">
+              Questions, blockers and reviews from your agents arrive in one inbox while they work,
+              and your answers go back to them.
+            </DialogDescription>
+          </div>
+
+          <div className="flex shrink-0 flex-col-reverse gap-2 sm:flex-row sm:items-center">
+            <button
+              ref={closeRef}
+              type="button"
+              data-inbox-announcement-close
+              onClick={() => onDismissRef.current()}
+              className="min-h-10 rounded-lg border border-border px-4 text-sm font-medium text-foreground outline-none transition-colors motion-reduce:transition-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-card"
+            >
+              Close
+            </button>
+            <a
+              href={INBOX_PAGE_URL}
+              target="_blank"
+              rel="noopener noreferrer"
+              data-inbox-announcement-learn-more
+              // Following the link counts as seeing the announcement. Closed on
+              // the next task: a link removed from the page during its own click
+              // is not followed.
+              onClick={() => {
+                setTimeout(() => onDismissRef.current(), 0);
+              }}
+              className="inline-flex min-h-10 items-center justify-center gap-1.5 rounded-lg bg-primary px-5 text-sm font-medium text-primary-foreground outline-none transition-opacity motion-reduce:transition-none hover:opacity-90 focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-card"
+            >
+              Learn about the Inbox
+              <ArrowUpRight className="size-4" aria-hidden="true" />
+            </a>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}

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 { forgeRefLinks } from "@plannotator/core/forge-refs";
-import { ensureHighlight, highlightToHtml } from "../utils/codeHighlight";
-import { useFenceTheme } from "../hooks/useFenceTheme";
+import { findCrossRepoRef, forgeRefLinks, matchCrossRepoRef, type CrossRepoRef } from "@plannotator/core/forge-refs";
+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) ||
@@ -380,6 +245,34 @@ export function trimUrlTail(url: string): string {
   return url;
 }
 
+// Index of the first bare `http(s)://` URL that starts after index 0 and
+// before `end` at a word boundary AND runs past `end`, or -1. Only such a
+// URL needs the chunk split: one that ends inside the chunk is linked by
+// emitPlainTextWithBareUrls in the same pass, exactly as before, so a
+// paragraph of many URLs stays one pass instead of a loop turn (and a
+// rescan of the rest of the text) per URL. Index 0 is left to the caller's
+// own bare-URL check, which already ran for it.
+const BARE_URL_SCHEME = /https?:\/\//g;
+const BARE_URL_AT = /https?:\/\/[^\s<>"']+/y;
+function bareUrlRunningPast(text: string, end: number): number {
+  // Only a scheme that starts before `end` counts, so read no further than
+  // `end` plus the longest scheme ("https://" less its first character).
+  const window = text.slice(0, end + 7);
+  BARE_URL_SCHEME.lastIndex = 1;
+  let m: RegExpExecArray | null;
+  while ((m = BARE_URL_SCHEME.exec(window)) !== null && m.index < end) {
+    if (/\w/.test(window[m.index - 1])) continue;
+    BARE_URL_AT.lastIndex = m.index;
+    const url = BARE_URL_AT.exec(text);
+    if (!url) continue;
+    const urlEnd = m.index + trimUrlTail(url[0]).length;
+    if (urlEnd > end) return m.index;
+    // The URL ends inside the chunk; look for the next one after it.
+    BARE_URL_SCHEME.lastIndex = Math.max(urlEnd, m.index + 1);
+  }
+  return -1;
+}
+
 // Scan a plain-text chunk for bare https?:// URLs and bare code file paths
 // at word boundaries, emitting them as interactive nodes. Surrounding text
 // passes through transformPlainText for emoji shortcodes + smart punctuation.
@@ -474,35 +367,73 @@ function emitPlainTextWithBareUrls(
   }
 }
 
-/** An image a host resolver chose; a load failure shows the placeholder. */
+/**
+ * An image a host resolver chose; a load failure shows the placeholder.
+ *
+ * The `<img>` element itself never leaves the document: on failure the
+ * placeholder is inserted BEFORE it (React's reference node is then the
+ * `<img>`, which it owns) and the `<img>` is hidden. Replacing the `<img>`
+ * would make React insert before the node that follows it, and when that is
+ * a text node the annotation highlighter already moved into a `<mark>` (a
+ * restored comment starting right after the image), `insertBefore` throws
+ * and the whole document unmounts. A loaded image's DOM is unchanged.
+ */
 const HostResolvedImage: React.FC<{
   src: string;
   alt: string;
+  /** The src as written in the markdown (`data-image-src`, read by the image viewer's region comments). */
+  writtenSrc?: string;
   onImageClick?: (src: string, alt: string) => void;
-}> = ({ src, alt, onImageClick }) => {
+}> = ({ src, alt, writtenSrc, onImageClick }) => {
   const [failedSrc, setFailedSrc] = useState<string | null>(null);
-  if (failedSrc === src) {
-    return (
-      <span className={UNAVAILABLE_IMAGE_CLASS} title="Image could not be loaded" data-image-unavailable="">
-        {alt || 'Image'}
-      </span>
-    );
-  }
+  const failed = failedSrc === src;
   return (
-    <img
-      src={src}
-      alt={alt}
-      className="max-w-full rounded my-2 cursor-zoom-in"
-      loading="lazy"
-      onError={() => setFailedSrc(src)}
-      onClick={(e) => {
-        e.stopPropagation();
-        onImageClick?.(src, alt);
-      }}
-    />
+    <>
+      {failed && (
+        <span key="unavailable" className={`${UNAVAILABLE_IMAGE_CLASS} annotation-exclude`} title="Image could not be loaded" data-image-unavailable="">
+          {alt || 'Image'}
+        </span>
+      )}
+      <img
+        key="image"
+        src={src}
+        alt={failed ? '' : alt}
+        data-image-src={writtenSrc}
+        data-image-failed={failed ? '' : undefined}
+        hidden={failed || undefined}
+        aria-hidden={failed || undefined}
+        className={failed ? undefined : 'max-w-full rounded my-2 cursor-zoom-in'}
+        loading="lazy"
+        onError={() => setFailedSrc(src)}
+        onClick={(e) => {
+          e.stopPropagation();
+          if (!failed) onImageClick?.(src, alt);
+        }}
+      />
+    </>
   );
 };
 
+/**
+ * Whether a digit-only 6/8-digit `#123456` is an issue ref (when a ref link can
+ * be built) rather than a hex swatch. Off by default: every host renders such
+ * values as colours. The Plannotator Inbox turns it on through
+ * `configurePlannotatorUI({ digitHexIssueRefs: true })` (#1932).
+ */
+let digitHexIssueRefs = false;
+
+export function setDigitHexIssueRefs(on: boolean): void {
+  digitHexIssueRefs = on;
+}
+
+export function resetDigitHexIssueRefs(): void {
+  digitHexIssueRefs = false;
+}
+
+export function getDigitHexIssueRefs(): boolean {
+  return digitHexIssueRefs;
+}
+
 /**
  * Scanner that walks a text string and emits React nodes for inline markdown:
  * emphasis (**bold**, *italic*, _italic_, ***both***), `code`, ~~strikethrough~~,
@@ -543,6 +474,13 @@ export const InlineMarkdown: React.FC<{
   const resolveLocalLink = useLocalLinkResolver();
   const resolveImage = useImageResolver();
   const refLinks = forgeRefLinks({ display: githubRepo, host: repoHost });
+  // Cross-repo `owner/repo#123` refs: only for a caller that names its
+  // project's repo (it knows the forge); otherwise they stay plain text, never
+  // a guessed github.com link. With a code-file handler, an `owner/repo` that
+  // is a code path not known to be missing stays the file (`src/app.js#12`).
+  const crossRepoProject = githubRepo ? { host: repoHost } : null;
+  const crossRepoAccept = (ref: CrossRepoRef): boolean =>
+    !(onOpenCodeFile && isCodeFilePathStrict(ref.path) && gateCodePath(ref.path, validation ?? null).render !== 'plain');
   const parts: React.ReactNode[] = [];
   let remaining = text;
   let key = 0;
@@ -650,6 +588,32 @@ export const InlineMarkdown: React.FC<{
       }
     }
 
+    // Cross-repo ref: owner/repo#123, shown as written, linked on the
+    // project's forge host. Read before file-path detection, so
+    // `vercel/next.js#1` is a ref, not a path (unless the viewer knows that
+    // file, see crossRepoAccept); `docs/guide.md#2` stays a path.
+    const crossRepoRef = crossRepoProject ? matchCrossRepoRef(remaining, previousChar, crossRepoProject) : null;
+    if (crossRepoRef && crossRepoAccept(crossRepoRef)) {
+      parts.push(
+        crossRepoRef.href ? (
+          <a
+            key={key++}
+            href={crossRepoRef.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="text-primary font-medium hover:underline"
+          >
+            {crossRepoRef.label}
+          </a>
+        ) : (
+          crossRepoRef.label
+        ),
+      );
+      remaining = remaining.slice(crossRepoRef.label.length);
+      previousChar = crossRepoRef.label[crossRepoRef.label.length - 1];
+      continue;
+    }
+
     // Autolinks: <https://url> or <email@domain.com>
     match = remaining.match(/^<(https?:\/\/[^>]+)>/);
     if (match) {
@@ -846,9 +810,19 @@ export const InlineMarkdown: React.FC<{
     }
 
     // Hex color swatch — 3/4-digit forms need an a-f letter to avoid matching issue refs like #123.
+    // 6/8-digit forms with no letter (#186379) are ambiguous. By default they
+    // stay swatches (greys like #333333 are common in docs; six-digit issues are
+    // rare). A host that opts in with `configurePlannotatorUI({ digitHexIssueRefs:
+    // true })` (the Plannotator Inbox, #1932) gets an issue ref instead, but only
+    // when a ref link can actually be built (`refLinks`: a repo path on a known
+    // forge) and the ref branch below would take it: a word boundary and no
+    // leading zero (issue numbers never start with 0, so #000000 stays a colour).
     match = remaining.match(
       /^(#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|(?=[0-9a-fA-F]*[a-fA-F])[0-9a-fA-F]{4}|(?=[0-9a-fA-F]*[a-fA-F])[0-9a-fA-F]{3}))(?![0-9a-fA-F\w])/,
     );
+    if (match && digitHexIssueRefs && refLinks && /^#[1-9]\d*$/.test(match[1]) && !/\w/.test(previousChar)) {
+      match = null;
+    }
     if (match) {
       const hex = match[1];
       parts.push(
@@ -872,8 +846,8 @@ export const InlineMarkdown: React.FC<{
     }
 
     // Issue / PR reference: #123 — only at word boundary, digits only.
-    // Hex-swatch branch above already consumed #fff / #123abc etc., so a bare
-    // #\d+ here is safe to treat as an issue ref.
+    // Hex-swatch branch above already consumed #fff / #123abc etc. (and digit-only
+    // #123456 / #12345678 unless the host opted in), so a bare #\d+ here is an issue ref.
     if (!/\w/.test(previousChar)) {
       match = remaining.match(/^#(\d+)(?!\w)/);
       if (match) {
@@ -1027,12 +1001,13 @@ export const InlineMarkdown: React.FC<{
         resolveImage ? (
           // With a host resolver, an image that fails to load becomes the
           // same placeholder instead of a broken-image icon.
-          <HostResolvedImage key={key++} src={imgSrc} alt={alt} onImageClick={onImageClick} />
+          <HostResolvedImage key={key++} src={imgSrc} alt={alt} writtenSrc={src} onImageClick={onImageClick} />
         ) : (
           <img
             key={key++}
             src={imgSrc}
             alt={alt}
+            data-image-src={src}
             className="max-w-full rounded my-2 cursor-zoom-in"
             loading="lazy"
             onClick={(e) => {
@@ -1272,6 +1247,24 @@ export const InlineMarkdown: React.FC<{
     // multi-char patterns like emoji shortcodes. Bare URLs are instead
     // detected inline via emitPlainTextWithBareUrls() below.
     const nextSpecial = remaining.slice(1).search(/[\*_`\[!~\\<#@$]/);
+    // A bare URL that starts inside this plain-text chunk and runs past its
+    // end would be cut there, and `_`, `~`, `#`, `@`, `$` and `!` all end a
+    // chunk (`…/w/ws_01…` rendered a link to `…/w/ws`). Stop the chunk where
+    // that URL starts instead, so the bare-URL branch above takes it whole.
+    const chunkEnd = nextSpecial === -1 ? remaining.length : nextSpecial + 1;
+    // Same for an owner/repo#123 ref: `#` (and `_` in a name) ends a chunk, so
+    // stop before the ref and let the cross-repo branch above take it whole.
+    // A ref inside a URL never splits it: the URL starts first and wins.
+    const urlAt = bareUrlRunningPast(remaining, chunkEnd);
+    const refAt = crossRepoProject ? findCrossRepoRef(remaining, urlAt === -1 ? chunkEnd : urlAt, crossRepoProject, crossRepoAccept) : -1;
+    const splitAt = refAt !== -1 ? refAt : urlAt;
+    if (splitAt !== -1) {
+      const before = remaining.slice(0, splitAt);
+      emitPlainTextWithBareUrls(before, previousChar, parts, () => key++, onOpenCodeFile, validation, imageBaseDir);
+      previousChar = before[before.length - 1] || previousChar;
+      remaining = remaining.slice(splitAt);
+      continue;
+    }
     const plainText = nextSpecial === -1 ? remaining : remaining.slice(0, nextSpecial + 1);
     emitPlainTextWithBareUrls(plainText, previousChar, parts, () => key++, onOpenCodeFile, validation, imageBaseDir);
     previousChar = plainText[plainText.length - 1] || previousChar;