interface CSSModuleClass {
    raw: string;
    moduleHint: string;
    localName: string;
}
interface SourceDetectionResult {
    source: string | null;
    component: string | null;
}
interface ElementFingerprint {
    dataAnnotate: string | null;
    dataTestId: string | null;
    id: string | null;
    tagName: string;
    textContent: string | null;
    role: string | null;
    ariaLabel: string | null;
    stableClasses: string[];
    domPath: string;
    siblingIndex: number;
    parentAnchor: string | null;
    rawClasses?: string[];
    cssModules?: CSSModuleClass[];
    sourceLocation: string | null;
    componentName: string | null;
    detectedSource: string | null;
    detectedComponent: string | null;
}
type AnnotationStatus = 'pending' | 'in_progress' | 'fixed_unverified' | 'verified' | 'dismissed';
type Actor = 'designer' | 'agent' | 'developer';
type AnnotationEventType = 'created' | 'acknowledged' | 'fix_claimed' | 'verified' | 'rejected' | 'dismissed' | 'reopened' | 'migrated';
interface AnnotationEvent {
    type: AnnotationEventType;
    actor: Actor | null;
    actorName?: string;
    timestamp: number;
    reason?: string;
}
interface Annotation {
    id: string;
    comment: string;
    fingerprint: ElementFingerprint;
    route: string;
    viewport: string;
    viewportBucket: number;
    timestamp: number;
    status: AnnotationStatus;
    lifecycle: AnnotationEvent[];
}
interface AnnotationStore {
    version: 1;
    annotations: Annotation[];
}
type ToolbarPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
interface WebRemarqOptions {
    theme?: 'light' | 'dark';
    classFilter?: (className: string) => boolean;
    dataAttribute?: string;
    position?: ToolbarPosition;
    shortcuts?: boolean;
    storage?: StorageAdapter;
}
type SearchConfidence = 'high' | 'medium' | 'low';
interface GrepQuery {
    query: string;
    glob: string;
    confidence: SearchConfidence;
}
interface AgentSearchHints {
    grepQueries: GrepQuery[];
    domContext: string;
    tagName: string;
    classes: string[];
}
interface AgentAnnotationSource {
    file: string;
    line: number;
    column: number;
    component: string | null;
}
interface AgentLifecycleEvent {
    type: AnnotationEventType;
    actor: Actor | null;
    timestamp: number;
    reason?: string;
}
interface AgentAnnotation {
    id: string;
    route: string;
    comment: string;
    status: AnnotationStatus;
    timestamp: number;
    source: AgentAnnotationSource | null;
    searchHints: AgentSearchHints;
    lifecycle: AgentLifecycleEvent[];
}
interface AgentExport {
    version: 1;
    format: 'agent';
    viewportBucket: number;
    annotations: AgentAnnotation[];
}
interface StorageChangeEvent {
    type: 'add' | 'update' | 'remove' | 'clear';
    annotation?: Annotation;
    id?: string;
}
interface StorageAdapter {
    load(): Promise<AnnotationStore | null>;
    save(annotation: Annotation): Promise<void>;
    remove(id: string): Promise<void>;
    clear(): Promise<void>;
    subscribe?(callback: (event: StorageChangeEvent) => void): () => void;
    readonly isMemoryOnly?: boolean;
}

declare function createFingerprint(el: HTMLElement, options?: Pick<WebRemarqOptions, 'classFilter' | 'dataAttribute'>): ElementFingerprint;

declare function matchElement(fp: ElementFingerprint, options?: Pick<WebRemarqOptions, 'dataAttribute'>): HTMLElement | null;

declare function migrateAnnotation(legacy: any): Annotation;
declare class AnnotationStorage {
    private adapter;
    private cache;
    readonly ready: Promise<void>;
    constructor(adapter: StorageAdapter);
    get isMemoryOnly(): boolean;
    getAll(): Annotation[];
    getByRoute(route: string): Annotation[];
    getById(id: string): Annotation | undefined;
    add(annotation: Annotation): Promise<void>;
    remove(id: string): Promise<void>;
    update(id: string, changes: Partial<Annotation>): Promise<void>;
    clearAll(): Promise<void>;
    exportJSON(): AnnotationStore;
    importJSON(data: AnnotationStore): Promise<void>;
    private init;
    private migrateViewportBuckets;
}

declare class LocalStorageAdapter implements StorageAdapter {
    isMemoryOnly: boolean;
    private extraFields;
    private memoryStore;
    load(): Promise<AnnotationStore | null>;
    save(annotation: Annotation): Promise<void>;
    remove(id: string): Promise<void>;
    clear(): Promise<void>;
    private ensureStore;
    private persist;
}

/**
 * Level 1: Read data-remarq-source/data-remarq-component attrs
 * injected by @web-remarq/babel-plugin or @web-remarq/unplugin.
 */
declare function detectRemarqPlugin(el: HTMLElement): SourceDetectionResult;
/**
 * Runs Level 2 detectors in order. Returns first non-null result.
 */
declare function detectSource(el: HTMLElement): SourceDetectionResult;

declare function generateAgentExport(annotations: Annotation[], viewportBucket: number): AgentExport;

type LifecycleAction = 'acknowledge' | 'claimFix' | 'verify' | 'reject' | 'dismiss' | 'reopen';
declare class InvalidTransitionError extends Error {
    constructor(from: AnnotationStatus, action: LifecycleAction);
}
interface EventOpts {
    actor?: Actor;
    actorName?: string;
    reason?: string;
    timestamp?: number;
}
declare function createEvent(type: AnnotationEventType, opts?: EventOpts): AnnotationEvent;
declare function transition(annotation: Annotation, action: LifecycleAction, opts?: EventOpts): {
    status: AnnotationStatus;
    event: AnnotationEvent;
};

export { type Actor, type AgentAnnotation, type AgentAnnotationSource, type AgentExport, type AgentLifecycleEvent, type AgentSearchHints, type Annotation, type AnnotationEvent, type AnnotationEventType, type AnnotationStatus, AnnotationStorage, type AnnotationStore, type CSSModuleClass, type ElementFingerprint, type EventOpts, type GrepQuery, InvalidTransitionError, type LifecycleAction, LocalStorageAdapter, type SearchConfidence, type SourceDetectionResult, type StorageAdapter, type StorageChangeEvent, type ToolbarPosition, createEvent, createFingerprint, detectRemarqPlugin, detectSource, generateAgentExport, matchElement, migrateAnnotation, transition };