eyecite-ts 0.2.0 → 0.4.0

package/README.md

@@ -1,18 +1,30 @@
 # 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)
+
+TypeScript legal citation extraction library — inspired by and extending 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
+- **Case name & full span**: Backward search extracts case names ("Smith v. Jones", "In re Smith"), `fullSpan` covers case name through closing parenthetical
+- **Parallel citation linking**: Automatic detection and grouping of comma-separated citations sharing a parenthetical (e.g., "410 U.S. 113, 93 S. Ct. 705 (1973)")
+- **Complex parentheticals**: Unified parser handles court+year, full dates (Jan. 15, 2020 / January 15, 2020 / 1/15/2020), disposition (en banc, per curiam), and chained parentheticals
 - **Short-form resolution**: Id./Ibid., supra, and short-form case citations resolved to their full antecedents
 - **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
+- **Zero dependencies**: No runtime dependencies, 7KB gzipped core bundle
 
 ## Installation
 
@@ -25,7 +37,7 @@ npm install eyecite-ts
 ```typescript
 import { extractCitations } from 'eyecite-ts'
 
-const text = 'See Smith v. Jones, 500 F.2d 123 (9th Cir. 2020)'
+const text = 'See Smith v. Jones, 500 F.2d 123 (9th Cir. Jan. 15, 2020)'
 const citations = extractCitations(text)
 
 console.log(citations[0])
@@ -36,8 +48,11 @@ console.log(citations[0])
 //   page: 123,
 //   court: '9th Cir.',
 //   year: 2020,
+//   caseName: 'Smith v. Jones',
+//   date: { iso: '2020-01-15', parsed: { year: 2020, month: 1, day: 15 } },
 //   confidence: 0.85,
-//   span: { originalStart: 4, originalEnd: 48, cleanStart: 4, cleanEnd: 48 }
+//   span: { originalStart: 20, originalEnd: 33, ... },
+//   fullSpan: { originalStart: 4, originalEnd: 57, ... }
 // }
 ```
 
@@ -91,6 +106,97 @@ const citations = extractCitations(html, {
 })
 ```
 
+## Case Names & Full Spans
+
+Case citations can include the case name and full citation boundaries:
+
+```typescript
+const text = 'In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc), the court held...'
+const citations = extractCitations(text)
+
+if (citations[0].type === 'case') {
+  console.log(citations[0].caseName)     // 'Smith v. Jones'
+  console.log(citations[0].disposition)  // 'en banc'
+  console.log(citations[0].fullSpan)     // covers "Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc)"
+  console.log(citations[0].span)         // covers "500 F.2d 123" only (citation core)
+}
+```
+
+Procedural prefixes are recognized automatically:
+
+```typescript
+const text = 'In re Smith, 410 U.S. 113 (1973)'
+// caseName: 'In re Smith'
+
+const text2 = 'Ex parte Young, 209 U.S. 123 (1908)'
+// caseName: 'Ex parte Young'
+```
+
+### Structured Dates
+
+Parentheticals with full dates return structured date objects:
+
+```typescript
+const text = '500 F.3d 100 (2d Cir. Jan. 15, 2020)'
+// date: { iso: '2020-01-15', parsed: { year: 2020, month: 1, day: 15 } }
+
+const text2 = '410 U.S. 113 (1973)'
+// date: { iso: '1973', parsed: { year: 1973 } }
+```
+
+Three date formats are supported: `Jan. 15, 2020`, `January 15, 2020`, and `1/15/2020`.
+
+### Blank Page Citations
+
+Citations can reference blank pages using placeholder notation:
+
+```typescript
+const text = '500 F.2d ___ (2020)'
+const citations = extractCitations(text)
+
+if (citations[0].type === 'case') {
+  console.log(citations[0].hasBlankPage)  // true
+  console.log(citations[0].page)          // undefined
+}
+```
+
+Both `___` (triple underscore) and `---` (triple dash) are recognized as blank page placeholders. These appear in slip opinions or unpublished decisions where the final reporter page number is not yet available.
+
+## Parallel Citations
+
+When multiple case citations share the same parenthetical, they represent parallel citations for the same case in different reporters. The library automatically detects and groups them:
+
+```typescript
+const text = 'See 410 U.S. 113, 93 S. Ct. 705, 35 L. Ed. 2d 147 (1973).'
+const citations = extractCitations(text)
+
+// Returns 3 citations, all linked by groupId
+console.log(citations[0].groupId)  // "410-U.S.-113"
+console.log(citations[1].groupId)  // "410-U.S.-113" (same group)
+console.log(citations[2].groupId)  // "410-U.S.-113" (same group)
+
+// Primary citation (first in group) has parallelCitations array
+if (citations[0].type === 'case') {
+  console.log(citations[0].parallelCitations)
+  // [
+  //   { volume: 93, reporter: 'S. Ct.', page: 705 },
+  //   { volume: 35, reporter: 'L. Ed. 2d', page: 147 }
+  // ]
+}
+
+// Secondary citations don't duplicate the array
+console.log(citations[1].parallelCitations)  // undefined
+console.log(citations[2].parallelCitations)  // undefined
+```
+
+**Key points:**
+- All citations in a parallel group share the same `groupId`
+- Only the **first citation** (primary) has the `parallelCitations` array
+- Secondary citations remain in the results array for individual processing
+- Group ID format: `${volume}-${reporter}-${page}` (e.g., "410-U.S.-113")
+
+Use `groupId` to identify which citations refer to the same case, or access `parallelCitations` on the primary to get all reporters at once.
+
 ## Resolving Short-Form Citations
 
 Short-form citations (Id., supra, short-form case) refer to earlier citations in the document. The resolution engine links them to their full antecedents.
@@ -212,6 +318,38 @@ const result = annotate(text, citations, {
 })
 ```
 
+### Annotating Full Spans
+
+By default, annotation wraps only the citation core (volume-reporter-page). Use `useFullSpan` to annotate from the case name through the closing parenthetical:
+
+```typescript
+const text = 'In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc), the court held...'
+const citations = extractCitations(text)
+
+// Default: annotates only "500 F.2d 123"
+const coreOnly = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' }
+})
+// Result: "In Smith v. Jones, <cite>500 F.2d 123</cite> (9th Cir. 2020) (en banc), the court held..."
+
+// With useFullSpan: annotates "Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc)"
+const fullSpan = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' },
+  useFullSpan: true
+})
+// Result: "In <cite>Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc)</cite>, the court held..."
+```
+
+Full span annotation covers:
+- Case name (if present)
+- Volume-reporter-page
+- Court and date parenthetical
+- Disposition parenthetical (en banc, per curiam)
+- Chained parentheticals
+- Subsequent history
+
+Use `useFullSpan: true` when you want to highlight the entire citation as a unit, or `useFullSpan: false` (default) to annotate only the citation core for minimal markup.
+
 ## Reporter Validation
 
 Validate case citations against the reporters database:
@@ -296,9 +434,9 @@ 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) |
+| Core extraction | `eyecite-ts` | 7.0 KB |
+| Annotation | `eyecite-ts/annotate` | 0.7 KB |
+| Reporter data | `eyecite-ts/data` | 86.5 KB (lazy-loaded) |
 
 ```typescript
 import { extractCitations } from 'eyecite-ts'           // Core only
@@ -322,16 +460,16 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 ## Development
 
 ```bash
-npm install          # Install dependencies
-npm test             # Run tests (vitest, watch mode)
-npx vitest run       # Run tests once
-npm run typecheck    # Type-check with tsc
-npm run build        # Build (ESM + CJS + DTS)
-npm run lint         # Lint with Biome
-npm run format       # Format with Biome
+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.
+527 tests across 22 test files.
 
 ## License
 
@@ -339,4 +477,4 @@ MIT
 
 ## Credits
 
-Ported from [eyecite](https://github.com/freelawproject/eyecite) (Python) by Free Law Project.
+Inspired by [eyecite](https://github.com/freelawproject/eyecite) (Python) by Free Law Project. This TypeScript implementation adds parallel citation linking, party name extraction, full span tracking, and performance optimizations while maintaining compatibility with the original API design.

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,useFullSpan:s=!1,template:c,callback:l}=i,u=[...t].sort((e,t)=>{let n=a?e.span.cleanStart:e.span.originalStart;return(a?t.span.cleanStart:t.span.originalStart)-n}),d=e,f=new Map,p=[];for(let t of u){let i,u;if(s&&`fullSpan`in t&&t.fullSpan?(i=a?t.fullSpan.cleanStart:t.fullSpan.originalStart,u=a?t.fullSpan.cleanEnd:t.fullSpan.originalEnd):(i=a?t.span.cleanStart:t.span.originalStart,u=a?t.span.cleanEnd:t.span.originalEnd),!a){let e=n(d,i,u);if(e===null){p.push(t);continue}i=e.start,u=e.end}let m=``;if(l)m=l(t,e.substring(Math.max(0,i-30),Math.min(e.length,u+30)));else if(c){let e=d.substring(i,u),t=o?r(e):e;m=c.before+t+c.after}else continue;d=d.slice(0,i)+m+d.slice(u),f.set(i,i)}return{text:d,positionMap:f,skipped:p}}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<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\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,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,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    useFullSpan = false,  // Backward compatible 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    // Determine which span to use\n    let start: number\n    let end: number\n\n    if (useFullSpan && 'fullSpan' in citation && citation.fullSpan) {\n      // Full span mode: case name through parenthetical\n      start = useCleanText ? citation.fullSpan.cleanStart : citation.fullSpan.originalStart\n      end = useCleanText ? citation.fullSpan.cleanEnd : citation.fullSpan.originalEnd\n    } else {\n      // Default mode: core citation only\n      start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n      end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n    }\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,cAAc,GACd,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,CAE7B,IAAI,EACA,EAaJ,GAXI,GAAe,aAAc,GAAY,EAAS,UAEpD,EAAQ,EAAe,EAAS,SAAS,WAAa,EAAS,SAAS,cACxE,EAAM,EAAe,EAAS,SAAS,SAAW,EAAS,SAAS,cAGpE,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,aAI1D,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-BhJJj_AZ.cjs";
+import { t as Citation } from "../citation-4bmWbhSK.cjs";
 
 //#region src/annotate/types.d.ts
 /**
@@ -56,6 +56,19 @@ interface AnnotationOptions<C extends Citation = Citation> {
   */
   autoEscape?: boolean;
   /**
+  * Use full citation span from case name through parenthetical (true) or core citation only (false).
+  *
+  * When enabled and citation has a fullSpan field (from Phase 6+), annotation will span:
+  * - Case name: "Smith v. Jones"
+  * - Reporter: "500 F.2d 123"
+  * - Parenthetical: "(9th Cir. 1974)"
+  *
+  * When disabled or fullSpan unavailable, falls back to core citation span (volume-reporter-page).
+  *
+  * @default false (backward compatible)
+  */
+  useFullSpan?: boolean;
+  /**
   * Callback for custom annotation logic.
   *
   * Receives each citation and surrounding context (±30 characters),

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,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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;;AAkFA;UAlFiB,iBAAA,WAA4B,QAAA,GAAW,QAAA;;;;;;;;;EAStD,YAAA;;;;ACUF;;;;;;;;;;;;;;EDSE,UAAA;;;;;;;;;;;;;EAcA,WAAA;;;;;;;;;;;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;;;;AAxGX;;;;;;;;;;;;;;;;;;;;;;;AAkFA;;;;;;;;;;;;;;AC/DA;;;;;;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-FJ10UFM7.mjs";
+import { t as Citation } from "../citation-BVN0o8TJ.mjs";
 
 //#region src/annotate/types.d.ts
 /**
@@ -56,6 +56,19 @@ interface AnnotationOptions<C extends Citation = Citation> {
   */
   autoEscape?: boolean;
   /**
+  * Use full citation span from case name through parenthetical (true) or core citation only (false).
+  *
+  * When enabled and citation has a fullSpan field (from Phase 6+), annotation will span:
+  * - Case name: "Smith v. Jones"
+  * - Reporter: "500 F.2d 123"
+  * - Parenthetical: "(9th Cir. 1974)"
+  *
+  * When disabled or fullSpan unavailable, falls back to core citation span (volume-reporter-page).
+  *
+  * @default false (backward compatible)
+  */
+  useFullSpan?: boolean;
+  /**
   * Callback for custom annotation logic.
   *
   * Receives each citation and surrounding context (±30 characters),

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,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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/annotate/types.ts","../../src/annotate/annotate.ts"],"mappings":";;;;;AA4BA;;;;;;;;;;;;;;;;;;;;;;;AAkFA;UAlFiB,iBAAA,WAA4B,QAAA,GAAW,QAAA;;;;;;;;;EAStD,YAAA;;;;ACUF;;;;;;;;;;;;;;EDSE,UAAA;;;;;;;;;;;;;EAcA,WAAA;;;;;;;;;;;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;;;;AAxGX;;;;;;;;;;;;;;;;;;;;;;;AAkFA;;;;;;;;;;;;;;AC/DA;;;;;;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,useFullSpan:s=!1,template:c,callback:l}=i,u=[...t].sort((e,t)=>{let n=a?e.span.cleanStart:e.span.originalStart;return(a?t.span.cleanStart:t.span.originalStart)-n}),d=e,f=new Map,p=[];for(let t of u){let i,u;if(s&&`fullSpan`in t&&t.fullSpan?(i=a?t.fullSpan.cleanStart:t.fullSpan.originalStart,u=a?t.fullSpan.cleanEnd:t.fullSpan.originalEnd):(i=a?t.span.cleanStart:t.span.originalStart,u=a?t.span.cleanEnd:t.span.originalEnd),!a){let e=n(d,i,u);if(e===null){p.push(t);continue}i=e.start,u=e.end}let m=``;if(l)m=l(t,e.substring(Math.max(0,i-30),Math.min(e.length,u+30)));else if(c){let e=d.substring(i,u),t=o?r(e):e;m=c.before+t+c.after}else continue;d=d.slice(0,i)+m+d.slice(u),f.set(i,i)}return{text:d,positionMap:f,skipped:p}}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<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\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,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,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    useFullSpan = false,  // Backward compatible 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    // Determine which span to use\n    let start: number\n    let end: number\n\n    if (useFullSpan && 'fullSpan' in citation && citation.fullSpan) {\n      // Full span mode: case name through parenthetical\n      start = useCleanText ? citation.fullSpan.cleanStart : citation.fullSpan.originalStart\n      end = useCleanText ? citation.fullSpan.cleanEnd : citation.fullSpan.originalEnd\n    } else {\n      // Default mode: core citation only\n      start = useCleanText ? citation.span.cleanStart : citation.span.originalStart\n      end = useCleanText ? citation.span.cleanEnd : citation.span.originalEnd\n    }\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,cAAc,GACd,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,CAE7B,IAAI,EACA,EAaJ,GAXI,GAAe,aAAc,GAAY,EAAS,UAEpD,EAAQ,EAAe,EAAS,SAAS,WAAa,EAAS,SAAS,cACxE,EAAM,EAAe,EAAS,SAAS,SAAW,EAAS,SAAS,cAGpE,EAAQ,EAAe,EAAS,KAAK,WAAa,EAAS,KAAK,cAChE,EAAM,EAAe,EAAS,KAAK,SAAW,EAAS,KAAK,aAI1D,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/{citation-BhJJj_AZ.d.cts → citation-4bmWbhSK.d.cts}

@@ -43,7 +43,7 @@ interface TransformationMap {
 /**
 * Citation type discriminator for type-safe pattern matching.
 */
-type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "id" | "supra" | "shortFormCase";
+type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "id" | "supra" | "shortFormCase";
 /**
 * Warning generated during citation parsing.
 */
@@ -93,17 +93,26 @@ interface CitationBase {
 */
 interface FullCaseCitation extends CitationBase {
   type: "case";
-  volume: number;
+  volume: number | string;
   reporter: string;
-  page: number;
+  /** Page number — optional for blank page placeholder citations (e.g., "___" or "---") */
+  page?: number;
   pincite?: number;
   court?: string;
   year?: number;
   /** Normalized reporter abbreviation from reporters-db (e.g., "F.2d" vs "F. 2d") */
   normalizedReporter?: string;
+  /**
+  * Group identifier for parallel citations (same case in multiple reporters).
+  * Populated by Phase 8 (Parallel Linking).
+  * Format: ${volume}-${reporter}-${page} (e.g., "410-U.S.-113")
+  * All citations in the same parallel group share the same groupId.
+  * @example "410-U.S.-113" for parallel group [410 U.S. 113, 93 S. Ct. 705]
+  */
+  groupId?: string;
   /** Parallel citations for same case in different reporters */
   parallelCitations?: Array<{
-    volume: number;
+    volume: number | string;
     reporter: string;
     page: number;
   }>;
@@ -131,12 +140,66 @@ interface FullCaseCitation extends CitationBase {
   * Used when reporter abbreviation matches multiple reporters or format is unclear.
   */
   possibleInterpretations?: Array<{
-    volume: number;
+    volume: number | string;
     reporter: string;
     page: number;
     confidence: number;
     reason: string;
   }>;
+  /**
+  * Full span covering citation from case name through closing parenthetical.
+  * Populated by Phase 6 (Full Span extraction).
+  * @example For "Smith v. Doe, 500 F.2d 123 (2020)", fullSpan covers entire text.
+  */
+  fullSpan?: Span;
+  /**
+  * Extracted case name (party names around "v.").
+  * Populated by Phase 6 (Full Span extraction).
+  * @example "Smith v. Doe" or "United States v. Jones"
+  */
+  caseName?: string;
+  /**
+  * Plaintiff party name (text before "v." or procedural prefix).
+  * Populated by Phase 7 (Party Name extraction).
+  * @example "Smith" from "Smith v. Doe" or "Jones" from "In re Jones"
+  */
+  plaintiff?: string;
+  /**
+  * Defendant party name (text after "v.").
+  * Populated by Phase 7 (Party Name extraction).
+  * @example "Doe" from "Smith v. Doe"
+  */
+  defendant?: string;
+  /**
+  * Normalized plaintiff name for matching (lowercase, stripped of noise).
+  * Populated by Phase 7 (Party Name extraction).
+  * @example "smith" from "The Smith Corp., Inc."
+  */
+  plaintiffNormalized?: string;
+  /**
+  * Normalized defendant name for matching (lowercase, stripped of noise).
+  * Populated by Phase 7 (Party Name extraction).
+  * @example "doe" from "Doe et al."
+  */
+  defendantNormalized?: string;
+  /**
+  * Procedural prefix for non-adversarial cases.
+  * Populated by Phase 7 (Party Name extraction).
+  * @example "In re" from "In re Smith"
+  */
+  proceduralPrefix?: string;
+  /**
+  * True when page position contains a blank placeholder ("___" or "---").
+  * Populated by Phase 5 (Blank Page support).
+  * When true, page field will be undefined and confidence reduced to 0.8.
+  */
+  hasBlankPage?: boolean;
+  /**
+  * Disposition or procedural status from parenthetical.
+  * Populated by Phase 6 (Complex Parentheticals).
+  * @example "en banc", "per curiam"
+  */
+  disposition?: string;
 }
 /**
 * Statute citation (U.S. Code, state codes, etc.).
@@ -163,8 +226,8 @@ interface JournalCitation extends CitationBase {
   author?: string;
   /** Article title (if extracted) */
   title?: string;
-  /** Volume number */
-  volume?: number;
+  /** Volume number (string for hyphenated volumes like "1984-1") */
+  volume?: number | string;
   /** Full journal name */
   journal: string;
   /** Standard journal abbreviation (e.g., "Harv. L. Rev.") */
@@ -221,7 +284,17 @@ interface PublicLawCitation extends CitationBase {
 interface FederalRegisterCitation extends CitationBase {
   type: "federalRegister";
   /** Federal Register volume */
-  volume: number;
+  volume: number | string;
+  /** Page number */
+  page: number;
+  /** Publication year (if extracted) */
+  year?: number;
+}
+/** Citation to the Statutes at Large (session law compilation) */
+interface StatutesAtLargeCitation extends CitationBase {
+  type: "statutesAtLarge";
+  /** Statutes at Large volume */
+  volume: number | string;
   /** Page number */
   page: number;
   /** Publication year (if extracted) */
@@ -258,7 +331,7 @@ interface SupraCitation extends CitationBase {
 */
 interface ShortFormCaseCitation extends CitationBase {
   type: "shortFormCase";
-  volume: number;
+  volume: number | string;
   reporter: string;
   page?: number;
   pincite?: number;
@@ -280,16 +353,16 @@ interface ShortFormCaseCitation extends CitationBase {
 *   // ...
 * }
 */
-type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
 /**
 * Citation type discriminators grouped by category.
 */
-type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister";
+type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge";
 type ShortFormCitationType = "id" | "supra" | "shortFormCase";
 /**
 * Union of all full citation types (not short-form references).
 */
-type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation;
+type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation;
 /**
 * Union of all short-form citation types (Id., supra, short-form case).
 */
@@ -312,5 +385,5 @@ type CitationOfType<T extends CitationType> = Extract<Citation, {
 */
 type ExtractorMap = { [K in FullCitationType]: CitationOfType<K> };
 //#endregion
-export { StatuteCitation as _, ExtractorMap as a, Span as b, FullCitation as c, JournalCitation as d, NeutralCitation as f, ShortFormCitationType as g, ShortFormCitation as h, CitationType as i, FullCitationType as l, ShortFormCaseCitation as m, CitationBase as n, FederalRegisterCitation as o, PublicLawCitation as p, CitationOfType as r, FullCaseCitation as s, Citation as t, IdCitation as u, SupraCitation as v, TransformationMap as x, Warning as y };
-//# sourceMappingURL=citation-BhJJj_AZ.d.cts.map
+export { TransformationMap as S, StatuteCitation as _, ExtractorMap as a, Warning as b, FullCitation as c, JournalCitation as d, NeutralCitation as f, ShortFormCitationType as g, ShortFormCitation as h, CitationType as i, FullCitationType as l, ShortFormCaseCitation as m, CitationBase as n, FederalRegisterCitation as o, PublicLawCitation as p, CitationOfType as r, FullCaseCitation as s, Citation as t, IdCitation as u, StatutesAtLargeCitation as v, Span as x, SupraCitation as y };
+//# sourceMappingURL=citation-4bmWbhSK.d.cts.map

package/dist/citation-4bmWbhSK.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-4bmWbhSK.d.cts","names":[],"sources":["../src/types/span.ts","../src/types/citation.ts"],"mappings":";;AAiBA;;;;;;;;;;AAoBA;;;;;;UApBiB,IAAA;;EAEf,UAAA;EAuBiB;EApBjB,QAAA;;EAGA,aAAA;ECpBF;EDuBE,WAAA;AAAA;;;AClBF;;;;UD2BiB,iBAAA;;EAEf,eAAA,EAAiB,GAAA;;EAGjB,eAAA,EAAiB,GAAA;AAAA;;;AAzBnB;;;AAAA,KCZY,YAAA;;;;UAKK,OAAA;;EAEf,KAAA;EDyBF;ECvBE,OAAA;;EAEA,QAAA;IAAY,KAAA;IAAe,GAAA;EAAA;;EAE3B,OAAA;AAAA;;;;UAMe,YAAA;EAnBL;EAqBV,IAAA;EArBU;EAwBV,IAAA,EAAM,IAAA;EAnBR;;;;;;;EA4BE,UAAA;;EAGA,WAAA;;EAGA,aAAA;EApBF;EAuBE,eAAA;;EAGA,QAAA,GAAW,OAAA;AAAA;;;;;;;UASI,gBAAA,SAAyB,YAAA;EACxC,IAAA;EACA,MAAA;EACA,QAAA;EAHF;EAKE,IAAA;EACA,OAAA;EACA,KAAA;EACA,IAAA;;EAGA,kBAAA;;;;;;;;EASA,OAAA;;EAGA,iBAAA,GAAoB,KAAA;IAClB,MAAA;IACA,QAAA;IACA,IAAA;EAAA;;EAIF,MAAA;;EAGA,aAAA;;EAGA,iBAAA;;;;;;EAOA,IAAA;IACE,GAAA;IACA,MAAA;MAAW,IAAA;MAAc,KAAA;MAAgB,GAAA;IAAA;EAAA;;;;;EAO3C,uBAAA,GAA0B,KAAA;IACxB,MAAA;IACA,QAAA;IACA,IAAA;IACA,UAAA;IACA,MAAA;EAAA;EAgEF;AAQF;;;;EAhEE,QAAA,GAAW,IAAA;;;;;;EAOX,QAAA;EAwEF;;;;;EAjEE,SAAA;;;;;;EAOA,SAAA;;;;;AAsFF;EA/EE,mBAAA;;;;;;EAOA,mBAAA;;;;AA0FF;;EAnFE,gBAAA;EAmFyC;;;;;EA5EzC,YAAA;;;AA8FF;;;EAvFE,WAAA;AAAA;;;;;;UAQe,eAAA,SAAwB,YAAA;EACvC,IAAA;EACA,KAAA;EACA,IAAA;EACA,OAAA;AAAA;;;;;;;AAsGF;;UA3FiB,eAAA,SAAwB,YAAA;EACvC,IAAA;;EAEA,MAAA;;EAEA,KAAA;EAwFA;EAtFA,MAAA;EA+Fe;EA7Ff,OAAA;EA6FqC;EA3FrC,YAAA;;EAEA,IAAA;;EAEA,OAAA;EA4FA;EA1FA,IAAA;AAAA;;;;;;;;;UAWe,eAAA,SAAwB,YAAA;EACvC,IAAA;EAgHF;EA9GE,IAAA;;EAEA,KAAA;;EAEA,cAAA;AAAA;;;;;;;;;UAWe,iBAAA,SAA0B,YAAA;EACzC,IAAA;;EAEA,QAAA;;EAEA,SAAA;;EAEA,KAAA;AAAA;;;;AAuGF;;;;;UA5FiB,uBAAA,SAAgC,YAAA;EAC/C,IAAA;;EAEA,MAAA;EA0FU;EAxFV,IAAA;EA6FU;EA3FV,IAAA;AAAA;;UAIe,uBAAA,SAAgC,YAAA;EAC/C,IAAA;;EAEA,MAAA;;EAEA,IAAA;EAkFgJ;EAhFhJ,IAAA;AAAA;;;;;;;UASe,UAAA,SAAmB,YAAA;EAClC,IAAA;EACA,OAAA;AAAA;;;;;;;UASe,aAAA,SAAsB,YAAA;EACrC,IAAA;;EAEA,SAAA;EAyEF;EAvEE,OAAA;AAAA;;;;;;;UASe,qBAAA,SAA8B,YAAA;EAC7C,IAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;EACA,OAAA;AAAA;;AA+DF;;;;;;;;;;;;;;;;KA3CY,QAAA,GACR,gBAAA,GACA,eAAA,GACA,eAAA,GACA,eAAA,GACA,iBAAA,GACA,uBAAA,GACA,uBAAA,GACA,UAAA,GACA,aAAA,GACA,qBAAA;;;;KAKQ,gBAAA;AAAA,KACA,qBAAA;;;;KAKA,YAAA,GAAe,gBAAA,GAAmB,eAAA,GAAkB,eAAA,GAAkB,eAAA,GAAkB,iBAAA,GAAoB,uBAAA,GAA0B,uBAAA;;;;KAKtI,iBAAA,GAAoB,UAAA,GAAa,aAAA,GAAgB,qBAAA;;;;;;;;;;KAWjD,cAAA,WAAyB,YAAA,IAAgB,OAAA,CAAQ,QAAA;EAAY,IAAA,EAAM,CAAA;AAAA;;;;;KAMnE,YAAA,WACJ,gBAAA,GAAmB,cAAA,CAAe,CAAA"}