interface ExternalAnnotationSet {
  // Identifies the source document
  documentId: string;  // Hash, filename, or unique ID
  documentHash?: string;  // SHA256 of document for integrity
  
  // Metadata
  createdAt: string;  // ISO timestamp
  updatedAt: string;
  version: string;  // Format version for migrations
  
  // Label definitions (annotation types/categories)
  labels: AnnotationLabel[];
  
  // The annotations themselves
  annotations: ExternalAnnotation[];
  
  // Optional relationships between annotations
  relationships?: AnnotationRelationship[];
}

interface ExternalAnnotation {
  id: string;
  labelId: string;
  
  // Text targeting - multiple strategies
  target: AnnotationTarget;
  
  // Cached/extracted data
  rawText: string;  // The annotated text
  
  // Metadata
  author?: string;
  createdAt?: string;
  metadata?: Record<string, unknown>;
}

interface AnnotationTarget {
  // Strategy 1: Character offsets (most portable)
  startOffset?: number;
  endOffset?: number;
  
  // Strategy 2: Element-based (uses DocumentStructure IDs)
  elementId?: string;  // e.g., "doc/p-5" or "doc/tbl-0/tr-1/tc-2"
  
  // Strategy 3: Text search (fallback)
  searchText?: string;
  occurrence?: number;
  
  // Strategy 4: Page-based with bounding box (for layout)
  page?: number;
  boundingBox?: BoundingBox;
  
  // Strategy 5: XPath (for advanced users)
  xpath?: string;
}

// Load and project annotations
export function renderWithExternalAnnotations(
  document: File | Uint8Array,
  annotations: ExternalAnnotationSet,
  options?: ConversionOptions
): Promise<string>;

// Create annotation from user selection
export function createAnnotationFromSelection(
  selection: Selection,
  label: AnnotationLabel,
  documentStructure: DocumentStructure
): ExternalAnnotation;

// Validate annotations against document
export function validateAnnotations(
  document: File | Uint8Array,
  annotations: ExternalAnnotationSet
): Promise<ValidationResult>;

// Types
export interface ExternalAnnotationSet { ... }
export interface ExternalAnnotation { ... }
export interface AnnotationTarget { ... }

// Hook for managing external annotations
export function useExternalAnnotations(
  document: File | Uint8Array | null,
  initialAnnotations?: ExternalAnnotationSet
): {
  annotations: ExternalAnnotationSet | null;
  addAnnotation: (annotation: ExternalAnnotation) => void;
  removeAnnotation: (id: string) => void;
  updateAnnotation: (id: string, updates: Partial<ExternalAnnotation>) => void;
  exportAnnotations: () => string;  // JSON
  importAnnotations: (json: string) => void;
  validateAnnotations: () => Promise<ValidationResult>;
};

// Hook for annotation-aware rendering
export function useAnnotatedDocument(
  document: File | Uint8Array | null,
  annotations: ExternalAnnotationSet | null,
  options?: ConversionOptions
): {
  html: string | null;
  isLoading: boolean;
  error: Error | null;
};

interface ValidationResult {
  valid: boolean;
  warnings: ValidationWarning[];
  errors: ValidationError[];
  repairable: boolean;
}

interface ValidationWarning {
  annotationId: string;
  type: 'text_mismatch' | 'offset_drift' | 'element_not_found';
  message: string;
  suggestedFix?: Partial<AnnotationTarget>;
}