@plannotator/ui 0.28.0 → 0.29.1

package/types.ts

@@ -25,6 +25,38 @@ export interface ImageAttachment {
   name: string;
 }
 
+/** DOM-relative text position used to restore a document annotation selection. */
+export interface AnnotationTextMeta {
+  parentTagName: string;
+  parentIndex: number;
+  textOffset: number;
+}
+
+/** Durable, media-specific location for a note created in the PR artifact viewer. */
+export type ArtifactAnnotationAnchor =
+  | {
+      kind: 'document';
+      originalText: string;
+      blockId: string;
+      startOffset: number;
+      endOffset: number;
+      startMeta?: AnnotationTextMeta;
+      endMeta?: AnnotationTextMeta;
+    }
+  | { kind: 'image'; x: number; y: number }
+  | { kind: 'video'; timestamp: number }
+  | { kind: 'page' };
+
+/** Context shared by description and comment annotations created on a PR artifact. */
+export interface ArtifactAnnotationMeta {
+  artifactId: string;
+  artifactName: string;
+  artifactUrl: string;
+  artifactKind: 'image' | 'gif' | 'video' | 'html' | 'markdown';
+  sourceUrl: string;
+  anchor: ArtifactAnnotationAnchor;
+}
+
 export interface Annotation {
   id: string;
   blockId: string; // Legacy - not used with web-highlighter
@@ -40,23 +72,56 @@ export interface Annotation {
   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
+  artifact?: ArtifactAnnotationMeta; // code-review artifact viewer anchor + source context
   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
+  htmlAnchor?: HtmlElementAnchor; // raw-HTML pinpoint: serialized element anchor for reliable restoration
+  htmlAdditionalTargets?: HtmlAnnotationTarget[]; // raw-HTML shift-click multi-select: extra elements this one comment covers (primary stays htmlAnchor/originalText)
   // web-highlighter metadata for cross-element selections
-  startMeta?: {
-    parentTagName: string;
-    parentIndex: number;
-    textOffset: number;
-  };
-  endMeta?: {
-    parentTagName: string;
-    parentIndex: number;
-    textOffset: number;
-  };
+  startMeta?: AnnotationTextMeta;
+  endMeta?: AnnotationTextMeta;
+}
+
+/**
+ * Serialized element anchor for annotations created on the raw-HTML surface
+ * (pinpoint mode). Built inside the sandboxed viewer bridge: a verified-unique
+ * CSS selector plus a fingerprint (tag + normalized text snapshot) used to
+ * fail closed when a weak selector no longer matches the same content.
+ * Additive — annotations without one restore via document-wide text search.
+ */
+export interface HtmlElementAnchor {
+  selector: string;
+  tagName: string;
+  text?: string;
+  /**
+   * The user's selected point inside the target element's rect, normalized to
+   * 0..1 on each axis. Placed comment markers reproject it against the
+   * element's CURRENT rect, so the marker follows the element through
+   * responsive movement instead of pinning stale pixels. Additive — anchors
+   * without one (older records, keyboard-driven selections) fall back to the
+   * target rect center.
+   */
+  point?: { x: number; y: number };
+}
+
+/**
+ * One additional element covered by a multi-target raw-HTML pinpoint comment
+ * (shift-click multi-select). Carries what the export and composer chips need
+ * even when anchoring failed closed: the semantic label from the pinpoint
+ * hover cascade and the element's text (or `[element: …]` description).
+ * Additive — annotations without the array behave exactly as before.
+ */
+export interface HtmlAnnotationTarget {
+  /** Semantic label from the hover-label cascade (e.g. "Button", "rowchip"). */
+  label?: string;
+  /** The target element's capped text, or an element description when text-less. */
+  text: string;
+  /** Element anchor for restoration; absent when the bridge failed closed. */
+  anchor?: HtmlElementAnchor;
 }
 
 export type AlertKind = 'note' | 'tip' | 'warning' | 'caution' | 'important';
@@ -122,6 +187,7 @@ export interface CommentAnnotation {
   text: string;           // the reviewer's note
   createdAt: number;
   prUrl?: string;         // the PR this note belongs to (see Annotation.prUrl)
+  artifact?: ArtifactAnnotationMeta; // optional artifact anchor within this source comment
 }
 
 export interface CodeAnnotation {
@@ -139,6 +205,15 @@ export interface CodeAnnotation {
   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)
+  /** Exact text highlighted when the comment was created inside an edit
+   *  session (captured from the editor selection). Exported alongside the
+   *  comment so the agent sees what was highlighted even when it differs
+   *  from the anchored diff lines. */
+  selectedText?: string;
+  /** True when the edit-session selection overlapped in-session edits: the
+   *  line anchor maps to the pristine lines those edits replace, so it is
+   *  approximate and the export labels it as such. */
+  selectedTextFromEdits?: boolean;
   createdAt: number;
   author?: string;
   source?: string; // External tool identifier (e.g., "eslint") — set when annotation comes from external API
@@ -159,6 +234,14 @@ export interface CodeAnnotation {
   commitSha?: string;
   /** The commit's one-line subject, captured for readable export labels. */
   commitSubject?: string;
+  /** GitButler target that supplied this annotation's line coordinates. */
+  gitButlerDiffType?: string;
+  /** Human-readable GitButler target label captured with the annotation. */
+  gitButlerDiffLabel?: string;
+  /** GitButler merge base active when the annotation was created. */
+  gitButlerBase?: string;
+  /** Exact server snapshot that supplied the GitButler line coordinates. */
+  gitButlerSnapshotId?: string;
 }
 
 /** Token-level metadata passed from selection to annotation creation. */

package/utils/agentSwitch.ts

@@ -1,8 +1,13 @@
 /**
  * Agent Switch Settings Utility
  *
- * Manages settings for automatic agent switching after plan approval.
- * Supports built-in agents (build), disabled, or custom agent names.
+ * Manages settings for automatic agent switching after plan approval and after
+ * sending code review feedback. Supports discovered agents, disabled, or custom
+ * agent names.
+ *
+ * The stored value is shared across surfaces, but the default when nothing is
+ * stored is surface-specific: plan approval keeps its historical hand-off to the
+ * build agent, while review feedback stays on the current agent.
  *
  * Uses cookies (not localStorage) because each hook invocation runs on a
  * random port, and localStorage is scoped by origin including port.
@@ -28,14 +33,32 @@ export const AGENT_OPTIONS: { value: string; label: string; description: string
   { value: 'disabled', label: 'Disabled', description: 'Stay on current agent after approval' },
 ];
 
-const DEFAULT_SETTINGS: AgentSwitchSettings = {
+/** UI surface asking for the setting — only affects the unset default. */
+export type AgentSwitchSurface = 'plan' | 'review';
+
+const PLAN_DEFAULT_SETTINGS: AgentSwitchSettings = {
   switchTo: 'build',
 };
 
+const REVIEW_DEFAULT_SETTINGS: AgentSwitchSettings = {
+  switchTo: 'disabled',
+};
+
+/**
+ * Default used when the user has never picked an agent switch setting.
+ * Plan approval hands off to the build agent (historical behavior); review
+ * feedback stays on the current agent.
+ */
+export function getAgentSwitchDefaults(surface: AgentSwitchSurface = 'plan'): AgentSwitchSettings {
+  return surface === 'review' ? REVIEW_DEFAULT_SETTINGS : PLAN_DEFAULT_SETTINGS;
+}
+
 /**
- * Get current agent switch settings from storage
+ * Get current agent switch settings from storage.
+ * An explicit user choice applies to every surface; only the unset default
+ * varies by surface.
  */
-export function getAgentSwitchSettings(): AgentSwitchSettings {
+export function getAgentSwitchSettings(surface: AgentSwitchSurface = 'plan'): AgentSwitchSettings {
   const stored = storage.getItem(STORAGE_KEY);
   const customName = storage.getItem(CUSTOM_NAME_KEY) || undefined;
 
@@ -43,7 +66,7 @@ export function getAgentSwitchSettings(): AgentSwitchSettings {
   if (stored) {
     return { switchTo: stored, customName };
   }
-  return DEFAULT_SETTINGS;
+  return getAgentSwitchDefaults(surface);
 }
 
 /**
@@ -67,5 +90,8 @@ export function getEffectiveAgentName(settings: AgentSwitchSettings): string | u
   if (settings.switchTo === 'custom' && settings.customName) {
     return settings.customName;
   }
-  return settings.switchTo; // 'build' or fallback
+  if (settings.switchTo === 'custom') {
+    return undefined;
+  }
+  return settings.switchTo;
 }