@plannotator/ui 0.47.0 → 0.50.0

package/components/BlockRenderer.tsx

@@ -8,6 +8,20 @@ import { Callout } from "./blocks/Callout";
 import { AlertBlock } from "./blocks/AlertBlock";
 import { TableBlock } from "./blocks/TableBlock";
 import { MathBlock } from "./blocks/MathBlock";
+import { QuestionBlock, type QuestionBlockProps } from "./blocks/QuestionBlock";
+import {
+  indexQuestionBlocks,
+  isQuestionDirectiveKind,
+  type IndexedQuestion,
+  type QuestionAnswer,
+} from "@plannotator/core/question-block";
+
+/** A question block rendered outside a Viewer's document index (plan diff,
+ *  other markdown surfaces): parsed alone, unnumbered. */
+const standaloneQuestion = (block: Block): IndexedQuestion | undefined => {
+  const [indexed] = indexQuestionBlocks([block]);
+  return indexed ? { ...indexed, number: 0 } : undefined;
+};
 
 export const BlockRenderer: React.FC<{
   block: Block;
@@ -22,7 +36,22 @@ export const BlockRenderer: React.FC<{
   repoHost?: string;
   headingAnchorId?: string;
   onNavigateAnchor?: (hash: string) => void;
-}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor }) => {
+  /** `:::question` blocks: this block's entry in the document's question
+   *  index (numbering, key, prompt line) and the document's question count.
+   *  Absent, a question block is parsed on its own and shows no "N of M". */
+  question?: IndexedQuestion;
+  questionTotal?: number;
+  /** The answer to draw (from the annotation carrying `questionAnswer`). */
+  questionAnswer?: QuestionAnswer;
+  /** Absent: question blocks render read-only. */
+  onAnswerQuestion?: (blockId: string, answer: QuestionAnswer | null, key: string) => void;
+  /** Explicit save mode for question cards (see `QuestionBlock`). */
+  onSaveQuestionAnswer?: QuestionBlockProps['onSaveAnswer'];
+  /** Label of the explicit-save-mode Save button (see `QuestionBlock`). */
+  saveQuestionAnswerLabel?: QuestionBlockProps['saveLabel'];
+  /** Host actions in a question card's footer (see `QuestionBlock`). */
+  renderQuestionFooter?: QuestionBlockProps['renderFooter'];
+}> = ({ block, onOpenLinkedDoc, onOpenCodeFile, imageBaseDir, onImageClick, onToggleCheckbox, checkboxOverrides, orderedIndex, githubRepo, repoHost, headingAnchorId, onNavigateAnchor, question, questionTotal, questionAnswer, onAnswerQuestion, onSaveQuestionAnswer, saveQuestionAnswerLabel, renderQuestionFooter }) => {
   switch (block.type) {
     case 'heading': {
       const Tag = `h${block.level || 1}` as React.ElementType;
@@ -135,6 +164,31 @@ export const BlockRenderer: React.FC<{
 
     case 'directive': {
       const kind = block.directiveKind || 'note';
+      if (isQuestionDirectiveKind(kind)) {
+        // An unparseable question (no prompt) falls through to the callout.
+        const indexed = question ?? standaloneQuestion(block);
+        if (indexed) {
+          return (
+            <QuestionBlock
+              blockId={block.id}
+              indexed={indexed}
+              total={questionTotal ?? 0}
+              answer={questionAnswer}
+              onAnswer={onAnswerQuestion}
+              onSaveAnswer={onSaveQuestionAnswer}
+              saveLabel={saveQuestionAnswerLabel}
+              renderFooter={renderQuestionFooter}
+              onOpenLinkedDoc={onOpenLinkedDoc}
+              onOpenCodeFile={onOpenCodeFile}
+              imageBaseDir={imageBaseDir}
+              onImageClick={onImageClick}
+              githubRepo={githubRepo}
+              repoHost={repoHost}
+              onNavigateAnchor={onNavigateAnchor}
+            />
+          );
+        }
+      }
       return (
         <Callout
           blockId={block.id}

package/components/CompletionOverlay.tsx

@@ -29,9 +29,15 @@ interface CompletionOverlayProps {
   title: string;
   subtitle: string;
   agentLabel: string;
+  /**
+   * Optional destinations shown under the subtitle as ordinary links (opened
+   * in a new tab by a real click, so no popup blocker applies) — e.g. the PR
+   * a platform review was just posted to. Omitted or empty renders nothing.
+   */
+  links?: ReadonlyArray<{ href: string; label: string }>;
 }
 
-export function CompletionOverlay({ submitted, title, subtitle, agentLabel }: CompletionOverlayProps) {
+export function CompletionOverlay({ submitted, title, subtitle, agentLabel, links }: CompletionOverlayProps) {
   const { state, enableAndStart } = useAutoClose(!!submitted);
 
   if (!submitted) return null;
@@ -52,6 +58,22 @@ export function CompletionOverlay({ submitted, title, subtitle, agentLabel }: Co
         <div className="space-y-2">
           <h2 className="text-xl font-semibold text-foreground">{title}</h2>
           <p className="text-muted-foreground">{subtitle}</p>
+          {links && links.length > 0 && (
+            <div className="flex flex-col items-center gap-1 pt-1">
+              {links.map((link) => (
+                <a
+                  key={link.href}
+                  href={link.href}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  data-completion-link
+                  className="text-sm font-medium text-primary underline-offset-4 hover:underline break-all"
+                >
+                  {link.label}
+                </a>
+              ))}
+            </div>
+          )}
         </div>
 
         <div className="pt-4 border-t border-border space-y-2">

package/components/DiffFileTree.tsx

@@ -0,0 +1,363 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  buildDiffFileTree,
+  type DiffFileTreeFile,
+  type DiffFileTreeNode,
+  type DiffFileTreeStatus,
+} from '../utils/diffFileTree';
+import { useDiffFileTreeExpansion, type DiffFileTreeDefaultExpanded } from '../hooks/useDiffFileTreeExpansion';
+
+export type { DiffFileTreeFile, DiffFileTreeNode, DiffFileTreeStatus } from '../utils/diffFileTree';
+export type { DiffFileTreeDefaultExpanded } from '../hooks/useDiffFileTreeExpansion';
+
+/*
+ * The diff file tree's presentational parts. Plannotator's code review renders
+ * its tree rows from the atoms below (folder row, file-row content, change
+ * letter, +/- counts, indentation), adding its review-only decorations
+ * (viewed/stage controls, annotation badge, context menu) around them; the
+ * `DiffFileTree` component at the bottom is the read-only, embeddable tree a
+ * host drops beside its own diff list.
+ */
+
+/** Left padding of a row at `depth` (px). */
+export function diffFileTreeIndent(depth: number): number {
+  return 4 + depth * 8;
+}
+
+/** Leading change-type letter — A/D/R/U carry weight and color; modified gets
+ * a whisper-quiet M so the column has no holes. Fixed slot keeps names aligned. */
+export const ChangeTypeLetter: React.FC<{
+  status: DiffFileTreeStatus;
+  oldPath?: string;
+  untracked?: boolean;
+}> = ({ status, oldPath, untracked }) => (
+  <span className="w-3 text-center text-[10px] flex-shrink-0">
+    {untracked ? (
+      <span className="font-semibold text-muted-foreground/70" title="Untracked file">U</span>
+    ) : status === 'added' ? (
+      <span className="font-semibold text-success" title="Added file">A</span>
+    ) : status === 'deleted' ? (
+      <span className="font-semibold text-destructive" title="Deleted file">D</span>
+    ) : status === 'renamed' ? (
+      <span className="font-semibold text-[#007aff]" title={oldPath ? `Renamed from ${oldPath}` : 'Renamed file'}>R</span>
+    ) : status === 'binary' ? (
+      <span className="font-semibold text-muted-foreground/70" title="Binary file">B</span>
+    ) : (
+      <span className="text-muted-foreground/40" title="Modified file">M</span>
+    )}
+  </span>
+);
+
+/** Right-anchored +/- pair — one fixed-width block so the numbers always end
+ * flush at the row edge, stay tight together, and add-only rows leave no
+ * phantom gap. */
+export const DiffCounts: React.FC<{ additions: number; deletions: number }> = ({ additions, deletions }) => (
+  <span className="min-w-[7ch] text-right whitespace-nowrap flex-shrink-0 text-[10px] tabular-nums">
+    {additions > 0 && <span className="additions">+{additions}</span>}
+    {additions > 0 && deletions > 0 && <span> </span>}
+    {deletions > 0 && <span className="deletions">-{deletions}</span>}
+  </span>
+);
+
+type FolderRowProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick' | 'className' | 'style' | 'children'> & {
+  node: Pick<DiffFileTreeNode, 'name' | 'depth' | 'additions' | 'deletions'>;
+  isExpanded: boolean;
+  onToggle: () => void;
+  ref?: React.Ref<HTMLButtonElement>;
+};
+
+/** A folder row: chevron, (possibly merged) folder name, summed +/- counts. */
+export const DiffFileTreeFolderRow: React.FC<FolderRowProps> = ({ node, isExpanded, onToggle, ...buttonProps }) => (
+  <button
+    {...buttonProps}
+    onClick={onToggle}
+    className="w-full flex items-center gap-1.5 py-1 px-2 text-[11px] text-muted-foreground hover:text-foreground hover:bg-muted/50 transition-colors rounded-sm"
+    style={{ paddingLeft: diffFileTreeIndent(node.depth) }}
+  >
+    <svg
+      className={`w-3 h-3 flex-shrink-0 transition-transform ${isExpanded ? 'rotate-90' : ''}`}
+      fill="none"
+      viewBox="0 0 24 24"
+      stroke="currentColor"
+      strokeWidth={2}
+    >
+      <path strokeLinecap="round" strokeLinejoin="round" d="M9 5l7 7-7 7" />
+    </svg>
+    <span className="truncate">{node.name}</span>
+    {(node.additions > 0 || node.deletions > 0) && (
+      <div className="flex items-center gap-1.5 ml-auto flex-shrink-0 text-[10px]">
+        {node.additions > 0 && (
+          <span className="additions">+{node.additions}</span>
+        )}
+        {node.deletions > 0 && (
+          <span className="deletions">-{node.deletions}</span>
+        )}
+      </div>
+    )}
+  </button>
+);
+
+/**
+ * The inside of a file row (render it in a `file-tree-item` row element):
+ * `[leading][letter][name][afterName]` then the right-anchored counts.
+ * `leading` and `afterName` are where the review puts its viewed/stage
+ * controls and annotation badge.
+ */
+export const DiffFileTreeFileRowContent: React.FC<{
+  file: Pick<DiffFileTreeFile, 'status' | 'oldPath' | 'additions' | 'deletions'>;
+  name: string;
+  untracked?: boolean;
+  leading?: React.ReactNode;
+  afterName?: React.ReactNode;
+}> = ({ file, name, untracked, leading, afterName }) => (
+  <>
+    <div className="flex items-center gap-1.5 flex-1 min-w-0">
+      {leading}
+      <ChangeTypeLetter status={file.status} oldPath={file.oldPath} untracked={untracked} />
+      <span className="truncate">{name}</span>
+      {afterName}
+    </div>
+    <DiffCounts additions={file.additions} deletions={file.deletions} />
+  </>
+);
+
+// --- Embeddable read-only tree ---
+
+export interface DiffFileTreeProps {
+  /** The changed files. Order does not matter; the tree sorts. */
+  files: readonly DiffFileTreeFile[];
+  /** Path of the selected file (controlled), or null. */
+  selectedPath: string | null;
+  /** Called with a file's `path` on click, Enter/Space, or arrow/j/k/Home/End. */
+  onSelect: (path: string) => void;
+  /** Which folders start open; re-applied when the set of files changes. Default 'all'. */
+  defaultExpanded?: DiffFileTreeDefaultExpanded;
+  /** Accessible name of the tree. Default "Changed files". */
+  label?: string;
+  className?: string;
+}
+
+interface VisibleRow {
+  key: string;
+  node: DiffFileTreeNode;
+  parentKey: string | null;
+}
+
+function rowKey(node: DiffFileTreeNode): string {
+  return node.type === 'file' ? `file:${node.path}` : `folder:${node.path}`;
+}
+
+function collectVisibleRows(
+  nodes: DiffFileTreeNode[],
+  expanded: Set<string>,
+  parentKey: string | null,
+  out: VisibleRow[],
+): VisibleRow[] {
+  for (const node of nodes) {
+    const key = rowKey(node);
+    out.push({ key, node, parentKey });
+    if (node.type === 'folder' && expanded.has(node.path) && node.children) {
+      collectVisibleRows(node.children, expanded, key, out);
+    }
+  }
+  return out;
+}
+
+/** File paths in the order the tree renders them (collapse state ignored). */
+function visualFilePaths(nodes: DiffFileTreeNode[], out: string[] = []): string[] {
+  for (const node of nodes) {
+    if (node.type === 'file') out.push(node.path);
+    else if (node.children) visualFilePaths(node.children, out);
+  }
+  return out;
+}
+
+/** Content signature, so a host that rebuilds an equal `files` array each
+ * render does not reset the folders it opened or closed. */
+function filesSignature(files: readonly DiffFileTreeFile[]): string {
+  return files.map((f) => `${f.path}\u0000${f.oldPath ?? ''}\u0000${f.status}\u0000${f.additions}\u0000${f.deletions}`).join('\u0001');
+}
+
+/**
+ * Read-only diff file tree: the same folder collapsing, change letters, +/-
+ * counts, icons and indentation as Plannotator's code-review tree, with WAI-ARIA
+ * tree semantics. Keyboard (while focus is in the tree, never window-wide):
+ * ArrowDown/`j` and ArrowUp/`k` select the next/previous file in tree order,
+ * Home/End the first/last (the review's keys); ArrowRight/ArrowLeft open/close
+ * a focused folder, and ArrowLeft from a file moves focus to its folder.
+ * Theme comes from the ThemeProvider tokens via `@plannotator/ui/styles.css`.
+ */
+export const DiffFileTree: React.FC<DiffFileTreeProps> = ({
+  files,
+  selectedPath,
+  onSelect,
+  defaultExpanded = 'all',
+  label = 'Changed files',
+  className,
+}) => {
+  const signature = filesSignature(files);
+  // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on content, not identity
+  const tree = useMemo(() => buildDiffFileTree(files), [signature]);
+  const filesInOrder = useMemo(() => visualFilePaths(tree), [tree]);
+
+  const { expandedFolders, setFolderExpanded, toggleFolder } = useDiffFileTreeExpansion(tree, selectedPath, defaultExpanded);
+  const rows = useMemo(() => collectVisibleRows(tree, expandedFolders, null, []), [tree, expandedFolders]);
+
+  const [focusedKey, setFocusedKey] = useState<string | null>(null);
+  const pendingFocus = useRef<string | null>(null);
+  const rowRefs = useRef(new Map<string, HTMLButtonElement>());
+
+  const selectedKey = selectedPath ? `file:${selectedPath}` : null;
+  const rowKeys = useMemo(() => new Set(rows.map((r) => r.key)), [rows]);
+  const tabStopKey =
+    focusedKey && rowKeys.has(focusedKey)
+      ? focusedKey
+      : selectedKey && rowKeys.has(selectedKey)
+        ? selectedKey
+        : rows[0]?.key ?? null;
+
+  // Move DOM focus once the target row exists (selecting a file inside a
+  // collapsed folder opens the folder first, one render later).
+  useEffect(() => {
+    const key = pendingFocus.current;
+    if (!key) return;
+    const el = rowRefs.current.get(key);
+    if (el) {
+      pendingFocus.current = null;
+      el.focus();
+    }
+  });
+
+  const focusRow = useCallback((key: string) => {
+    setFocusedKey(key);
+    pendingFocus.current = key;
+    const el = rowRefs.current.get(key);
+    if (el) {
+      pendingFocus.current = null;
+      el.focus();
+    }
+  }, []);
+
+  const selectFile = useCallback(
+    (path: string) => {
+      onSelect(path);
+      focusRow(`file:${path}`);
+    },
+    [onSelect, focusRow],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLDivElement>) => {
+      if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.altKey) return;
+      if (filesInOrder.length === 0) return;
+      const pos = selectedPath ? filesInOrder.indexOf(selectedPath) : -1;
+
+      if (e.key === 'j' || e.key === 'ArrowDown') {
+        e.preventDefault();
+        if (pos < filesInOrder.length - 1) selectFile(filesInOrder[pos + 1]);
+        return;
+      }
+      if (e.key === 'k' || e.key === 'ArrowUp') {
+        e.preventDefault();
+        if (pos > 0) selectFile(filesInOrder[pos - 1]);
+        return;
+      }
+      if (e.key === 'Home') {
+        e.preventDefault();
+        selectFile(filesInOrder[0]);
+        return;
+      }
+      if (e.key === 'End') {
+        e.preventDefault();
+        selectFile(filesInOrder[filesInOrder.length - 1]);
+        return;
+      }
+      if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return;
+
+      const current = rows.find((r) => r.key === tabStopKey);
+      if (!current) return;
+      e.preventDefault();
+      const { node } = current;
+      if (e.key === 'ArrowRight') {
+        if (node.type !== 'folder') return;
+        if (!expandedFolders.has(node.path)) {
+          setFolderExpanded(node.path, true);
+        } else {
+          const index = rows.indexOf(current);
+          const child = rows[index + 1];
+          if (child && child.parentKey === current.key) focusRow(child.key);
+        }
+        return;
+      }
+      if (node.type === 'folder' && expandedFolders.has(node.path)) {
+        setFolderExpanded(node.path, false);
+      } else if (current.parentKey) {
+        focusRow(current.parentKey);
+      }
+    },
+    [filesInOrder, selectedPath, selectFile, rows, tabStopKey, expandedFolders, setFolderExpanded, focusRow],
+  );
+
+  const setRef = (key: string) => (el: HTMLButtonElement | null) => {
+    if (el) rowRefs.current.set(key, el);
+    else rowRefs.current.delete(key);
+  };
+
+  return (
+    <div
+      role="tree"
+      aria-label={label}
+      className={className ? `px-1 py-1 ${className}` : 'px-1 py-1'}
+      onKeyDown={handleKeyDown}
+      data-diff-file-tree=""
+    >
+      {rows.map(({ key, node }) => {
+        const level = node.depth + 1;
+        const tabIndex = key === tabStopKey ? 0 : -1;
+        if (node.type === 'folder') {
+          const isExpanded = expandedFolders.has(node.path);
+          return (
+            <DiffFileTreeFolderRow
+              key={key}
+              ref={setRef(key)}
+              type="button"
+              role="treeitem"
+              aria-level={level}
+              aria-expanded={isExpanded}
+              tabIndex={tabIndex}
+              data-path={node.path}
+              onFocus={() => setFocusedKey(key)}
+              node={node}
+              isExpanded={isExpanded}
+              onToggle={() => {
+                toggleFolder(node.path);
+                setFocusedKey(key);
+              }}
+            />
+          );
+        }
+        const file = node.file!;
+        const isActive = node.path === selectedPath;
+        return (
+          <button
+            key={key}
+            ref={setRef(key)}
+            type="button"
+            role="treeitem"
+            aria-level={level}
+            aria-selected={isActive}
+            tabIndex={tabIndex}
+            data-path={node.path}
+            title={node.path}
+            onFocus={() => setFocusedKey(key)}
+            onClick={() => selectFile(node.path)}
+            className={`file-tree-item w-full text-left group${isActive ? ' active' : ''}`}
+            style={{ paddingLeft: diffFileTreeIndent(node.depth) }}
+          >
+            <DiffFileTreeFileRowContent file={file} name={node.name} />
+          </button>
+        );
+      })}
+    </div>
+  );
+};

package/components/ImageLightbox.tsx

@@ -0,0 +1,66 @@
+import React, { useEffect, useRef } from 'react';
+
+/**
+ * Overlay for viewing one image enlarged. Shared by the markdown Viewer
+ * (clicking an image in a document) and the raw-HTML surface (a link to a
+ * local image inside the annotated page).
+ *
+ * The image is only ever shown through `<img src>`, so an SVG runs no script
+ * and cannot reach the page.
+ *
+ * It is modal for the keyboard. Its keydown listener runs on the CAPTURE phase
+ * at the window and stops every key there, so nothing behind it reacts:
+ * Escape closes the lightbox before the HTML surface's Esc ladder sees it,
+ * and Mod+Enter cannot submit a decision behind it. Focus moves to the
+ * overlay when it opens, which also pulls focus out of an HTML page's iframe
+ * (whose keys the parent would otherwise never see), and goes back to where
+ * it was when it closes.
+ */
+export const ImageLightbox: React.FC<{ src: string; alt: string; onClose: () => void }> = ({ src, alt, onClose }) => {
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  useEffect(() => {
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    overlayRef.current?.focus({ preventScroll: true });
+    const handleKeyDown = (e: KeyboardEvent) => {
+      // Tab stays native: the overlay is the only focusable thing that matters
+      // here, and trapping it buys nothing for a click-to-close surface.
+      if (e.key === 'Tab') return;
+      e.stopImmediatePropagation();
+      if (e.key === 'Escape' || (e.key === 'Enter' && (e.metaKey || e.ctrlKey))) {
+        e.preventDefault();
+      }
+      if (e.key === 'Escape') onCloseRef.current();
+    };
+    window.addEventListener('keydown', handleKeyDown, true);
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown, true);
+      if (previous && previous.isConnected) previous.focus({ preventScroll: true });
+    };
+  }, []);
+
+  return (
+    <div
+      ref={overlayRef}
+      tabIndex={-1}
+      role="dialog"
+      aria-modal="true"
+      aria-label={alt || 'Image'}
+      data-image-lightbox=""
+      className="fixed inset-0 z-[200] flex flex-col items-center justify-center bg-black/80 backdrop-blur-sm cursor-zoom-out outline-none"
+      onClick={onClose}
+    >
+      <img
+        src={src}
+        alt={alt}
+        className="max-w-[90vw] max-h-[85vh] object-contain rounded-lg shadow-2xl"
+        onClick={(e) => e.stopPropagation()}
+      />
+      {alt && (
+        <div className="mt-3 text-sm text-white/70 max-w-[90vw] text-center truncate">{alt}</div>
+      )}
+    </div>
+  );
+};

package/components/PRPlatformIcon.tsx

@@ -0,0 +1,22 @@
+import React from "react";
+import { GitHubIcon } from "./GitHubIcon";
+import { GitLabIcon } from "./GitLabIcon";
+
+/** Bitbucket bucket mark (simple-icons, CC0). Uses currentColor. */
+export const BitbucketIcon: React.FC<{ className?: string }> = ({ className }) => (
+  <svg
+    className={className}
+    viewBox="0 0 24 24"
+    fill="currentColor"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path d="M.778 1.213a.768.768 0 00-.768.892l3.263 19.81c.084.5.515.868 1.022.873H19.95a.772.772 0 00.77-.646l3.27-20.03a.768.768 0 00-.768-.891zM14.52 15.53H9.522L8.17 8.466h7.561z" />
+  </svg>
+);
+
+/** The mark of the platform a PR/MR lives on. Unknown platforms get GitHub's. */
+export const PRPlatformIcon: React.FC<{ platform: string; className?: string }> = ({ platform, className }) => {
+  if (platform === "gitlab") return <GitLabIcon className={className} />;
+  if (platform === "bitbucket") return <BitbucketIcon className={className} />;
+  return <GitHubIcon className={className} />;
+};

package/components/ProviderIcons.tsx

@@ -37,15 +37,27 @@ const GenericProviderIcon: React.FC<{ className?: string }> = ({ className = 'w-
   </svg>
 );
 
+/** "Ask this session": a speech bubble, since the answer comes from the agent session itself. */
+const SessionIcon: React.FC<{ className?: string }> = ({ className = 'w-4 h-4' }) => (
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} className={className}>
+    <path strokeLinecap="round" strokeLinejoin="round" d="M8 10h8M8 14h5m-7 6 2.5-3H18a3 3 0 0 0 3-3V7a3 3 0 0 0-3-3H6a3 3 0 0 0-3 3v7a3 3 0 0 0 3 3z" />
+  </svg>
+);
+
 /** Provider metadata: maps provider type name to display label and icon component. */
 export const PROVIDER_META: Record<string, { label: string; icon: React.FC<{ className?: string }> }> = {
   'claude-agent-sdk': { label: 'Claude', icon: ClaudeIcon },
   'codex-sdk': { label: 'Codex', icon: CodexIcon },
   'pi-sdk': { label: 'Pi', icon: PiIcon },
   'opencode-sdk': { label: 'OpenCode', icon: OpenCodeIcon },
+  'session-bridge': { label: 'Ask this session', icon: SessionIcon },
 };
 
-/** Get provider metadata, with fallback for unknown providers. */
-export function getProviderMeta(providerName: string): { label: string; icon: React.FC<{ className?: string }> } {
-  return PROVIDER_META[providerName] ?? { label: providerName, icon: GenericProviderIcon };
+/**
+ * Get provider metadata, with fallback for unknown providers. A server-sent
+ * `label` (e.g. "Ask this session · Pi") overrides the name lookup.
+ */
+export function getProviderMeta(providerName: string, label?: string): { label: string; icon: React.FC<{ className?: string }> } {
+  const meta = PROVIDER_META[providerName] ?? { label: providerName, icon: GenericProviderIcon };
+  return label ? { ...meta, label } : meta;
 }

package/components/QuestionProgressChip.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { cn } from '../lib/utils';
+
+/**
+ * The header "N/M answered" chip for documents with `:::question` blocks
+ * (the approved Card mock): a progress ring and the count. It is a button:
+ * a click jumps to the next open question. With no open question left it
+ * still reads the progress but has nothing to jump to.
+ */
+export interface QuestionProgressChipProps {
+  /** Answered or settled questions. */
+  done: number;
+  total: number;
+  /** Whether a question is still open (not answered, settled or skipped). */
+  hasOpen: boolean;
+  onJump: () => void;
+  className?: string;
+}
+
+const Ring: React.FC<{ done: number; total: number }> = ({ done, total }) => {
+  const r = 6;
+  const c = 2 * Math.PI * r;
+  const f = total > 0 ? done / total : 0;
+  const complete = total > 0 && done === total;
+  return (
+    <svg viewBox="0 0 16 16" width="16" height="16" aria-hidden="true" className="shrink-0">
+      <circle cx="8" cy="8" r={r} fill="none" stroke="var(--border)" strokeWidth="2.2" />
+      <circle
+        cx="8"
+        cy="8"
+        r={r}
+        fill="none"
+        stroke={complete ? 'var(--success)' : 'var(--primary)'}
+        strokeWidth="2.2"
+        strokeDasharray={`${c * f} ${c}`}
+        transform="rotate(-90 8 8)"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+};
+
+export const QuestionProgressChip: React.FC<QuestionProgressChipProps> = ({ done, total, hasOpen, onJump, className }) => {
+  if (total <= 0) return null;
+  const label = `${done} of ${total} question${total === 1 ? '' : 's'} answered.${hasOpen ? ' Go to next unanswered.' : ''}`;
+  return (
+    <button
+      type="button"
+      data-question-progress="true"
+      onClick={onJump}
+      aria-label={label}
+      title={hasOpen ? 'Go to the next open question' : done >= total ? 'All questions answered' : 'No open questions'}
+      className={cn(
+        'inline-flex h-7 shrink-0 items-center gap-[7px] whitespace-nowrap rounded-full border border-border bg-card pl-[7px] pr-2.5 text-xs text-muted-foreground transition-colors',
+        'hover:border-primary/50 hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring',
+        className,
+      )}
+    >
+      <Ring done={done} total={total} />
+      <span>
+        <b className="font-semibold text-foreground">{done}/{total}</b>
+        <span className="hidden md:inline"> answered</span>
+      </span>
+    </button>
+  );
+};