md-annotator 0.8.0 → 0.10.0

package/client/src/utils/export.js

@@ -80,7 +80,8 @@ export function formatAnnotationsForExport(annotations, blocks, filePath) {
       output += `Remove (${lineRef})\n\n`
       output += `\`\`\`\n${ann.originalText}\n\`\`\`\n\n`
     } else if (ann.type === 'COMMENT') {
-      output += `Comment (${lineRef})\n\n`
+      const labelTag = ann.label ? ` [${ann.label.emoji} ${ann.label.text}]` : ''
+      output += `Comment (${lineRef})${labelTag}\n\n`
       output += `\`\`\`\n${ann.originalText}\n\`\`\`\n\n`
       output += `> ${ann.text}\n\n`
     } else if (ann.type === 'INSERTION') {
@@ -159,6 +160,7 @@ export function formatAnnotationsForJsonExport(annotations, filePath, contentHas
         endMeta: ann.endMeta
       }
       if (ann.targetType) { base.targetType = ann.targetType }
+      if (ann.label) { base.label = ann.label }
       if (ann.imageAlt !== undefined) { base.imageAlt = ann.imageAlt }
       if (ann.imageSrc !== undefined) { base.imageSrc = ann.imageSrc }
       if (ann.afterContext !== undefined) { base.afterContext = ann.afterContext }

package/client/src/utils/parser.js

@@ -22,7 +22,7 @@ const HTML_MIXED_CONTENT_TAGS = new Set([
  * Simplified markdown parser that splits content into linear blocks.
  * Designed for predictable text-anchoring (not AST-based).
  */
-export function parseMarkdownToBlocks(markdown) {
+export function parseMarkdownToBlocks(markdown, { allowFrontmatter = true } = {}) {
   const lines = markdown.split('\n')
   const blocks = []
   let currentId = 0
@@ -30,6 +30,42 @@ export function parseMarkdownToBlocks(markdown) {
   let currentType = 'paragraph'
   const currentLevel = 0
   let bufferStartLine = 1
+  let startIndex = 0
+
+  // YAML frontmatter: must start at line 0 with exactly '---'
+  if (allowFrontmatter && lines[0]?.trim() === '---') {
+    let closeIndex = -1
+    for (let j = 1; j < lines.length; j++) {
+      if (lines[j].trim() === '---') {
+        closeIndex = j
+        break
+      }
+    }
+    if (closeIndex > 1) {
+      const fmLines = lines.slice(1, closeIndex)
+      const entries = []
+      for (const fmLine of fmLines) {
+        const colonIdx = fmLine.indexOf(':')
+        if (colonIdx > 0) {
+          entries.push({
+            key: fmLine.slice(0, colonIdx).trim(),
+            value: fmLine.slice(colonIdx + 1).trim()
+          })
+        }
+      }
+      if (entries.length > 0) {
+        blocks.push({
+          id: `block-${currentId++}`,
+          type: 'frontmatter',
+          content: fmLines.join('\n'),
+          entries,
+          order: currentId,
+          startLine: 1
+        })
+        startIndex = closeIndex + 1
+      }
+    }
+  }
 
   const flush = () => {
     if (buffer.length > 0) {
@@ -46,7 +82,7 @@ export function parseMarkdownToBlocks(markdown) {
     }
   }
 
-  for (let i = 0; i < lines.length; i++) {
+  for (let i = startIndex; i < lines.length; i++) {
     const line = lines[i]
     const trimmed = line.trim()
     const currentLineNum = i + 1
@@ -253,7 +289,7 @@ export function parseMarkdownToBlocks(markdown) {
             startLine: htmlStartLine
           })
           // Recursively parse inner content as markdown
-          for (const inner of parseMarkdownToBlocks(innerLines.join('\n'))) {
+          for (const inner of parseMarkdownToBlocks(innerLines.join('\n'), { allowFrontmatter: false })) {
             blocks.push({ ...inner, id: `block-${currentId++}`, order: currentId, startLine: htmlStartLine + inner.startLine })
           }
           // Emit closing tag

package/client/src/utils/quickLabels.js

@@ -0,0 +1,56 @@
+/**
+ * Quick annotation labels for fast categorization.
+ * Alt+1–0 shortcuts apply a label directly to the current selection.
+ */
+
+const STORAGE_KEY = 'md-annotator-quick-labels'
+
+export const LABEL_COLORS = {
+  yellow:  { bg: 'rgb(235 203 139 / 18%)', text: '#ebcb8b', darkText: '#ebcb8b' },
+  blue:    { bg: 'rgb(94 129 172 / 15%)',   text: '#5e81ac', darkText: '#88c0d0' },
+  red:     { bg: 'rgb(191 97 106 / 12%)',   text: '#bf616a', darkText: '#bf616a' },
+  green:   { bg: 'rgb(163 190 140 / 15%)',  text: '#a3be8c', darkText: '#a3be8c' },
+  orange:  { bg: 'rgb(208 135 112 / 12%)',  text: '#d08770', darkText: '#d08770' },
+  purple:  { bg: 'rgb(180 142 173 / 15%)',  text: '#b48ead', darkText: '#b48ead' },
+  cyan:    { bg: 'rgb(136 192 208 / 15%)',  text: '#88c0d0', darkText: '#88c0d0' },
+  teal:    { bg: 'rgb(143 188 187 / 15%)',  text: '#8fbcbb', darkText: '#8fbcbb' },
+  pink:    { bg: 'rgb(180 142 173 / 18%)',  text: '#b48ead', darkText: '#d196d0' },
+  amber:   { bg: 'rgb(235 203 139 / 22%)',  text: '#c9a227', darkText: '#ebcb8b' },
+}
+
+export const DEFAULT_LABELS = [
+  { id: 'unclear',        emoji: '\u2753', text: 'Unclear',         color: 'yellow' },
+  { id: 'rephrase',       emoji: '\u270F\uFE0F', text: 'Rephrase',        color: 'blue' },
+  { id: 'missing-context', emoji: '\uD83D\uDCDD', text: 'Missing Context', color: 'orange' },
+  { id: 'factual-error',  emoji: '\u274C', text: 'Factual Error',   color: 'red' },
+  { id: 'restructure',    emoji: '\uD83D\uDD04', text: 'Restructure',     color: 'purple' },
+  { id: 'expand',         emoji: '\u2795', text: 'Expand',          color: 'cyan' },
+  { id: 'shorten',        emoji: '\u2796', text: 'Shorten',         color: 'teal' },
+  { id: 'suggestion',     emoji: '\uD83D\uDCA1', text: 'Suggestion',      color: 'amber' },
+  { id: 'good',           emoji: '\u2705', text: 'Good',            color: 'green' },
+  { id: 'reference',      emoji: '\uD83D\uDD17', text: 'Reference',       color: 'pink' },
+]
+
+export function getQuickLabels() {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    if (stored) {
+      const parsed = JSON.parse(stored)
+      if (Array.isArray(parsed) && parsed.length > 0) {
+        return parsed
+      }
+    }
+  } catch { /* ignore */ }
+  return DEFAULT_LABELS
+}
+
+export function getLabelColors(colorName) {
+  const entry = LABEL_COLORS[colorName]
+  if (!entry) { return { bg: 'rgb(94 129 172 / 15%)', text: '#5e81ac' } }
+  const isDark = document.documentElement.getAttribute('data-theme') === 'dark'
+  return { bg: entry.bg, text: isDark ? entry.darkText : entry.text }
+}
+
+export function formatLabelText(label) {
+  return `${label.emoji} ${label.text}`
+}

package/client/src/utils/searchHighlight.js

@@ -0,0 +1,121 @@
+/**
+ * DOM-based search highlighting.
+ * Injects/removes <mark> elements for text search matches.
+ */
+
+const MATCH_CLASS = 'search-match'
+const ACTIVE_CLASS = 'search-match-active'
+
+// Selectors for containers whose text content should not be searched
+// (rendered diagrams, hidden source blocks, UI chrome, line numbers, etc.)
+const SKIP_SELECTOR = [
+  'svg',
+  '.source-line-number',
+  '.annotation-toolbar',
+  '.comment-popover',
+  '.diagram-render-area',
+  '.diagram-source',
+  '.diagram-controls',
+  '.code-copy-btn',
+].join(', ')
+
+/**
+ * Walk all text nodes in container, find case-insensitive matches for query,
+ * and wrap them in <mark class="search-match">.
+ * Skips text nodes inside <mark> elements (avoids double-wrapping).
+ * Returns an array of the created <mark> elements.
+ */
+export function highlightMatches(container, query) {
+  if (!container || !query) { return [] }
+
+  const lowerQuery = query.toLowerCase()
+  const marks = []
+
+  // Collect text nodes first to avoid walking newly inserted marks
+  const textNodes = []
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      if (node.parentElement?.closest('mark')) { return NodeFilter.FILTER_REJECT }
+      if (node.parentElement?.closest(SKIP_SELECTOR)) { return NodeFilter.FILTER_REJECT }
+      return NodeFilter.FILTER_ACCEPT
+    }
+  })
+  while (walker.nextNode()) {
+    textNodes.push(walker.currentNode)
+  }
+
+  for (const node of textNodes) {
+    const text = node.textContent
+    const lowerText = text.toLowerCase()
+    const indices = []
+    let idx = 0
+
+    while ((idx = lowerText.indexOf(lowerQuery, idx)) !== -1) {
+      indices.push(idx)
+      idx += lowerQuery.length
+    }
+
+    if (indices.length === 0) { continue }
+
+    const parent = node.parentNode
+    const frag = document.createDocumentFragment()
+    let lastEnd = 0
+
+    for (const start of indices) {
+      if (start > lastEnd) {
+        frag.appendChild(document.createTextNode(text.slice(lastEnd, start)))
+      }
+      const mark = document.createElement('mark')
+      mark.className = MATCH_CLASS
+      mark.textContent = text.slice(start, start + query.length)
+      frag.appendChild(mark)
+      marks.push(mark)
+      lastEnd = start + query.length
+    }
+
+    if (lastEnd < text.length) {
+      frag.appendChild(document.createTextNode(text.slice(lastEnd)))
+    }
+
+    parent.replaceChild(frag, node)
+  }
+
+  return marks
+}
+
+/**
+ * Set the active match class on matches[activeIndex] and scroll it into view.
+ * Removes active class from all other matches.
+ */
+export function setActiveMatch(matches, activeIndex) {
+  for (let i = 0; i < matches.length; i++) {
+    matches[i].classList.toggle(ACTIVE_CLASS, i === activeIndex)
+  }
+  if (matches[activeIndex]) {
+    matches[activeIndex].scrollIntoView({ behavior: 'smooth', block: 'nearest' })
+  }
+}
+
+/**
+ * Remove all search-match <mark> elements, restoring original text nodes.
+ * Calls normalize() only on direct parents of removed marks (not the entire container)
+ * to avoid disrupting web-highlighter's [data-highlight-id] spans.
+ */
+export function clearSearchHighlights(container) {
+  if (!container) { return }
+
+  const marks = container.querySelectorAll(`mark.${MATCH_CLASS}`)
+  const parentsToNormalize = new Set()
+
+  for (const mark of marks) {
+    const parent = mark.parentNode
+    if (!parent) { continue }
+    const text = document.createTextNode(mark.textContent)
+    parent.replaceChild(text, mark)
+    parentsToNormalize.add(parent)
+  }
+
+  for (const parent of parentsToNormalize) {
+    parent.normalize()
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-annotator",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Browser-based Markdown annotator for AI-assisted review",
   "type": "module",
   "bin": {
@@ -43,7 +43,6 @@
     "open": "^10.1.0",
     "pako": "^2.1.0",
     "plantuml-encoder": "^1.4.0",
-    "portfinder": "^1.0.32",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "web-highlighter": "^0.7.4"
@@ -55,6 +54,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.0.1",
     "globals": "^17.2.0",
+    "jsdom": "^29.0.1",
     "stylelint": "^17.0.0",
     "stylelint-config-standard": "^40.0.0",
     "vite": "^6.0.0",

package/server/annotator.js

@@ -3,13 +3,12 @@
  * Provides startAnnotatorServer() for both CLI and plugin usage.
  */
 
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import express from 'express'
 import cors from 'cors'
-import portfinder from 'portfinder'
 import { config } from './config.js'
 import { createApiRouter } from './routes.js'
 import { readMarkdownFile } from './file.js'
@@ -19,6 +18,15 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 const DIST_PATH = join(__dirname, '..', 'client', 'dist')
 const DEV_PATH = join(__dirname, '..', 'client')
 
+// Pre-load index.html into memory at module load time (avoids per-request disk I/O)
+const DIST_INDEX = join(DIST_PATH, 'index.html')
+const DEV_INDEX = join(DEV_PATH, 'index.html')
+const preloadedHtml = existsSync(DIST_INDEX)
+  ? readFileSync(DIST_INDEX, 'utf-8')
+  : existsSync(DEV_INDEX)
+    ? readFileSync(DEV_INDEX, 'utf-8')
+    : null
+
 /**
  * Resolve notes for a specific file from the feedbackNotes array.
  * Notes apply to the first file only (multi-file uses one invocation per file).
@@ -59,14 +67,14 @@ export async function startAnnotatorServer(options) {
   app.use(cors())
   app.use(express.json({ limit: config.jsonLimit }))
 
-  // Serve static files or embedded HTML
-  if (htmlContent) {
-    // Plugin mode: serve embedded HTML
+  // Serve HTML from memory (pre-loaded or embedded)
+  const html = htmlContent || preloadedHtml
+  if (html) {
     app.get('/', (_req, res) => {
-      res.type('html').send(htmlContent)
+      res.type('html').send(html)
     })
   } else {
-    // CLI mode: serve from disk
+    // Fallback: serve from disk (dev mode without built index.html)
     const clientPath = existsSync(DIST_PATH) ? DIST_PATH : DEV_PATH
     app.use(express.static(clientPath))
   }
@@ -131,15 +139,14 @@ export async function startAnnotatorServer(options) {
   // API routes with multi-file support
   app.use(createApiRouter(filePaths, safeResolve, origin, stores))
 
-  // Find available port
-  portfinder.basePort = config.port
-  const port = await portfinder.getPortPromise()
-
-  // Start server
+  // Start server — use port 0 to let the OS assign a free port instantly,
+  // falling back to configured port if explicitly set via MD_ANNOTATOR_PORT
+  const requestedPort = config.portExplicit ? config.port : 0
   const server = await new Promise((resolve) => {
-    const s = app.listen(port, () => resolve(s))
+    const s = app.listen(requestedPort, () => resolve(s))
   })
 
+  const port = server.address().port
   const url = `http://localhost:${port}`
 
   // Call onReady callback if provided

package/server/config.js

@@ -45,6 +45,7 @@ function getKrokiServerUrl() {
 
 export const config = {
   port: getServerPort(),
+  portExplicit: !!process.env.MD_ANNOTATOR_PORT,
   browser: process.env.MD_ANNOTATOR_BROWSER || null,
   heartbeatTimeoutMs: getHeartbeatTimeoutMs(),
   forceExitTimeoutMs: 5000,

package/server/feedback.js

@@ -49,6 +49,27 @@ function formatAnnotation(ann, block, heading) {
     return output + '\n'
   }
 
+  // Source view annotations — blockId is "source-line-N" (0-indexed)
+  if (ann.targetType === 'source') {
+    const lineMatch = ann.blockId?.match(/^source-line-(\d+)$/)
+    const startLine = lineMatch ? parseInt(lineMatch[1], 10) + 1 : 1
+    const newlinesInSelection = (ann.originalText.match(/\n/g) || []).length
+    const endLine = startLine + newlinesInSelection
+    const lineRef = startLine === endLine ? `Line ${startLine}` : `Lines ${startLine}-${endLine}`
+
+    let output = `${heading} `
+    if (ann.type === 'DELETION') {
+      output += `Remove this (${lineRef}, source)\n`
+      output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`
+      output += `> User wants this removed from the document.\n`
+    } else if (ann.type === 'COMMENT') {
+      output += `Comment on (${lineRef}, source)\n`
+      output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`
+      output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n`
+    }
+    return output + '\n'
+  }
+
   const blockContent = block?.content || ''
   const textBeforeSelection = blockContent.slice(0, ann.startOffset)
   const linesBeforeSelection = (textBeforeSelection.match(/\n/g) || []).length
@@ -64,7 +85,8 @@ function formatAnnotation(ann, block, heading) {
     output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`
     output += `> User wants this removed from the document.\n`
   } else if (ann.type === 'COMMENT') {
-    output += `Comment on (${lineRef})\n`
+    const labelTag = ann.label ? ` [${ann.label.emoji} ${ann.label.text}]` : ''
+    output += `Comment on (${lineRef})${labelTag}\n`
     output += `\`\`\`\n${ann.originalText}\n\`\`\`\n`
     output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n`
   } else if (ann.type === 'INSERTION') {
@@ -79,10 +101,18 @@ function formatAnnotation(ann, block, heading) {
   return output + '\n'
 }
 
+function getBlockOrder(blockId, blocks) {
+  const sourceMatch = blockId?.match(/^source-line-(\d+)$/)
+  if (sourceMatch) { return parseInt(sourceMatch[1], 10) + 1 }
+  const block = blocks.find(blk => blk.id === blockId)
+  if (block?.startLine) { return block.startLine }
+  return Infinity
+}
+
 function sortAnnotations(annotations, blocks) {
   return [...annotations].sort((a, b) => {
-    const blockA = blocks.findIndex(blk => blk.id === a.blockId)
-    const blockB = blocks.findIndex(blk => blk.id === b.blockId)
+    const blockA = getBlockOrder(a.blockId, blocks)
+    const blockB = getBlockOrder(b.blockId, blocks)
     if (blockA !== blockB) {return blockA - blockB}
     return a.startOffset - b.startOffset
   })

package/client/src/utils/storage.js

@@ -1,44 +0,0 @@
-/**
- * Cookie-based storage utility.
- *
- * Uses cookies instead of localStorage so settings persist across
- * different ports (each session uses a random port).
- * Cookies are scoped by domain, not port, so localhost:54321 and
- * localhost:54322 share the same cookies.
- */
-
-const ONE_YEAR_SECONDS = 60 * 60 * 24 * 365
-
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-}
-
-function getItem(key) {
-  try {
-    const match = document.cookie.match(new RegExp(`(?:^|; )${escapeRegex(key)}=([^;]*)`))
-    return match ? decodeURIComponent(match[1]) : null
-  } catch {
-    return null
-  }
-}
-
-function setItem(key, value) {
-  try {
-    const encoded = encodeURIComponent(value)
-    document.cookie = `${key}=${encoded}; path=/; max-age=${ONE_YEAR_SECONDS}; SameSite=Lax`
-  } catch {
-    // Cookie not available
-  }
-}
-
-const AUTO_CLOSE_KEY = 'md-annotator-auto-close'
-
-export function getAutoCloseDelay() {
-  const val = getItem(AUTO_CLOSE_KEY)
-  if (val === '0' || val === '3' || val === '5') {return val}
-  return 'off'
-}
-
-export function setAutoCloseDelay(delay) {
-  setItem(AUTO_CLOSE_KEY, delay)
-}