eyecite-ts 0.1.0

package/README.md

@@ -0,0 +1,338 @@
+# eyecite-ts
+
+TypeScript legal citation extraction library - port of Python [eyecite](https://github.com/freelawproject/eyecite).
+
+Extract, validate, annotate, and resolve legal citations from court opinions and legal documents with zero runtime dependencies and a <50KB bundle size.
+
+## 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
+
+## Installation
+
+```bash
+npm install eyecite-ts
+```
+
+## Quick Start
+
+```typescript
+import { extractCitations } from 'eyecite-ts'
+
+const text = 'See Smith v. Jones, 500 F.2d 123 (9th Cir. 2020)'
+const citations = extractCitations(text)
+
+console.log(citations[0])
+// {
+//   type: 'case',
+//   volume: 500,
+//   reporter: 'F.2d',
+//   page: 123,
+//   court: '9th Cir.',
+//   year: 2020,
+//   confidence: 0.85,
+//   span: { originalStart: 4, originalEnd: 48 }
+// }
+```
+
+## Citation Extraction
+
+### Basic Usage
+
+```typescript
+import { extractCitations } from 'eyecite-ts'
+
+const text = `
+  See Smith v. Jones, 500 F.2d 123 (9th Cir. 2020).
+  Also 42 U.S.C. § 1983.
+  Compare 123 Harv. L. Rev. 456.
+`
+const citations = extractCitations(text)
+
+citations.forEach(citation => {
+  console.log(citation.type) // 'case', 'statute', 'journal', etc.
+})
+```
+
+### Async API
+
+```typescript
+import { extractCitationsAsync } from 'eyecite-ts'
+
+const citations = await extractCitationsAsync(text)
+```
+
+### Custom Patterns
+
+```typescript
+import { extractCitations, casePatterns } from 'eyecite-ts'
+
+// Extract only case citations
+const citations = extractCitations(text, {
+  patterns: casePatterns
+})
+```
+
+### Custom Cleaners
+
+```typescript
+import { extractCitations, stripHtmlTags } from 'eyecite-ts'
+
+// Use only HTML stripping, skip Unicode normalization
+const citations = extractCitations(html, {
+  cleaners: [stripHtmlTags]
+})
+```
+
+## 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.
+
+### Convenience API
+
+```typescript
+import { extractCitations } from 'eyecite-ts'
+
+const text = `
+  Smith v. Jones, 500 F.2d 123 (2020).
+  Id. at 125.
+  Smith, supra, at 130.
+  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: []
+// }
+```
+
+### Power-User API
+
+```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
+})
+```
+
+### Resolution Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `scopeStrategy` | `'paragraph'` \| `'section'` \| `'footnote'` \| `'none'` | `'paragraph'` | How far back to search for antecedents |
+| `autoDetectParagraphs` | `boolean` | `true` | Auto-detect paragraph boundaries from text |
+| `paragraphBoundaryPattern` | `RegExp` | `/\n\n+/` | Pattern to detect paragraphs |
+| `fuzzyPartyMatching` | `boolean` | `true` | Enable fuzzy party name matching for supra |
+| `partyMatchThreshold` | `number` | `0.8` | Similarity threshold (0-1) for fuzzy matching |
+| `allowNestedResolution` | `boolean` | `false` | Allow Id. to resolve to other short-form citations |
+| `reportUnresolved` | `boolean` | `true` | Report failure reasons for unresolved citations |
+
+### Resolution Examples
+
+**Id. citations:**
+
+```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)
+```
+
+**Supra citations:**
+
+```typescript
+const text = 'Smith v. Jones, 500 F.2d 123. See also 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 citations = extractCitations(text, { resolve: true })
+
+// citations[1].resolution.resolvedTo === 0 (volume/reporter matches)
+```
+
+### Handling 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
+```
+
+## Citation Annotation
+
+Add HTML/Markdown markup to citations:
+
+```typescript
+import { annotate } from 'eyecite-ts/annotate'
+
+// Template mode (simple)
+const html = annotate(
+  text,
+  citations,
+  '<a href="{{url}}">{{text}}</a>'
+)
+
+// 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>`
+})
+```
+
+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
+})
+```
+
+## Bundle Size
+
+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:
+
+```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
+```
+
+## Citation Types
+
+All citation types are exported with full TypeScript types:
+
+```typescript
+import type {
+  Citation,
+  FullCaseCitation,
+  StatuteCitation,
+  JournalCitation,
+  NeutralCitation,
+  PublicLawCitation,
+  FederalRegisterCitation,
+  IdCitation,
+  SupraCitation,
+  ShortFormCaseCitation
+} 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.
+  }
+})
+```
+
+## Architecture
+
+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
+
+All positions (spans) track both cleaned and original text offsets.
+
+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
+```
+
+## License
+
+MIT
+
+## Credits
+
+Ported from [eyecite](https://github.com/freelawproject/eyecite) (Python) by Free Law Project.

package/dist/annotate/index.cjs

@@ -0,0 +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;
+//# sourceMappingURL=index.cjs.map

package/dist/annotate/index.cjs.map

@@ -0,0 +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"}

package/dist/annotate/index.d.cts

@@ -0,0 +1,163 @@
+import { t as Citation } from "../citation-BcY5zzWb.cjs";
+
+//#region src/annotate/types.d.ts
+/**
+* Options for annotating citations in text.
+*
+* Supports two modes:
+* - **Template mode**: Simple before/after string wrapping (e.g., `<cite>...</cite>`)
+* - **Callback mode**: Full custom annotation logic with access to citation and surrounding context
+*
+* @example Template mode
+* ```typescript
+* annotate(text, citations, {
+*   template: { before: '<mark data-type="case">', after: '</mark>' }
+* })
+* ```
+*
+* @example Callback mode
+* ```typescript
+* annotate(text, citations, {
+*   callback: (citation, surrounding) => {
+*     if (citation.type === 'case') {
+*       return `<a href="/cases/${citation.volume}-${citation.page}">${citation.matchedText}</a>`
+*     }
+*     return `<span>${citation.matchedText}</span>`
+*   }
+* })
+* ```
+*/
+interface AnnotationOptions {
+  /**
+  * Apply annotations to cleaned text (true) or original text (false).
+  *
+  * - `true`: Use citation.span.cleanStart/End positions
+  * - `false`: Use citation.span.originalStart/End positions
+  *
+  * @default false
+  */
+  useCleanText?: boolean;
+  /**
+  * Auto-escape HTML entities to prevent XSS injection.
+  *
+  * When enabled, special HTML characters are escaped:
+  * - `<` → `&lt;`
+  * - `>` → `&gt;`
+  * - `&` → `&amp;`
+  * - `"` → `&quot;`
+  * - `'` → `&#39;`
+  * - `/` → `&#x2F;`
+  *
+  * **SECURITY WARNING:** Disabling this option introduces XSS vulnerability
+  * if the text contains untrusted user input. Only disable if you are certain
+  * the text comes from a trusted source.
+  *
+  * @default true (secure by default)
+  */
+  autoEscape?: boolean;
+  /**
+  * Callback for custom annotation logic.
+  *
+  * Receives each citation and surrounding context (±30 characters),
+  * returns the complete markup string to replace the citation text.
+  *
+  * @param citation - The citation to annotate
+  * @param surrounding - Text around the citation (for context-aware markup)
+  * @returns Complete markup string (replaces citation.matchedText)
+  */
+  callback?: (citation: Citation, surrounding: string) => string;
+  /**
+  * Template mode: simple before/after markup strings.
+  *
+  * The citation text (with auto-escaping applied if enabled) is wrapped
+  * with these strings: `template.before + citationText + template.after`
+  *
+  * @example
+  * ```typescript
+  * template: {
+  *   before: '<cite data-type="case">',
+  *   after: '</cite>'
+  * }
+  * // Result: <cite data-type="case">500 F.2d 123</cite>
+  * ```
+  */
+  template?: {
+    /** Markup inserted before citation text */before: string; /** Markup inserted after citation text */
+    after: string;
+  };
+}
+/**
+* Result of annotation operation.
+*/
+interface AnnotationResult {
+  /**
+  * Annotated text with markup inserted at citation positions.
+  */
+  text: string;
+  /**
+  * Position mapping from original positions to annotated positions.
+  *
+  * Tracks how citation positions shift after markup insertion.
+  * Useful for updating external indices (search, highlighting, etc.)
+  *
+  * Maps: original position → new position after annotation
+  */
+  positionMap: Map<number, number>;
+  /**
+  * Citations that couldn't be annotated.
+  *
+  * Currently empty (all citations are annotated if callback/template provided).
+  * Future versions may skip overlapping citations or invalid positions.
+  */
+  skipped: Citation[];
+}
+//#endregion
+//#region src/annotate/annotate.d.ts
+/**
+* Annotate citations in text with custom markup.
+*
+* Supports two modes:
+* - **Template mode**: Simple before/after wrapping (set `options.template`)
+* - **Callback mode**: Custom logic with full citation context (set `options.callback`)
+*
+* Citations are processed in reverse order to avoid position shifts invalidating
+* subsequent annotations. Position tracking maps original positions to new positions
+* after markup insertion.
+*
+* @param text - Original or cleaned text to annotate
+* @param citations - Citations to mark up (from extraction pipeline)
+* @param options - Annotation configuration
+* @returns Annotated text with position mapping
+*
+* @example Template mode
+* ```typescript
+* const result = annotate(text, citations, {
+*   template: { before: '<cite>', after: '</cite>' }
+* })
+* // Result: "See <cite>500 F.2d 123</cite>"
+* ```
+*
+* @example Callback mode
+* ```typescript
+* const result = annotate(text, citations, {
+*   callback: (citation) => {
+*     if (citation.type === 'case') {
+*       return `<a href="/cases/${citation.volume}">${citation.matchedText}</a>`
+*     }
+*     return citation.matchedText
+*   }
+* })
+* ```
+*
+* @example Position tracking
+* ```typescript
+* const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })
+* // result.positionMap tracks how positions shifted
+* const originalPos = 10
+* const newPos = result.positionMap.get(originalPos)
+* ```
+*/
+declare function annotate(text: string, citations: Citation[], options?: AnnotationOptions): AnnotationResult;
+//#endregion
+export { AnnotationOptions, AnnotationResult, annotate };
+//# sourceMappingURL=index.d.cts.map

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

@@ -0,0 +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"}

package/dist/annotate/index.d.mts

@@ -0,0 +1,163 @@
+import { t as Citation } from "../citation-8_GvfEuj.mjs";
+
+//#region src/annotate/types.d.ts
+/**
+* Options for annotating citations in text.
+*
+* Supports two modes:
+* - **Template mode**: Simple before/after string wrapping (e.g., `<cite>...</cite>`)
+* - **Callback mode**: Full custom annotation logic with access to citation and surrounding context
+*
+* @example Template mode
+* ```typescript
+* annotate(text, citations, {
+*   template: { before: '<mark data-type="case">', after: '</mark>' }
+* })
+* ```
+*
+* @example Callback mode
+* ```typescript
+* annotate(text, citations, {
+*   callback: (citation, surrounding) => {
+*     if (citation.type === 'case') {
+*       return `<a href="/cases/${citation.volume}-${citation.page}">${citation.matchedText}</a>`
+*     }
+*     return `<span>${citation.matchedText}</span>`
+*   }
+* })
+* ```
+*/
+interface AnnotationOptions {
+  /**
+  * Apply annotations to cleaned text (true) or original text (false).
+  *
+  * - `true`: Use citation.span.cleanStart/End positions
+  * - `false`: Use citation.span.originalStart/End positions
+  *
+  * @default false
+  */
+  useCleanText?: boolean;
+  /**
+  * Auto-escape HTML entities to prevent XSS injection.
+  *
+  * When enabled, special HTML characters are escaped:
+  * - `<` → `&lt;`
+  * - `>` → `&gt;`
+  * - `&` → `&amp;`
+  * - `"` → `&quot;`
+  * - `'` → `&#39;`
+  * - `/` → `&#x2F;`
+  *
+  * **SECURITY WARNING:** Disabling this option introduces XSS vulnerability
+  * if the text contains untrusted user input. Only disable if you are certain
+  * the text comes from a trusted source.
+  *
+  * @default true (secure by default)
+  */
+  autoEscape?: boolean;
+  /**
+  * Callback for custom annotation logic.
+  *
+  * Receives each citation and surrounding context (±30 characters),
+  * returns the complete markup string to replace the citation text.
+  *
+  * @param citation - The citation to annotate
+  * @param surrounding - Text around the citation (for context-aware markup)
+  * @returns Complete markup string (replaces citation.matchedText)
+  */
+  callback?: (citation: Citation, surrounding: string) => string;
+  /**
+  * Template mode: simple before/after markup strings.
+  *
+  * The citation text (with auto-escaping applied if enabled) is wrapped
+  * with these strings: `template.before + citationText + template.after`
+  *
+  * @example
+  * ```typescript
+  * template: {
+  *   before: '<cite data-type="case">',
+  *   after: '</cite>'
+  * }
+  * // Result: <cite data-type="case">500 F.2d 123</cite>
+  * ```
+  */
+  template?: {
+    /** Markup inserted before citation text */before: string; /** Markup inserted after citation text */
+    after: string;
+  };
+}
+/**
+* Result of annotation operation.
+*/
+interface AnnotationResult {
+  /**
+  * Annotated text with markup inserted at citation positions.
+  */
+  text: string;
+  /**
+  * Position mapping from original positions to annotated positions.
+  *
+  * Tracks how citation positions shift after markup insertion.
+  * Useful for updating external indices (search, highlighting, etc.)
+  *
+  * Maps: original position → new position after annotation
+  */
+  positionMap: Map<number, number>;
+  /**
+  * Citations that couldn't be annotated.
+  *
+  * Currently empty (all citations are annotated if callback/template provided).
+  * Future versions may skip overlapping citations or invalid positions.
+  */
+  skipped: Citation[];
+}
+//#endregion
+//#region src/annotate/annotate.d.ts
+/**
+* Annotate citations in text with custom markup.
+*
+* Supports two modes:
+* - **Template mode**: Simple before/after wrapping (set `options.template`)
+* - **Callback mode**: Custom logic with full citation context (set `options.callback`)
+*
+* Citations are processed in reverse order to avoid position shifts invalidating
+* subsequent annotations. Position tracking maps original positions to new positions
+* after markup insertion.
+*
+* @param text - Original or cleaned text to annotate
+* @param citations - Citations to mark up (from extraction pipeline)
+* @param options - Annotation configuration
+* @returns Annotated text with position mapping
+*
+* @example Template mode
+* ```typescript
+* const result = annotate(text, citations, {
+*   template: { before: '<cite>', after: '</cite>' }
+* })
+* // Result: "See <cite>500 F.2d 123</cite>"
+* ```
+*
+* @example Callback mode
+* ```typescript
+* const result = annotate(text, citations, {
+*   callback: (citation) => {
+*     if (citation.type === 'case') {
+*       return `<a href="/cases/${citation.volume}">${citation.matchedText}</a>`
+*     }
+*     return citation.matchedText
+*   }
+* })
+* ```
+*
+* @example Position tracking
+* ```typescript
+* const result = annotate(text, citations, { template: { before: '<mark>', after: '</mark>' } })
+* // result.positionMap tracks how positions shifted
+* const originalPos = 10
+* const newPos = result.positionMap.get(originalPos)
+* ```
+*/
+declare function annotate(text: string, citations: Citation[], options?: AnnotationOptions): AnnotationResult;
+//#endregion
+export { AnnotationOptions, AnnotationResult, annotate };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +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"}

package/dist/annotate/index.mjs

@@ -0,0 +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};
+//# sourceMappingURL=index.mjs.map