@plannotator/ui 0.22.0

package/utils/annotationHelpers.ts

@@ -0,0 +1,101 @@
+import type { Block, Annotation } from '../types';
+
+/**
+ * Calculate annotation counts per section (grouped by headings)
+ * A section includes all blocks from a heading until the next heading of same/higher level
+ */
+export function getAnnotationCountBySection(
+  blocks: Block[],
+  annotations: Annotation[]
+): Map<string, number> {
+  const counts = new Map<string, number>();
+  
+  // Find all headings
+  const headings = blocks.filter(b => b.type === 'heading' && (b.level ?? 0) <= 3);
+  
+  if (headings.length === 0) return counts;
+  
+  // For each heading, determine which blocks belong to its section
+  for (let i = 0; i < headings.length; i++) {
+    const heading = headings[i];
+    const currentLevel = heading.level ?? 1;
+    const startLine = heading.startLine;
+    
+    // Find the end of this section (next heading of same/higher level)
+    let endLine = Infinity;
+    for (let j = i + 1; j < headings.length; j++) {
+      const nextHeading = headings[j];
+      const nextLevel = nextHeading.level ?? 1;
+      if (nextLevel <= currentLevel) {
+        endLine = nextHeading.startLine;
+        break;
+      }
+    }
+    
+    // Count annotations in blocks within this section
+    let count = 0;
+    for (const block of blocks) {
+      if (block.startLine >= startLine && block.startLine < endLine) {
+        // Count annotations that belong to this block
+        const blockAnnotations = annotations.filter(a => a.blockId === block.id);
+        count += blockAnnotations.length;
+      }
+    }
+    
+    counts.set(heading.id, count);
+  }
+  
+  return counts;
+}
+
+/**
+ * Build hierarchical TOC structure from flat blocks array
+ */
+export interface TocItem {
+  id: string;
+  content: string;
+  level: number;
+  order: number;
+  children: TocItem[];
+  annotationCount: number;
+}
+
+export function buildTocHierarchy(
+  blocks: Block[],
+  annotationCounts: Map<string, number>
+): TocItem[] {
+  const headings = blocks
+    .filter(b => b.type === 'heading' && (b.level ?? 0) <= 3)
+    .sort((a, b) => a.order - b.order);
+  
+  const root: TocItem[] = [];
+  const stack: TocItem[] = [];
+  
+  for (const heading of headings) {
+    const item: TocItem = {
+      id: heading.id,
+      content: heading.content,
+      level: heading.level ?? 1,
+      order: heading.order,
+      children: [],
+      annotationCount: annotationCounts.get(heading.id) ?? 0,
+    };
+    
+    // Find the correct parent based on level
+    while (stack.length > 0 && stack[stack.length - 1].level >= item.level) {
+      stack.pop();
+    }
+    
+    if (stack.length === 0) {
+      // Top-level item
+      root.push(item);
+    } else {
+      // Child of the last item in stack
+      stack[stack.length - 1].children.push(item);
+    }
+    
+    stack.push(item);
+  }
+  
+  return root;
+}

package/utils/bear.ts

@@ -0,0 +1,59 @@
+/**
+ * Bear Notes Integration Utility
+ *
+ * Manages settings for auto-saving plans to Bear.
+ * Uses x-callback-url protocol - no vault detection needed.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY_ENABLED = 'plannotator-bear-enabled';
+const STORAGE_KEY_CUSTOM_TAGS = 'plannotator-bear-custom-tags';
+const STORAGE_KEY_TAG_POSITION = 'plannotator-bear-tag-position';
+const STORAGE_KEY_AUTOSAVE = 'plannotator-bear-autosave';
+
+export type TagPosition = 'prepend' | 'append';
+
+/**
+ * Bear integration settings
+ */
+export interface BearSettings {
+  enabled: boolean;
+  customTags: string;
+  tagPosition: TagPosition;
+  autoSave: boolean;
+}
+
+/**
+ * Get current Bear settings from storage
+ */
+export function getBearSettings(): BearSettings {
+  return {
+    enabled: storage.getItem(STORAGE_KEY_ENABLED) === 'true',
+    customTags: storage.getItem(STORAGE_KEY_CUSTOM_TAGS) ?? '',
+    tagPosition: (storage.getItem(STORAGE_KEY_TAG_POSITION) as TagPosition) || 'append',
+    autoSave: storage.getItem(STORAGE_KEY_AUTOSAVE) === 'true',
+  };
+}
+
+/**
+ * Save Bear settings to storage
+ */
+export function saveBearSettings(settings: BearSettings): void {
+  storage.setItem(STORAGE_KEY_ENABLED, String(settings.enabled));
+  storage.setItem(STORAGE_KEY_CUSTOM_TAGS, settings.customTags);
+  storage.setItem(STORAGE_KEY_TAG_POSITION, settings.tagPosition);
+  storage.setItem(STORAGE_KEY_AUTOSAVE, String(settings.autoSave));
+}
+
+/**
+ * Normalize raw tag input to clean kebab-case, comma-separated string.
+ * Strips # prefixes, lowercases, replaces spaces with hyphens, removes invalid chars.
+ */
+export function normalizeTags(raw: string): string {
+  return raw
+    .split(',')
+    .map(t => t.trim().replace(/^#+/, '').toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9\-\/]/g, '').replace(/\/+/g, '/').replace(/^\/|\/$/g, ''))
+    .filter(Boolean)
+    .join(', ');
+}

package/utils/blockTargeting.ts

@@ -0,0 +1,240 @@
+/**
+ * Block Targeting — resolves which element to annotate in pinpoint mode.
+ *
+ * Walks from the element under the cursor upward through the block tree
+ * to find the most specific targetable element (inline, cell, or block).
+ */
+
+/** Elements that should never be targeted */
+const SKIP_SELECTORS = [
+  '.annotation-toolbar',
+  '.annotation-highlight',
+  'mark[data-bind-id]',
+  'button',
+  '[data-pinpoint-ignore]',
+].join(',');
+
+/** Inline elements that are individually targetable within a block */
+const INLINE_TARGETS = new Set(['STRONG', 'EM', 'A']);
+
+/** Table cell elements */
+const CELL_TARGETS = new Set(['TD', 'TH']);
+
+export interface PinpointTarget {
+  /** The DOM element to highlight and select */
+  element: HTMLElement;
+  /** The data-block-id of the parent block */
+  blockId: string;
+  /** Human-readable label for the hover tooltip */
+  label: string;
+  /** Whether this is a code block (needs special annotation path) */
+  isCodeBlock: boolean;
+}
+
+/** Edge-zone threshold for table hover (px). Covers the outermost cell padding
+ *  area (cells have px-3/py-2 = 12px/8px padding) so you need to aim at actual
+ *  text content to target a specific cell. */
+const TABLE_EDGE_ZONE = 22;
+
+/**
+ * Given a mousemove/click target element, find the best annotation target
+ * within the viewer container. Optionally accepts mouse coordinates for
+ * edge-zone detection (tables).
+ */
+export function resolvePinpointTarget(
+  target: HTMLElement,
+  container: HTMLElement,
+  mousePos?: { clientX: number; clientY: number },
+): PinpointTarget | null {
+  // Skip toolbar, buttons, existing annotations
+  if (target.closest(SKIP_SELECTORS)) return null;
+  if (!container.contains(target)) return null;
+
+  // Group detection: cursor is in the gap/gutter of a list group wrapper
+  const groupEl = target.closest('[data-pinpoint-group]') as HTMLElement | null;
+  if (groupEl && container.contains(groupEl) && !target.closest('[data-block-id]')) {
+    const groupType = groupEl.getAttribute('data-pinpoint-group');
+    const label = groupType === 'list' ? 'list' : groupType === 'blockquote' ? 'blockquote group' : 'group';
+    return { element: groupEl, blockId: '', label, isCodeBlock: false };
+  }
+
+  // Find the parent block
+  const blockEl = target.closest('[data-block-id]') as HTMLElement | null;
+  if (!blockEl || !container.contains(blockEl)) return null;
+
+  const blockId = blockEl.getAttribute('data-block-id')!;
+
+  // Skip hr (no text content)
+  if (blockEl.tagName === 'HR') return null;
+
+  // Code block detection: pre > code.hljs
+  const codeEl = blockEl.querySelector('pre > code.hljs');
+  if (codeEl && (target === codeEl || codeEl.contains(target) || target.closest('pre'))) {
+    return {
+      element: blockEl,
+      blockId,
+      label: getCodeBlockLabel(blockEl),
+      isCodeBlock: true,
+    };
+  }
+
+  // Table edge-zone detection: edges target whole table or row
+  const tableEl = blockEl.querySelector('table');
+  if (tableEl && mousePos) {
+    const tableRect = tableEl.getBoundingClientRect();
+    const nearLeft = mousePos.clientX - tableRect.left < TABLE_EDGE_ZONE;
+    const nearRight = tableRect.right - mousePos.clientX < TABLE_EDGE_ZONE;
+    const nearTop = mousePos.clientY - tableRect.top < TABLE_EDGE_ZONE;
+    const nearBottom = tableRect.bottom - mousePos.clientY < TABLE_EDGE_ZONE;
+
+    // Top/bottom edge → whole table
+    if (nearTop || nearBottom) {
+      return { element: blockEl, blockId, label: 'table', isCodeBlock: false };
+    }
+
+    // Left/right edge → the row at this Y position
+    if (nearLeft || nearRight) {
+      const row = findRowAtY(tableEl, mousePos.clientY);
+      if (row) {
+        return { element: row, blockId, label: getRowLabel(row), isCodeBlock: false };
+      }
+      return { element: blockEl, blockId, label: 'table', isCodeBlock: false };
+    }
+  }
+
+  // Inline code (not inside a code block) — target the <code> element
+  if (target.tagName === 'CODE' && !target.classList.contains('hljs')) {
+    const text = target.textContent?.trim() || '';
+    if (text) {
+      return {
+        element: target,
+        blockId,
+        label: `code: \`${truncate(text, 30)}\``,
+        isCodeBlock: false,
+      };
+    }
+  }
+
+  // Inline elements: strong, em, a
+  if (INLINE_TARGETS.has(target.tagName)) {
+    const text = target.textContent?.trim() || '';
+    if (text) {
+      return {
+        element: target,
+        blockId,
+        label: getInlineLabel(target, text),
+        isCodeBlock: false,
+      };
+    }
+  }
+
+  // Table cells (only reached when cursor is deep inside, not near edge)
+  if (CELL_TARGETS.has(target.tagName)) {
+    return {
+      element: target,
+      blockId,
+      label: 'table cell',
+      isCodeBlock: false,
+    };
+  }
+  // Check if inside a table cell
+  const cell = target.closest('td, th') as HTMLElement | null;
+  if (cell && blockEl.contains(cell)) {
+    return {
+      element: cell,
+      blockId,
+      label: 'table cell',
+      isCodeBlock: false,
+    };
+  }
+
+  // List item — target the content span (second child), not the bullet
+  if (blockEl.querySelector('.select-none')) {
+    // This is a list item with a bullet. Find the content span.
+    const contentSpan = blockEl.children[1] as HTMLElement | undefined;
+    if (contentSpan && (contentSpan === target || contentSpan.contains(target))) {
+      return {
+        element: contentSpan,
+        blockId,
+        label: getListItemLabel(contentSpan),
+        isCodeBlock: false,
+      };
+    }
+    // Clicked on the bullet area — still target the content span
+    if (contentSpan) {
+      return {
+        element: contentSpan,
+        blockId,
+        label: getListItemLabel(contentSpan),
+        isCodeBlock: false,
+      };
+    }
+  }
+
+  // Fall back to the full block
+  return {
+    element: blockEl,
+    blockId,
+    label: getBlockLabel(blockEl),
+    isCodeBlock: false,
+  };
+}
+
+function getInlineLabel(el: HTMLElement, text: string): string {
+  switch (el.tagName) {
+    case 'STRONG': return `bold: "${truncate(text, 30)}"`;
+    case 'EM': return `italic: "${truncate(text, 30)}"`;
+    case 'A': return `link: "${truncate(text, 25)}"`;
+    default: return truncate(text, 30);
+  }
+}
+
+function getBlockLabel(el: HTMLElement): string {
+  const tag = el.tagName.toLowerCase();
+  const text = el.textContent?.trim() || '';
+
+  if (el.querySelector('table')) return 'table';
+  if (el.dataset.blockType === 'heading' || /^h[1-6]$/.test(tag)) {
+    return `heading: "${truncate(text, 35)}"`;
+  }
+  if (tag === 'blockquote') return `blockquote: "${truncate(text, 30)}"`;
+  if (tag === 'p') return text ? `paragraph: "${truncate(text, 35)}"` : 'paragraph';
+  return truncate(text, 35) || tag;
+}
+
+function getListItemLabel(contentSpan: HTMLElement): string {
+  const text = contentSpan.textContent?.trim() || '';
+  return text ? `list item: "${truncate(text, 30)}"` : 'list item';
+}
+
+function getCodeBlockLabel(blockEl: HTMLElement): string {
+  const codeEl = blockEl.querySelector('code');
+  const lang = codeEl?.className?.match(/language-(\S+)/)?.[1];
+  return lang ? `code block (${lang})` : 'code block';
+}
+
+/** Find the table row whose bounding box contains the given Y coordinate */
+function findRowAtY(tableEl: HTMLTableElement, clientY: number): HTMLTableRowElement | null {
+  const rows = tableEl.querySelectorAll('tr');
+  for (const row of rows) {
+    const rect = row.getBoundingClientRect();
+    if (clientY >= rect.top && clientY <= rect.bottom) {
+      return row;
+    }
+  }
+  return null;
+}
+
+/** Human-readable label for a table row */
+function getRowLabel(row: HTMLTableRowElement): string {
+  // Header row
+  if (row.querySelector('th')) return 'table header row';
+  // Body row — use first cell text as hint
+  const firstCell = row.querySelector('td');
+  const text = firstCell?.textContent?.trim() || '';
+  return text ? `row: "${truncate(text, 25)}"` : 'table row';
+}
+
+function truncate(text: string, max: number): string {
+  return text.length > max ? text.slice(0, max) + '...' : text;
+}

package/utils/callback.ts

@@ -0,0 +1,99 @@
+/**
+ * Bot callback integration for Plannotator share URLs.
+ *
+ * When the bot posts a plan URL with ?cb=<encoded_url>&ct=<token>,
+ * these utilities parse the config and POST the user's decision back.
+ */
+
+/** Actions the user can trigger via the in-Plannotator callback buttons. */
+export enum CallbackAction {
+  Approve  = "approve",
+  Feedback = "feedback",
+}
+
+/** Callback config parsed from ?cb=<encoded_url>&ct=<token> in the URL. */
+export interface CallbackConfig {
+  callbackUrl: string;
+  token: string;
+}
+
+export interface ToastSuccess { readonly type: 'success'; readonly message: string }
+export interface ToastError   { readonly type: 'error';   readonly message: string }
+export type ToastPayload = ToastSuccess | ToastError | null;
+
+/**
+ * Parse callback configuration from URL search params.
+ * Checks both the standard query string (before #) and query-style params
+ * embedded in the hash (e.g. `#<hash>?cb=...&ct=...`).
+ *
+ * The decoded `cb` value must use http: or https: — other schemes (file://, javascript://, etc.)
+ * are rejected to prevent protocol-based attacks.
+ *
+ * @param loc - Location object to parse (defaults to window.location; injectable for tests)
+ * @returns CallbackConfig if both cb and ct are present and valid, null otherwise
+ */
+export function getCallbackConfig(
+  loc: { readonly search: string; readonly hash: string } = window.location,
+): CallbackConfig | null {
+  const searchParams = new URLSearchParams(loc.search);
+  let cb = searchParams.get("cb");
+  let ct = searchParams.get("ct");
+
+  if (!cb || !ct) {
+    const qIdx = loc.hash.indexOf("?");
+    if (qIdx !== -1) {
+      const hashParams = new URLSearchParams(loc.hash.slice(qIdx + 1));
+      cb = cb ?? hashParams.get("cb");
+      ct = ct ?? hashParams.get("ct");
+    }
+  }
+
+  if (!cb || !ct) return null;
+
+  try {
+    const { protocol } = new URL(cb);
+    if (protocol !== "https:" && protocol !== "http:") return null;
+  } catch {
+    return null; // malformed URL
+  }
+
+  return { callbackUrl: cb, token: ct };
+}
+
+/**
+ * Execute a bot callback POST request.
+ *
+ * Pure function (no React deps) — testable without a DOM.
+ *
+ * @param action - The action to send
+ * @param config - Callback URL and single-use token from `getCallbackConfig()`
+ * @param annotatedUrl - Current share URL (with annotations encoded); sent to the bot
+ * @returns Toast payload to display
+ */
+export async function executeCallback(
+  action: CallbackAction,
+  config: CallbackConfig,
+  annotatedUrl: string,
+): Promise<ToastPayload> {
+  const successMsg = action === CallbackAction.Approve
+    ? "Plan approved! The bot will proceed to implementation."
+    : "Feedback sent! The bot will re-plan with your annotations.";
+  try {
+    const res = await fetch(config.callbackUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ action, token: config.token, annotated_url: annotatedUrl }),
+    });
+    if (!res.ok) {
+      return {
+        type: "error",
+        message: res.status === 401
+          ? "Plan link expired — request a new one from the bot."
+          : "Callback failed.",
+      };
+    }
+    return { type: "success", message: successMsg };
+  } catch {
+    return { type: "error", message: "Callback failed." };
+  }
+}

package/utils/commentContent.ts

@@ -0,0 +1,8 @@
+import type { ImageAttachment } from "../types";
+
+export function hasUnsavedCommentContent(
+  text: string,
+  images: readonly ImageAttachment[] = [],
+): boolean {
+  return text.trim().length > 0 || images.length > 0;
+}

package/utils/defaultNotesApp.ts

@@ -0,0 +1,20 @@
+/**
+ * Default Notes App Preference
+ *
+ * Stores the user's preferred notes app for the Cmd/Ctrl+S shortcut.
+ * Uses cookies (not localStorage) because each hook invocation runs on a random port.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY = 'plannotator-default-notes-app';
+
+export type DefaultNotesApp = 'obsidian' | 'bear' | 'octarine' | 'download' | 'ask';
+
+export function getDefaultNotesApp(): DefaultNotesApp {
+  return (storage.getItem(STORAGE_KEY) as DefaultNotesApp) || 'ask';
+}
+
+export function saveDefaultNotesApp(app: DefaultNotesApp): void {
+  storage.setItem(STORAGE_KEY, app);
+}

package/utils/diffFonts.ts

@@ -0,0 +1,33 @@
+/**
+ * Dynamic font loading for code review diff viewer.
+ *
+ * Injects Google Fonts / CDN stylesheet links on demand when the user
+ * selects a custom diff font. Each font is loaded at most once.
+ */
+
+const FONT_URLS: Record<string, string> = {
+  'Red Hat Mono': 'https://fonts.googleapis.com/css2?family=Red+Hat+Mono:wght@300..700&display=swap',
+  'Fira Code': 'https://fonts.googleapis.com/css2?family=Fira+Code:wght@300..700&display=swap',
+  'Atkinson Hyperlegible Mono': 'https://fonts.googleapis.com/css2?family=Atkinson+Hyperlegible+Mono:wght@200..700&display=swap',
+  'Source Code Pro': 'https://fonts.googleapis.com/css2?family=Source+Code+Pro:wght@300..700&display=swap',
+  'JetBrains Mono': 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300..700&display=swap',
+  'IBM Plex Mono': 'https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@300..700&display=swap',
+  'Inconsolata': 'https://fonts.googleapis.com/css2?family=Inconsolata:wght@300..700&display=swap',
+  'Roboto Mono': 'https://fonts.googleapis.com/css2?family=Roboto+Mono:wght@300..700&display=swap',
+  'Hack': 'https://cdn.jsdelivr.net/npm/hack-font@3/build/web/hack.css',
+};
+
+const loaded = new Set<string>();
+
+export function loadDiffFont(fontFamily: string): void {
+  if (!fontFamily || loaded.has(fontFamily)) return;
+  const url = FONT_URLS[fontFamily];
+  if (!url) return;
+
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = url;
+  link.dataset.diffFont = fontFamily;
+  document.head.appendChild(link);
+  loaded.add(fontFamily);
+}

package/utils/editorMode.ts

@@ -0,0 +1,31 @@
+/**
+ * Editor Mode Settings Utility
+ *
+ * Persists the last-used editor mode (selection, comment, redline) so it
+ * carries over between plan reviews.
+ */
+
+import { storage } from './storage';
+import type { EditorMode } from '../types';
+
+const STORAGE_KEY = 'plannotator-editor-mode';
+
+const DEFAULT_MODE: EditorMode = 'selection';
+
+/**
+ * Get the last-used editor mode from storage
+ */
+export function getEditorMode(): EditorMode {
+  const stored = storage.getItem(STORAGE_KEY);
+  if (stored === 'selection' || stored === 'comment' || stored === 'redline' || stored === 'quickLabel') {
+    return stored;
+  }
+  return DEFAULT_MODE;
+}
+
+/**
+ * Save editor mode to storage
+ */
+export function saveEditorMode(mode: EditorMode): void {
+  storage.setItem(STORAGE_KEY, mode);
+}

package/utils/fileBrowser.ts

@@ -0,0 +1,40 @@
+/**
+ * File Browser Settings
+ *
+ * Manages settings for the markdown file browser sidebar tab.
+ * Users add directories to browse; settings persist via cookies.
+ */
+
+import { storage } from './storage';
+
+const STORAGE_KEY_ENABLED = 'plannotator-filebrowser-enabled';
+const STORAGE_KEY_DIRS = 'plannotator-filebrowser-dirs';
+
+export interface FileBrowserSettings {
+  enabled: boolean;
+  directories: string[];
+}
+
+export function getFileBrowserSettings(): FileBrowserSettings {
+  const dirsRaw = storage.getItem(STORAGE_KEY_DIRS);
+  let directories: string[] = [];
+  if (dirsRaw) {
+    try {
+      directories = JSON.parse(dirsRaw);
+    } catch { /* ignore corrupt cookie */ }
+  }
+  return {
+    enabled: storage.getItem(STORAGE_KEY_ENABLED) === 'true',
+    directories,
+  };
+}
+
+export function saveFileBrowserSettings(settings: FileBrowserSettings): void {
+  storage.setItem(STORAGE_KEY_ENABLED, String(settings.enabled));
+  storage.setItem(STORAGE_KEY_DIRS, JSON.stringify(settings.directories));
+}
+
+export function isFileBrowserEnabled(): boolean {
+  const settings = getFileBrowserSettings();
+  return settings.enabled && settings.directories.length > 0;
+}

package/utils/generateId.ts

@@ -0,0 +1,7 @@
+export function generateId(prefix?: string): string {
+  const id = typeof crypto !== 'undefined' && 'randomUUID' in crypto
+    ? crypto.randomUUID()
+    : Math.random().toString(36).slice(2);
+
+  return prefix ? `${prefix}-${id}` : id;
+}

package/utils/generateIdentity.ts

@@ -0,0 +1,29 @@
+/**
+ * Tater name generator — pure function, no storage dependencies.
+ *
+ * Extracted to its own module to avoid circular imports:
+ * settings.ts needs this for the default value, and identity.ts
+ * needs configStore (which imports settings.ts).
+ */
+
+import { uniqueUsernameGenerator, adjectives, nouns } from 'unique-username-generator';
+
+/**
+ * Generate a new random tater identity.
+ * Format: {adjective}-{noun}-tater
+ * Examples: "swift-falcon-tater", "gentle-crystal-tater"
+ */
+export function generateIdentity(): string {
+  // Use a unique separator to split adjective from noun, avoiding issues
+  // with compound words that contain hyphens (e.g., "behind-the-scenes")
+  const generated = uniqueUsernameGenerator({
+    dictionaries: [adjectives, nouns],
+    separator: '|||',
+    style: 'lowerCase',
+    randomDigits: 0,
+    length: 50, // Prevent word truncation (default is too short)
+  });
+
+  const [adjective, noun] = generated.split('|||');
+  return `${adjective}-${noun}-tater`;
+}