md-annotator 0.5.2 → 0.5.4

package/client/src/utils/export.js

@@ -0,0 +1,244 @@
+/**
+ * Export utilities for annotations.
+ * Mirrors server/feedback.js format for consistency.
+ */
+
+/**
+ * Format annotations as exportable markdown.
+ */
+export function formatAnnotationsForExport(annotations, blocks, filePath) {
+  if (annotations.length === 0) {
+    return 'No annotations.'
+  }
+
+  const sorted = [...annotations].sort((a, b) => {
+    const blockA = blocks.findIndex(blk => blk.id === a.blockId)
+    const blockB = blocks.findIndex(blk => blk.id === b.blockId)
+    if (blockA !== blockB) {return blockA - blockB}
+    return a.startOffset - b.startOffset
+  })
+
+  const globalComments = sorted.filter(a => a.targetType === 'global')
+  const regularAnnotations = sorted.filter(a => a.targetType !== 'global')
+
+  let output = `# Annotation Feedback\n\n`
+  output += `**File:** \`${filePath}\`\n\n`
+  output += `**Count:** ${annotations.length} annotation${annotations.length > 1 ? 's' : ''}\n\n`
+  output += `---\n\n`
+
+  if (globalComments.length > 0) {
+    output += `## General Feedback\n\n`
+    globalComments.forEach(ann => {
+      output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n\n`
+    })
+  }
+
+  regularAnnotations.forEach((ann, index) => {
+    const block = blocks.find(blk => blk.id === ann.blockId)
+    const blockStartLine = block?.startLine || 1
+
+    // Element-level annotations
+    if (ann.targetType === 'image') {
+      const isDeletion = ann.type === 'DELETION'
+      const label = isDeletion ? 'Remove image' : 'Comment on image'
+      output += `## ${index + 1}. ${label} (Line ${blockStartLine})\n\n`
+      output += `Image: \`${ann.originalText}\`\n\n`
+      if (ann.imageAlt) { output += `Alt text: "${ann.imageAlt}"\n\n` }
+      if (ann.imageSrc) { output += `Source: ${ann.imageSrc}\n\n` }
+      if (isDeletion) {
+        output += `> User wants this image removed from the document.\n\n`
+      } else {
+        output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n\n`
+      }
+      return
+    }
+    if (ann.targetType === 'diagram') {
+      const isDeletion = ann.type === 'DELETION'
+      const label = isDeletion ? 'Remove Mermaid diagram' : 'Comment on Mermaid diagram'
+      output += `## ${index + 1}. ${label} (Line ${blockStartLine})\n\n`
+      output += `\`\`\`mermaid\n${block?.content || ann.originalText}\n\`\`\`\n\n`
+      if (isDeletion) {
+        output += `> User wants this diagram removed from the document.\n\n`
+      } else {
+        output += `> ${(ann.text ?? '').replace(/\n/g, '\n> ')}\n\n`
+      }
+      return
+    }
+
+    const blockContent = block?.content || ''
+    const textBeforeSelection = blockContent.slice(0, ann.startOffset)
+    const linesBeforeSelection = (textBeforeSelection.match(/\n/g) || []).length
+    const startLine = blockStartLine + linesBeforeSelection
+    const newlinesInSelection = (ann.originalText.match(/\n/g) || []).length
+    const endLine = startLine + newlinesInSelection
+
+    const lineRef = startLine === endLine ? `Line ${startLine}` : `Lines ${startLine}-${endLine}`
+
+    output += `## ${index + 1}. `
+
+    if (ann.type === 'DELETION') {
+      output += `Remove (${lineRef})\n\n`
+      output += `\`\`\`\n${ann.originalText}\n\`\`\`\n\n`
+    } else if (ann.type === 'COMMENT') {
+      output += `Comment (${lineRef})\n\n`
+      output += `\`\`\`\n${ann.originalText}\n\`\`\`\n\n`
+      output += `> ${ann.text}\n\n`
+    } else if (ann.type === 'INSERTION') {
+      output += `Insert text (${lineRef})\n\n`
+      if (ann.afterContext) {
+        output += `After: \`${ann.afterContext}\`\n\n`
+      }
+      output += `\`\`\`\n${ann.text}\n\`\`\`\n\n`
+    }
+  })
+
+  return output
+}
+
+/**
+ * Copy text to clipboard with fallback.
+ */
+export async function copyToClipboard(text) {
+  try {
+    await navigator.clipboard.writeText(text)
+    return true
+  } catch {
+    const textarea = document.createElement('textarea')
+    textarea.value = text
+    textarea.style.position = 'fixed'
+    textarea.style.opacity = '0'
+    document.body.appendChild(textarea)
+    textarea.select()
+    document.execCommand('copy')
+    document.body.removeChild(textarea)
+    return true
+  }
+}
+
+/**
+ * Trigger a browser file download from a Blob.
+ */
+function downloadBlob(blob, filename) {
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  document.body.appendChild(a)
+  a.click()
+  document.body.removeChild(a)
+  URL.revokeObjectURL(url)
+}
+
+/**
+ * Download text as Markdown file.
+ */
+export function downloadAsFile(content, filename = 'annotations.md') {
+  downloadBlob(new Blob([content], { type: 'text/markdown' }), filename)
+}
+
+/**
+ * Format annotations as JSON export with metadata.
+ */
+export function formatAnnotationsForJsonExport(annotations, filePath, contentHash) {
+  return {
+    version: 1,
+    filePath,
+    contentHash,
+    exportedAt: new Date().toISOString(),
+    annotations: annotations.map(ann => {
+      const base = {
+        id: ann.id,
+        blockId: ann.blockId,
+        startOffset: ann.startOffset,
+        endOffset: ann.endOffset,
+        type: ann.type,
+        text: ann.text,
+        originalText: ann.originalText,
+        createdAt: ann.createdAt,
+        startMeta: ann.startMeta,
+        endMeta: ann.endMeta
+      }
+      if (ann.targetType) { base.targetType = ann.targetType }
+      if (ann.imageAlt !== undefined) { base.imageAlt = ann.imageAlt }
+      if (ann.imageSrc !== undefined) { base.imageSrc = ann.imageSrc }
+      if (ann.afterContext !== undefined) { base.afterContext = ann.afterContext }
+      return base
+    })
+  }
+}
+
+/**
+ * Download data as JSON file.
+ */
+export function downloadAsJsonFile(data, filename = 'annotations.json') {
+  downloadBlob(new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' }), filename)
+}
+
+/**
+ * Validate imported JSON annotation data.
+ */
+const REQUIRED_ANNOTATION_FIELDS = [
+  'id', 'blockId', 'startOffset', 'endOffset',
+  'type', 'originalText'
+]
+
+export function validateAnnotationImport(data) {
+  if (!data || typeof data !== 'object') {
+    return { valid: false, error: 'Invalid JSON format' }
+  }
+  if (data.version !== 1) {
+    return { valid: false, error: `Unsupported version: ${data.version}` }
+  }
+  if (!Array.isArray(data.annotations)) {
+    return { valid: false, error: 'Missing annotations array' }
+  }
+  if (data.annotations.length > 10000) {
+    return { valid: false, error: 'Too many annotations (max 10,000)' }
+  }
+  for (const ann of data.annotations) {
+    for (const field of REQUIRED_ANNOTATION_FIELDS) {
+      if (ann[field] === undefined) {
+        return { valid: false, error: `Annotation missing required field: ${field}` }
+      }
+    }
+    if (typeof ann.id !== 'string' || typeof ann.blockId !== 'string') {
+      return { valid: false, error: 'Annotation id and blockId must be strings' }
+    }
+    if (typeof ann.startOffset !== 'number' || typeof ann.endOffset !== 'number') {
+      return { valid: false, error: 'Annotation offsets must be numbers' }
+    }
+    if (ann.startOffset < 0 || ann.endOffset < 0 || ann.endOffset < ann.startOffset) {
+      return { valid: false, error: 'Invalid annotation offset values' }
+    }
+    if (ann.type !== 'DELETION' && ann.type !== 'COMMENT' && ann.type !== 'INSERTION') {
+      return { valid: false, error: `Invalid annotation type: ${ann.type}` }
+    }
+    if (typeof ann.originalText !== 'string') {
+      return { valid: false, error: 'Annotation originalText must be a string' }
+    }
+    if (ann.text !== null && ann.text !== undefined && typeof ann.text !== 'string') {
+      return { valid: false, error: 'Annotation text must be a string or null' }
+    }
+    if (ann.targetType && ann.targetType !== 'image' && ann.targetType !== 'diagram' && ann.targetType !== 'global') {
+      return { valid: false, error: `Invalid annotation targetType: ${ann.targetType}` }
+    }
+    // Element annotations (image/diagram/global) and insertions have null startMeta/endMeta
+    const isElement = ann.targetType === 'image' || ann.targetType === 'diagram' || ann.targetType === 'global'
+    const isInsertion = ann.type === 'INSERTION'
+    if (!isElement && !isInsertion) {
+      if (!ann.startMeta || typeof ann.startMeta !== 'object') {
+        return { valid: false, error: 'Annotation startMeta must be an object' }
+      }
+      if (!ann.endMeta || typeof ann.endMeta !== 'object') {
+        return { valid: false, error: 'Annotation endMeta must be an object' }
+      }
+    }
+  }
+  return {
+    valid: true,
+    error: null,
+    annotations: data.annotations,
+    filePath: data.filePath || null,
+    contentHash: data.contentHash || null
+  }
+}

package/client/src/utils/parser.js

@@ -0,0 +1,245 @@
+const HTML_BLOCK_TAGS = new Set([
+  'address', 'article', 'aside', 'blockquote', 'center', 'dd', 'details',
+  'dialog', 'dir', 'div', 'dl', 'dt', 'fieldset', 'figcaption', 'figure',
+  'footer', 'form', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hgroup',
+  'hr', 'iframe', 'main', 'menu', 'nav', 'ol', 'p', 'picture', 'pre',
+  'section', 'source', 'summary', 'table', 'tbody', 'td', 'template',
+  'tfoot', 'th', 'thead', 'tr', 'ul', 'video'
+])
+
+const HTML_VOID_TAGS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+])
+
+/**
+ * Simplified markdown parser that splits content into linear blocks.
+ * Designed for predictable text-anchoring (not AST-based).
+ */
+export function parseMarkdownToBlocks(markdown) {
+  const lines = markdown.split('\n')
+  const blocks = []
+  let currentId = 0
+  let buffer = []
+  let currentType = 'paragraph'
+  const currentLevel = 0
+  let bufferStartLine = 1
+
+  const flush = () => {
+    if (buffer.length > 0) {
+      const content = buffer.join('\n')
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: currentType,
+        content,
+        level: currentLevel,
+        order: currentId,
+        startLine: bufferStartLine
+      })
+      buffer = []
+    }
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const trimmed = line.trim()
+    const currentLineNum = i + 1
+
+    // Headings
+    if (trimmed.startsWith('#')) {
+      flush()
+      const level = trimmed.match(/^#+/)?.[0].length || 1
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'heading',
+        content: trimmed.replace(/^#+\s*/, ''),
+        level,
+        order: currentId,
+        startLine: currentLineNum
+      })
+      continue
+    }
+
+    // Horizontal Rule
+    if (trimmed === '---' || trimmed === '***') {
+      flush()
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'hr',
+        content: '',
+        order: currentId,
+        startLine: currentLineNum
+      })
+      continue
+    }
+
+    // List Items
+    if (trimmed.match(/^(\*|-|\d+\.)\s/)) {
+      flush()
+      const leadingWhitespace = line.match(/^(\s*)/)?.[1] || ''
+      const spaceCount = leadingWhitespace.replace(/\t/g, '  ').length
+      const listLevel = Math.floor(spaceCount / 2)
+
+      let content = trimmed.replace(/^(\*|-|\d+\.)\s/, '')
+
+      let checked = undefined
+      const checkboxMatch = content.match(/^\[([ xX])\]\s*/)
+      if (checkboxMatch) {
+        checked = checkboxMatch[1].toLowerCase() === 'x'
+        content = content.replace(/^\[([ xX])\]\s*/, '')
+      }
+
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'list-item',
+        content,
+        level: listLevel,
+        checked,
+        order: currentId,
+        startLine: currentLineNum
+      })
+      continue
+    }
+
+    // Blockquotes
+    if (trimmed.startsWith('>')) {
+      flush()
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'blockquote',
+        content: trimmed.replace(/^>\s*/, ''),
+        order: currentId,
+        startLine: currentLineNum
+      })
+      continue
+    }
+
+    // Code blocks
+    if (trimmed.startsWith('```')) {
+      flush()
+      const codeStartLine = currentLineNum
+      const language = trimmed.slice(3).trim() || undefined
+      const codeContent = []
+      i++
+      while (i < lines.length && !lines[i].trim().startsWith('```')) {
+        codeContent.push(lines[i])
+        i++
+      }
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'code',
+        content: codeContent.join('\n'),
+        language,
+        order: currentId,
+        startLine: codeStartLine
+      })
+      continue
+    }
+
+    // Tables
+    if (trimmed.startsWith('|') || (trimmed.includes('|') && trimmed.match(/^\|?.+\|.+\|?$/))) {
+      flush()
+      const tableStartLine = currentLineNum
+      const tableLines = [line]
+
+      while (i + 1 < lines.length) {
+        const nextLine = lines[i + 1].trim()
+        if (nextLine.startsWith('|') || (nextLine.includes('|') && nextLine.match(/^\|?.+\|.+\|?$/))) {
+          i++
+          tableLines.push(lines[i])
+        } else {
+          break
+        }
+      }
+
+      blocks.push({
+        id: `block-${currentId++}`,
+        type: 'table',
+        content: tableLines.join('\n'),
+        order: currentId,
+        startLine: tableStartLine
+      })
+      continue
+    }
+
+    // HTML blocks
+    if (trimmed.startsWith('<')) {
+      // HTML comments
+      if (trimmed.startsWith('<!--')) {
+        flush()
+        const htmlStartLine = currentLineNum
+        const htmlLines = [line]
+        if (!trimmed.includes('-->')) {
+          i++
+          while (i < lines.length) {
+            htmlLines.push(lines[i])
+            if (lines[i].includes('-->')) { break }
+            i++
+          }
+        }
+        blocks.push({
+          id: `block-${currentId++}`,
+          type: 'html',
+          content: htmlLines.join('\n'),
+          order: currentId,
+          startLine: htmlStartLine
+        })
+        continue
+      }
+
+      // Block-level HTML tags
+      const tagMatch = trimmed.match(/^<([a-zA-Z][a-zA-Z0-9]*)[\s>/]/)
+      if (tagMatch && HTML_BLOCK_TAGS.has(tagMatch[1].toLowerCase())) {
+        flush()
+        const tagName = tagMatch[1].toLowerCase()
+        const htmlStartLine = currentLineNum
+        const htmlLines = [line]
+
+        const isSelfClosing = trimmed.endsWith('/>')
+        const isVoid = HTML_VOID_TAGS.has(tagName)
+        const hasSameLineClose = new RegExp(`</${tagName}\\s*>`, 'i').test(trimmed)
+
+        if (!isSelfClosing && !isVoid && !hasSameLineClose) {
+          const closePattern = new RegExp(`</${tagName}\\s*>`, 'i')
+          const openPattern = new RegExp(`<${tagName}[\\s>/]`, 'i')
+          let depth = 1
+          i++
+          while (i < lines.length) {
+            htmlLines.push(lines[i])
+            if (openPattern.test(lines[i])) { depth++ }
+            if (closePattern.test(lines[i])) {
+              depth--
+              if (depth === 0) { break }
+            }
+            i++
+          }
+        }
+
+        blocks.push({
+          id: `block-${currentId++}`,
+          type: 'html',
+          content: htmlLines.join('\n'),
+          order: currentId,
+          startLine: htmlStartLine
+        })
+        continue
+      }
+    }
+
+    // Empty lines separate paragraphs
+    if (trimmed === '') {
+      flush()
+      currentType = 'paragraph'
+      continue
+    }
+
+    // Accumulate paragraph text
+    if (buffer.length === 0) {
+      bufferStartLine = currentLineNum
+    }
+    buffer.push(line)
+  }
+
+  flush()
+  return blocks
+}

package/client/src/utils/storage.js

@@ -0,0 +1,44 @@
+/**
+ * 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)
+}

package/client/src/utils/textStats.js

@@ -0,0 +1,8 @@
+const WORDS_PER_MINUTE = 200
+
+export function getTextStats(text) {
+  const lines = text.split('\n').length
+  const words = text.split(/\s+/).filter(Boolean).length
+  const readingTime = Math.max(1, Math.ceil(words / WORDS_PER_MINUTE))
+  return { lines, words, readingTime }
+}

package/index.js

@@ -18,9 +18,10 @@ Options:
   --feedback-notes <json|path> AI notes to display as read-only annotations
 
 Environment:
-  MD_ANNOTATOR_PORT      Base port (default: 3000)
-  MD_ANNOTATOR_BROWSER   Custom browser app name
-  MD_ANNOTATOR_TIMEOUT   Heartbeat timeout in ms (default: 30000, range: 5000–300000)
+  MD_ANNOTATOR_PORT            Base port (default: 3000)
+  MD_ANNOTATOR_BROWSER         Custom browser app name
+  MD_ANNOTATOR_TIMEOUT         Heartbeat timeout in ms (default: 30000, range: 5000–300000)
+  MD_ANNOTATOR_FEEDBACK_NOTES  JSON string or file path for feedback notes
 
 Examples:
   md-annotator README.md
@@ -86,6 +87,14 @@ function parseArgs(argv) {
     return { error: `Unknown origin "${origin}". Valid: ${validOrigins.join(', ')}` }
   }
 
+  if (!feedbackNotes && process.env.MD_ANNOTATOR_FEEDBACK_NOTES) {
+    try {
+      feedbackNotes = parseFeedbackNotes(process.env.MD_ANNOTATOR_FEEDBACK_NOTES)
+    } catch (err) {
+      return { error: `MD_ANNOTATOR_FEEDBACK_NOTES: ${err.message}` }
+    }
+  }
+
   return { filePaths, origin, feedbackNotes }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md-annotator",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Browser-based Markdown annotator for AI-assisted review",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "index.js",
     "server",
-    "client/dist"
+    "client/dist",
+    "client/src/utils"
   ],
   "scripts": {
     "start": "node index.js",