eyecite-ts 0.1.0 → 0.3.0

package/README.md

@@ -1,17 +1,27 @@
 # eyecite-ts
 
-TypeScript legal citation extraction library - port of Python [eyecite](https://github.com/freelawproject/eyecite).
+[![CI](https://github.com/medelman17/eyecite-ts/actions/workflows/ci.yml/badge.svg)](https://github.com/medelman17/eyecite-ts/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/medelman17/eyecite-ts/branch/main/graph/badge.svg)](https://codecov.io/gh/medelman17/eyecite-ts)
+[![npm version](https://img.shields.io/npm/v/eyecite-ts.svg)](https://www.npmjs.com/package/eyecite-ts)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/eyecite-ts)](https://bundlephobia.com/package/eyecite-ts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/node/v/eyecite-ts.svg)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/eyecite-ts)
 
-Extract, validate, annotate, and resolve legal citations from court opinions and legal documents with zero runtime dependencies and a <50KB bundle size.
+TypeScript legal citation extraction library — port of Python [eyecite](https://github.com/freelawproject/eyecite).
+
+Extract, resolve, and annotate legal citations from court opinions and legal documents with zero runtime dependencies.
 
 ## Features
 
 - **Full citation extraction**: Case citations, statutes, journal articles, neutral citations, public laws, federal register
 - **Short-form resolution**: Id./Ibid., supra, and short-form case citations resolved to their full antecedents
-- **Reporter database**: 1235 reporters with variant matching and confidence scoring
-- **Citation annotation**: HTML/Markdown markup with auto-escape and position tracking
-- **Bundle optimization**: Tree-shakeable exports, lazy-loaded data, separate entry points
-- **TypeScript native**: Discriminated unions, strict types, full IntelliSense
+- **Reporter database**: 1,200+ reporters with variant matching and confidence scoring
+- **Citation annotation**: HTML markup with auto-escape XSS protection and position tracking
+- **Bundle optimization**: Tree-shakeable exports, lazy-loaded reporter data, separate entry points
+- **TypeScript native**: Discriminated unions, conditional types, type guards, full IntelliSense
+- **Zero dependencies**: No runtime dependencies, 4.4KB gzipped core bundle
 
 ## Installation
 
@@ -36,13 +46,13 @@ console.log(citations[0])
 //   court: '9th Cir.',
 //   year: 2020,
 //   confidence: 0.85,
-//   span: { originalStart: 4, originalEnd: 48 }
+//   span: { originalStart: 4, originalEnd: 48, cleanStart: 4, cleanEnd: 48 }
 // }
 ```
 
 ## Citation Extraction
 
-### Basic Usage
+### Multiple Citation Types
 
 ```typescript
 import { extractCitations } from 'eyecite-ts'
@@ -70,7 +80,8 @@ const citations = await extractCitationsAsync(text)
 ### Custom Patterns
 
 ```typescript
-import { extractCitations, casePatterns } from 'eyecite-ts'
+import { extractCitations } from 'eyecite-ts'
+import { casePatterns } from 'eyecite-ts'
 
 // Extract only case citations
 const citations = extractCitations(text, {
@@ -81,17 +92,17 @@ const citations = extractCitations(text, {
 ### Custom Cleaners
 
 ```typescript
-import { extractCitations, stripHtmlTags } from 'eyecite-ts'
+import { extractCitations, cleanText } from 'eyecite-ts'
 
-// Use only HTML stripping, skip Unicode normalization
+// Use only HTML stripping
 const citations = extractCitations(html, {
-  cleaners: [stripHtmlTags]
+  cleaners: [(text) => text.replace(/<[^>]+>/g, '')]
 })
 ```
 
 ## Resolving Short-Form Citations
 
-Short-form citations (Id., supra, short-form case) refer to earlier citations in the document. The resolution engine automatically links them to their full antecedents.
+Short-form citations (Id., supra, short-form case) refer to earlier citations in the document. The resolution engine links them to their full antecedents.
 
 ### Convenience API
 
@@ -105,16 +116,11 @@ const text = `
   500 F.2d at 140.
 `
 
-// Convenience: extract + resolve in one call
 const citations = extractCitations(text, { resolve: true })
 
 // citations[1] is Id. citation
 console.log(citations[1].resolution)
-// {
-//   resolvedTo: 0,  // Points to Smith v. Jones (index 0)
-//   confidence: 1.0,
-//   warnings: []
-// }
+// { resolvedTo: 0, confidence: 1.0 }
 ```
 
 ### Power-User API
@@ -122,15 +128,13 @@ console.log(citations[1].resolution)
 ```typescript
 import { extractCitations, resolveCitations } from 'eyecite-ts'
 
-// Step 1: Extract citations
 const citations = extractCitations(text)
 
-// Step 2: Resolve short-form citations
 const resolved = resolveCitations(citations, text, {
-  scopeStrategy: 'paragraph',      // Only resolve within paragraphs
-  fuzzyPartyMatching: true,        // Enable fuzzy supra matching
-  partyMatchThreshold: 0.8,        // Similarity threshold (0-1)
-  reportUnresolved: true           // Report failure reasons
+  scopeStrategy: 'paragraph',
+  fuzzyPartyMatching: true,
+  partyMatchThreshold: 0.8,
+  reportUnresolved: true
 })
 ```
 
@@ -153,125 +157,91 @@ const resolved = resolveCitations(citations, text, {
 ```typescript
 const text = 'Smith v. Jones, 500 F.2d 123. Id. at 125.'
 const citations = extractCitations(text, { resolve: true })
-
-// citations[1].resolution.resolvedTo === 0 (points to Smith v. Jones)
+// citations[1].resolution.resolvedTo === 0
 ```
 
 **Supra citations:**
 
 ```typescript
-const text = 'Smith v. Jones, 500 F.2d 123. See also Smith, supra, at 130.'
+const text = 'Smith v. Jones, 500 F.2d 123. Smith, supra, at 130.'
 const citations = extractCitations(text, { resolve: true })
-
 // citations[1].resolution.resolvedTo === 0 (party name matches "Smith")
 ```
 
 **Short-form case citations:**
 
 ```typescript
-const text = 'Brown v. Board, 347 U.S. 483 (1954). See 347 U.S. at 495.'
+const text = 'Brown v. Board, 347 U.S. 483. See 347 U.S. at 495.'
 const citations = extractCitations(text, { resolve: true })
-
 // citations[1].resolution.resolvedTo === 0 (volume/reporter matches)
 ```
 
-### Handling Unresolved Citations
+**Unresolved citations:**
 
 ```typescript
 const text = 'Id. at 100.' // Orphan Id. with no preceding citation
-
 const citations = extractCitations(text, { resolve: true })
-
-console.log(citations[0].resolution)
-// {
-//   resolvedTo: undefined,
-//   failureReason: 'No preceding full citation found',
-//   confidence: 0,
-//   warnings: []
-// }
-```
-
-To suppress unresolved warnings:
-
-```typescript
-const citations = extractCitations(text, {
-  resolve: true,
-  resolutionOptions: {
-    reportUnresolved: false  // Omits resolution field for unresolved citations
-  }
-})
-```
-
-## Citation Validation
-
-Validate case citations against the reporters database:
-
-```typescript
-import { validateCitation } from 'eyecite-ts/data'
-
-// Returns citations with adjusted confidence scores
-const validated = await validateCitation(citations)
-
-// Confidence adjustments:
-// - +0.2 boost for reporter match
-// - -0.3 penalty for reporter mismatch
-// - -0.1 penalty for ambiguous reporter
+// citations[0].resolution.failureReason === 'No preceding full case citation found'
 ```
 
 ## Citation Annotation
 
-Add HTML/Markdown markup to citations:
+Add HTML markup to citations in text:
 
 ```typescript
 import { annotate } from 'eyecite-ts/annotate'
+import { extractCitations } from 'eyecite-ts'
+
+const text = 'See Smith v. Jones, 500 F.2d 123 (2020).'
+const citations = extractCitations(text)
 
-// Template mode (simple)
-const html = annotate(
-  text,
-  citations,
-  '<a href="{{url}}">{{text}}</a>'
-)
+// Template mode
+const result = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' }
+})
+// result.text === 'See Smith v. Jones, <cite>500 F.2d 123</cite> (2020).'
 
 // Callback mode (full control)
-const html = annotate(text, citations, (citation, text) => {
-  const url = `https://example.com/${citation.volume}/${citation.reporter}/${citation.page}`
-  return `<a href="${url}">${text}</a>`
+const result2 = annotate(text, citations, {
+  callback: (citation, surrounding) => {
+    if (citation.type === 'case') {
+      return `<a href="/cases/${citation.volume}">${citation.matchedText}</a>`
+    }
+    return citation.matchedText
+  }
 })
 ```
 
 Auto-escape is enabled by default for XSS protection:
 
 ```typescript
-// User input is automatically escaped
-const html = annotate(text, citations, '<a>{{text}}</a>', {
-  autoEscape: true  // default
+const result = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' },
+  autoEscape: true  // default — escapes &, <, >, ", ', /
 })
 ```
 
-## Bundle Size
+## Reporter Validation
 
-Core library is optimized for tree-shaking:
-
-- **Core extraction**: 2.5 KB gzipped
-- **Reporter database**: 88.5 KB gzipped (lazy-loaded)
-- **Annotation**: 0.5 KB gzipped
-
-Import only what you need:
+Validate case citations against the reporters database:
 
 ```typescript
-// Tree-shakeable imports
-import { extractCitations } from 'eyecite-ts'           // Core only
-import { validateCitation } from 'eyecite-ts/data'      // Core + data
-import { annotate } from 'eyecite-ts/annotate'          // Core + annotate
+import { extractWithValidation } from 'eyecite-ts'
+
+const validated = await extractWithValidation(text, { validate: true })
+// Confidence adjustments:
+//   +0.2 boost for reporter match
+//   -0.3 penalty for unknown reporter
+//   -0.1 per extra match for ambiguous reporter
 ```
 
-## Citation Types
+## Type System
 
-All citation types are exported with full TypeScript types:
+All citation types use a discriminated union on the `type` field:
 
 ```typescript
 import type {
-  Citation,
+  Citation,           // Union of all 9 types
   FullCaseCitation,
   StatuteCitation,
   JournalCitation,
@@ -280,24 +250,69 @@ import type {
   FederalRegisterCitation,
   IdCitation,
   SupraCitation,
-  ShortFormCaseCitation
+  ShortFormCaseCitation,
+  CitationOfType,     // Extract subtype: CitationOfType<'case'> = FullCaseCitation
+  ExtractorMap,       // Maps FullCitationType keys to citation subtypes
+  FullCitation,       // Union of full citation types
+  ShortFormCitation,  // Union of short-form types
 } from 'eyecite-ts'
+```
 
-// Discriminated union - switch on type
-citations.forEach(citation => {
-  switch (citation.type) {
-    case 'case':
-      console.log(citation.reporter)  // FullCaseCitation
-      break
-    case 'statute':
-      console.log(citation.title)     // StatuteCitation
-      break
-    case 'id':
-      console.log(citation.pincite)   // IdCitation
-      break
-    // etc.
-  }
-})
+### Type Guards
+
+```typescript
+import {
+  isFullCitation,
+  isShortFormCitation,
+  isCaseCitation,
+  isCitationType,
+  assertUnreachable
+} from 'eyecite-ts'
+
+// Specific guards
+if (isFullCitation(citation)) {
+  // citation: FullCitation
+}
+
+// Generic guard — narrows to any specific type
+if (isCitationType(citation, 'statute')) {
+  // citation: StatuteCitation
+}
+
+// Exhaustiveness check in switch statements
+switch (citation.type) {
+  case 'case': /* ... */ break
+  case 'statute': /* ... */ break
+  // ... all 9 types ...
+  default: assertUnreachable(citation.type)
+}
+```
+
+### Resolved Citation Types
+
+`ResolvedCitation` uses a conditional type — `resolution` is only meaningfully present on short-form citations:
+
+```typescript
+import type { ResolvedCitation } from 'eyecite-ts'
+
+// On short-form citations: resolution: ResolutionResult | undefined
+// On full citations: resolution?: undefined
+```
+
+## Bundle Size
+
+Three entry points for optimal tree-shaking:
+
+| Entry Point | Import | Gzipped |
+|------------|--------|---------|
+| Core extraction | `eyecite-ts` | 4.4 KB |
+| Annotation | `eyecite-ts/annotate` | 0.5 KB |
+| Reporter data | `eyecite-ts/data` | 88.5 KB (lazy-loaded) |
+
+```typescript
+import { extractCitations } from 'eyecite-ts'           // Core only
+import { annotate } from 'eyecite-ts/annotate'           // Annotation
+import { loadReporters } from 'eyecite-ts/data'          // Reporter database
 ```
 
 ## Architecture
@@ -307,28 +322,26 @@ Citation extraction follows a 4-stage pipeline:
 1. **Clean**: Remove HTML, normalize Unicode, fix smart quotes
 2. **Tokenize**: Apply regex patterns to find citation candidates
 3. **Extract**: Parse metadata (volume, reporter, page, etc.)
-4. **Translate**: Map positions from cleaned text → original text
+4. **Resolve** (optional): Link short-form citations to antecedents
 
-All positions (spans) track both cleaned and original text offsets.
+All positions (spans) track both cleaned and original text offsets via `TransformationMap`.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Type checking
-npm run typecheck
-
-# Build
-npm run build
+pnpm install         # Install dependencies
+pnpm test            # Run tests (vitest, watch mode)
+pnpm exec vitest run # Run tests once
+pnpm typecheck       # Type-check with tsc
+pnpm build           # Build (ESM + CJS + DTS)
+pnpm lint            # Lint with Biome
+pnpm format          # Format with Biome
 ```
 
+304 tests, 97% statement coverage, 91% branch coverage.
+
 ## License
 
 MIT

package/dist/annotate/index.cjs

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,n,r={}){let{useCleanText:i=!1,autoEscape:a=!0,template:o,callback:s}=r,c=[...n].sort((e,t)=>{let n=i?e.span.cleanStart:e.span.originalStart;return(i?t.span.cleanStart:t.span.originalStart)-n}),l=e,u=new Map;for(let n of c){let r=i?n.span.cleanStart:n.span.originalStart,c=i?n.span.cleanEnd:n.span.originalEnd,d=``;if(s)d=s(n,e.substring(Math.max(0,r-30),Math.min(e.length,c+30)));else if(o){let e=l.substring(r,c),n=a?t(e):e;d=o.before+n+o.after}else continue;l=l.slice(0,r)+d+l.slice(c),u.set(r,r)}return{text:l,positionMap:u,skipped:[]}}function t(e){let t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`,"/":`&#x2F;`};return e.replace(/[&<>"'\/]/g,e=>t[e])}exports.annotate=e;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});function e(e,t,i={}){let{useCleanText:a=!1,autoEscape:o=!0,template:s,callback:c}=i,l=[...t].sort((e,t)=>{let n=a?e.span.cleanStart:e.span.originalStart;return(a?t.span.cleanStart:t.span.originalStart)-n}),u=e,d=new Map,f=[];for(let t of l){let i=a?t.span.cleanStart:t.span.originalStart,l=a?t.span.cleanEnd:t.span.originalEnd;if(!a){let e=n(u,i,l);if(e===null){f.push(t);continue}i=e.start,l=e.end}let p=``;if(c)p=c(t,e.substring(Math.max(0,i-30),Math.min(e.length,l+30)));else if(s){let e=u.substring(i,l),t=o?r(e):e;p=s.before+t+s.after}else continue;u=u.slice(0,i)+p+u.slice(l),d.set(i,i)}return{text:u,positionMap:d,skipped:f}}function t(e,t){let n=t-1;for(;n>=0;){if(e[n]===`>`)return null;if(e[n]===`<`){let r=t;for(;r<e.length;){if(e[r]===`>`)return{tagStart:n,tagEnd:r+1};r++}return{tagStart:n,tagEnd:e.length}}n--}return null}function n(e,n,r){let i=n,a=r,o=t(e,n);o&&(i=o.tagStart);let s=t(e,r);return s&&(a=s.tagEnd),i>=a?null:{start:i,end:a}}function r(e){let t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`,"/":`&#x2F;`};return e.replace(/[&<>"'/]/g,e=>t[e])}exports.annotate=e;
 //# sourceMappingURL=index.cjs.map

package/dist/annotate/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate(\n  text: string,\n  citations: Citation[],\n  options: AnnotationOptions = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n\n  for (const citation of sorted) {\n    const start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    const end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped: [] }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'\\/]/g, (char) => map[char])\n}\n"],"mappings":"mEA+CA,SAAgB,EACd,EACA,EACA,EAA6B,EAAE,CACb,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAExB,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAM,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAE9D,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,QAAS,EAAE,CAAE,CAiBnD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,aAAe,GAAS,EAAI,GAAM"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate<C extends Citation = Citation>(\n  text: string,\n  citations: C[],\n  options: AnnotationOptions<C> = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n  const skipped: Citation[] = []\n\n  for (const citation of sorted) {\n    let start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    let end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    // Snap positions out of HTML tags when annotating original text\n    if (!useCleanText) {\n      const snapped = snapOutOfHtmlTags(result, start, end)\n      if (snapped === null) {\n        // Could not safely snap — skip this citation\n        skipped.push(citation)\n        continue\n      }\n      start = snapped.start\n      end = snapped.end\n    }\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped }\n}\n\n/**\n * Check if a position falls inside an HTML tag (between `<` and `>`).\n * Returns the index of the opening `<` if inside a tag, otherwise -1.\n */\nfunction findContainingTag(text: string, pos: number): { tagStart: number; tagEnd: number } | null {\n  // Search backwards from pos for '<' without encountering '>' first\n  let i = pos - 1\n  while (i >= 0) {\n    if (text[i] === '>') return null  // Hit a tag close — we're outside\n    if (text[i] === '<') {\n      // Found opening '<' — now find the closing '>'\n      let j = pos\n      while (j < text.length) {\n        if (text[j] === '>') return { tagStart: i, tagEnd: j + 1 }\n        j++\n      }\n      // Unclosed tag — treat as inside\n      return { tagStart: i, tagEnd: text.length }\n    }\n    i--\n  }\n  return null\n}\n\n/**\n * Snap annotation start/end positions to avoid landing inside HTML tags.\n *\n * If a position falls inside an HTML tag, it is moved:\n * - Start position: snapped to before the tag's `<`\n * - End position: snapped to after the tag's `>`\n *\n * Returns null if the positions can't be safely adjusted (e.g., entirely\n * within a single tag).\n */\nfunction snapOutOfHtmlTags(\n  text: string,\n  start: number,\n  end: number,\n): { start: number; end: number } | null {\n  let snappedStart = start\n  let snappedEnd = end\n\n  const startTag = findContainingTag(text, start)\n  if (startTag) {\n    snappedStart = startTag.tagStart\n  }\n\n  const endTag = findContainingTag(text, end)\n  if (endTag) {\n    snappedEnd = endTag.tagEnd\n  }\n\n  // Sanity check: start must come before end\n  if (snappedStart >= snappedEnd) return null\n\n  return { start: snappedStart, end: snappedEnd }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'/]/g, (char) => map[char])\n}\n"],"mappings":"mEA+CA,SAAgB,EACd,EACA,EACA,EAAgC,EAAE,CAChB,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAClB,EAAsB,EAAE,CAE9B,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAI,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAGhE,GAAI,CAAC,EAAc,CACjB,IAAM,EAAU,EAAkB,EAAQ,EAAO,EAAI,CACrD,GAAI,IAAY,KAAM,CAEpB,EAAQ,KAAK,EAAS,CACtB,SAEF,EAAQ,EAAQ,MAChB,EAAM,EAAQ,IAGhB,IAAI,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,UAAS,CAO/C,SAAS,EAAkB,EAAc,EAA0D,CAEjG,IAAI,EAAI,EAAM,EACd,KAAO,GAAK,GAAG,CACb,GAAI,EAAK,KAAO,IAAK,OAAO,KAC5B,GAAI,EAAK,KAAO,IAAK,CAEnB,IAAI,EAAI,EACR,KAAO,EAAI,EAAK,QAAQ,CACtB,GAAI,EAAK,KAAO,IAAK,MAAO,CAAE,SAAU,EAAG,OAAQ,EAAI,EAAG,CAC1D,IAGF,MAAO,CAAE,SAAU,EAAG,OAAQ,EAAK,OAAQ,CAE7C,IAEF,OAAO,KAaT,SAAS,EACP,EACA,EACA,EACuC,CACvC,IAAI,EAAe,EACf,EAAa,EAEX,EAAW,EAAkB,EAAM,EAAM,CAC3C,IACF,EAAe,EAAS,UAG1B,IAAM,EAAS,EAAkB,EAAM,EAAI,CAQ3C,OAPI,IACF,EAAa,EAAO,QAIlB,GAAgB,EAAmB,KAEhC,CAAE,MAAO,EAAc,IAAK,EAAY,CAiBjD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,YAAc,GAAS,EAAI,GAAM"}

package/dist/annotate/index.d.cts

@@ -1,4 +1,4 @@
-import { t as Citation } from "../citation-BcY5zzWb.cjs";
+import { t as Citation } from "../citation-qKSc_Myj.cjs";
 
 //#region src/annotate/types.d.ts
 /**
@@ -27,7 +27,7 @@ import { t as Citation } from "../citation-BcY5zzWb.cjs";
 * })
 * ```
 */
-interface AnnotationOptions {
+interface AnnotationOptions<C extends Citation = Citation> {
   /**
   * Apply annotations to cleaned text (true) or original text (false).
   *
@@ -65,7 +65,7 @@ interface AnnotationOptions {
   * @param surrounding - Text around the citation (for context-aware markup)
   * @returns Complete markup string (replaces citation.matchedText)
   */
-  callback?: (citation: Citation, surrounding: string) => string;
+  callback?: (citation: C, surrounding: string) => string;
   /**
   * Template mode: simple before/after markup strings.
   *
@@ -157,7 +157,7 @@ interface AnnotationResult {
 * const newPos = result.positionMap.get(originalPos)
 * ```
 */
-declare function annotate(text: string, citations: Citation[], options?: AnnotationOptions): AnnotationResult;
+declare function annotate<C extends Citation = Citation>(text: string, citations: C[], options?: AnnotationOptions<C>): AnnotationResult;
 //#endregion
 export { AnnotationOptions, AnnotationResult, annotate };
 //# sourceMappingURL=index.d.cts.map

package/dist/annotate/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;AAoEA;;;;;;;;;UApEiB,iBAAA;EA0FN;;;;ACvEX;;;;EDVE,YAAA;;;;;;;;;;;;;;;;;;EAmBA,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,QAAA,EAAU,WAAA;;;;;;;;;;;;;;;;EAiBhC,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;;;;;;;;iBAAgB,QAAA,CACd,IAAA,UACA,SAAA,EAAW,QAAA,IACX,OAAA,GAAS,iBAAA,GACR,gBAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;AAoEA;;UApEiB,iBAAA,WAA4B,QAAA,GAAW,QAAA;EA0F7C;;;;;;;;EAjFT,YAAA;;;ACUF;;;;;;;;;;;;;;;EDSE,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,CAAA,EAAG,WAAA;;;;;;;;;;;;;;;;EAiBzB,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;iBAAgB,QAAA,WAAmB,QAAA,GAAW,QAAA,CAAA,CAC5C,IAAA,UACA,SAAA,EAAW,CAAA,IACX,OAAA,GAAS,iBAAA,CAAkB,CAAA,IAC1B,gBAAA"}

package/dist/annotate/index.d.mts

@@ -1,4 +1,4 @@
-import { t as Citation } from "../citation-8_GvfEuj.mjs";
+import { t as Citation } from "../citation-DAyM8kNA.mjs";
 
 //#region src/annotate/types.d.ts
 /**
@@ -27,7 +27,7 @@ import { t as Citation } from "../citation-8_GvfEuj.mjs";
 * })
 * ```
 */
-interface AnnotationOptions {
+interface AnnotationOptions<C extends Citation = Citation> {
   /**
   * Apply annotations to cleaned text (true) or original text (false).
   *
@@ -65,7 +65,7 @@ interface AnnotationOptions {
   * @param surrounding - Text around the citation (for context-aware markup)
   * @returns Complete markup string (replaces citation.matchedText)
   */
-  callback?: (citation: Citation, surrounding: string) => string;
+  callback?: (citation: C, surrounding: string) => string;
   /**
   * Template mode: simple before/after markup strings.
   *
@@ -157,7 +157,7 @@ interface AnnotationResult {
 * const newPos = result.positionMap.get(originalPos)
 * ```
 */
-declare function annotate(text: string, citations: Citation[], options?: AnnotationOptions): AnnotationResult;
+declare function annotate<C extends Citation = Citation>(text: string, citations: C[], options?: AnnotationOptions<C>): AnnotationResult;
 //#endregion
 export { AnnotationOptions, AnnotationResult, annotate };
 //# sourceMappingURL=index.d.mts.map

package/dist/annotate/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;AAoEA;;;;;;;;;UApEiB,iBAAA;EA0FN;;;;ACvEX;;;;EDVE,YAAA;;;;;;;;;;;;;;;;;;EAmBA,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,QAAA,EAAU,WAAA;;;;;;;;;;;;;;;;EAiBhC,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;;;;;;;;iBAAgB,QAAA,CACd,IAAA,UACA,SAAA,EAAW,QAAA,IACX,OAAA,GAAS,iBAAA,GACR,gBAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;AAoEA;;UApEiB,iBAAA,WAA4B,QAAA,GAAW,QAAA;EA0F7C;;;;;;;;EAjFT,YAAA;;;ACUF;;;;;;;;;;;;;;;EDSE,UAAA;;;;;;;;;;;EAYA,QAAA,IAAY,QAAA,EAAU,CAAA,EAAG,WAAA;;;;;;;;;;;;;;;;EAiBzB,QAAA;+CAEE,MAAA;IAEA,KAAA;EAAA;AAAA;;;;UAOa,gBAAA;;;;EAIf,IAAA;;;;;;;;;EAUA,WAAA,EAAa,GAAA;;;;;;;EAQb,OAAA,EAAS,QAAA;AAAA;;;;AA1FX;;;;;;;;;;;;;;;;;;;;;;AAoEA;;;;;;;;;;;;;;ACjDA;;;;;;;iBAAgB,QAAA,WAAmB,QAAA,GAAW,QAAA,CAAA,CAC5C,IAAA,UACA,SAAA,EAAW,CAAA,IACX,OAAA,GAAS,iBAAA,CAAkB,CAAA,IAC1B,gBAAA"}

package/dist/annotate/index.mjs

@@ -1,2 +1,2 @@
-function e(e,n,r={}){let{useCleanText:i=!1,autoEscape:a=!0,template:o,callback:s}=r,c=[...n].sort((e,t)=>{let n=i?e.span.cleanStart:e.span.originalStart;return(i?t.span.cleanStart:t.span.originalStart)-n}),l=e,u=new Map;for(let n of c){let r=i?n.span.cleanStart:n.span.originalStart,c=i?n.span.cleanEnd:n.span.originalEnd,d=``;if(s)d=s(n,e.substring(Math.max(0,r-30),Math.min(e.length,c+30)));else if(o){let e=l.substring(r,c),n=a?t(e):e;d=o.before+n+o.after}else continue;l=l.slice(0,r)+d+l.slice(c),u.set(r,r)}return{text:l,positionMap:u,skipped:[]}}function t(e){let t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`,"/":`&#x2F;`};return e.replace(/[&<>"'\/]/g,e=>t[e])}export{e as annotate};
+function e(e,t,i={}){let{useCleanText:a=!1,autoEscape:o=!0,template:s,callback:c}=i,l=[...t].sort((e,t)=>{let n=a?e.span.cleanStart:e.span.originalStart;return(a?t.span.cleanStart:t.span.originalStart)-n}),u=e,d=new Map,f=[];for(let t of l){let i=a?t.span.cleanStart:t.span.originalStart,l=a?t.span.cleanEnd:t.span.originalEnd;if(!a){let e=n(u,i,l);if(e===null){f.push(t);continue}i=e.start,l=e.end}let p=``;if(c)p=c(t,e.substring(Math.max(0,i-30),Math.min(e.length,l+30)));else if(s){let e=u.substring(i,l),t=o?r(e):e;p=s.before+t+s.after}else continue;u=u.slice(0,i)+p+u.slice(l),d.set(i,i)}return{text:u,positionMap:d,skipped:f}}function t(e,t){let n=t-1;for(;n>=0;){if(e[n]===`>`)return null;if(e[n]===`<`){let r=t;for(;r<e.length;){if(e[r]===`>`)return{tagStart:n,tagEnd:r+1};r++}return{tagStart:n,tagEnd:e.length}}n--}return null}function n(e,n,r){let i=n,a=r,o=t(e,n);o&&(i=o.tagStart);let s=t(e,r);return s&&(a=s.tagEnd),i>=a?null:{start:i,end:a}}function r(e){let t={"&":`&amp;`,"<":`&lt;`,">":`&gt;`,'"':`&quot;`,"'":`&#39;`,"/":`&#x2F;`};return e.replace(/[&<>"'/]/g,e=>t[e])}export{e as annotate};
 //# sourceMappingURL=index.mjs.map

package/dist/annotate/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate(\n  text: string,\n  citations: Citation[],\n  options: AnnotationOptions = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n\n  for (const citation of sorted) {\n    const start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    const end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped: [] }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'\\/]/g, (char) => map[char])\n}\n"],"mappings":"AA+CA,SAAgB,EACd,EACA,EACA,EAA6B,EAAE,CACb,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAExB,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAM,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAE9D,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,QAAS,EAAE,CAAE,CAiBnD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,aAAe,GAAS,EAAI,GAAM"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/annotate/annotate.ts"],"sourcesContent":["import type { Citation } from '../types/citation'\nimport type { AnnotationOptions, AnnotationResult } from './types'\n\n/**\n * Annotate citations in text with custom markup.\n *\n * Supports two modes:\n * - **Template mode**: Simple before/after wrapping (set `options.template`)\n * - **Callback mode**: Custom logic with full citation context (set `options.callback`)\n *\n * Citations are processed in reverse order to avoid position shifts invalidating\n * subsequent annotations. Position tracking maps original positions to new positions\n * after markup insertion.\n *\n * @param text - Original or cleaned text to annotate\n * @param citations - Citations to mark up (from extraction pipeline)\n * @param options - Annotation configuration\n * @returns Annotated text with position mapping\n *\n * @example Template mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   template: { before: '<cite>', after: '</cite>' }\n * })\n * // Result: \"See <cite>500 F.2d 123</cite>\"\n * ```\n *\n * @example Callback mode\n * ```typescript\n * const result = annotate(text, citations, {\n *   callback: (citation) => {\n *     if (citation.type === 'case') {\n *       return `<a href=\"/cases/${citation.volume}\">${citation.matchedText}</a>`\n *     }\n *     return citation.matchedText\n *   }\n * })\n * ```\n *\n * @example Position tracking\n * ```typescript\n * const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })\n * // result.positionMap tracks how positions shifted\n * const originalPos = 10\n * const newPos = result.positionMap.get(originalPos)\n * ```\n */\nexport function annotate<C extends Citation = Citation>(\n  text: string,\n  citations: C[],\n  options: AnnotationOptions<C> = {}\n): AnnotationResult {\n  const {\n    useCleanText = false,\n    autoEscape = true,  // Secure by default\n    template,\n    callback,\n  } = options\n\n  // Sort reverse to avoid position shifts invalidating subsequent annotations\n  const sorted = [...citations].sort((a, b) => {\n    const aPos = useCleanText ? a.span.cleanStart : a.span.originalStart\n    const bPos = useCleanText ? b.span.cleanStart : b.span.originalStart\n    return bPos - aPos  // Reverse for backward iteration\n  })\n\n  let result = text\n  const positionMap = new Map<number, number>()\n  const skipped: Citation[] = []\n\n  for (const citation of sorted) {\n    let start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n    let end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n\n    // Snap positions out of HTML tags when annotating original text\n    if (!useCleanText) {\n      const snapped = snapOutOfHtmlTags(result, start, end)\n      if (snapped === null) {\n        // Could not safely snap — skip this citation\n        skipped.push(citation)\n        continue\n      }\n      start = snapped.start\n      end = snapped.end\n    }\n\n    let markup = ''\n\n    if (callback) {\n      // Callback mode: developer provides full logic\n      const surrounding = text.substring(\n        Math.max(0, start - 30),\n        Math.min(text.length, end + 30)\n      )\n      markup = callback(citation, surrounding)\n    } else if (template) {\n      // Template mode: simple before/after wrapping\n      const citationText = result.substring(start, end)\n      const escaped = autoEscape ? escapeHtmlEntities(citationText) : citationText\n      markup = template.before + escaped + template.after\n    } else {\n      // No annotation specified\n      continue\n    }\n\n    // Insert annotation (working backwards preserves positions for later citations)\n    result = result.slice(0, start) + markup + result.slice(end)\n\n    // Track original position to new position (before this annotation was added)\n    positionMap.set(start, start)\n  }\n\n  return { text: result, positionMap, skipped }\n}\n\n/**\n * Check if a position falls inside an HTML tag (between `<` and `>`).\n * Returns the index of the opening `<` if inside a tag, otherwise -1.\n */\nfunction findContainingTag(text: string, pos: number): { tagStart: number; tagEnd: number } | null {\n  // Search backwards from pos for '<' without encountering '>' first\n  let i = pos - 1\n  while (i >= 0) {\n    if (text[i] === '>') return null  // Hit a tag close — we're outside\n    if (text[i] === '<') {\n      // Found opening '<' — now find the closing '>'\n      let j = pos\n      while (j < text.length) {\n        if (text[j] === '>') return { tagStart: i, tagEnd: j + 1 }\n        j++\n      }\n      // Unclosed tag — treat as inside\n      return { tagStart: i, tagEnd: text.length }\n    }\n    i--\n  }\n  return null\n}\n\n/**\n * Snap annotation start/end positions to avoid landing inside HTML tags.\n *\n * If a position falls inside an HTML tag, it is moved:\n * - Start position: snapped to before the tag's `<`\n * - End position: snapped to after the tag's `>`\n *\n * Returns null if the positions can't be safely adjusted (e.g., entirely\n * within a single tag).\n */\nfunction snapOutOfHtmlTags(\n  text: string,\n  start: number,\n  end: number,\n): { start: number; end: number } | null {\n  let snappedStart = start\n  let snappedEnd = end\n\n  const startTag = findContainingTag(text, start)\n  if (startTag) {\n    snappedStart = startTag.tagStart\n  }\n\n  const endTag = findContainingTag(text, end)\n  if (endTag) {\n    snappedEnd = endTag.tagEnd\n  }\n\n  // Sanity check: start must come before end\n  if (snappedStart >= snappedEnd) return null\n\n  return { start: snappedStart, end: snappedEnd }\n}\n\n/**\n * Escape HTML entities to prevent XSS injection.\n *\n * Converts special HTML characters to their entity equivalents:\n * - `&` → `&amp;`\n * - `<` → `&lt;`\n * - `>` → `&gt;`\n * - `\"` → `&quot;`\n * - `'` → `&#39;`\n * - `/` → `&#x2F;`\n *\n * @param text - Text to escape\n * @returns Escaped text safe for HTML insertion\n */\nfunction escapeHtmlEntities(text: string): string {\n  const map: Record<string, string> = {\n    '&': '&amp;',\n    '<': '&lt;',\n    '>': '&gt;',\n    '\"': '&quot;',\n    \"'\": '&#39;',\n    '/': '&#x2F;',\n  }\n  return text.replace(/[&<>\"'/]/g, (char) => map[char])\n}\n"],"mappings":"AA+CA,SAAgB,EACd,EACA,EACA,EAAgC,EAAE,CAChB,CAClB,GAAM,CACJ,eAAe,GACf,aAAa,GACb,WACA,YACE,EAGE,EAAS,CAAC,GAAG,EAAU,CAAC,MAAM,EAAG,IAAM,CAC3C,IAAM,EAAO,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,cAEvD,OADa,EAAe,EAAE,KAAK,WAAa,EAAE,KAAK,eACzC,GACd,CAEE,EAAS,EACP,EAAc,IAAI,IAClB,EAAsB,EAAE,CAE9B,IAAK,IAAM,KAAY,EAAQ,CAC7B,IAAI,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,YAGhE,GAAI,CAAC,EAAc,CACjB,IAAM,EAAU,EAAkB,EAAQ,EAAO,EAAI,CACrD,GAAI,IAAY,KAAM,CAEpB,EAAQ,KAAK,EAAS,CACtB,SAEF,EAAQ,EAAQ,MAChB,EAAM,EAAQ,IAGhB,IAAI,EAAS,GAEb,GAAI,EAMF,EAAS,EAAS,EAJE,EAAK,UACvB,KAAK,IAAI,EAAG,EAAQ,GAAG,CACvB,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAChC,CACuC,SAC/B,EAAU,CAEnB,IAAM,EAAe,EAAO,UAAU,EAAO,EAAI,CAC3C,EAAU,EAAa,EAAmB,EAAa,CAAG,EAChE,EAAS,EAAS,OAAS,EAAU,EAAS,WAG9C,SAIF,EAAS,EAAO,MAAM,EAAG,EAAM,CAAG,EAAS,EAAO,MAAM,EAAI,CAG5D,EAAY,IAAI,EAAO,EAAM,CAG/B,MAAO,CAAE,KAAM,EAAQ,cAAa,UAAS,CAO/C,SAAS,EAAkB,EAAc,EAA0D,CAEjG,IAAI,EAAI,EAAM,EACd,KAAO,GAAK,GAAG,CACb,GAAI,EAAK,KAAO,IAAK,OAAO,KAC5B,GAAI,EAAK,KAAO,IAAK,CAEnB,IAAI,EAAI,EACR,KAAO,EAAI,EAAK,QAAQ,CACtB,GAAI,EAAK,KAAO,IAAK,MAAO,CAAE,SAAU,EAAG,OAAQ,EAAI,EAAG,CAC1D,IAGF,MAAO,CAAE,SAAU,EAAG,OAAQ,EAAK,OAAQ,CAE7C,IAEF,OAAO,KAaT,SAAS,EACP,EACA,EACA,EACuC,CACvC,IAAI,EAAe,EACf,EAAa,EAEX,EAAW,EAAkB,EAAM,EAAM,CAC3C,IACF,EAAe,EAAS,UAG1B,IAAM,EAAS,EAAkB,EAAM,EAAI,CAQ3C,OAPI,IACF,EAAa,EAAO,QAIlB,GAAgB,EAAmB,KAEhC,CAAE,MAAO,EAAc,IAAK,EAAY,CAiBjD,SAAS,EAAmB,EAAsB,CAChD,IAAM,EAA8B,CAClC,IAAK,QACL,IAAK,OACL,IAAK,OACL,IAAK,SACL,IAAK,QACL,IAAK,SACN,CACD,OAAO,EAAK,QAAQ,YAAc,GAAS,EAAI,GAAM"}