@plannotator/ui 0.47.0 → 0.50.0

package/types.ts

@@ -1,7 +1,9 @@
 import type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
 import type { DiagramRenderKind } from '@plannotator/core/annotatable';
+import type { QuestionAnswer } from '@plannotator/core/question-block';
 
 export type { DiagramAnchor } from '@plannotator/core/diagram-anchor';
+export type { QuestionAnswer } from '@plannotator/core/question-block';
 export type { DiagramRenderKind } from '@plannotator/core/annotatable';
 
 /**
@@ -100,6 +102,7 @@ export interface Annotation {
   elementContext?: HtmlElementContext; // raw-HTML / live-app pinpoint: bounded agent-facing description of the primary element (never used by restore)
   htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   diagramAnchor?: DiagramAnchor; // a comment on a rendered diagram part (Mermaid / Graphviz fence): the part's own id, label and document source line; the highlighter skips it and the diagram overlay restores it (see @plannotator/core/diagram-anchor)
+  questionAnswer?: QuestionAnswer; // the reviewer's answer to a `:::question` block (id `ann-question-<key>`): the Viewer draws the answer from it, the highlighter skips it, and the export prints it in the "Answers to your questions" section instead of as a numbered comment (see @plannotator/core/question-block)
   // web-highlighter metadata for cross-element selections
   startMeta?: AnnotationTextMeta;
   endMeta?: AnnotationTextMeta;
@@ -459,6 +462,10 @@ export interface AIResponse {
   text: string;
   isStreaming: boolean;
   error?: string;
+  /** Server error code with `error` (e.g. `agent_busy`, `session_gone` from "Ask this session"). */
+  errorCode?: string;
+  /** "Ask this session": the question is waiting for a busy session, or interrupting it. */
+  status?: 'waiting' | 'interrupting';
   createdAt: number;
 }
 

package/utils/aiPrompt.ts

@@ -27,3 +27,34 @@ export function buildReviewContextPreamble(
     ? '[Still reviewing the same changes shown earlier in this conversation.]'
     : ctx;
 }
+
+const MAX_IDENTITY_FILES = 30;
+
+/**
+ * The code-review context for "Ask this session". The agent that opened the
+ * review wrote (or can read) the changes, so it gets the diff's identity —
+ * which comparison, against which base, which files — and never the patch
+ * itself, which would land permanently in its context window.
+ */
+export function buildSessionReviewIdentity(review: {
+  diffType?: string | null;
+  base?: string | null;
+  patch?: string | null;
+}): string {
+  const files: string[] = [];
+  for (const match of (review.patch ?? '').matchAll(/^diff --git a\/.+? b\/(.+)$/gm)) {
+    files.push(match[1]);
+  }
+  const lines: string[] = [];
+  if (review.diffType) {
+    lines.push(`Diff on screen: ${review.diffType}${review.base ? ` (against ${review.base})` : ''}`);
+  } else if (review.base) {
+    lines.push(`Diff on screen: against ${review.base}`);
+  }
+  if (files.length > 0) {
+    const shown = files.slice(0, MAX_IDENTITY_FILES).join(', ');
+    const more = files.length > MAX_IDENTITY_FILES ? ` (+${files.length - MAX_IDENTITY_FILES} more)` : '';
+    lines.push(`Changed files (${files.length}): ${shown}${more}`);
+  }
+  return lines.join('\n');
+}

package/utils/aiProvider.ts

@@ -25,6 +25,45 @@ export interface AIProviderOption {
   modelsSource?: 'fallback' | 'discovered';
   /** The installed CLI's version, when the server reports it. */
   toolVersion?: string;
+  /** Display label overriding the name lookup (e.g. "Ask this session · Pi"). */
+  label?: string;
+  /** Present only on the "Ask this session" provider: the host session's live status. */
+  sessionBridge?: SessionBridgeInfo;
+}
+
+/** "Ask this session": Ask AI answered by the agent session that opened Plannotator. */
+export const SESSION_BRIDGE_PROVIDER_NAME = 'session-bridge';
+
+export interface SessionBridgeInfo {
+  host: string;
+  status: 'ready' | 'busy' | 'blocked' | 'gone';
+  modes: { turn: boolean; transient: boolean };
+}
+
+/** Error codes "Ask this session" answers with that the panel turns into actions. */
+export const SESSION_ASK_ERROR_CODES = {
+  agentBusy: 'agent_busy',
+  blocked: 'session_blocked',
+  gone: 'session_gone',
+} as const;
+
+export function isSessionBridgeProvider(provider: Pick<AIProviderOption, 'name' | 'sessionBridge'> | null | undefined): boolean {
+  return !!provider && (provider.name === SESSION_BRIDGE_PROVIDER_NAME || !!provider.sessionBridge);
+}
+
+/**
+ * The "Ask this session" provider when it can answer here: present, the
+ * session not gone, and not blocked unless it offers a transient answer.
+ */
+export function findUsableSessionBridge(providers: AIProviderOption[]): AIProviderOption | null {
+  for (const provider of providers) {
+    const bridge = provider.sessionBridge;
+    if (!bridge) continue;
+    if (bridge.status === 'gone') continue;
+    if (bridge.status === 'blocked' && !bridge.modes.transient) continue;
+    return provider;
+  }
+  return null;
 }
 
 export interface AIProviderSettings {
@@ -153,8 +192,20 @@ export function resolveAIProviderSelection(options: {
   const byId = (id: string | null | undefined) =>
     id ? providers.find(provider => provider.id === id) ?? null : null;
 
+  // An explicit saved pick wins, then "Ask this session" whenever the host
+  // session can answer, then the origin's own SDK provider and the older
+  // fallbacks. Without a usable bridge this is exactly the previous order.
+  const sessionBridge = findUsableSessionBridge(providers);
+  const explicitPick = sessionBridge
+    ? byId(originHasDedicatedAIProvider(origin)
+        ? (origin ? settings.providerByOrigin[origin] : null)
+        : settings.providerId)
+    : null;
+
   const provider =
+    explicitPick ??
     byId(origin ? settings.providerByOrigin[origin] : null) ??
+    sessionBridge ??
     findOriginAIProvider(providers, origin) ??
     byId(settings.providerId) ??
     byId(serverDefaultProvider) ??
@@ -167,6 +218,23 @@ export function resolveAIProviderSelection(options: {
   };
 }
 
+/**
+ * Where "Ask a separate AI instead" goes when "Ask this session" cannot
+ * answer: the selection the app would make if the bridge were not there.
+ */
+export function resolveSessionBridgeFallback(options: {
+  providers: AIProviderOption[];
+  origin?: Origin | null;
+  settings?: AIProviderSettings;
+  serverDefaultProvider?: string | null;
+}): AIProviderSelection {
+  const providers = options.providers.filter(provider => !isSessionBridgeProvider(provider));
+  const serverDefaultProvider = providers.some(provider => provider.id === options.serverDefaultProvider)
+    ? options.serverDefaultProvider
+    : null;
+  return resolveAIProviderSelection({ ...options, providers, serverDefaultProvider });
+}
+
 export function saveAIProviderSelection(options: {
   providerId: string | null;
   model?: string | null;

package/utils/autoUpdateNotice.ts

@@ -0,0 +1,59 @@
+/**
+ * One-time notice after a background auto-update (#1634).
+ *
+ * The compiled CLI's servers attach `autoUpdateNotice` to /api/plan and
+ * /api/diff when the data dir records an install attempt: `updated` once the
+ * running binary is the new version, `failed` when the install script exited
+ * non-zero. The notice id is stable per attempt; the "seen" marker is a cookie,
+ * which is shared across the random ports sessions run on, so the toast shows
+ * once whichever app (plan, annotate, review) loads first.
+ */
+
+import { getItem, setItem } from './storage';
+
+export interface AutoUpdateNotice {
+  id: string;
+  kind: 'updated' | 'failed';
+  version: string;
+  releaseUrl: string;
+  logPath?: string;
+}
+
+const SEEN_KEY = 'plannotator-auto-update-notice-seen';
+
+export function parseAutoUpdateNotice(value: unknown): AutoUpdateNotice | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  const v = value as Record<string, unknown>;
+  if (typeof v.id !== 'string' || !v.id) return undefined;
+  if (v.kind !== 'updated' && v.kind !== 'failed') return undefined;
+  if (typeof v.version !== 'string' || typeof v.releaseUrl !== 'string') return undefined;
+  if (!/^https:\/\/github\.com\//.test(v.releaseUrl)) return undefined;
+  return {
+    id: v.id,
+    kind: v.kind,
+    version: v.version,
+    releaseUrl: v.releaseUrl,
+    ...(typeof v.logPath === 'string' && { logPath: v.logPath }),
+  };
+}
+
+/**
+ * True the first time a given notice is claimed in this browser, false after.
+ * Claiming marks it seen, so a caller shows the toast only when this is true.
+ */
+export function claimAutoUpdateNotice(notice: AutoUpdateNotice): boolean {
+  if (getItem(SEEN_KEY) === notice.id) return false;
+  setItem(SEEN_KEY, notice.id);
+  return true;
+}
+
+/** Title and description for the toast. */
+export function describeAutoUpdateNotice(notice: AutoUpdateNotice): { title: string; description: string } {
+  if (notice.kind === 'updated') {
+    return { title: `Updated to v${notice.version}`, description: 'Plannotator updated itself in the background.' };
+  }
+  return {
+    title: 'Auto-update failed',
+    description: notice.logPath ? `See ${notice.logPath}` : `Could not install v${notice.version}.`,
+  };
+}

package/utils/diffFileTree.ts

@@ -0,0 +1,203 @@
+/**
+ * Pure tree builder for a list of changed files (a diff), shared by
+ * Plannotator's code-review file tree (`packages/review-editor`) and the
+ * embeddable `DiffFileTree` component. Browser-safe, no React.
+ *
+ * Shape rules (the review's, unchanged when this moved here):
+ * - folders before files at every level, each group sorted by name
+ *   (`localeCompare`);
+ * - a folder whose only child is a folder is merged into it
+ *   (`packages/app/src`), recursively;
+ * - when the whole tree is one root folder holding only files, that folder is
+ *   unwrapped and the files sit at the root;
+ * - a folder's +/- counts are the sums of everything under it.
+ */
+
+/** Change status a tree row can show. 'binary' is a host-facing extra; the
+ * review's own parser never produces it. */
+export type DiffFileTreeStatus = 'added' | 'modified' | 'deleted' | 'renamed' | 'binary';
+
+/** The minimum a file needs to sit in the tree. */
+export interface DiffFileTreeFile {
+  path: string;
+  oldPath?: string;
+  status: DiffFileTreeStatus;
+  additions: number;
+  deletions: number;
+}
+
+export interface DiffFileTreeNode<F extends DiffFileTreeFile = DiffFileTreeFile> {
+  type: 'file' | 'folder';
+  /** Display name: the file name, or the (possibly merged) folder segment(s). */
+  name: string;
+  /** File: the file's own path. Folder: the full folder path from the root. */
+  path: string;
+  depth: number;
+  /** Index of the file in the input array (file nodes only). */
+  fileIndex?: number;
+  file?: F;
+  children?: DiffFileTreeNode<F>[];
+  additions: number;
+  deletions: number;
+}
+
+interface TrieNode<F> {
+  children: Map<string, TrieNode<F>>;
+  file?: { index: number; data: F };
+}
+
+function buildTrie<F extends DiffFileTreeFile>(files: readonly F[]): TrieNode<F> {
+  const root: TrieNode<F> = { children: new Map() };
+
+  for (let i = 0; i < files.length; i++) {
+    const segments = files[i].path.split('/').filter(Boolean);
+    let current = root;
+
+    for (let j = 0; j < segments.length - 1; j++) {
+      if (!current.children.has(segments[j])) {
+        current.children.set(segments[j], { children: new Map() });
+      }
+      current = current.children.get(segments[j])!;
+    }
+
+    const fileName = segments[segments.length - 1];
+    const leaf: TrieNode<F> = { children: new Map(), file: { index: i, data: files[i] } };
+    current.children.set(fileName, leaf);
+  }
+
+  return root;
+}
+
+function trieToNodes<F extends DiffFileTreeFile>(
+  trie: TrieNode<F>,
+  parentPath: string,
+  depth: number,
+): DiffFileTreeNode<F>[] {
+  const folders: DiffFileTreeNode<F>[] = [];
+  const fileNodes: DiffFileTreeNode<F>[] = [];
+
+  for (const [name, child] of trie.children) {
+    const fullPath = parentPath ? `${parentPath}/${name}` : name;
+
+    if (child.file) {
+      fileNodes.push({
+        type: 'file',
+        name,
+        path: child.file.data.path,
+        depth,
+        fileIndex: child.file.index,
+        file: child.file.data,
+        additions: child.file.data.additions,
+        deletions: child.file.data.deletions,
+      });
+    } else {
+      const children = trieToNodes(child, fullPath, depth + 1);
+      const additions = children.reduce((s, c) => s + c.additions, 0);
+      const deletions = children.reduce((s, c) => s + c.deletions, 0);
+
+      folders.push({
+        type: 'folder',
+        name,
+        path: fullPath,
+        depth,
+        children,
+        additions,
+        deletions,
+      });
+    }
+  }
+
+  folders.sort((a, b) => a.name.localeCompare(b.name));
+  fileNodes.sort((a, b) => a.name.localeCompare(b.name));
+
+  return [...folders, ...fileNodes];
+}
+
+function collapseSingleChild<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[]): DiffFileTreeNode<F>[] {
+  return nodes.map(node => {
+    if (node.type !== 'folder' || !node.children) return node;
+
+    let current = node;
+    while (
+      current.children &&
+      current.children.length === 1 &&
+      current.children[0].type === 'folder'
+    ) {
+      const child = current.children[0];
+      current = {
+        ...child,
+        name: `${current.name}/${child.name}`,
+        depth: node.depth,
+      };
+    }
+
+    return {
+      ...current,
+      children: current.children ? collapseSingleChild(fixDepths(current.children, node.depth + 1)) : undefined,
+    };
+  });
+}
+
+function fixDepths<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[], depth: number): DiffFileTreeNode<F>[] {
+  return nodes.map(node => ({
+    ...node,
+    depth,
+    children: node.children ? fixDepths(node.children, depth + 1) : undefined,
+  }));
+}
+
+export function buildDiffFileTree<F extends DiffFileTreeFile>(files: readonly F[]): DiffFileTreeNode<F>[] {
+  if (files.length === 0) return [];
+
+  const trie = buildTrie(files);
+  let tree = trieToNodes(trie, '', 0);
+  tree = collapseSingleChild(tree);
+
+  // Flat fallback: if the tree is a single root folder with only file children, unwrap it
+  if (
+    tree.length === 1 &&
+    tree[0].type === 'folder' &&
+    tree[0].children?.every(c => c.type === 'file')
+  ) {
+    return fixDepths(tree[0].children!, 0);
+  }
+
+  return tree;
+}
+
+/** Every proper ancestor folder path of a file path (`a/b/c.ts` → `a`, `a/b`).
+ * A merged folder's path is one of these, so expanding them all reveals the file. */
+export function getAncestorPaths(filePath: string): string[] {
+  const segments = filePath.split('/').filter(Boolean);
+  const paths: string[] = [];
+  for (let i = 1; i < segments.length; i++) {
+    paths.push(segments.slice(0, i).join('/'));
+  }
+  return paths;
+}
+
+/** File indexes in the order the tree renders them (ignores collapse state). */
+export function getVisualFileOrder<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[]): number[] {
+  const order: number[] = [];
+  for (const node of nodes) {
+    if (node.type === 'file' && node.fileIndex != null) {
+      order.push(node.fileIndex);
+    } else if (node.children) {
+      order.push(...getVisualFileOrder(node.children));
+    }
+  }
+  return order;
+}
+
+export function getAllFolderPaths<F extends DiffFileTreeFile>(nodes: DiffFileTreeNode<F>[]): string[] {
+  const paths: string[] = [];
+  for (const node of nodes) {
+    if (node.type === 'folder') {
+      paths.push(node.path);
+      if (node.children) {
+        paths.push(...getAllFolderPaths(node.children));
+      }
+    }
+  }
+  return paths;
+}

package/utils/htmlLinkNavigation.ts

@@ -12,8 +12,16 @@
  * server origin and the directories, so every branch is unit-testable.
  */
 
+import { isReviewImagePath } from "@plannotator/core/diff-paths";
 import { hasLinkedDocExtension } from "./markdownExtensions";
 
+/**
+ * Route the servers serve a raw-HTML page's support assets from. Spelled here
+ * rather than imported because `@plannotator/shared/html-assets` is node-side
+ * (parse5, `path`); `htmlLinkNavigation.test.ts` pins the two together.
+ */
+export const HTML_ASSET_ROUTE_PREFIX = "/api/html-assets";
+
 /** Longest href the parent will look at. Matches the bridge's own cap. */
 export const MAX_HTML_LINK_HREF_LENGTH = 2048;
 
@@ -27,11 +35,29 @@ export type HtmlLinkIntent =
 	| { kind: "document"; path: string; hash: string; rendersHtml: boolean }
 	/** Another origin. Opens in a new tab; the frame never navigates. */
 	| { kind: "external"; url: string }
-	/** A local file Plannotator cannot render as a document (`.pdf`, `.zip`, …). */
-	| { kind: "unsupported"; path: string; label: string }
+	/**
+	 * A local image inside the page's asset root, shown in the image lightbox.
+	 * `url` is the page's own `/api/html-assets/<token>/…` route, so the
+	 * lightbox reads exactly what the page itself can already load.
+	 */
+	| { kind: "image"; path: string; url: string; label: string }
+	/**
+	 * A local file Plannotator will not open. `type`: not a document or image
+	 * (`.pdf`, `.zip`, …). `outside-asset-root`: an image outside the page's
+	 * own folder, which the asset route refuses. `no-asset-root`: an image on
+	 * a page served without an asset route (share links, converted pages).
+	 */
+	| {
+			kind: "unsupported";
+			path: string;
+			label: string;
+			reason: HtmlLinkUnsupportedReason;
+	  }
 	/** Nothing to do: empty, fragment-only, or a scheme we do not follow. */
 	| { kind: "ignored"; reason: HtmlLinkIgnoreReason };
 
+export type HtmlLinkUnsupportedReason = "type" | "outside-asset-root" | "no-asset-root";
+
 export type HtmlLinkIgnoreReason =
 	| "empty"
 	| "too-long"
@@ -55,6 +81,12 @@ export interface HtmlLinkContext {
 	/** The session's `--markdown` preference: HTML is Turndowned by `/api/doc`,
 	 *  so an `.html` target renders as markdown rather than as an HTML surface. */
 	convertHtml?: boolean;
+	/**
+	 * The current page's asset root: the directory its `/api/html-assets`
+	 * token was minted for, and that token's route (`/api/html-assets/<t>/`).
+	 * Image links open in the lightbox only from inside `dir`.
+	 */
+	assetRoot?: { dir: string; url: string } | null;
 }
 
 /** Control characters never appear in a real href; they are how structure gets smuggled. */
@@ -119,11 +151,13 @@ function resolveRelative(
 	if (!baseDir) return { kind: "ignored", reason: "no-base" };
 	const resolved = joinPath(baseDir, decoded);
 	if (!resolved) return { kind: "ignored", reason: "invalid" };
+	const label = basename(resolved);
+	if (isReviewImagePath(resolved)) return resolveImage(resolved, label, context.assetRoot);
 	// Containment is the server's call (`/api/doc` answers 403 for an escaping
 	// path). The extension gate is ours: a `.pdf` would be a pointless fetch
 	// and a confusing server error, so it is reported as unsupported here.
 	if (!hasLinkedDocExtension(resolved)) {
-		return { kind: "unsupported", path: resolved, label: basename(resolved) };
+		return { kind: "unsupported", path: resolved, label, reason: "type" };
 	}
 	return {
 		kind: "document",
@@ -133,6 +167,56 @@ function resolveRelative(
 	};
 }
 
+/**
+ * An image link opens in the lightbox, read through the page's own asset
+ * route. That route serves only files below the token's directory (it refuses
+ * `..` and checks the realpath), so an image outside it is reported here
+ * instead of becoming a request the server would refuse. This check is
+ * lexical and only decides the UI; the server's check is the one that holds.
+ */
+function resolveImage(
+	path: string,
+	label: string,
+	assetRoot: HtmlLinkContext["assetRoot"],
+): HtmlLinkIntent {
+	if (!assetRoot?.dir || !assetRoot.url) {
+		return { kind: "unsupported", path, label, reason: "no-asset-root" };
+	}
+	const dir = assetRoot.dir.replace(/\\/g, "/").replace(/\/+$/, "");
+	if (!path.startsWith(`${dir}/`)) {
+		return { kind: "unsupported", path, label, reason: "outside-asset-root" };
+	}
+	const relative = path
+		.slice(dir.length + 1)
+		.split("/")
+		.map(encodeURIComponent)
+		.join("/");
+	const base = assetRoot.url.endsWith("/") ? assetRoot.url : `${assetRoot.url}/`;
+	return { kind: "image", path, url: `${base}${relative}`, label };
+}
+
+/**
+ * The asset route a served raw-HTML page is anchored at. Both servers install
+ * `<base href="/api/html-assets/<token>/">` first in `<head>` (re-anchoring a
+ * relative author base under the same token). Returns that token's route, or
+ * null when the page carries none (share links, an author's absolute base).
+ *
+ * Only the FIRST `<base>` element counts, as in the browser, and comments are
+ * skipped: a page cannot name a different token in a comment or a later base
+ * tag and have the lightbox read through it.
+ */
+const HTML_COMMENT_PATTERN = new RegExp("<!--[\\s\\S]*?(?:-->|$)", "g");
+
+export function htmlAssetRouteFromDocument(rawHtml: string | null | undefined): string | null {
+	if (!rawHtml) return null;
+	// RegExp constructor, not a literal: Semgrep's TS parser chokes on `<!--` in a regex literal.
+	const withoutComments = rawHtml.replace(HTML_COMMENT_PATTERN, "");
+	const baseTag = /<base\b[^>]*>/i.exec(withoutComments);
+	if (!baseTag) return null;
+	const match = /\bhref\s*=\s*["']?\/api\/html-assets\/([A-Za-z0-9_-]+)\//i.exec(baseTag[0]);
+	return match ? `${HTML_ASSET_ROUTE_PREFIX}/${match[1]}/` : null;
+}
+
 /**
  * Whether opening `path` lands on another raw-HTML surface rather than a
  * markdown one. `--markdown` sessions convert HTML on the way in, so nothing