eyecite-ts 0.5.0 → 0.6.1

package/README.md

@@ -15,7 +15,7 @@ Extract, resolve, and annotate legal citations from court opinions and legal doc
 
 ## Features
 
-- **Full citation extraction**: Case citations, statutes (20 jurisdictions), journal articles, neutral citations, public laws, federal register
+- **Full citation extraction**: Case citations, statutes (20 jurisdictions), constitutional citations (U.S. + 50 states), 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
@@ -115,6 +115,35 @@ const citations = extractCitations(text)
 | Abbreviated-code | FL, OH, MI, UT, CO, WA, NC, GA, PA, IN, NJ, DE |
 | Chapter-act | IL (ILCS) |
 
+### Constitutional Citations
+
+Extract U.S. and state constitutional citations with article, amendment, section, and clause parsing:
+
+```typescript
+import { extractCitations } from 'eyecite-ts'
+
+const text = `
+  Under U.S. Const. amend. XIV, § 1, equal protection is guaranteed.
+  See also Cal. Const. art. I, § 7.
+  And U.S. Const. art. I, § 8, cl. 3.
+`
+const citations = extractCitations(text)
+
+// U.S. amendment with section
+// { type: 'constitutional', jurisdiction: 'US', amendment: 14,
+//   section: '1', confidence: 0.95 }
+
+// California article with section
+// { type: 'constitutional', jurisdiction: 'CA', article: 1,
+//   section: '7', confidence: 0.9 }
+
+// Commerce Clause (article + section + clause)
+// { type: 'constitutional', jurisdiction: 'US', article: 1,
+//   section: '8', clause: 3, confidence: 0.95 }
+```
+
+Roman numerals (I–XXVII) are automatically parsed to integers. All 50 state abbreviations are supported.
+
 ### Async API
 
 ```typescript
@@ -410,9 +439,10 @@ All citation types use a discriminated union on the `type` field:
 
 ```typescript
 import type {
-  Citation,           // Union of all 9 types
+  Citation,                // Union of all 11 types
   FullCaseCitation,
   StatuteCitation,
+  ConstitutionalCitation,
   JournalCitation,
   NeutralCitation,
   PublicLawCitation,
@@ -420,10 +450,10 @@ import type {
   IdCitation,
   SupraCitation,
   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
+  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'
 ```
 
@@ -452,7 +482,7 @@ if (isCitationType(citation, 'statute')) {
 switch (citation.type) {
   case 'case': /* ... */ break
   case 'statute': /* ... */ break
-  // ... all 9 types ...
+  // ... all 11 types ...
   default: assertUnreachable(citation.type)
 }
 ```
@@ -509,7 +539,7 @@ pnpm lint            # Lint with Biome
 pnpm format          # Format with Biome
 ```
 
-985+ tests across 32 test files.
+1030+ tests across 34 test files.
 
 ## License
 

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    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"}
+{"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(Math.max(0, start - 30), Math.min(text.length, end + 30))\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,EAGF,EAAS,EAAS,EADE,EAAK,UAAU,KAAK,IAAI,EAAG,EAAQ,GAAG,CAAE,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAAC,CACpD,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-Cymq3pJ-.cjs";
+import { t as Citation } from "../citation-BB_vC_7x.cjs";
 
 //#region src/annotate/types.d.ts
 /**

package/dist/annotate/index.d.mts

@@ -1,4 +1,4 @@
-import { t as Citation } from "../citation-25ZydLsu.mjs";
+import { t as Citation } from "../citation-Bg1QDUYb.mjs";
 
 //#region src/annotate/types.d.ts
 /**

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    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"}
+{"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(Math.max(0, start - 30), Math.min(text.length, end + 30))\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,EAGF,EAAS,EAAS,EADE,EAAK,UAAU,KAAK,IAAI,EAAG,EAAQ,GAAG,CAAE,KAAK,IAAI,EAAK,OAAQ,EAAM,GAAG,CAAC,CACpD,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-25ZydLsu.d.mts → citation-BB_vC_7x.d.cts}

@@ -1,3 +1,70 @@
+//#region src/extract/pincite.d.ts
+/**
+* Structured pincite information parsed from citation text.
+*/
+interface PinciteInfo {
+  /** Primary page number */
+  page: number;
+  /** End page for ranges: "570-75" → 575 */
+  endPage?: number;
+  /** Footnote number: "570 n.3" → 3 */
+  footnote?: number;
+  /** True if this is a page range */
+  isRange: boolean;
+  /** Original text before parsing */
+  raw: string;
+}
+/**
+* Parse a pincite string into structured components.
+*
+* Handles simple pages, ranges (with abbreviated end pages),
+* footnote references, and "at" prefixes.
+*
+* @example
+* parsePincite("570")       // { page: 570, isRange: false, raw: "570" }
+* parsePincite("570-75")    // { page: 570, endPage: 575, isRange: true, raw: "570-75" }
+* parsePincite("570 n.3")   // { page: 570, footnote: 3, isRange: false, raw: "570 n.3" }
+*
+* @returns Parsed pincite info, or null if unparseable
+*/
+declare function parsePincite(raw: string): PinciteInfo | null;
+//#endregion
+//#region src/clean/segmentMap.d.ts
+/**
+* Segment-based position mapping.
+*
+* Compresses a per-character position map into contiguous segments where the
+* offset between clean and original coordinates is constant. Lookups use
+* binary search (O(log k) where k = number of segments, typically 50-200).
+*/
+interface Segment {
+  /** Start position in clean text */
+  cleanPos: number;
+  /** Corresponding start position in original text */
+  origPos: number;
+  /** Number of positions covered by this segment */
+  len: number;
+}
+declare class SegmentMap {
+  readonly segments: readonly Segment[];
+  constructor(segments: Segment[]);
+  /**
+  * Create an identity map (clean position === original position).
+  */
+  static identity(length: number): SegmentMap;
+  /**
+  * Compress a per-position Map into a SegmentMap.
+  * Adjacent entries with the same offset (origPos - cleanPos) are merged
+  * into a single segment.
+  */
+  static fromMap(map: Map<number, number>): SegmentMap;
+  /**
+  * Look up the original position for a clean-text position.
+  * Uses binary search on sorted segments.
+  */
+  lookup(cleanPos: number): number;
+}
+//#endregion
 //#region src/types/span.d.ts
 /**
 * Represents a text span with positions tracked through transformations.
@@ -37,13 +104,15 @@ interface TransformationMap {
   cleanToOriginal: Map<number, number>;
   /** Maps original text position to cleaned text position */
   originalToClean: Map<number, number>;
+  /** Compressed segment-based clean→original mapping for O(log k) lookup */
+  cleanToOriginalSegments?: SegmentMap;
 }
 //#endregion
 //#region src/types/citation.d.ts
 /**
 * Citation type discriminator for type-safe pattern matching.
 */
-type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "id" | "supra" | "shortFormCase";
+type CitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "constitutional" | "id" | "supra" | "shortFormCase";
 /**
 * Warning generated during citation parsing.
 */
@@ -61,6 +130,11 @@ interface Warning {
   context?: string;
 }
 /**
+* Introductory signal word classification for citation support level.
+* Based on Bluebook signal categories (Rule 1.2).
+*/
+type CitationSignal = "see" | "see also" | "see generally" | "cf" | "but see" | "but cf" | "compare" | "accord" | "contra";
+/**
 * Base fields shared by all citation types.
 */
 interface CitationBase {
@@ -84,6 +158,75 @@ interface CitationBase {
   patternsChecked: number;
   /** Warnings for malformed or ambiguous regions */
   warnings?: Warning[];
+  /** Introductory signal word (e.g., "see", "see also", "but see") */
+  signal?: CitationSignal;
+  /** Group ID for string citations sharing the same proposition */
+  stringCitationGroupId?: string;
+  /** Position within the string citation group (0-indexed) */
+  stringCitationIndex?: number;
+  /** Total number of citations in this string citation group */
+  stringCitationGroupSize?: number;
+  /** Whether this citation appears in a footnote (only populated when detectFootnotes enabled) */
+  inFootnote?: boolean;
+  /** Footnote number, if applicable (only populated when detectFootnotes enabled) */
+  footnoteNumber?: number;
+}
+/**
+* Court level and jurisdiction inferred from reporter series.
+* Populated independently of the parenthetical-extracted `court` field.
+*/
+interface CourtInference {
+  /** Court level classification */
+  level: "supreme" | "appellate" | "trial" | "unknown";
+  /** Jurisdiction classification */
+  jurisdiction: "federal" | "state" | "unknown";
+  /** 2-letter state code, only for state-specific reporters */
+  state?: string;
+  /** Confidence score 0.0-1.0 (1.0 for unambiguous, 0.7 for regional multi-state) */
+  confidence: number;
+}
+/**
+* Signal-word classification for explanatory parentheticals.
+* Based on the leading gerund/verb form in the parenthetical text.
+*/
+type ParentheticalType = "holding" | "finding" | "stating" | "noting" | "explaining" | "quoting" | "citing" | "discussing" | "describing" | "recognizing" | "applying" | "rejecting" | "adopting" | "requiring" | "other";
+/**
+* An extracted explanatory parenthetical from a case citation.
+*
+* @example
+* ```typescript
+* { text: "holding that X requires Y", type: "holding" }
+* { text: "citing Doe v. City for the same proposition", type: "citing" }
+* ```
+*/
+interface Parenthetical {
+  /** Full text content between the parentheses (excluding parens themselves) */
+  text: string;
+  /** Signal-word classification based on leading gerund */
+  type: ParentheticalType;
+}
+/**
+* Normalized subsequent history signal classification.
+* Maps variant spellings (aff'd, affirmed) to canonical forms.
+*/
+type HistorySignal = "affirmed" | "reversed" | "cert_denied" | "cert_granted" | "overruled" | "vacated" | "remanded" | "modified" | "abrogated" | "superseded" | "disapproved" | "questioned" | "distinguished" | "withdrawn" | "reinstated";
+/**
+* A single subsequent history entry from a case citation.
+*
+* @example
+* ```typescript
+* { signal: "affirmed", rawSignal: "aff'd", signalSpan: { ... }, order: 0 }
+* ```
+*/
+interface SubsequentHistoryEntry {
+  /** Normalized signal classification */
+  signal: HistorySignal;
+  /** Raw signal text as it appeared in the document */
+  rawSignal: string;
+  /** Position of the signal text in the document */
+  signalSpan: Span;
+  /** Order in the history chain (0-based) */
+  order: number;
 }
 /**
 * Full case citation (volume-reporter-page format).
@@ -98,7 +241,11 @@ interface FullCaseCitation extends CitationBase {
   /** Page number — optional for blank page placeholder citations (e.g., "___" or "---") */
   page?: number;
   pincite?: number;
+  /** Structured pincite information (page, range, footnote) */
+  pinciteInfo?: PinciteInfo;
   court?: string;
+  /** Normalized court string: spaces collapsed, trailing period ensured */
+  normalizedCourt?: string;
   year?: number;
   /** Normalized reporter abbreviation from reporters-db (e.g., "F.2d" vs "F. 2d") */
   normalizedReporter?: string;
@@ -116,12 +263,29 @@ interface FullCaseCitation extends CitationBase {
     reporter: string;
     page: number;
   }>;
-  /** Citation signal (introductory phrase) */
-  signal?: "see" | "see also" | "cf" | "but see" | "compare";
-  /** Parenthetical explanation following the citation */
-  parenthetical?: string;
-  /** Subsequent procedural history (e.g., "aff'd", "rev'd", "cert. denied") */
-  subsequentHistory?: string;
+  /**
+  * Explanatory parentheticals following the citation.
+  * Only populated when explanatory content is found (not court/year/disposition).
+  * @example [{ text: "holding that X requires Y", type: "holding" }]
+  */
+  parentheticals?: Parenthetical[];
+  /**
+  * Subsequent history entries for this citation.
+  * Each entry describes a procedural event (affirmed, reversed, etc.).
+  * Only populated on the parent (original) citation.
+  * @example [{ signal: "affirmed", rawSignal: "aff'd", signalSpan: {...}, order: 0 }]
+  */
+  subsequentHistoryEntries?: SubsequentHistoryEntry[];
+  /**
+  * Back-pointer indicating this citation is a subsequent history citation.
+  * `index` is the parent's position in the results array returned by
+  * `extractCitations()` — it becomes invalid if the array is filtered or reordered.
+  * @example { index: 0, signal: "affirmed" }
+  */
+  subsequentHistoryOf?: {
+    index: number;
+    signal: HistorySignal;
+  };
   /**
   * Date information in multiple formats.
   * - iso: ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)
@@ -189,6 +353,18 @@ interface FullCaseCitation extends CitationBase {
   */
   proceduralPrefix?: string;
   /**
+  * Nominative (historical) reporter volume for early SCOTUS citations.
+  * Present only when citation includes a nominative parenthetical, e.g.,
+  * `67 U.S. (2 Black) 635` → nominativeVolume: 2
+  */
+  nominativeVolume?: number;
+  /**
+  * Nominative (historical) reporter abbreviation for early SCOTUS citations.
+  * Present only when citation includes a nominative parenthetical, e.g.,
+  * `67 U.S. (2 Black) 635` → nominativeReporter: "Black"
+  */
+  nominativeReporter?: 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.
@@ -200,6 +376,13 @@ interface FullCaseCitation extends CitationBase {
   * @example "en banc", "per curiam"
   */
   disposition?: string;
+  /**
+  * Court level/jurisdiction inferred from reporter series.
+  * Always populated independently of the parenthetical `court` field.
+  * Uses a curated static lookup table — does not depend on the reporter DB
+  * to preserve tree-shaking of the `eyecite-ts/data` entry point.
+  */
+  inferredCourt?: CourtInference;
 }
 /**
 * Statute citation (U.S. Code, state codes, etc.).
@@ -314,6 +497,26 @@ interface StatutesAtLargeCitation extends CitationBase {
   year?: number;
 }
 /**
+* Constitutional citation (U.S. or state constitution).
+*
+* @example "U.S. Const. art. III, § 2"
+* @example "U.S. Const. amend. XIV, § 1"
+* @example "Cal. Const. art. I, § 7"
+*/
+interface ConstitutionalCitation extends CitationBase {
+  type: "constitutional";
+  /** Jurisdiction code: "US", 2-letter state code, or undefined for bare "Const." */
+  jurisdiction?: string;
+  /** Article number (parsed from Roman numerals) — mutually exclusive with amendment */
+  article?: number;
+  /** Amendment number (parsed from Roman numerals) — mutually exclusive with article */
+  amendment?: number;
+  /** Section identifier (string to handle non-numeric like "3-a") */
+  section?: string;
+  /** Clause number (always numeric) */
+  clause?: number;
+}
+/**
 * Id. citation (refers to immediately preceding citation).
 *
 * @example "Id."
@@ -366,16 +569,16 @@ interface ShortFormCaseCitation extends CitationBase {
 *   // ...
 * }
 */
-type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
+type Citation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | ConstitutionalCitation | IdCitation | SupraCitation | ShortFormCaseCitation;
 /**
 * Citation type discriminators grouped by category.
 */
-type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge";
+type FullCitationType = "case" | "statute" | "journal" | "neutral" | "publicLaw" | "federalRegister" | "statutesAtLarge" | "constitutional";
 type ShortFormCitationType = "id" | "supra" | "shortFormCase";
 /**
 * Union of all full citation types (not short-form references).
 */
-type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation;
+type FullCitation = FullCaseCitation | StatuteCitation | JournalCitation | NeutralCitation | PublicLawCitation | FederalRegisterCitation | StatutesAtLargeCitation | ConstitutionalCitation;
 /**
 * Union of all short-form citation types (Id., supra, short-form case).
 */
@@ -398,5 +601,5 @@ type CitationOfType<T extends CitationType> = Extract<Citation, {
 */
 type ExtractorMap = { [K in FullCitationType]: CitationOfType<K> };
 //#endregion
-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-25ZydLsu.d.mts.map
+export { PinciteInfo as A, StatuteCitation as C, Warning as D, SupraCitation as E, Span as O, ShortFormCitationType as S, SubsequentHistoryEntry as T, Parenthetical as _, CitationType as a, ShortFormCaseCitation as b, ExtractorMap as c, FullCitation as d, FullCitationType as f, NeutralCitation as g, JournalCitation as h, CitationSignal as i, parsePincite as j, TransformationMap as k, FederalRegisterCitation as l, IdCitation as m, CitationBase as n, ConstitutionalCitation as o, HistorySignal as p, CitationOfType as r, CourtInference as s, Citation as t, FullCaseCitation as u, ParentheticalType as v, StatutesAtLargeCitation as w, ShortFormCitation as x, PublicLawCitation as y };
+//# sourceMappingURL=citation-BB_vC_7x.d.cts.map

package/dist/citation-BB_vC_7x.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-BB_vC_7x.d.cts","names":[],"sources":["../src/extract/pincite.ts","../src/clean/segmentMap.ts","../src/types/span.ts","../src/types/citation.ts"],"mappings":"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"}