@plannotator/ui 0.52.1 → 0.53.1

package/components/html-viewer/useHtmlAnnotation.ts

@@ -1,5 +1,5 @@
-import { useState, useEffect, useCallback, useRef, type RefObject } from "react";
-import { AnnotationType, type Annotation, type EditorMode, type HtmlAnnotationTarget, type HtmlElementAnchor, type HtmlElementContext, type ImageAttachment } from "../../types";
+import { useState, useEffect, useLayoutEffect, useCallback, useRef, type RefObject } from "react";
+import { AnnotationType, type Annotation, type EditorMode, type HostDraft, type HtmlAnnotationTarget, type HtmlElementAnchor, type HtmlElementContext, type ImageAttachment } from "../../types";
 import { THUMBS_UP_LABEL, type QuickLabel } from "../../utils/quickLabels";
 import { getIdentity } from "../../utils/identity";
 import type {
@@ -199,6 +199,10 @@ export interface UseHtmlAnnotationOptions {
   /** scrollIntoView behavior for scroll-to (selecting an annotation).
    *  Absent: smooth, as before; pass 'auto' to honor reduced motion. */
   scrollBehavior?: 'smooth' | 'auto';
+  /** The composer handed to the host (see `HostDraft` and HtmlViewer's
+   *  `onHostDraft`): a selection or a pin reports a draft instead of opening
+   *  the toolbar or the composer. Absent: unchanged. */
+  onHostDraft?: (draft: HostDraft | null) => void;
 }
 
 /** Clamp a host cap into the package's bound; anything unusable is the default. */
@@ -465,6 +469,7 @@ export function useHtmlAnnotation({
   onUnanchoredChange,
   maxAdditionalTargets,
   scrollBehavior,
+  onHostDraft,
 }: UseHtmlAnnotationOptions): Omit<
   UseAnnotationHighlighterReturn,
   "highlighterRef" | "highlightRange" | "highlightMathElement"
@@ -536,6 +541,10 @@ export function useHtmlAnnotation({
   onPageChangeRef.current = onPageChange;
   const onLinkClickRef = useRef(onLinkClick);
   onLinkClickRef.current = onLinkClick;
+  const onHostDraftRef = useRef(onHostDraft);
+  onHostDraftRef.current = onHostDraft;
+  // The id of the draft the host holds, so a stale cancel cannot drop a newer one.
+  const hostDraftIdRef = useRef<string | null>(null);
   // The effective cap and whether the host set one: only an explicit cap
   // rides on arm-multi-select, so an unconfigured viewer posts today's message.
   const maxTargetsRef = useRef(resolveMaxAdditionalTargets(maxAdditionalTargets));
@@ -628,7 +637,9 @@ export function useHtmlAnnotation({
     [iframeRef, getOrCreateAnchor],
   );
 
-  useEffect(() => {
+  // A layout effect, like HtmlViewer's own listener: listening from the
+  // commit that inserts the iframe, before its document can post anything.
+  useLayoutEffect(() => {
     function handler(e: MessageEvent<unknown>) {
       if (e.source !== iframeRef.current?.contentWindow) return;
       // Live sessions verify origin + session token BEFORE parsing. The
@@ -659,6 +670,39 @@ export function useHtmlAnnotation({
         pendingAnchorRef.current = message.anchor ?? null;
         pendingContextRef.current = message.context ?? null;
         setDraftTargets([]); // a new selection always starts a fresh draft
+        const reportDraft = onHostDraftRef.current;
+        if (reportDraft) {
+          // The host composes: HTML is comment-only, so every selection or
+          // pin is a comment draft, and nothing of ours opens.
+          const id = nextHtmlAnnId();
+          hostDraftIdRef.current = id;
+          reportDraft({
+            annotation: {
+              id,
+              blockId: "",
+              startOffset: 0,
+              endOffset: 0,
+              type: AnnotationType.COMMENT,
+              text: "",
+              originalText: message.text,
+              author: getIdentity(),
+              createdA: Date.now(),
+              htmlAnchor: message.anchor,
+              elementContext: message.context,
+            },
+            intent: message.pinpoint ? "compose" : "selection",
+            label: message.targetLabel,
+            cancel: () => {
+              if (hostDraftIdRef.current !== id) return;
+              hostDraftIdRef.current = null;
+              post({ type: `${PREFIX}cancel-selection` });
+              pendingTextRef.current = "";
+              pendingAnchorRef.current = null;
+              pendingContextRef.current = null;
+            },
+          });
+          return;
+        }
         const anchor = positionAnchor(message.rect);
         if (!anchor) return;
 
@@ -754,6 +798,10 @@ export function useHtmlAnnotation({
       }
 
       if (type === `${PREFIX}selection-clear`) {
+        if (onHostDraftRef.current && hostDraftIdRef.current) {
+          hostDraftIdRef.current = null;
+          onHostDraftRef.current(null);
+        }
         setToolbarState(null);
         // Keep the captured text alive while a comment/quick-label is open: the user
         // is composing, and the selection collapsing or scrolling out of view must

package/components/icons/AgentIcons.tsx

@@ -19,14 +19,16 @@ export function CodexIcon({ className }: { className?: string }) {
   return <img src={CODEX_DATA_URI} className={className} alt="" aria-hidden="true" draggable={false} />;
 }
 
-// Pi brand mark — path data from packages/ui/components/ProviderIcons.tsx's
-// PiIcon (itself extracted from apps/marketing/public/assets/icon-pi.svg).
-// currentColor so it adapts to theme, like OpenCodeIcon below.
+// Pi brand mark: the pi.dev logo (https://pi.dev/logo.svg), the same paths as
+// ProviderIcons.tsx's PiIcon and apps/marketing/public/assets/icon-pi.svg. Its
+// own three colours in every theme; the viewBox crops pi.dev's 800-unit canvas
+// to the mark plus an even margin so it sits level with the other marks.
 export function PiIcon({ className }: { className?: string }) {
   return (
-    <svg viewBox="0 0 800 800" className={className} xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
-      <path fill="currentColor" fillRule="evenodd" d="M165.29 165.29H517.36V400H400V517.36H282.65V634.72H165.29ZM282.65 282.65V400H400V282.65Z" />
-      <path fill="currentColor" d="M517.36 400H634.72V634.72H517.36Z" />
+    <svg viewBox="130 130 540 540" className={className} xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">
+      <path fill="#F09082" d="M165.29 165.29H517.36V400H400V282.65H165.29Z" />
+      <path fill="#4D9ABF" d="M165.29 282.65H282.65V400H400V517.36H282.65V634.72H165.29Z" />
+      <path fill="#F1BE58" d="M517.36 400H634.72V634.72H517.36Z" />
     </svg>
   );
 }
@@ -34,7 +36,7 @@ export function PiIcon({ className }: { className?: string }) {
 // GitHub Copilot brand mark — path from the official agent icon set
 // (welcome.developers.workers.dev/icons/agents/copilot); the dark/light
 // variants there differ only by fill, so one currentColor component covers
-// both themes, like PiIcon/OpenCodeIcon.
+// both themes, like OpenCodeIcon.
 export function CopilotIcon({ className }: { className?: string }) {
   return (
     <svg viewBox="0 0 256 208" className={className} xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false">

package/components/plan-diff/PlanCleanDiffView.tsx

@@ -6,17 +6,20 @@
  * hover in Viewer) — no text selection, no web-highlighter.
  */
 
-import React, { useEffect, useRef, useState, useCallback } from "react";
+import React, { useEffect, useRef, useState, useCallback, createContext, useContext, useMemo } from "react";
 import { parseMarkdownToBlocks, computeListIndices } from "../../utils/parser";
 import { applyHighlight, codeBlockClassName, codeBlockKeepsLayout } from "../../utils/codeHighlight";
 import { useFenceTheme } from "../../hooks/useFenceTheme";
 import { ListItemBody } from "../ListItemBody";
+import { BlockquoteBlock, BLOCKQUOTE_CLASS_NAME } from "../blocks/BlockquoteBlock";
 import type { Block, Annotation, EditorMode, ImageAttachment } from "../../types";
 import { AnnotationType } from "../../types";
-import type {
-  PlanDiffBlock,
-  InlineDiffToken,
-  InlineDiffWrap,
+import {
+  foldUnchangedPlanDiff,
+  type PlanDiffBlock,
+  type PlanDiffFold,
+  type InlineDiffToken,
+  type InlineDiffWrap,
 } from "../../utils/planDiffEngine";
 import type { QuickLabel } from "../../utils/quickLabels";
 import { AnnotationToolbar } from "../AnnotationToolbar";
@@ -24,6 +27,22 @@ import { CommentPopover } from "../CommentPopover";
 import { FloatingQuickLabelPicker } from "../FloatingQuickLabelPicker";
 import { getIdentity } from "../../utils/identity";
 
+/**
+ * Which version a rendered chunk comes from: 'old' for a removed block and
+ * the old half of a modified block, 'new' for everything else.
+ */
+export type PlanDiffSide = "old" | "new";
+
+/** Host renderer for one parsed markdown block (see `renderBlock`). */
+export type PlanDiffBlockRenderer = (
+  block: Block,
+  orderedIndex: number | null,
+  side: PlanDiffSide,
+) => React.ReactNode;
+
+/** Provided only when a host passes `renderBlock`; absent, chunks render as always. */
+const RenderBlockContext = createContext<PlanDiffBlockRenderer | null>(null);
+
 interface PlanCleanDiffViewProps {
   blocks: PlanDiffBlock[];
   annotations?: Annotation[];
@@ -38,8 +57,33 @@ interface PlanCleanDiffViewProps {
    * "Classic" diff view exposed in the mode switcher.
    */
   wordLevel?: boolean;
+  /**
+   * Optional: render each parsed markdown block (headings, paragraphs, code,
+   * tables, …) with the host's renderer instead of the view's built-in
+   * simple one. Not used for inline word-level modified blocks. Absent, the
+   * view renders exactly as before.
+   */
+  renderBlock?: PlanDiffBlockRenderer;
+  /**
+   * Optional: a left gutter on every block naming its source lines
+   * ("11–12", "old 15–16"; a modified block shows both). Needs the line
+   * ranges `computePlanDiff` fills. Absent, no gutter.
+   */
+  lineGutter?: boolean;
+  /**
+   * Optional: fold long runs of unchanged sections behind a "N unchanged
+   * sections" row that expands in place (see `foldUnchangedPlanDiff`).
+   */
+  foldUnchanged?: boolean;
+  /**
+   * Optional: classes for unchanged blocks, replacing the default dimming
+   * (`opacity-60 hover:opacity-100 transition-opacity`).
+   */
+  unchangedClassName?: string;
 }
 
+const DEFAULT_UNCHANGED_CLASS = "opacity-60 hover:opacity-100 transition-opacity";
+
 export const PlanCleanDiffView: React.FC<PlanCleanDiffViewProps> = ({
   blocks,
   annotations = [],
@@ -48,6 +92,10 @@ export const PlanCleanDiffView: React.FC<PlanCleanDiffViewProps> = ({
   selectedAnnotationId = null,
   mode = "selection",
   wordLevel = true,
+  renderBlock,
+  lineGutter = false,
+  foldUnchanged = false,
+  unchangedClassName,
 }) => {
   const modeRef = useRef<EditorMode>(mode);
   const onAddAnnotationRef = useRef(onAddAnnotation);
@@ -285,22 +333,104 @@ export const PlanCleanDiffView: React.FC<PlanCleanDiffViewProps> = ({
   // Check if a block index has been annotated (for highlight ring)
   const isBlockAnnotated = (index: number) => annotatedBlockIds.has(`diff-block-${index}`);
 
+  // Fold state per fold key (expanded folds render their pieces in place).
+  const [expandedFolds, setExpandedFolds] = useState<ReadonlySet<string>>(() => new Set());
+  const toggleFold = useCallback((key: string) => {
+    setExpandedFolds((prev) => {
+      const next = new Set(prev);
+      if (next.has(key)) next.delete(key);
+      else next.add(key);
+      return next;
+    });
+  }, []);
+  const segments = useMemo(
+    () => (foldUnchanged ? foldUnchangedPlanDiff(blocks) : null),
+    [blocks, foldUnchanged],
+  );
+
+  const renderDiffBlock = (block: PlanDiffBlock, index: number, key: React.Key) => {
+    const rendered = (
+      <DiffBlockRenderer
+        key={lineGutter ? undefined : key}
+        block={block}
+        index={index}
+        hoveredIndex={hoveredBlock?.index ?? null}
+        hoveredDiffContext={hoveredBlock?.diffContext}
+        isBlockAnnotated={isBlockAnnotated}
+        wordLevel={wordLevel}
+        unchangedClassName={unchangedClassName}
+        onHover={onAddAnnotation ? (el, diffContext) => handleHover(el, block, index, diffContext) : undefined}
+        onLeave={onAddAnnotation ? handleLeave : undefined}
+        onClick={onAddAnnotation ? (el, diffContext) => handleBlockClick(block, index, el, diffContext) : undefined}
+      />
+    );
+    if (!lineGutter) return rendered;
+    return (
+      <GutterRow key={key} labels={blockGutterLabels(block)}>
+        {rendered}
+      </GutterRow>
+    );
+  };
+
+  const renderFold = (fold: PlanDiffFold, index: number) => {
+    const expanded = expandedFolds.has(fold.key);
+    const noun = fold.sectionCount === 1 ? "section" : "sections";
+    const row = expanded ? (
+      <button
+        type="button"
+        data-plan-diff-fold=""
+        aria-expanded
+        onClick={() => toggleFold(fold.key)}
+        className="annotation-exclude flex items-center gap-1.5 rounded-md px-2 py-1 text-xs text-muted-foreground hover:bg-muted/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50"
+      >
+        <FoldChevron expanded />
+        Hide {fold.sectionCount} unchanged {noun}
+      </button>
+    ) : (
+      <button
+        type="button"
+        data-plan-diff-fold=""
+        aria-expanded={false}
+        onClick={() => toggleFold(fold.key)}
+        className="annotation-exclude flex w-full min-w-0 items-center gap-2 rounded-md bg-muted/40 px-3 py-1.5 text-left text-xs text-muted-foreground hover:bg-muted/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50"
+      >
+        <FoldChevron expanded={false} />
+        <span className="flex-none">{fold.sectionCount} unchanged {noun}</span>
+        {fold.headings.length > 0 && (
+          <span className="min-w-0 truncate text-muted-foreground/70">
+            · {fold.headings.join(" · ")}
+          </span>
+        )}
+        <span className="ml-auto flex-none pl-2">Show</span>
+      </button>
+    );
+    return (
+      <React.Fragment key={fold.key}>
+        {lineGutter ? (
+          <GutterRow labels={expanded ? [] : [rangeLabel(fold.newStart, fold.newEnd) ?? ""]}>{row}</GutterRow>
+        ) : (
+          row
+        )}
+        {expanded && fold.pieces.map((piece, i) => renderDiffBlock(piece, index, `${fold.key}-${i}`))}
+      </React.Fragment>
+    );
+  };
+
+  const body = segments
+    ? segments.map((segment, i) =>
+        segment.kind === "fold"
+          ? renderFold(segment, i)
+          : renderDiffBlock(segment.block, segment.index, `seg-${i}`),
+      )
+    : blocks.map((block, index) => renderDiffBlock(block, index, index));
+
   return (
     <div className="space-y-1">
-      {blocks.map((block, index) => (
-        <DiffBlockRenderer
-          key={index}
-          block={block}
-          index={index}
-          hoveredIndex={hoveredBlock?.index ?? null}
-          hoveredDiffContext={hoveredBlock?.diffContext}
-          isBlockAnnotated={isBlockAnnotated}
-          wordLevel={wordLevel}
-          onHover={onAddAnnotation ? (el, diffContext) => handleHover(el, block, index, diffContext) : undefined}
-          onLeave={onAddAnnotation ? handleLeave : undefined}
-          onClick={onAddAnnotation ? (el, diffContext) => handleBlockClick(block, index, el, diffContext) : undefined}
-        />
-      ))}
+      {renderBlock ? (
+        <RenderBlockContext.Provider value={renderBlock}>{body}</RenderBlockContext.Provider>
+      ) : (
+        body
+      )}
 
       {/* Block hover toolbar (selection mode) */}
       {hoveredBlock && !commentPopover && !quickLabelPicker && (
@@ -349,6 +479,61 @@ export const PlanCleanDiffView: React.FC<PlanCleanDiffViewProps> = ({
   );
 };
 
+// --- Line gutter + fold row (optional seams) ---
+
+/** "11–12", or "14" for one line; null when the side has no lines. */
+function rangeLabel(start?: number, end?: number): string | null {
+  if (start === undefined) return null;
+  return end !== undefined && end !== start ? `${start}–${end}` : `${start}`;
+}
+
+/** The gutter lines for one rendered diff block. */
+function blockGutterLabels(block: PlanDiffBlock): string[] {
+  const newLabel = rangeLabel(block.newStart, block.newEnd);
+  const oldLabel = rangeLabel(block.oldStart, block.oldEnd);
+  switch (block.type) {
+    case "removed":
+      return oldLabel ? [`old ${oldLabel}`] : [];
+    case "modified":
+      return [newLabel, oldLabel ? `old ${oldLabel}` : null].filter((l): l is string => !!l);
+    default:
+      return newLabel ? [newLabel] : [];
+  }
+}
+
+/** A block beside its source-line gutter. The gutter is never selectable or part of a quote. */
+// Baseline alignment puts the label beside the first line of text, past a
+// heading's top margin.
+const GutterRow: React.FC<{ labels: string[]; children: React.ReactNode }> = ({ labels, children }) => (
+  <div className="flex items-baseline gap-3">
+    <div
+      data-plan-diff-gutter=""
+      aria-hidden="true"
+      className="annotation-exclude w-[4.5rem] flex-none select-none text-right font-mono text-[11px] leading-4 tabular-nums text-muted-foreground/70"
+    >
+      {labels.map((label, i) => (
+        <div key={i}>{label}</div>
+      ))}
+    </div>
+    <div className="min-w-0 flex-1">{children}</div>
+  </div>
+);
+
+const FoldChevron: React.FC<{ expanded: boolean }> = ({ expanded }) => (
+  <svg
+    aria-hidden="true"
+    className={`h-3 w-3 flex-none transition-transform ${expanded ? "rotate-90" : ""}`}
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth={2.5}
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    <path d="M9 6l6 6-6 6" />
+  </svg>
+);
+
 // --- DiffBlockRenderer with hover support ---
 
 interface DiffBlockRendererProps {
@@ -359,13 +544,15 @@ interface DiffBlockRendererProps {
   isBlockAnnotated: (index: number) => boolean;
   /** When false, force block-level fallback even if inlineTokens is populated. */
   wordLevel: boolean;
+  /** Replaces the default unchanged-block dimming classes when set. */
+  unchangedClassName?: string;
   onHover?: (element: HTMLElement, diffContext: Annotation['diffContext']) => void;
   onLeave?: () => void;
   onClick?: (element: HTMLElement, diffContext: Annotation['diffContext']) => void;
 }
 
 const DiffBlockRenderer: React.FC<DiffBlockRendererProps> = ({
-  block, index, hoveredIndex, hoveredDiffContext, isBlockAnnotated, wordLevel, onHover, onLeave, onClick,
+  block, index, hoveredIndex, hoveredDiffContext, isBlockAnnotated, wordLevel, unchangedClassName, onHover, onLeave, onClick,
 }) => {
   const hoverProps = (diffContext: Annotation['diffContext']) => onHover ? {
     onMouseEnter: (e: React.MouseEvent<HTMLElement>) => onHover(e.currentTarget, diffContext),
@@ -386,7 +573,7 @@ const DiffBlockRenderer: React.FC<DiffBlockRendererProps> = ({
   switch (block.type) {
     case "unchanged":
       return (
-        <div className="plan-diff-unchanged opacity-60 hover:opacity-100 transition-opacity">
+        <div className={`plan-diff-unchanged ${unchangedClassName ?? DEFAULT_UNCHANGED_CLASS}`}>
           <MarkdownChunk content={block.content} />
         </div>
       );
@@ -409,7 +596,7 @@ const DiffBlockRenderer: React.FC<DiffBlockRendererProps> = ({
           data-diff-block-index={index}
           {...hoverProps('removed')}
         >
-          <MarkdownChunk content={block.content} />
+          <MarkdownChunk content={block.content} side="old" />
         </div>
       );
 
@@ -435,7 +622,7 @@ const DiffBlockRenderer: React.FC<DiffBlockRendererProps> = ({
             className={`plan-diff-removed line-through decoration-destructive/30 opacity-60 transition-shadow ${ringClass('removed')}`}
             {...hoverProps('removed')}
           >
-            <MarkdownChunk content={block.oldContent!} />
+            <MarkdownChunk content={block.oldContent!} side="old" />
           </div>
           <div
             className={`plan-diff-added transition-shadow ${ringClass('modified')}`}
@@ -566,7 +753,8 @@ const InlineModifiedBlock: React.FC<InlineModifiedBlockProps> = ({
 
 // --- Rendering components (unchanged from main) ---
 
-const MarkdownChunk: React.FC<{ content: string }> = ({ content }) => {
+const MarkdownChunk: React.FC<{ content: string; side?: PlanDiffSide }> = ({ content, side = "new" }) => {
+  const renderBlock = useContext(RenderBlockContext);
   const blocks = React.useMemo(
     () => parseMarkdownToBlocks(content),
     [content]
@@ -580,6 +768,16 @@ const MarkdownChunk: React.FC<{ content: string }> = ({ content }) => {
     [blocks]
   );
 
+  if (renderBlock) {
+    return (
+      <>
+        {blocks.map((block, i) => (
+          <React.Fragment key={block.id}>{renderBlock(block, orderedIndices[i], side)}</React.Fragment>
+        ))}
+      </>
+    );
+  }
+
   return (
     <>
       {blocks.map((block, i) => (
@@ -606,18 +804,23 @@ const SimpleBlockRenderer: React.FC<{ block: Block; orderedIndex?: number | null
     }
 
     case "blockquote": {
-      // Split on blank-line paragraph breaks so merged `> a\n>\n> b`
-      // renders as two <p> children instead of collapsing to one line.
-      const paragraphs = block.content.split(/\n\n+/);
-      return (
-        <blockquote className="border-l-2 border-primary/50 pl-4 my-4 text-muted-foreground italic">
-          {paragraphs.map((para, i) => (
-            <p key={i} className={i > 0 ? "mt-2" : ""}>
-              <InlineMarkdown text={para} />
-            </p>
-          ))}
-        </blockquote>
-      );
+      // The document's quote renderer, without a block id (the diff view
+      // keeps none): a prose quote renders as it always has, and a quote
+      // with a code fence, a list or a nested quote renders them inside one
+      // quote. Alerts keep the plain quote look they have always had here.
+      if (block.alertKind) {
+        const paragraphs = block.content.split(/\n\n+/);
+        return (
+          <blockquote className={BLOCKQUOTE_CLASS_NAME}>
+            {paragraphs.map((para, i) => (
+              <p key={i} className={i > 0 ? "mt-2" : ""}>
+                <InlineMarkdown text={para} />
+              </p>
+            ))}
+          </blockquote>
+        );
+      }
+      return <BlockquoteBlock block={{ ...block, id: undefined as unknown as string }} />;
     }
 
     case "list-item": {

package/components/plan-diff/PlanDiffViewer.tsx

@@ -17,6 +17,7 @@ import { PlanCleanDiffView } from "./PlanCleanDiffView";
 import { PlanRawDiffView } from "./PlanRawDiffView";
 import { PlanDiffBadge } from "./PlanDiffBadge";
 import { VSCodeIcon } from "./VSCodeIcon";
+import { noteServerSessionMismatch, withServerSession } from "../../utils/serverSession";
 
 interface PlanDiffViewerProps {
   diffBlocks: PlanDiffBlock[];
@@ -44,8 +45,12 @@ const defaultOpenVscodeDiff = async (
     const res = await fetch("/api/plan/vscode-diff", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ baseVersion }),
+      // The stale-tab guard (a no-op for a host that never adopted a session).
+      body: JSON.stringify(withServerSession({ baseVersion })),
     });
+    if (await noteServerSessionMismatch(res)) {
+      return { error: "This review was replaced. Reload the page." };
+    }
     const data = (await res.json()) as { ok?: boolean; error?: string };
     if (!res.ok || data.error) {
       return { error: data.error || "Failed to open VS Code diff" };

package/configure.ts

@@ -7,15 +7,17 @@ import { setFileTreeBackend, type FileTreeBackend } from './hooks/useFileBrowser
 import { setDraftTransport, type DraftTransport } from './hooks/useAnnotationDraft';
 import { setExternalAnnotationTransport, type ExternalAnnotationTransport } from './hooks/useExternalAnnotations';
 import { setAITransport, type AITransport } from './hooks/useAIChat';
-import { setSkillCatalogTransport, setSkillContentTransport, type SkillCatalogTransport, type SkillContentTransport } from './utils/skillCatalog';
+import { setSkillCatalogExportRegistration, setSkillCatalogTransport, setSkillContentTransport, type SkillCatalogTransport, type SkillContentTransport } from './utils/skillCatalog';
 import { setWebMcpPolicy, type WebMcpPolicy } from './webmcp/policy';
 import { setMathRendererLoader, type MathRenderer, type MathRendererLoader } from './utils/math';
 import { setIdentityGenerator, type IdentityGenerator } from './utils/generateIdentity';
 import { setAlertIconRenderer, type AlertIconRenderer } from './components/blocks/AlertBlock';
+import { setSkillInstructionsDestination } from './components/SkillReferenceMenu';
 import { setFenceThemeResolver, type FenceThemeResolver } from './utils/syntaxTheme';
 import { configStore } from './config';
 import type { ServerSyncFn } from './config/configStore';
 import type { ExternalAnnotationEvent, VaultNode } from './types';
+import { setComponentTooltips } from './components/HostTitle';
 
 // One-stop type barrel: every seam contract a host implements is importable
 // from this module, next to configurePlannotatorUI itself.
@@ -66,6 +68,19 @@ export interface PlannotatorUIConfig {
   skillCatalogTransport?: SkillCatalogTransport;
   /** Human-only skill contents request for feedback injection. Default: `GET /api/skills/content?name=` on the page origin. */
   skillContentTransport?: SkillContentTransport;
+  /**
+   * Register the fetched skill catalog for the per-comment feedback export
+   * (each comment's "Skills referenced" list). Default: true. A host that
+   * composes one block per message itself passes false, so a comment's
+   * `$name` stays plain text in its export.
+   */
+  skillReferenceExport?: boolean;
+  /**
+   * What a composer's "Includes skill instructions" line says a human-only
+   * skill's instructions go with. Default: "your feedback". The Plannotator
+   * Inbox, where a comment rides a reply, says "your reply".
+   */
+  skillInstructionsDestination?: string;
   serverSync?: ServerSyncFn;
   /**
    * WebMCP provider policy: `{ enabled, namePrefix }`. Default: enabled
@@ -104,6 +119,14 @@ export interface PlannotatorUIConfig {
    * pane keeps its own pair. An unknown theme name renders plain text.
    */
   fenceTheme?: FenceThemeResolver;
+  /**
+   * Draw ui's own hover text (the annotation panel's and toolbar's buttons, a
+   * question card's decision tag, a host-resolved local link's
+   * `LocalLinkResolution.title`) as ui's `Tooltip` instead of a native
+   * `title` (`components/HostTitle`). Default: false, native titles exactly
+   * as before. The Plannotator Inbox passes true.
+   */
+  componentTooltips?: boolean;
   /** Re-hydrate settings from the installed (SYNCHRONOUS) storageBackend after install. */
   loadSettingsFromBackend?: boolean;
 }
@@ -120,12 +143,15 @@ export function configurePlannotatorUI(config: PlannotatorUIConfig): void {
   if (config.aiTransport) setAITransport(config.aiTransport);
   if (config.skillCatalogTransport) setSkillCatalogTransport(config.skillCatalogTransport);
   if (config.skillContentTransport) setSkillContentTransport(config.skillContentTransport);
+  if (config.skillReferenceExport !== undefined) setSkillCatalogExportRegistration(config.skillReferenceExport);
+  if (config.skillInstructionsDestination) setSkillInstructionsDestination(config.skillInstructionsDestination);
   if (config.serverSync) configStore.setServerSync(config.serverSync);
   if (config.webmcp) setWebMcpPolicy(config.webmcp);
   if (config.mathRendererLoader) setMathRendererLoader(config.mathRendererLoader);
   if (config.identityGenerator) setIdentityGenerator(config.identityGenerator);
   if (config.alertIconRenderer) setAlertIconRenderer(config.alertIconRenderer);
   if (config.fenceTheme) setFenceThemeResolver(config.fenceTheme);
+  if (config.componentTooltips !== undefined) setComponentTooltips(config.componentTooltips);
   // Re-hydrate AFTER storageBackend is installed (load-bearing order — gated last).
   if (config.loadSettingsFromBackend) configStore.loadFromBackend();
 }

package/hooks/useAgentJobs.ts

@@ -12,6 +12,7 @@
 
 import { useState, useEffect, useCallback, useRef } from 'react';
 import type { AgentJobInfo, AgentJobEvent, AgentCapabilities } from '../types';
+import { noteServerSessionMismatch, withServerSession, withServerSessionQuery } from '../utils/serverSession';
 
 const POLL_INTERVAL_MS = 500;
 const STREAM_URL = '/api/agents/jobs/stream';
@@ -273,9 +274,11 @@ export function useAgentJobs(
       const res = await fetch(JOBS_URL, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(params),
+        // The stale-tab guard (a no-op for a host that never adopted a session).
+        body: JSON.stringify(withServerSession(params)),
       });
       if (!res.ok) {
+        await noteServerSessionMismatch(res);
         throw new Error(await readResponseError(res));
       }
 
@@ -289,9 +292,10 @@ export function useAgentJobs(
 
   const killJob = useCallback(async (id: string) => {
     try {
-      await fetch(`${JOBS_URL}/${encodeURIComponent(id)}`, {
+      const res = await fetch(withServerSessionQuery(`${JOBS_URL}/${encodeURIComponent(id)}`), {
         method: 'DELETE',
       });
+      await noteServerSessionMismatch(res);
     } catch {
       // SSE will reconcile
     }
@@ -299,7 +303,8 @@ export function useAgentJobs(
 
   const killAll = useCallback(async () => {
     try {
-      await fetch(JOBS_URL, { method: 'DELETE' });
+      const res = await fetch(withServerSessionQuery(JOBS_URL), { method: 'DELETE' });
+      await noteServerSessionMismatch(res);
     } catch {
       // SSE will reconcile
     }