@plannotator/ui 0.22.0

package/types.ts

@@ -0,0 +1,264 @@
+export enum AnnotationType {
+  DELETION = 'DELETION',
+  COMMENT = 'COMMENT',
+  GLOBAL_COMMENT = 'GLOBAL_COMMENT',
+}
+
+export type EditorMode = 'selection' | 'comment' | 'redline' | 'quickLabel';
+
+export type InputMethod = 'drag' | 'pinpoint';
+
+/**
+ * Compactness of the Viewer action button labels (Image / Comment / Copy).
+ * Driven by measured plan-area width so the cluster collapses responsively
+ * when the side panel squeezes the plan.
+ *   full  → "Global comment" / "Copy plan"
+ *   short → "Comment" / "Copy"
+ *   icon  → labels hidden entirely
+ */
+export type ActionsLabelMode = 'full' | 'short' | 'icon';
+
+export type WideModeType = 'wide' | 'focus';
+
+export interface ImageAttachment {
+  path: string;
+  name: string;
+}
+
+export interface Annotation {
+  id: string;
+  blockId: string; // Legacy - not used with web-highlighter
+  startOffset: number; // Legacy
+  endOffset: number; // Legacy
+  type: AnnotationType;
+  text?: string; // For comments
+  originalText: string; // The text that was selected
+  createdA: number;
+  author?: string; // Tater identity for collaborative sharing
+  source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API
+  images?: ImageAttachment[]; // Attached images with human-readable names
+  isQuickLabel?: boolean; // true if created via quick label chip
+  quickLabelTip?: string; // optional instruction tip from the label definition
+  diffContext?: 'added' | 'removed' | 'modified'; // set when annotation created in plan diff view
+  mathTargets?: Array<{
+    blockId: string;
+    tex: string;
+    displayMode: boolean;
+  }>; // math elements covered by a mixed text+formula selection
+  prUrl?: string; // code-review PR mode: the PR this note belongs to, so it isn't shown/exported against another PR after an in-place switch
+  // web-highlighter metadata for cross-element selections
+  startMeta?: {
+    parentTagName: string;
+    parentIndex: number;
+    textOffset: number;
+  };
+  endMeta?: {
+    parentTagName: string;
+    parentIndex: number;
+    textOffset: number;
+  };
+}
+
+export type AlertKind = 'note' | 'tip' | 'warning' | 'caution' | 'important';
+
+export interface Block {
+  id: string;
+  type: 'paragraph' | 'heading' | 'blockquote' | 'list-item' | 'code' | 'hr' | 'table' | 'html' | 'directive' | 'math';
+  content: string; // Plain text, or raw (unsanitized) HTML for type === 'html'
+  level?: number; // For headings (1-6) or list indentation
+  language?: string; // For code blocks (e.g., 'rust', 'typescript')
+  checked?: boolean; // For checkbox list items (true = checked, false = unchecked, undefined = not a checkbox)
+  ordered?: boolean; // For list items: true when source marker was \d+.
+  orderedStart?: number; // For ordered list items: integer parsed from the marker (e.g. 5 for "5.")
+  alertKind?: AlertKind; // For blockquotes starting with [!NOTE] / [!TIP] / etc.
+  directiveKind?: string; // For directive containers (e.g. ':::note' → 'note')
+  order: number; // Sorting order
+  startLine: number; // 1-based line number in source
+  sourceLineCount?: number; // Number of source lines consumed when it differs from content lines
+}
+
+export interface DiffResult {
+  original: string;
+  modified: string;
+  diffText: string;
+}
+
+// Code Review Types
+export type CodeAnnotationType = 'comment' | 'suggestion' | 'concern';
+// 'general' is a review-level comment tied to no file and no line. For 'general'
+// (and the file-less case) filePath is "" and lineStart/lineEnd are 0 — consumers
+// must branch on scope, never read those sentinels as a real path or row.
+export type CodeAnnotationScope = 'line' | 'file' | 'general';
+
+/** Conventional Comments label — see https://conventionalcomments.org */
+export type ConventionalLabel =
+  | 'praise'
+  | 'nitpick'
+  | 'suggestion'
+  | 'issue'
+  | 'todo'
+  | 'question'
+  | 'thought'
+  | 'chore'
+  | 'note'
+  | 'typo'
+  | 'polish'
+  | (string & {}); // Allow custom labels while preserving autocomplete for built-ins
+
+/** Conventional Comments decoration (parenthesized modifier) */
+export type ConventionalDecoration = 'blocking' | 'non-blocking' | 'if-minor';
+
+/**
+ * A note attached to a whole PR comment/review/thread (code-review Phase 2).
+ * Button-driven (not text-anchored): the reviewer clicks "Annotate" on a card
+ * and leaves a note. The comment body travels with it so the agent — which
+ * can't see PR discussion — receives the full context on export.
+ */
+export interface CommentAnnotation {
+  id: string;
+  commentId: string;      // the timeline entry id (matches data-comment-id on the card)
+  commentAuthor: string;
+  commentBody: string;
+  text: string;           // the reviewer's note
+  createdAt: number;
+  prUrl?: string;         // the PR this note belongs to (see Annotation.prUrl)
+}
+
+export interface CodeAnnotation {
+  id: string;
+  type: CodeAnnotationType;
+  scope?: CodeAnnotationScope; // Defaults to 'line' for backward compatibility
+  filePath: string;
+  lineStart: number;
+  lineEnd: number;
+  side: 'old' | 'new'; // Maps to 'deletions' | 'additions' in @pierre/diffs
+  text?: string;
+  images?: ImageAttachment[];
+  suggestedCode?: string;
+  originalCode?: string; // Original selected lines for suggestion diff
+  charStart?: number; // Character offset within lineStart (token-level selection)
+  charEnd?: number; // Character offset within lineEnd (token-level selection)
+  tokenText?: string; // Selected token/span text (token-level selection)
+  createdAt: number;
+  author?: string;
+  source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API
+  severity?: 'important' | 'nit' | 'pre_existing'; // Agent review severity (Claude)
+  reasoning?: string; // Validation chain — how the issue was confirmed (Claude)
+  reviewProfileLabel?: string; // Custom review that produced this finding — shown as a tag
+  conventionalLabel?: ConventionalLabel;
+  decorations?: ConventionalDecoration[];
+  prUrl?: string;
+  prNumber?: number;
+  prTitle?: string;
+  prRepo?: string;
+  diffScope?: 'layer' | 'full-stack';
+  /** Set when the annotation was created on a commit:<sha> diff (Commits
+   *  panel). Line numbers anchor to THAT commit's diff-vs-parent — the export
+   *  labels the annotation with its commit when sent from any other diff, so
+   *  the agent never reads historical line numbers against the current diff. */
+  commitSha?: string;
+  /** The commit's one-line subject, captured for readable export labels. */
+  commitSubject?: string;
+}
+
+/** Token-level metadata passed from selection to annotation creation. */
+export interface TokenAnnotationMeta {
+  charStart: number;
+  charEnd: number;
+  tokenText: string;
+}
+
+/** Severity display styles — shared between agent detail panel and inline diff annotations. */
+export const SEVERITY_STYLES: Record<string, { dot: string; label: string }> = {
+  important: { dot: 'bg-destructive', label: 'Important' },
+  nit: { dot: 'bg-amber-500', label: 'Nit' },
+  pre_existing: { dot: 'bg-muted-foreground', label: 'Pre-existing' },
+};
+
+// For @pierre/diffs integration
+export interface DiffAnnotationMetadata {
+  annotationId: string;
+  type: CodeAnnotationType;
+  text?: string;
+  suggestedCode?: string;
+  originalCode?: string;
+  author?: string;
+  severity?: 'important' | 'nit' | 'pre_existing';
+  reasoning?: string;
+  conventionalLabel?: ConventionalLabel;
+  decorations?: ConventionalDecoration[];
+  // Shared comment-meta fields (so the inline diff card shows the same identity
+  // row — author, time, badges — as the sidebar and file-banner cards).
+  createdAt?: number;
+  reviewProfileLabel?: string;
+  source?: string;
+  /** Precomputed clipboard text (location prefix + body + reasoning) so the
+   *  inline copy action matches the sidebar/banner — the inline card only has
+   *  the projected metadata, not the full annotation. */
+  copyText?: string;
+  // AI marker fields (set when kind === 'ai-marker')
+  kind?: 'annotation' | 'ai-marker';
+  questionId?: string;
+  promptPreview?: string;
+  hasResponse?: boolean;
+  isStreaming?: boolean;
+}
+
+export interface SelectedLineRange {
+  start: number;
+  end: number;
+  side: 'deletions' | 'additions';
+  endSide?: 'deletions' | 'additions';
+}
+
+// ---------------------------------------------------------------------------
+// AI Chat (inline AI on diffs)
+// ---------------------------------------------------------------------------
+
+export interface AIQuestion {
+  id: string;
+  prompt: string;
+  scope?: {
+    kind: 'general' | 'selection';
+    label?: string;
+    text?: string;
+    sourcePath?: string;
+  };
+  /** undefined = general question (no file scope) */
+  filePath?: string;
+  /** undefined + filePath present = file-scoped; with filePath = line-scoped */
+  lineStart?: number;
+  lineEnd?: number;
+  side?: 'old' | 'new';
+  selectedCode?: string;
+  createdAt: number;
+}
+
+export interface AIResponse {
+  questionId: string;
+  text: string;
+  isStreaming: boolean;
+  error?: string;
+  createdAt: number;
+}
+
+export interface VaultNode {
+  name: string;
+  path: string; // relative path within vault
+  type: "file" | "folder";
+  children?: VaultNode[];
+}
+
+export type { EditorAnnotation } from '@plannotator/core/types';
+
+export type {
+  ExternalAnnotationEvent,
+} from '@plannotator/core/external-annotation';
+
+export type {
+  AgentJobInfo,
+  AgentJobEvent,
+  AgentJobStatus,
+  AgentCapability,
+  AgentCapabilities,
+} from '@plannotator/core/agent-jobs';

package/utils/agentSwitch.ts

@@ -0,0 +1,71 @@
+/**
+ * Agent Switch Settings Utility
+ *
+ * Manages settings for automatic agent switching after plan approval.
+ * Supports built-in agents (build), disabled, or custom agent names.
+ *
+ * Uses cookies (not localStorage) because each hook invocation runs on a
+ * random port, and localStorage is scoped by origin including port.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-agent-switch';
+const CUSTOM_NAME_KEY = 'plannotator-agent-custom';
+
+// AgentSwitchOption is now a string to support dynamic agent names from OpenCode
+export type AgentSwitchOption = string;
+
+export interface AgentSwitchSettings {
+  switchTo: AgentSwitchOption;
+  customName?: string;
+}
+
+// Fallback options when API is unavailable or for non-OpenCode origins
+export const AGENT_OPTIONS: { value: string; label: string; description: string }[] = [
+  { value: 'build', label: 'Build', description: 'Switch to build agent after approval' },
+  { value: 'custom', label: 'Custom', description: 'Switch to a custom agent after approval' },
+  { value: 'disabled', label: 'Disabled', description: 'Stay on current agent after approval' },
+];
+
+const DEFAULT_SETTINGS: AgentSwitchSettings = {
+  switchTo: 'build',
+};
+
+/**
+ * Get current agent switch settings from storage
+ */
+export function getAgentSwitchSettings(): AgentSwitchSettings {
+  const stored = storage.getItem(STORAGE_KEY);
+  const customName = storage.getItem(CUSTOM_NAME_KEY) || undefined;
+
+  // Accept any non-empty string (supports dynamic agent names from OpenCode)
+  if (stored) {
+    return { switchTo: stored, customName };
+  }
+  return DEFAULT_SETTINGS;
+}
+
+/**
+ * Save agent switch settings to storage
+ */
+export function saveAgentSwitchSettings(settings: AgentSwitchSettings): void {
+  storage.setItem(STORAGE_KEY, settings.switchTo);
+  if (settings.customName) {
+    storage.setItem(CUSTOM_NAME_KEY, settings.customName);
+  }
+}
+
+/**
+ * Get the effective agent name for switching
+ * Returns undefined if disabled, otherwise returns the agent name
+ */
+export function getEffectiveAgentName(settings: AgentSwitchSettings): string | undefined {
+  if (settings.switchTo === 'disabled') {
+    return undefined;
+  }
+  if (settings.switchTo === 'custom' && settings.customName) {
+    return settings.customName;
+  }
+  return settings.switchTo; // 'build' or fallback
+}

package/utils/aiChatFormat.ts

@@ -0,0 +1,33 @@
+import { createElement, type ReactNode } from 'react';
+import { marked } from 'marked';
+import DOMPurify from 'dompurify';
+
+export function renderChatMarkdown(text: string): ReactNode {
+  const html = marked.parse(text, { async: false, breaks: true }) as string;
+  const clean = DOMPurify.sanitize(html, {
+    ALLOWED_TAGS: [
+      'p', 'br', 'strong', 'em', 'code', 'pre', 'ul', 'ol', 'li',
+      'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'hr', 'a', 'blockquote',
+    ],
+    ALLOWED_ATTR: ['href', 'rel', 'class'],
+  });
+
+  return createElement('div', {
+    className: 'ai-markdown',
+    dangerouslySetInnerHTML: { __html: clean },
+  });
+}
+
+export function formatRelativeTime(ts: number): string {
+  const seconds = Math.max(0, Math.floor((Date.now() - ts) / 1000));
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (seconds < 60) return 'now';
+  if (minutes < 60) return `${minutes}m`;
+  if (hours < 24) return `${hours}h`;
+  if (days < 7) return `${days}d`;
+
+  return new Date(ts).toLocaleDateString(undefined, { month: 'short', day: 'numeric' });
+}

package/utils/aiPrompt.ts

@@ -0,0 +1,29 @@
+/**
+ * Compose the per-message "changes under review" preamble for Ask AI.
+ *
+ * `reviewContext` is the server-built changeset description (from the shared
+ * agent-review prompt machine — the same text the launchable review jobs get).
+ * It is either a short git command to run, or a pasted diff for view modes git
+ * can't reproduce (stacked-PR full-stack, hide-whitespace, untracked, workspace).
+ *
+ * On the first message — and whenever the user switches what they're viewing
+ * mid-chat, so the context string changes — we inject the full block so the
+ * agent always sees exactly the on-screen changeset. On an unchanged follow-up
+ * we avoid re-pasting a large diff (the conversation history already carries it)
+ * and emit only a short reminder; a short command-based context is cheap enough
+ * to restate every turn, which keeps the agent oriented.
+ */
+export function buildReviewContextPreamble(
+  reviewContext: string | null | undefined,
+  opts: { changed: boolean },
+): string {
+  const ctx = reviewContext?.trim();
+  if (!ctx) return '';
+  if (opts.changed) return ctx;
+  // Unchanged follow-up. A pasted diff (fenced code block) must NOT be repeated
+  // every turn; a command-based context is short, so restating it is fine.
+  const isPasted = ctx.includes('```');
+  return isPasted
+    ? '[Still reviewing the same changes shown earlier in this conversation.]'
+    : ctx;
+}

package/utils/aiProvider.ts

@@ -0,0 +1,217 @@
+/**
+ * AI Provider Settings Utility
+ *
+ * Manages the user's default AI provider and per-provider model preferences.
+ * Uses cookies (not localStorage) because each hook invocation runs on a
+ * random port, and localStorage is scoped by origin including port.
+ */
+
+import { storage } from './storage';
+import { AGENT_CONFIG, getAgentAIProviderTypes, type Origin } from '@plannotator/core/agents';
+
+const PROVIDER_KEY = 'plannotator-ai-provider';
+const MODELS_KEY = 'plannotator-ai-models';
+const PROVIDER_BY_ORIGIN_KEY = 'plannotator-ai-provider-by-origin';
+
+export interface AIProviderModel {
+  id: string;
+  label: string;
+  default?: boolean;
+  /** Reasoning-effort options this model supports (provider-reported, e.g. Codex). */
+  reasoningEfforts?: { id: string; label: string }[];
+  /** The model's default reasoning effort. */
+  defaultReasoningEffort?: string;
+}
+
+export interface AIProviderOption {
+  id: string;
+  name: string;
+  models?: AIProviderModel[];
+}
+
+export interface AIProviderSettings {
+  /** The provider instance ID to use, or null for server default. */
+  providerId: string | null;
+  /** Preferred model per provider. Key = provider instance ID, value = model ID. */
+  preferredModels: Record<string, string>;
+  /** Preferred provider per detected agent origin. Key = Origin, value = provider instance ID. */
+  providerByOrigin: Partial<Record<Origin, string>>;
+}
+
+export interface AIProviderSelection {
+  providerId: string | null;
+  model: string | null;
+}
+
+export function originHasDedicatedAIProvider(origin: Origin | null | undefined): boolean {
+  return getAgentAIProviderTypes(origin).length > 0;
+}
+
+/**
+ * Get current AI provider settings from storage
+ */
+export function getAIProviderSettings(): AIProviderSettings {
+  const providerId = storage.getItem(PROVIDER_KEY) || null;
+  let preferredModels: Record<string, string> = {};
+  let providerByOrigin: Partial<Record<Origin, string>> = {};
+  try {
+    const raw = storage.getItem(MODELS_KEY);
+    if (raw) preferredModels = JSON.parse(raw);
+  } catch {
+    // Invalid JSON — start fresh
+  }
+  try {
+    const raw = storage.getItem(PROVIDER_BY_ORIGIN_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object') {
+        for (const [origin, value] of Object.entries(parsed)) {
+          if (origin in AGENT_CONFIG && typeof value === 'string') {
+            providerByOrigin[origin as Origin] = value;
+          }
+        }
+      }
+    }
+  } catch {
+    // Invalid JSON — start fresh
+  }
+  return { providerId, preferredModels, providerByOrigin };
+}
+
+/**
+ * Save AI provider settings to storage
+ */
+export function saveAIProviderSettings(settings: AIProviderSettings): void {
+  if (settings.providerId) {
+    storage.setItem(PROVIDER_KEY, settings.providerId);
+  } else {
+    storage.removeItem(PROVIDER_KEY);
+  }
+  storage.setItem(MODELS_KEY, JSON.stringify(settings.preferredModels));
+  const providerByOrigin = settings.providerByOrigin ?? {};
+  if (Object.keys(providerByOrigin).length > 0) {
+    storage.setItem(PROVIDER_BY_ORIGIN_KEY, JSON.stringify(providerByOrigin));
+  } else {
+    storage.removeItem(PROVIDER_BY_ORIGIN_KEY);
+  }
+}
+
+/**
+ * Get the preferred model for a specific provider
+ */
+export function getPreferredModel(providerId: string): string | null {
+  const { preferredModels } = getAIProviderSettings();
+  return preferredModels[providerId] ?? null;
+}
+
+/**
+ * Save the preferred model for a specific provider (without changing other preferences)
+ */
+export function savePreferredModel(providerId: string, modelId: string): void {
+  const settings = getAIProviderSettings();
+  settings.preferredModels[providerId] = modelId;
+  saveAIProviderSettings(settings);
+}
+
+/**
+ * Find the first available provider that naturally matches the current origin.
+ * Instance IDs can be custom, so we match both the registry ID and provider type.
+ */
+export function findOriginAIProvider(
+  providers: AIProviderOption[],
+  origin: Origin | null | undefined,
+): AIProviderOption | null {
+  const providerTypes = getAgentAIProviderTypes(origin);
+  for (const providerType of providerTypes) {
+    const provider = providers.find(p => p.id === providerType || p.name === providerType);
+    if (provider) return provider;
+  }
+  return null;
+}
+
+export function resolveAIModelForProvider(
+  provider: AIProviderOption | null | undefined,
+  preferredModels: Record<string, string>,
+): string | null {
+  if (!provider) return null;
+  const models = provider.models ?? [];
+  const modelIds = new Set(models.map(m => m.id));
+  const preferredModel = preferredModels[provider.id];
+  if (preferredModel && (modelIds.size === 0 || modelIds.has(preferredModel))) {
+    return preferredModel;
+  }
+  const defaultModel = models.find(m => m.default) ?? models[0];
+  return defaultModel?.id ?? null;
+}
+
+export function resolveAIProviderSelection(options: {
+  providers: AIProviderOption[];
+  origin?: Origin | null;
+  settings?: AIProviderSettings;
+  serverDefaultProvider?: string | null;
+}): AIProviderSelection {
+  const { providers, origin, serverDefaultProvider } = options;
+  const settings = options.settings ?? getAIProviderSettings();
+  if (providers.length === 0) return { providerId: null, model: null };
+
+  const byId = (id: string | null | undefined) =>
+    id ? providers.find(provider => provider.id === id) ?? null : null;
+
+  const provider =
+    byId(origin ? settings.providerByOrigin[origin] : null) ??
+    findOriginAIProvider(providers, origin) ??
+    byId(settings.providerId) ??
+    byId(serverDefaultProvider) ??
+    providers[0] ??
+    null;
+
+  return {
+    providerId: provider?.id ?? null,
+    model: resolveAIModelForProvider(provider, settings.preferredModels),
+  };
+}
+
+export function saveAIProviderSelection(options: {
+  providerId: string | null;
+  model?: string | null;
+  origin?: Origin | null;
+  settings?: AIProviderSettings;
+}): void {
+  const settings = options.settings ?? getAIProviderSettings();
+  saveAIProviderSettings(applyAIProviderSelection(settings, options));
+}
+
+export function applyAIProviderSelection(
+  settings: AIProviderSettings,
+  options: {
+    providerId: string | null;
+    model?: string | null;
+    origin?: Origin | null;
+  },
+): AIProviderSettings {
+  const preferredModels = { ...settings.preferredModels };
+  if (options.providerId && options.model) {
+    preferredModels[options.providerId] = options.model;
+  }
+
+  const providerByOrigin = { ...settings.providerByOrigin };
+  let providerId = settings.providerId;
+  const hasOriginDefault = originHasDedicatedAIProvider(options.origin);
+
+  if (options.origin && hasOriginDefault) {
+    if (options.providerId) {
+      providerByOrigin[options.origin] = options.providerId;
+    } else {
+      delete providerByOrigin[options.origin];
+    }
+  } else {
+    providerId = options.providerId;
+  }
+
+  return {
+    ...settings,
+    providerId,
+    preferredModels,
+    providerByOrigin,
+  };
+}

package/utils/anchors.ts

@@ -0,0 +1,11 @@
+export function decodeAnchorHash(hash: string): string | null {
+  const raw = hash.replace(/^#/, '').split('?')[0]?.trim();
+  if (!raw) return null;
+
+  try {
+    const decoded = decodeURIComponent(raw).trim();
+    return decoded || null;
+  } catch {
+    return raw;
+  }
+}

package/utils/annotateAgentTerminal.ts

@@ -0,0 +1,29 @@
+import type { AgentTerminalAgent } from "@plannotator/core/agent-terminal";
+import { storage } from "./storage";
+
+const DEFAULT_AGENT_KEY = "plannotator-annotate-agent-terminal-default";
+
+export function getSavedAnnotateAgentId(): string | null {
+  return storage.getItem(DEFAULT_AGENT_KEY);
+}
+
+export function saveAnnotateAgentId(agentId: string): void {
+  storage.setItem(DEFAULT_AGENT_KEY, agentId);
+}
+
+export function resolveAnnotateAgentId(
+  agents: AgentTerminalAgent[],
+  savedAgentId: string | null,
+): string {
+  const availableAgents = agents.filter((agent) => agent.available);
+  if (savedAgentId && availableAgents.some((agent) => agent.id === savedAgentId)) {
+    return savedAgentId;
+  }
+  return availableAgents[0]?.id ?? "";
+}
+
+export function resolveAgentTerminalWebSocketUrl(path: string): string {
+  const url = new URL(path, window.location.href);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString();
+}