eyecite-ts 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,8 +1,9 @@
-import { S as TransformationMap, _ as StatuteCitation, a as ExtractorMap, b as Warning, c as FullCitation, d as JournalCitation, f as NeutralCitation, g as ShortFormCitationType, h as ShortFormCitation, i as CitationType, l as FullCitationType, m as ShortFormCaseCitation, n as CitationBase, o as FederalRegisterCitation, p as PublicLawCitation, r as CitationOfType, s as FullCaseCitation, t as Citation, u as IdCitation, v as StatutesAtLargeCitation, x as Span, y as SupraCitation } from "./citation-4bmWbhSK.cjs";
+import { A as PinciteInfo, C as StatuteCitation, D as Warning, E as SupraCitation, O as Span, S as ShortFormCitationType, T as SubsequentHistoryEntry, _ as Parenthetical, a as CitationType, b as ShortFormCaseCitation, c as ExtractorMap, d as FullCitation, f as FullCitationType, g as NeutralCitation, h as JournalCitation, i as CitationSignal, j as parsePincite, k as TransformationMap, l as FederalRegisterCitation, m as IdCitation, n as CitationBase, o as ConstitutionalCitation, p as HistorySignal, r as CitationOfType, s as CourtInference, t as Citation, u as FullCaseCitation, v as ParentheticalType, w as StatutesAtLargeCitation, x as ShortFormCitation, y as PublicLawCitation } from "./citation-By8QXtGC.cjs";
+import { a as FootnoteMap, i as ScopeStrategy, n as ResolutionResult, o as FootnoteZone, r as ResolvedCitation, t as ResolutionOptions } from "./types-C_5aOCZ1.cjs";
 
 //#region src/types/guards.d.ts
 /**
-* Type guard: narrows Citation to a full citation (case, statute, journal, neutral, publicLaw, federalRegister).
+* Type guard: narrows Citation to a full citation (case, statute, journal, neutral, publicLaw, federalRegister, statutesAtLarge, constitutional).
 */
 declare function isFullCitation(citation: Citation): citation is FullCitation;
 /**
@@ -44,93 +45,6 @@ interface Pattern {
   type: FullCitationType;
 }
 //#endregion
-//#region src/resolve/types.d.ts
-/**
-* Scope boundary strategy for resolution.
-* Determines how far back to search for antecedent citations.
-*/
-type ScopeStrategy = "paragraph" | "section" | "footnote" | "none";
-/**
-* Options for citation resolution.
-*/
-interface ResolutionOptions {
-  /**
-  * Scope boundary strategy (default: 'paragraph')
-  * - paragraph: Only resolve within same paragraph
-  * - section: Only resolve within same section
-  * - footnote: Only resolve within same footnote
-  * - none: Resolve across entire document
-  */
-  scopeStrategy?: ScopeStrategy;
-  /**
-  * Auto-detect paragraph boundaries from text (default: true)
-  * Uses paragraphBoundaryPattern to split text
-  */
-  autoDetectParagraphs?: boolean;
-  /**
-  * Regex pattern to detect paragraph boundaries (default: /\n\n+/)
-  * Only used if autoDetectParagraphs is true
-  */
-  paragraphBoundaryPattern?: RegExp;
-  /**
-  * Enable fuzzy party name matching for supra resolution (default: true)
-  * Uses Levenshtein distance to handle typos and variations
-  */
-  fuzzyPartyMatching?: boolean;
-  /**
-  * Similarity threshold for fuzzy party matching (default: 0.8)
-  * Range: 0-1 where 1.0 is exact match
-  * Only used if fuzzyPartyMatching is true
-  */
-  partyMatchThreshold?: number;
-  /**
-  * Allow Id. citations to resolve to other short-form citations (default: false)
-  * If true: "Smith v. Jones, 500 F.2d 100" -> "Id." -> "Id. at 105"
-  * If false: Second Id. fails to resolve (no full citation between them)
-  */
-  allowNestedResolution?: boolean;
-  /**
-  * Report unresolved citations with failure reasons (default: true)
-  * If false: resolution field will be undefined for unresolved citations
-  */
-  reportUnresolved?: boolean;
-}
-/**
-* Result of resolving a short-form citation.
-*/
-interface ResolutionResult {
-  /**
-  * Index of the citation this resolves to.
-  * undefined if resolution failed
-  */
-  resolvedTo?: number;
-  /**
-  * Reason for resolution failure (if any)
-  */
-  failureReason?: string;
-  /**
-  * Warnings about ambiguous or uncertain resolutions
-  */
-  warnings?: string[];
-  /**
-  * Confidence in the resolution (0-1)
-  * Factors: party name similarity, scope boundary, citation type match
-  */
-  confidence: number;
-}
-/**
-* Citation with resolution metadata.
-*
-* Uses a distributive conditional type so that `resolution` is only
-* meaningfully present on short-form citations (Id., supra, short-form case).
-* On full citations, `resolution` is typed as `undefined`.
-*/
-type ResolvedCitation<C extends Citation = Citation> = C extends ShortFormCitation ? C & {
-  resolution: ResolutionResult | undefined;
-} : C & {
-  resolution?: undefined;
-};
-//#endregion
 //#region src/extract/extractCitations.d.ts
 /**
 * Options for customizing citation extraction behavior.
@@ -195,6 +109,25 @@ interface ExtractOptions {
   * ```
   */
   resolutionOptions?: ResolutionOptions;
+  /**
+  * Remove citations flagged as likely false positives (default: false).
+  *
+  * When false (default), flagged citations get reduced confidence (0.1) and a warning.
+  * When true, flagged citations are removed from results entirely.
+  *
+  * False positive detection uses:
+  * - A static blocklist of known non-US reporter abbreviations (international, UK, European)
+  * - A year plausibility heuristic (years before 1750 predate US legal reporting)
+  *
+  * @example
+  * ```typescript
+  * // Remove false positives from results
+  * const citations = extractCitations(text, { filterFalsePositives: true })
+  * ```
+  */
+  filterFalsePositives?: boolean;
+  /** Detect footnote zones and annotate citations with inFootnote/footnoteNumber (default: false) */
+  detectFootnotes?: boolean;
 }
 /**
 * Extracts legal citations from text using the full parsing pipeline.
@@ -285,6 +218,16 @@ declare function extractCitationsAsync(text: string, options: ExtractOptions & {
 }): Promise<ResolvedCitation[]>;
 declare function extractCitationsAsync(text: string, options?: ExtractOptions): Promise<Citation[]>;
 //#endregion
+//#region src/extract/filterFalsePositives.d.ts
+/**
+* Apply false positive filters to extracted citations.
+*
+* @param citations - Extracted citations (may be mutated in penalize mode)
+* @param remove - If true, remove flagged citations. If false, penalize confidence + add warning.
+* @returns Filtered array (same reference if remove=false, new array if remove=true and items removed)
+*/
+declare function applyFalsePositiveFilters(citations: Citation[], remove: boolean): Citation[];
+//#endregion
 //#region src/clean/cleanText.d.ts
 /**
 * Result of text cleaning operation.
@@ -305,7 +248,7 @@ interface CleanTextResult {
 * cleaned text while reporting positions in the original text.
 *
 * @param original - Original input text
-* @param cleaners - Array of cleaner functions to apply (default: stripHtmlTags, normalizeWhitespace, normalizeUnicode, fixSmartQuotes)
+* @param cleaners - Array of cleaner functions to apply (default: stripHtmlTags, decodeHtmlEntities, normalizeWhitespace, normalizeUnicode, normalizeDashes, fixSmartQuotes, normalizeTypography, normalizeReporterSpacing)
 * @returns Cleaned text with position mappings and warnings
 *
 * @example
@@ -425,44 +368,51 @@ declare function tokenize(cleanedText: string, patterns?: Pattern[]): Token[];
 */
 declare function extractCase(token: Token, transformationMap: TransformationMap, cleanedText?: string): FullCaseCitation;
 //#endregion
-//#region src/extract/extractStatute.d.ts
+//#region src/extract/extractConstitutional.d.ts
 /**
-* Extracts statute citation metadata from a tokenized citation.
+* Extract a constitutional citation from a tokenized match.
+*
+* @param token - Tokenized citation candidate from the tokenizer
+* @param transformationMap - Maps cleaned text positions to original text positions
+* @returns Parsed constitutional citation with structured fields
+*/
+declare function extractConstitutional(token: Token, transformationMap: TransformationMap): ConstitutionalCitation;
+//#endregion
+//#region src/extract/extractFederalRegister.d.ts
+/**
+* Extracts Federal Register citation metadata from a tokenized citation.
 *
 * Parses token text to extract:
-* - Title: Optional leading digits (e.g., "42" from "42 U.S.C. § 1983")
-* - Code: Statutory code abbreviation (e.g., "U.S.C.", "Cal. Civ. Code")
-* - Section: Section number after § symbol (e.g., "1983")
-* - Subsections: Optional parenthetical subdivisions (e.g., "(a)(1)")
+* - Volume: Federal Register volume number (e.g., "85")
+* - Page: Page number (e.g., "12345")
+* - Year: Optional publication year in parentheses (e.g., "(2021)")
 *
 * Confidence scoring:
-* - Base: 0.5
-* - Known code pattern (U.S.C., C.F.R., state codes): +0.3
-* - Capped at 1.0
+* - 0.9 (Federal Register format is standardized)
 *
 * @param token - Token from tokenizer containing matched text and clean positions
 * @param transformationMap - Position mapping from clean → original text
-* @returns StatuteCitation with parsed metadata and translated positions
+* @returns FederalRegisterCitation with parsed metadata and translated positions
 *
 * @example
 * ```typescript
 * const token = {
-*   text: "42 U.S.C. § 1983",
-*   span: { cleanStart: 10, cleanEnd: 26 },
-*   type: "statute",
-*   patternId: "usc"
+*   text: "85 Fed. Reg. 12345",
+*   span: { cleanStart: 10, cleanEnd: 28 },
+*   type: "federalRegister",
+*   patternId: "federal-register"
 * }
-* const citation = extractStatute(token, transformationMap)
+* const citation = extractFederalRegister(token, transformationMap)
 * // citation = {
-* //   type: "statute",
-* //   title: 42,
-* //   code: "U.S.C.",
-* //   section: "1983",
+* //   type: "federalRegister",
+* //   volume: 85,
+* //   page: 12345,
+* //   confidence: 0.9,
 * //   ...
 * // }
 * ```
 */
-declare function extractStatute(token: Token, transformationMap: TransformationMap): StatuteCitation;
+declare function extractFederalRegister(token: Token, transformationMap: TransformationMap): FederalRegisterCitation;
 //#endregion
 //#region src/extract/extractJournal.d.ts
 /**
@@ -580,45 +530,31 @@ declare function extractNeutral(token: Token, transformationMap: TransformationM
 */
 declare function extractPublicLaw(token: Token, transformationMap: TransformationMap): PublicLawCitation;
 //#endregion
-//#region src/extract/extractFederalRegister.d.ts
+//#region src/extract/extractStatute.d.ts
 /**
-* Extracts Federal Register citation metadata from a tokenized citation.
-*
-* Parses token text to extract:
-* - Volume: Federal Register volume number (e.g., "85")
-* - Page: Page number (e.g., "12345")
-* - Year: Optional publication year in parentheses (e.g., "(2021)")
-*
-* Confidence scoring:
-* - 0.9 (Federal Register format is standardized)
-*
-* @param token - Token from tokenizer containing matched text and clean positions
-* @param transformationMap - Position mapping from clean → original text
-* @returns FederalRegisterCitation with parsed metadata and translated positions
-*
-* @example
-* ```typescript
-* const token = {
-*   text: "85 Fed. Reg. 12345",
-*   span: { cleanStart: 10, cleanEnd: 28 },
-*   type: "federalRegister",
-*   patternId: "federal-register"
-* }
-* const citation = extractFederalRegister(token, transformationMap)
-* // citation = {
-* //   type: "federalRegister",
-* //   volume: 85,
-* //   page: 12345,
-* //   confidence: 0.9,
-* //   ...
-* // }
-* ```
+* Extracts statute citation metadata from a tokenized citation.
+* Dispatches to family-specific extractors based on patternId.
 */
-declare function extractFederalRegister(token: Token, transformationMap: TransformationMap): FederalRegisterCitation;
+declare function extractStatute(token: Token, transformationMap: TransformationMap): StatuteCitation;
 //#endregion
 //#region src/extract/extractStatutesAtLarge.d.ts
 declare function extractStatutesAtLarge(token: Token, transformationMap: TransformationMap): StatutesAtLargeCitation;
 //#endregion
+//#region src/extract/courtNormalization.d.ts
+/**
+* Normalize a court string extracted from a citation parenthetical.
+*
+* - Collapses spaces after periods: "S.D. N.Y." → "S.D.N.Y."
+* - Ensures trailing period on abbreviated forms: "2d Cir" → "2d Cir."
+* - Returns undefined for empty/undefined input
+*
+* @example
+* normalizeCourt("S.D. N.Y.")  // "S.D.N.Y."
+* normalizeCourt("2d Cir")     // "2d Cir."
+* normalizeCourt("U.S.")       // "U.S."
+*/
+declare function normalizeCourt(court: string | undefined): string | undefined;
+//#endregion
 //#region src/resolve/DocumentResolver.d.ts
 /**
 * Document-scoped resolver that processes citations sequentially
@@ -703,5 +639,19 @@ declare class DocumentResolver {
 */
 declare function resolveCitations(citations: Citation[], text: string, options?: ResolutionOptions): ResolvedCitation[];
 //#endregion
-export { type Citation, type CitationBase, type CitationOfType, type CitationType, type CleanTextResult, DocumentResolver, type ExtractOptions, type ExtractorMap, type FederalRegisterCitation, type FullCaseCitation, type FullCitation, type FullCitationType, type IdCitation, type JournalCitation, type NeutralCitation, type PublicLawCitation, type ResolutionOptions, type ResolutionResult, type ResolvedCitation, type ScopeStrategy, type ShortFormCaseCitation, type ShortFormCitation, type ShortFormCitationType, type Span, type StatuteCitation, type StatutesAtLargeCitation, type SupraCitation, type Token, type TransformationMap, type Warning, assertUnreachable, cleanText, extractCase, extractCitations, extractCitationsAsync, extractFederalRegister, extractJournal, extractNeutral, extractPublicLaw, extractStatute, extractStatutesAtLarge, isCaseCitation, isCitationType, isFullCitation, isShortFormCitation, resolveCitations, tokenize };
+//#region src/footnotes/detectFootnotes.d.ts
+/**
+* Detect footnote zones in text (HTML or plain text).
+*
+* Strategy: if the input contains HTML tags, try HTML structural detection
+* first. If that yields no results (HTML without footnote elements), fall
+* back to plain-text heuristic detection. For non-HTML input, use plain-text
+* detection directly.
+*
+* @param text - Raw input text (HTML or plain text)
+* @returns FootnoteMap with zones in input-text coordinates, sorted by start
+*/
+declare function detectFootnotes(text: string): FootnoteMap;
+//#endregion
+export { type Citation, type CitationBase, type CitationOfType, type CitationSignal, type CitationType, type CleanTextResult, type ConstitutionalCitation, type CourtInference, DocumentResolver, type ExtractOptions, type ExtractorMap, type FederalRegisterCitation, type FootnoteMap, type FootnoteZone, type FullCaseCitation, type FullCitation, type FullCitationType, type HistorySignal, type IdCitation, type JournalCitation, type NeutralCitation, type Parenthetical, type ParentheticalType, type PinciteInfo, type PublicLawCitation, type ResolutionOptions, type ResolutionResult, type ResolvedCitation, type ScopeStrategy, type ShortFormCaseCitation, type ShortFormCitation, type ShortFormCitationType, type Span, type StatuteCitation, type StatutesAtLargeCitation, type SubsequentHistoryEntry, type SupraCitation, type Token, type TransformationMap, type Warning, applyFalsePositiveFilters, assertUnreachable, cleanText, detectFootnotes, extractCase, extractCitations, extractCitationsAsync, extractConstitutional, extractFederalRegister, extractJournal, extractNeutral, extractPublicLaw, extractStatute, extractStatutesAtLarge, isCaseCitation, isCitationType, isFullCitation, isShortFormCitation, normalizeCourt, parsePincite, resolveCitations, tokenize };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types/guards.ts","../src/patterns/casePatterns.ts","../src/resolve/types.ts","../src/extract/extractCitations.ts","../src/clean/cleanText.ts","../src/tokenize/tokenizer.ts","../src/extract/extractCase.ts","../src/extract/extractStatute.ts","../src/extract/extractJournal.ts","../src/extract/extractNeutral.ts","../src/extract/extractPublicLaw.ts","../src/extract/extractFederalRegister.ts","../src/extract/extractStatutesAtLarge.ts","../src/resolve/DocumentResolver.ts","../src/resolve/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types/guards.ts","../src/patterns/casePatterns.ts","../src/extract/extractCitations.ts","../src/extract/filterFalsePositives.ts","../src/clean/cleanText.ts","../src/tokenize/tokenizer.ts","../src/extract/extractCase.ts","../src/extract/extractConstitutional.ts","../src/extract/extractFederalRegister.ts","../src/extract/extractJournal.ts","../src/extract/extractNeutral.ts","../src/extract/extractPublicLaw.ts","../src/extract/extractStatute.ts","../src/extract/extractStatutesAtLarge.ts","../src/extract/courtNormalization.ts","../src/resolve/DocumentResolver.ts","../src/resolve/index.ts","../src/footnotes/detectFootnotes.ts"],"mappings":"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"}

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { S as TransformationMap, _ as StatuteCitation, a as ExtractorMap, b as Warning, c as FullCitation, d as JournalCitation, f as NeutralCitation, g as ShortFormCitationType, h as ShortFormCitation, i as CitationType, l as FullCitationType, m as ShortFormCaseCitation, n as CitationBase, o as FederalRegisterCitation, p as PublicLawCitation, r as CitationOfType, s as FullCaseCitation, t as Citation, u as IdCitation, v as StatutesAtLargeCitation, x as Span, y as SupraCitation } from "./citation-BVN0o8TJ.mjs";
+import { A as PinciteInfo, C as StatuteCitation, D as Warning, E as SupraCitation, O as Span, S as ShortFormCitationType, T as SubsequentHistoryEntry, _ as Parenthetical, a as CitationType, b as ShortFormCaseCitation, c as ExtractorMap, d as FullCitation, f as FullCitationType, g as NeutralCitation, h as JournalCitation, i as CitationSignal, j as parsePincite, k as TransformationMap, l as FederalRegisterCitation, m as IdCitation, n as CitationBase, o as ConstitutionalCitation, p as HistorySignal, r as CitationOfType, s as CourtInference, t as Citation, u as FullCaseCitation, v as ParentheticalType, w as StatutesAtLargeCitation, x as ShortFormCitation, y as PublicLawCitation } from "./citation-BwXdJTA9.mjs";
+import { a as FootnoteMap, i as ScopeStrategy, n as ResolutionResult, o as FootnoteZone, r as ResolvedCitation, t as ResolutionOptions } from "./types-BfYnmSHC.mjs";
 
 //#region src/types/guards.d.ts
 /**
-* Type guard: narrows Citation to a full citation (case, statute, journal, neutral, publicLaw, federalRegister).
+* Type guard: narrows Citation to a full citation (case, statute, journal, neutral, publicLaw, federalRegister, statutesAtLarge, constitutional).
 */
 declare function isFullCitation(citation: Citation): citation is FullCitation;
 /**
@@ -44,93 +45,6 @@ interface Pattern {
   type: FullCitationType;
 }
 //#endregion
-//#region src/resolve/types.d.ts
-/**
-* Scope boundary strategy for resolution.
-* Determines how far back to search for antecedent citations.
-*/
-type ScopeStrategy = "paragraph" | "section" | "footnote" | "none";
-/**
-* Options for citation resolution.
-*/
-interface ResolutionOptions {
-  /**
-  * Scope boundary strategy (default: 'paragraph')
-  * - paragraph: Only resolve within same paragraph
-  * - section: Only resolve within same section
-  * - footnote: Only resolve within same footnote
-  * - none: Resolve across entire document
-  */
-  scopeStrategy?: ScopeStrategy;
-  /**
-  * Auto-detect paragraph boundaries from text (default: true)
-  * Uses paragraphBoundaryPattern to split text
-  */
-  autoDetectParagraphs?: boolean;
-  /**
-  * Regex pattern to detect paragraph boundaries (default: /\n\n+/)
-  * Only used if autoDetectParagraphs is true
-  */
-  paragraphBoundaryPattern?: RegExp;
-  /**
-  * Enable fuzzy party name matching for supra resolution (default: true)
-  * Uses Levenshtein distance to handle typos and variations
-  */
-  fuzzyPartyMatching?: boolean;
-  /**
-  * Similarity threshold for fuzzy party matching (default: 0.8)
-  * Range: 0-1 where 1.0 is exact match
-  * Only used if fuzzyPartyMatching is true
-  */
-  partyMatchThreshold?: number;
-  /**
-  * Allow Id. citations to resolve to other short-form citations (default: false)
-  * If true: "Smith v. Jones, 500 F.2d 100" -> "Id." -> "Id. at 105"
-  * If false: Second Id. fails to resolve (no full citation between them)
-  */
-  allowNestedResolution?: boolean;
-  /**
-  * Report unresolved citations with failure reasons (default: true)
-  * If false: resolution field will be undefined for unresolved citations
-  */
-  reportUnresolved?: boolean;
-}
-/**
-* Result of resolving a short-form citation.
-*/
-interface ResolutionResult {
-  /**
-  * Index of the citation this resolves to.
-  * undefined if resolution failed
-  */
-  resolvedTo?: number;
-  /**
-  * Reason for resolution failure (if any)
-  */
-  failureReason?: string;
-  /**
-  * Warnings about ambiguous or uncertain resolutions
-  */
-  warnings?: string[];
-  /**
-  * Confidence in the resolution (0-1)
-  * Factors: party name similarity, scope boundary, citation type match
-  */
-  confidence: number;
-}
-/**
-* Citation with resolution metadata.
-*
-* Uses a distributive conditional type so that `resolution` is only
-* meaningfully present on short-form citations (Id., supra, short-form case).
-* On full citations, `resolution` is typed as `undefined`.
-*/
-type ResolvedCitation<C extends Citation = Citation> = C extends ShortFormCitation ? C & {
-  resolution: ResolutionResult | undefined;
-} : C & {
-  resolution?: undefined;
-};
-//#endregion
 //#region src/extract/extractCitations.d.ts
 /**
 * Options for customizing citation extraction behavior.
@@ -195,6 +109,25 @@ interface ExtractOptions {
   * ```
   */
   resolutionOptions?: ResolutionOptions;
+  /**
+  * Remove citations flagged as likely false positives (default: false).
+  *
+  * When false (default), flagged citations get reduced confidence (0.1) and a warning.
+  * When true, flagged citations are removed from results entirely.
+  *
+  * False positive detection uses:
+  * - A static blocklist of known non-US reporter abbreviations (international, UK, European)
+  * - A year plausibility heuristic (years before 1750 predate US legal reporting)
+  *
+  * @example
+  * ```typescript
+  * // Remove false positives from results
+  * const citations = extractCitations(text, { filterFalsePositives: true })
+  * ```
+  */
+  filterFalsePositives?: boolean;
+  /** Detect footnote zones and annotate citations with inFootnote/footnoteNumber (default: false) */
+  detectFootnotes?: boolean;
 }
 /**
 * Extracts legal citations from text using the full parsing pipeline.
@@ -285,6 +218,16 @@ declare function extractCitationsAsync(text: string, options: ExtractOptions & {
 }): Promise<ResolvedCitation[]>;
 declare function extractCitationsAsync(text: string, options?: ExtractOptions): Promise<Citation[]>;
 //#endregion
+//#region src/extract/filterFalsePositives.d.ts
+/**
+* Apply false positive filters to extracted citations.
+*
+* @param citations - Extracted citations (may be mutated in penalize mode)
+* @param remove - If true, remove flagged citations. If false, penalize confidence + add warning.
+* @returns Filtered array (same reference if remove=false, new array if remove=true and items removed)
+*/
+declare function applyFalsePositiveFilters(citations: Citation[], remove: boolean): Citation[];
+//#endregion
 //#region src/clean/cleanText.d.ts
 /**
 * Result of text cleaning operation.
@@ -305,7 +248,7 @@ interface CleanTextResult {
 * cleaned text while reporting positions in the original text.
 *
 * @param original - Original input text
-* @param cleaners - Array of cleaner functions to apply (default: stripHtmlTags, normalizeWhitespace, normalizeUnicode, fixSmartQuotes)
+* @param cleaners - Array of cleaner functions to apply (default: stripHtmlTags, decodeHtmlEntities, normalizeWhitespace, normalizeUnicode, normalizeDashes, fixSmartQuotes, normalizeTypography, normalizeReporterSpacing)
 * @returns Cleaned text with position mappings and warnings
 *
 * @example
@@ -425,44 +368,51 @@ declare function tokenize(cleanedText: string, patterns?: Pattern[]): Token[];
 */
 declare function extractCase(token: Token, transformationMap: TransformationMap, cleanedText?: string): FullCaseCitation;
 //#endregion
-//#region src/extract/extractStatute.d.ts
+//#region src/extract/extractConstitutional.d.ts
 /**
-* Extracts statute citation metadata from a tokenized citation.
+* Extract a constitutional citation from a tokenized match.
+*
+* @param token - Tokenized citation candidate from the tokenizer
+* @param transformationMap - Maps cleaned text positions to original text positions
+* @returns Parsed constitutional citation with structured fields
+*/
+declare function extractConstitutional(token: Token, transformationMap: TransformationMap): ConstitutionalCitation;
+//#endregion
+//#region src/extract/extractFederalRegister.d.ts
+/**
+* Extracts Federal Register citation metadata from a tokenized citation.
 *
 * Parses token text to extract:
-* - Title: Optional leading digits (e.g., "42" from "42 U.S.C. § 1983")
-* - Code: Statutory code abbreviation (e.g., "U.S.C.", "Cal. Civ. Code")
-* - Section: Section number after § symbol (e.g., "1983")
-* - Subsections: Optional parenthetical subdivisions (e.g., "(a)(1)")
+* - Volume: Federal Register volume number (e.g., "85")
+* - Page: Page number (e.g., "12345")
+* - Year: Optional publication year in parentheses (e.g., "(2021)")
 *
 * Confidence scoring:
-* - Base: 0.5
-* - Known code pattern (U.S.C., C.F.R., state codes): +0.3
-* - Capped at 1.0
+* - 0.9 (Federal Register format is standardized)
 *
 * @param token - Token from tokenizer containing matched text and clean positions
 * @param transformationMap - Position mapping from clean → original text
-* @returns StatuteCitation with parsed metadata and translated positions
+* @returns FederalRegisterCitation with parsed metadata and translated positions
 *
 * @example
 * ```typescript
 * const token = {
-*   text: "42 U.S.C. § 1983",
-*   span: { cleanStart: 10, cleanEnd: 26 },
-*   type: "statute",
-*   patternId: "usc"
+*   text: "85 Fed. Reg. 12345",
+*   span: { cleanStart: 10, cleanEnd: 28 },
+*   type: "federalRegister",
+*   patternId: "federal-register"
 * }
-* const citation = extractStatute(token, transformationMap)
+* const citation = extractFederalRegister(token, transformationMap)
 * // citation = {
-* //   type: "statute",
-* //   title: 42,
-* //   code: "U.S.C.",
-* //   section: "1983",
+* //   type: "federalRegister",
+* //   volume: 85,
+* //   page: 12345,
+* //   confidence: 0.9,
 * //   ...
 * // }
 * ```
 */
-declare function extractStatute(token: Token, transformationMap: TransformationMap): StatuteCitation;
+declare function extractFederalRegister(token: Token, transformationMap: TransformationMap): FederalRegisterCitation;
 //#endregion
 //#region src/extract/extractJournal.d.ts
 /**
@@ -580,45 +530,31 @@ declare function extractNeutral(token: Token, transformationMap: TransformationM
 */
 declare function extractPublicLaw(token: Token, transformationMap: TransformationMap): PublicLawCitation;
 //#endregion
-//#region src/extract/extractFederalRegister.d.ts
+//#region src/extract/extractStatute.d.ts
 /**
-* Extracts Federal Register citation metadata from a tokenized citation.
-*
-* Parses token text to extract:
-* - Volume: Federal Register volume number (e.g., "85")
-* - Page: Page number (e.g., "12345")
-* - Year: Optional publication year in parentheses (e.g., "(2021)")
-*
-* Confidence scoring:
-* - 0.9 (Federal Register format is standardized)
-*
-* @param token - Token from tokenizer containing matched text and clean positions
-* @param transformationMap - Position mapping from clean → original text
-* @returns FederalRegisterCitation with parsed metadata and translated positions
-*
-* @example
-* ```typescript
-* const token = {
-*   text: "85 Fed. Reg. 12345",
-*   span: { cleanStart: 10, cleanEnd: 28 },
-*   type: "federalRegister",
-*   patternId: "federal-register"
-* }
-* const citation = extractFederalRegister(token, transformationMap)
-* // citation = {
-* //   type: "federalRegister",
-* //   volume: 85,
-* //   page: 12345,
-* //   confidence: 0.9,
-* //   ...
-* // }
-* ```
+* Extracts statute citation metadata from a tokenized citation.
+* Dispatches to family-specific extractors based on patternId.
 */
-declare function extractFederalRegister(token: Token, transformationMap: TransformationMap): FederalRegisterCitation;
+declare function extractStatute(token: Token, transformationMap: TransformationMap): StatuteCitation;
 //#endregion
 //#region src/extract/extractStatutesAtLarge.d.ts
 declare function extractStatutesAtLarge(token: Token, transformationMap: TransformationMap): StatutesAtLargeCitation;
 //#endregion
+//#region src/extract/courtNormalization.d.ts
+/**
+* Normalize a court string extracted from a citation parenthetical.
+*
+* - Collapses spaces after periods: "S.D. N.Y." → "S.D.N.Y."
+* - Ensures trailing period on abbreviated forms: "2d Cir" → "2d Cir."
+* - Returns undefined for empty/undefined input
+*
+* @example
+* normalizeCourt("S.D. N.Y.")  // "S.D.N.Y."
+* normalizeCourt("2d Cir")     // "2d Cir."
+* normalizeCourt("U.S.")       // "U.S."
+*/
+declare function normalizeCourt(court: string | undefined): string | undefined;
+//#endregion
 //#region src/resolve/DocumentResolver.d.ts
 /**
 * Document-scoped resolver that processes citations sequentially
@@ -703,5 +639,19 @@ declare class DocumentResolver {
 */
 declare function resolveCitations(citations: Citation[], text: string, options?: ResolutionOptions): ResolvedCitation[];
 //#endregion
-export { type Citation, type CitationBase, type CitationOfType, type CitationType, type CleanTextResult, DocumentResolver, type ExtractOptions, type ExtractorMap, type FederalRegisterCitation, type FullCaseCitation, type FullCitation, type FullCitationType, type IdCitation, type JournalCitation, type NeutralCitation, type PublicLawCitation, type ResolutionOptions, type ResolutionResult, type ResolvedCitation, type ScopeStrategy, type ShortFormCaseCitation, type ShortFormCitation, type ShortFormCitationType, type Span, type StatuteCitation, type StatutesAtLargeCitation, type SupraCitation, type Token, type TransformationMap, type Warning, assertUnreachable, cleanText, extractCase, extractCitations, extractCitationsAsync, extractFederalRegister, extractJournal, extractNeutral, extractPublicLaw, extractStatute, extractStatutesAtLarge, isCaseCitation, isCitationType, isFullCitation, isShortFormCitation, resolveCitations, tokenize };
+//#region src/footnotes/detectFootnotes.d.ts
+/**
+* Detect footnote zones in text (HTML or plain text).
+*
+* Strategy: if the input contains HTML tags, try HTML structural detection
+* first. If that yields no results (HTML without footnote elements), fall
+* back to plain-text heuristic detection. For non-HTML input, use plain-text
+* detection directly.
+*
+* @param text - Raw input text (HTML or plain text)
+* @returns FootnoteMap with zones in input-text coordinates, sorted by start
+*/
+declare function detectFootnotes(text: string): FootnoteMap;
+//#endregion
+export { type Citation, type CitationBase, type CitationOfType, type CitationSignal, type CitationType, type CleanTextResult, type ConstitutionalCitation, type CourtInference, DocumentResolver, type ExtractOptions, type ExtractorMap, type FederalRegisterCitation, type FootnoteMap, type FootnoteZone, type FullCaseCitation, type FullCitation, type FullCitationType, type HistorySignal, type IdCitation, type JournalCitation, type NeutralCitation, type Parenthetical, type ParentheticalType, type PinciteInfo, type PublicLawCitation, type ResolutionOptions, type ResolutionResult, type ResolvedCitation, type ScopeStrategy, type ShortFormCaseCitation, type ShortFormCitation, type ShortFormCitationType, type Span, type StatuteCitation, type StatutesAtLargeCitation, type SubsequentHistoryEntry, type SupraCitation, type Token, type TransformationMap, type Warning, applyFalsePositiveFilters, assertUnreachable, cleanText, detectFootnotes, extractCase, extractCitations, extractCitationsAsync, extractConstitutional, extractFederalRegister, extractJournal, extractNeutral, extractPublicLaw, extractStatute, extractStatutesAtLarge, isCaseCitation, isCitationType, isFullCitation, isShortFormCitation, normalizeCourt, parsePincite, resolveCitations, tokenize };
 //# sourceMappingURL=index.d.mts.map