eyecite-ts 0.10.0 → 0.10.2

package/README.md

@@ -9,22 +9,9 @@
 [![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).
+TypeScript legal citation extraction — a port of Python [eyecite](https://github.com/freelawproject/eyecite) with extended capabilities.
 
-Extract, resolve, and annotate legal citations from court opinions and legal documents with zero runtime dependencies.
-
-## Features
-
-- **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
-- **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, ~10KB gzipped core bundle
+Extract structured data from legal citations in court opinions, briefs, and legal documents. A citation like `500 F.2d 123 (9th Cir. 2020)` encodes a volume (500), reporter (Federal Reporter, 2nd Series), page (123), court (Ninth Circuit), and year. This library parses all of that into typed objects, resolves short-form references like "Id." back to their antecedents, and can annotate the original text with HTML markup. Zero runtime dependencies, browser-compatible, ~20 KB brotli.
 
 ## Installation
 
@@ -34,511 +21,246 @@ npm install eyecite-ts
 
 ## Quick Start
 
-```typescript
-import { extractCitations } from 'eyecite-ts'
-
-const text = 'See Smith v. Jones, 500 F.2d 123 (9th Cir. Jan. 15, 2020)'
-const citations = extractCitations(text)
-
-console.log(citations[0])
-// {
-//   type: 'case',
-//   volume: 500,
-//   reporter: 'F.2d',
-//   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: 20, originalEnd: 33, ... },
-//   fullSpan: { originalStart: 4, originalEnd: 57, ... }
-// }
-```
-
-## Citation Extraction
-
-### Multiple Citation Types
-
-```typescript
-import { extractCitations } from 'eyecite-ts'
-
-const text = `
-  See Smith v. Jones, 500 F.2d 123 (9th Cir. 2020).
-  Also 42 U.S.C. § 1983.
-  Compare 123 Harv. L. Rev. 456.
-`
-const citations = extractCitations(text)
-
-citations.forEach(citation => {
-  console.log(citation.type) // 'case', 'statute', 'journal', etc.
-})
-```
-
-### Statute Citations
-
-Extract citations from 20 state and federal jurisdictions with subsection, et seq., and jurisdiction identification:
+A complete extract → resolve → annotate workflow:
 
 ```typescript
-import { extractCitations } from 'eyecite-ts'
-
-const text = `
-  See 42 U.S.C. § 1983(a)(1) et seq.
-  Also Cal. Penal Code § 187.
-  And N.Y. Penal Law § 125.25(1)(a).
-  Compare 735 ILCS 5/2-1001.
-`
-const citations = extractCitations(text)
-
-// Federal with subsections + et seq.
-// { type: 'statute', title: 42, code: 'U.S.C.', section: '1983',
-//   subsection: '(a)(1)', jurisdiction: 'US', hasEtSeq: true, confidence: 1.0 }
-
-// California named-code
-// { type: 'statute', code: 'Penal', section: '187', jurisdiction: 'CA', confidence: 0.95 }
-
-// New York named-code with subsections
-// { type: 'statute', code: 'Penal Law', section: '125.25',
-//   subsection: '(1)(a)', jurisdiction: 'NY', confidence: 1.0 }
-
-// Illinois chapter-act format
-// { type: 'statute', title: 735, code: '5', section: '2-1001',
-//   jurisdiction: 'IL', confidence: 0.95 }
-```
-
-**Supported jurisdictions:**
-
-| Family | Jurisdictions |
-|--------|--------------|
-| Federal | USC, CFR, prose ("section X of title Y") |
-| Named-code | NY (21 laws), CA (29 codes), TX (29 codes), MD (36 articles), VA, AL, MA |
-| 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 }
-```
+import { extractCitations } from "eyecite-ts"
+import { annotate } from "eyecite-ts/annotate"
 
-Roman numerals (I–XXVII) are automatically parsed to integers. All 50 state abbreviations are supported.
+const text = `In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020), the court
+applied 42 U.S.C. § 1983. Id. at 130. See also 123 Harv. L. Rev. 456 (2019).`
 
-### Async API
-
-```typescript
-import { extractCitationsAsync } from 'eyecite-ts'
-
-const citations = await extractCitationsAsync(text)
-```
-
-### Custom Patterns
-
-```typescript
-import { extractCitations } from 'eyecite-ts'
-import { casePatterns } from 'eyecite-ts'
-
-// Extract only case citations
-const citations = extractCitations(text, {
-  patterns: casePatterns
-})
-```
-
-### Custom Cleaners
-
-```typescript
-import { extractCitations, cleanText } from 'eyecite-ts'
-
-// Use only HTML stripping
-const citations = extractCitations(html, {
-  cleaners: [(text) => text.replace(/<[^>]+>/g, '')]
-})
-```
-
-## 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)
+// Step 1: Extract and resolve in one call
+const citations = extractCitations(text, { resolve: true })
 
-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)
+// Step 2: Inspect results
+for (const cite of citations) {
+  switch (cite.type) {
+    case "case":
+      console.log(cite.caseName, cite.reporter, cite.year)
+      // "Smith v. Jones" "F.2d" 2020
+      break
+    case "statute":
+      console.log(cite.title, cite.code, cite.section)
+      // 42 "U.S.C." "1983"
+      break
+    case "id":
+      console.log("Id. resolves to index", cite.resolution?.resolvedTo)
+      // Id. resolves to index 0
+      break
+    case "journal":
+      console.log(cite.journal, cite.volume, cite.page)
+      // "Harv. L. Rev." 123 456
+      break
+  }
 }
-```
-
-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'
+// Step 3: Annotate the original text
+const result = annotate(text, citations, {
+  template: { before: '<cite>', after: '</cite>' },
+})
+console.log(result.text)
 ```
 
-### Structured Dates
-
-Parentheticals with full dates return structured date objects:
+## What It Extracts
 
-```typescript
-const text = '500 F.3d 100 (2d Cir. Jan. 15, 2020)'
-// date: { iso: '2020-01-15', parsed: { year: 2020, month: 1, day: 15 } }
+| Type | Example | Key Fields |
+|------|---------|------------|
+| `case` | `500 F.2d 123 (9th Cir. 2020)` | volume, reporter, page, court, year, caseName |
+| `statute` | `42 U.S.C. § 1983(a)(1)` | title, code, section, subsection, jurisdiction |
+| `constitutional` | `U.S. Const. amend. XIV, § 1` | jurisdiction, amendment, section, clause |
+| `journal` | `123 Harv. L. Rev. 456` | volume, journal, page, year |
+| `neutral` | `2020 WL 123456` | year, court, documentNumber |
+| `publicLaw` | `Pub. L. No. 117-263` | congress, lawNumber |
+| `federalRegister` | `87 Fed. Reg. 1234` | volume, page, year |
+| `statutesAtLarge` | `136 Stat. 4459` | volume, page, year |
+| `id` | `Id. at 125` | pincite |
+| `supra` | `Smith, supra, at 130` | partyName, pincite |
+| `shortFormCase` | `500 F.2d at 140` | volume, reporter, pincite |
 
-const text2 = '410 U.S. 113 (1973)'
-// date: { iso: '1973', parsed: { year: 1973 } }
-```
+Statute coverage spans 52 jurisdictions (50 states + DC + federal). See the [Advanced Extraction Guide](docs/guides/advanced-extraction.md) for jurisdiction details.
 
-Three date formats are supported: `Jan. 15, 2020`, `January 15, 2020`, and `1/15/2020`.
+## Key Features
 
-### Blank Page Citations
+### Case Names & Full Spans
 
-Citations can reference blank pages using placeholder notation:
+The library backward-searches for party names and tracks full citation boundaries:
 
 ```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
+const text = "In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc), the court held..."
+const [cite] = extractCitations(text)
+
+if (cite.type === "case") {
+  cite.caseName   // "Smith v. Jones"
+  cite.plaintiff  // "Smith"
+  cite.defendant  // "Jones"
+  cite.disposition // "en banc"
+  cite.span       // covers "500 F.2d 123" (citation core)
+  cite.fullSpan   // covers "Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc)"
 }
 ```
 
-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.
+Procedural prefixes like `In re`, `Ex parte`, and `Matter of` are recognized automatically.
 
-## Parallel Citations
+### 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:
+When multiple reporters cite the same case (common in older Supreme Court opinions), the library groups them automatically:
 
 ```typescript
-const text = 'See 410 U.S. 113, 93 S. Ct. 705, 35 L. Ed. 2d 147 (1973).'
+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 }
-  // ]
-}
+citations[0].groupId // "410-U.S.-113"
+citations[1].groupId // "410-U.S.-113" (same group)
+citations[2].groupId // "410-U.S.-113" (same group)
 
-// Secondary citations don't duplicate the array
-console.log(citations[1].parallelCitations)  // undefined
-console.log(citations[2].parallelCitations)  // undefined
+// Primary citation carries the linked array
+if (citations[0].type === "case") {
+  citations[0].parallelCitations
+  // [{ volume: 93, reporter: 'S. Ct.', page: 705 },
+  //  { volume: 35, reporter: 'L. Ed. 2d', page: 147 }]
+}
 ```
 
-**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.
+### Short-Form Resolution
 
-### Convenience API
+Pass `{ resolve: true }` to link Id., supra, and short-form case citations to their full antecedents:
 
 ```typescript
-import { extractCitations } from 'eyecite-ts'
-
-const text = `
-  Smith v. Jones, 500 F.2d 123 (2020).
-  Id. at 125.
-  Smith, supra, at 130.
-  500 F.2d at 140.
-`
-
+const text = `Smith v. Jones, 500 F.2d 123 (2020). Id. at 125.`
 const citations = extractCitations(text, { resolve: true })
 
-// citations[1] is Id. citation
-console.log(citations[1].resolution)
+citations[1].resolution
 // { resolvedTo: 0, confidence: 1.0 }
 ```
 
-### Power-User API
-
-```typescript
-import { extractCitations, resolveCitations } from 'eyecite-ts'
-
-const citations = extractCitations(text)
-
-const resolved = resolveCitations(citations, text, {
-  scopeStrategy: 'paragraph',
-  fuzzyPartyMatching: true,
-  partyMatchThreshold: 0.8,
-  reportUnresolved: true
-})
-```
-
-### Resolution Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `scopeStrategy` | `'paragraph'` \| `'section'` \| `'footnote'` \| `'none'` | `'paragraph'` | How far back to search for antecedents |
-| `autoDetectParagraphs` | `boolean` | `true` | Auto-detect paragraph boundaries from text |
-| `paragraphBoundaryPattern` | `RegExp` | `/\n\n+/` | Pattern to detect paragraphs |
-| `fuzzyPartyMatching` | `boolean` | `true` | Enable fuzzy party name matching for supra |
-| `partyMatchThreshold` | `number` | `0.8` | Similarity threshold (0-1) for fuzzy matching |
-| `reportUnresolved` | `boolean` | `true` | Report failure reasons for unresolved citations |
-
-### Resolution Examples
-
-**Id. citations:**
-
-```typescript
-const text = 'Smith v. Jones, 500 F.2d 123. Id. at 125.'
-const citations = extractCitations(text, { resolve: true })
-// citations[1].resolution.resolvedTo === 0
-```
-
-**Supra citations:**
-
-```typescript
-const text = 'Smith v. Jones, 500 F.2d 123. Smith, supra, at 130.'
-const citations = extractCitations(text, { resolve: true })
-// citations[1].resolution.resolvedTo === 0 (party name matches "Smith")
-```
-
-**Short-form case citations:**
+The resolver supports paragraph/section/footnote scope boundaries, fuzzy party name matching, and configurable thresholds. See the [Resolution Guide](docs/guides/resolution.md) for the power-user API.
 
-```typescript
-const text = 'Brown v. Board, 347 U.S. 483. See 347 U.S. at 495.'
-const citations = extractCitations(text, { resolve: true })
-// citations[1].resolution.resolvedTo === 0 (volume/reporter matches)
-```
+### Citation Annotation
 
-**Unresolved citations:**
+Mark up citations with HTML using template or callback modes:
 
 ```typescript
-const text = 'Id. at 100.' // Orphan Id. with no preceding citation
-const citations = extractCitations(text, { resolve: true })
-// citations[0].resolution.failureReason === 'No preceding citation found'
-```
-
-## Citation Annotation
+import { annotate } from "eyecite-ts/annotate"
 
-Add HTML markup to citations in text:
-
-```typescript
-import { annotate } from 'eyecite-ts/annotate'
-import { extractCitations } from 'eyecite-ts'
-
-const text = 'See Smith v. Jones, 500 F.2d 123 (2020).'
-const citations = extractCitations(text)
-
-// Template mode
-const result = annotate(text, citations, {
-  template: { before: '<cite>', after: '</cite>' }
-})
-// result.text === 'See Smith v. Jones, <cite>500 F.2d 123</cite> (2020).'
-
-// Callback mode (full control)
-const result2 = annotate(text, citations, {
-  callback: (citation, surrounding) => {
-    if (citation.type === 'case') {
-      return `<a href="/cases/${citation.volume}">${citation.matchedText}</a>`
-    }
-    return citation.matchedText
-  }
-})
-```
-
-Auto-escape is enabled by default for XSS protection:
-
-```typescript
 const result = annotate(text, citations, {
   template: { before: '<cite>', after: '</cite>' },
-  autoEscape: true  // default — escapes &, <, >, ", ', /
 })
+// "See Smith v. Jones, <cite>500 F.2d 123</cite> (2020)."
 ```
 
-### Annotating Full Spans
+XSS auto-escape is enabled by default. Use `useFullSpan: true` to annotate from case name through closing parenthetical. See the [Annotation Guide](docs/guides/annotation.md) for callback mode and full options.
 
-By default, annotation wraps only the citation core (volume-reporter-page). Use `useFullSpan` to annotate from the case name through the closing parenthetical:
+### Confidence & Signals
 
-```typescript
-const text = 'In Smith v. Jones, 500 F.2d 123 (9th Cir. 2020) (en banc), the court held...'
-const citations = extractCitations(text)
+Each citation carries a `confidence` score (0-1) based on pattern match quality and reporter validation. Citations preceded by legal signals are tagged:
 
-// 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..."
+```typescript
+const text = "See also Smith v. Jones, 500 F.2d 123 (2020)."
+const [cite] = extractCitations(text)
 
-// 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..."
+cite.confidence // 0.85
+cite.signal     // "see also"
 ```
 
-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.
+### Footnote Detection
 
-## Reporter Validation
-
-Validate case citations against the reporters database:
+Opt-in feature that tags citations with their footnote context and enables zone-scoped resolution:
 
 ```typescript
-import { extractWithValidation } from 'eyecite-ts'
+const citations = extractCitations(text, { detectFootnotes: true })
 
-const validated = await extractWithValidation(text, { validate: true })
-// Confidence adjustments:
-//   +0.2 boost for reporter match
-//   -0.3 penalty for unknown reporter
-//   -0.1 per extra match for ambiguous reporter
+for (const cite of citations) {
+  if (cite.inFootnote) {
+    console.log(`Footnote ${cite.footnoteNumber}: ${cite.matchedText}`)
+  }
+}
 ```
 
-## Type System
-
-All citation types use a discriminated union on the `type` field:
+Supports HTML footnote tags and plaintext footnote sections (separator + numbered markers). See the [Footnote Detection Guide](docs/guides/footnote-detection.md).
 
-```typescript
-import type {
-  Citation,                // Union of all 11 types
-  FullCaseCitation,
-  StatuteCitation,
-  ConstitutionalCitation,
-  JournalCitation,
-  NeutralCitation,
-  PublicLawCitation,
-  FederalRegisterCitation,
-  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
-} from 'eyecite-ts'
-```
+## Type System
 
-### Type Guards
+All citation types use a [discriminated union](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions) on the `type` field:
 
 ```typescript
-import {
-  isFullCitation,
-  isShortFormCitation,
-  isCaseCitation,
-  isCitationType,
-  assertUnreachable
-} from 'eyecite-ts'
-
-// Specific guards
-if (isFullCitation(citation)) {
-  // citation: FullCitation
-}
+import type { Citation, FullCaseCitation, StatuteCitation } from "eyecite-ts"
+import { isFullCitation, isCaseCitation, assertUnreachable } from "eyecite-ts"
 
-// Generic guard — narrows to any specific type
-if (isCitationType(citation, 'statute')) {
-  // citation: StatuteCitation
+// Type guards
+if (isCaseCitation(citation)) {
+  citation.reporter // typed as string
 }
 
-// Exhaustiveness check in switch statements
+// Exhaustive switch
 switch (citation.type) {
-  case 'case': /* ... */ break
-  case 'statute': /* ... */ break
-  // ... all 11 types ...
+  case "case": /* ... */ break
+  case "statute": /* ... */ break
+  // ... all 11 types
   default: assertUnreachable(citation.type)
 }
 ```
 
-### Resolved Citation Types
+`CitationOfType<'case'>` extracts the subtype: `CitationOfType<'case'>` = `FullCaseCitation`. See the [Type Reference](docs/api/types.md) for the full catalog.
 
-`ResolvedCitation` uses a conditional type — `resolution` is only meaningfully present on short-form citations:
+## Bundle Size
 
-```typescript
-import type { ResolvedCitation } from 'eyecite-ts'
+Three entry points for tree-shaking:
 
-// On short-form citations: resolution: ResolutionResult | undefined
-// On full citations: resolution?: undefined
-```
+| Entry Point | Import | Size (brotli) |
+|-------------|--------|---------------|
+| Core extraction | `eyecite-ts` | ~20 KB |
+| Annotation | `eyecite-ts/annotate` | ~1.3 KB |
+| Reporter data | `eyecite-ts/data` | lazy-loaded |
 
-## Bundle Size
+Import only what you need — the reporter database is loaded on first use, not at import time.
 
-Three entry points for optimal tree-shaking:
+## Comparison with Python eyecite
 
-| Entry Point | Import | Gzipped |
-|------------|--------|---------|
-| Core extraction | `eyecite-ts` | ~10 KB |
-| Annotation | `eyecite-ts/annotate` | 0.7 KB |
-| Reporter data | `eyecite-ts/data` | 86.5 KB (lazy-loaded) |
+Every claim verified against [Python eyecite](https://github.com/freelawproject/eyecite) source code (April 2026).
 
-```typescript
-import { extractCitations } from 'eyecite-ts'           // Core only
-import { annotate } from 'eyecite-ts/annotate'           // Annotation
-import { loadReporters } from 'eyecite-ts/data'          // Reporter database
-```
+| Capability | Python eyecite | eyecite-ts | Notes |
+|---|---|---|---|
+| Case citations | Yes | Yes | Both extract volume/reporter/page/court/year |
+| Statute citations | Yes (all 50 states + DC + territories) | Yes (50 states + DC + federal) | Python uses `reporters-db`; TS uses built-in patterns |
+| Constitutional citations | No | Yes (U.S. + 50 states) | Dedicated type with article/amendment/section/clause |
+| Journal / law review | Yes | Yes | |
+| Neutral (WL/LEXIS) | Yes (as case citations) | Yes (dedicated type) | |
+| Short-form resolution | Yes | Yes | |
+| Case name extraction | Yes | Yes | Both use backward scanning |
+| Parallel citation linking | Partial (detection + metadata copy) | Yes (`groupId` + `parallelCitations`) | |
+| Full span tracking | Yes | Yes | TS carries dual clean/original positions |
+| Component spans | Minimal (pin cite only) | Yes (all fields) | |
+| Footnote detection | No | Yes | HTML + plaintext strategies |
+| Citation signals | No (stop words only) | Yes (extracted as metadata) | |
+| Annotation | Yes (HTML modes) | Yes (template/callback + XSS auto-escape) | |
+| Position mapping | Yes (diff-based) | Yes (incremental TransformationMap) | |
+| Type system | Class inheritance | Discriminated union | TS enables exhaustive switch |
 
-## Architecture
+eyecite-ts started as a port and has diverged. Both are capable citation extractors — eyecite-ts adds constitutional citations, footnote detection, citation signals, rich component spans, and a TypeScript-native type system, while Python eyecite has broader statute coverage via `reporters-db` and a mature ecosystem.
 
-Citation extraction follows a 4-stage pipeline:
+Coming from Python eyecite? See the [Migration Guide](docs/guides/migration-from-python.md).
 
-1. **Clean**: Remove HTML, normalize Unicode, fix smart quotes
-2. **Tokenize**: Apply regex patterns to find citation candidates
-3. **Extract**: Parse metadata (volume, reporter, page, etc.)
-4. **Resolve** (optional): Link short-form citations to antecedents
+## Architecture
 
-All positions (spans) track both cleaned and original text offsets via `TransformationMap`.
+Citations flow through a 4-stage pipeline: **clean → tokenize → extract → resolve**. Text cleaning builds a `TransformationMap` that tracks position shifts, so every citation carries dual coordinates (cleaned and original text). Resolution is optional and runs as a final pass.
 
 See [ARCHITECTURE.md](ARCHITECTURE.md) for details.
 
 ## Development
 
 ```bash
-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
+pnpm install           # Install dependencies (corepack, pnpm 10)
+pnpm test              # Run tests (vitest, watch mode)
+pnpm exec vitest run   # Run tests once (1,748 tests, 72 files)
+pnpm typecheck         # Type-check with tsc
+pnpm build             # Build (ESM + CJS + DTS)
+pnpm lint              # Lint with Biome
+pnpm format            # Format with Biome
+pnpm size              # Check bundle size limits
 ```
 
-1030+ tests across 34 test files.
+Requires Node.js >= 18.0.0. See [ARCHITECTURE.md](ARCHITECTURE.md) for contributor orientation.
 
 ## License
 
@@ -546,4 +268,4 @@ MIT
 
 ## Credits
 
-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.
+Inspired by and ported from [eyecite](https://github.com/freelawproject/eyecite) (Python) by [Free Law Project](https://free.law/). This TypeScript implementation extends the original with constitutional citations, footnote detection, citation signals, parallel citation grouping, component spans, and a discriminated-union type system.