/**
 * PM Position Validation Module
 *
 * Part of Phase 0 instrumentation for typing performance optimization.
 * Validates that all rendered text spans have proper pmStart/pmEnd attributes
 * to ensure cursor positioning can always fall back to PM DOM coordinates.
 *
 * Key principles:
 * 1. All text-containing elements must have data-pm-start and data-pm-end
 * 2. Missing attributes indicate a gap in position mapping
 * 3. Warnings are dev-mode only (zero overhead in production)
 * 4. Provides fallback guidance when positions are missing
 */
/**
 * Validation statistics for monitoring position coverage.
 */
export interface PmPositionValidationStats {
    /** Total text spans checked */
    totalSpans: number;
    /** Spans with complete pmStart/pmEnd */
    validSpans: number;
    /** Spans missing pmStart */
    missingPmStart: number;
    /** Spans missing pmEnd */
    missingPmEnd: number;
    /** Spans missing both */
    missingBoth: number;
}
/**
 * Global validation statistics collector.
 */
declare class ValidationStatsCollector {
    private stats;
    record(hasPmStart: boolean, hasPmEnd: boolean): void;
    getStats(): Readonly<PmPositionValidationStats>;
    reset(): void;
    getCoveragePercent(): number;
    logSummary(): void;
}
/**
 * Global stats collector instance.
 */
export declare const globalValidationStats: ValidationStatsCollector;
/**
 * Asserts that a rendered text run has pmStart and pmEnd positions.
 *
 * Used during DOM rendering to validate that all text content has position markers.
 * In dev mode, logs a warning if positions are missing. In production, silent no-op.
 *
 * @param run - The text run being rendered
 * @param context - Context string for debugging (e.g., "paragraph text run", "list marker")
 *
 * @example
 * ```typescript
 * const span = document.createElement('span');
 * span.textContent = run.text;
 * assertPmPositions(run, 'paragraph text run');
 * if (run.pmStart != null) span.dataset.pmStart = String(run.pmStart);
 * if (run.pmEnd != null) span.dataset.pmEnd = String(run.pmEnd);
 * ```
 */
export declare function assertPmPositions(run: {
    pmStart?: number | null;
    pmEnd?: number | null;
    text?: string;
}, context: string): void;
/**
 * Asserts that a rendered fragment has pmStart and pmEnd positions.
 *
 * Used for paragraph fragments and other block-level elements.
 *
 * **Note on validation warnings:** This function only records statistics and does not emit
 * warnings for missing PM positions. Fragment-level position validation warnings were removed
 * because certain fragment types (e.g., inline SDT wrappers) intentionally have PM positions
 * on wrapper elements for selection highlighting, while their child spans are used for
 * accurate click-to-position mapping. The presence of wrapper PM positions is valid for
 * rendering purposes, but warning about them creates noise without indicating an actual issue.
 * Text run validation (via `assertPmPositions`) remains active to catch genuine position gaps.
 *
 * @param fragment - The fragment being rendered
 * @param context - Context string for debugging
 */
export declare function assertFragmentPmPositions(fragment: {
    pmStart?: number | null;
    pmEnd?: number | null;
    kind?: string;
}, _context: string): void;
/**
 * Validates PM positions on a rendered DOM element.
 *
 * Checks that the element has data-pm-start and data-pm-end attributes.
 * Useful for validating elements after they've been rendered.
 *
 * @param element - The rendered DOM element
 * @param context - Context string for debugging
 */
export declare function validateRenderedElement(element: HTMLElement, context: string): void;
/**
 * Logs a summary of PM position validation statistics.
 * Call this periodically (e.g., after each render) to monitor coverage.
 *
 * Only logs in development mode and only if coverage is < 100%.
 */
export declare function logValidationSummary(): void;
/**
 * Resets validation statistics.
 * Useful for testing or when starting a new document.
 */
export declare function resetValidationStats(): void;
/**
 * Gets current validation statistics.
 *
 * @returns Current validation stats (readonly copy)
 */
export declare function getValidationStats(): Readonly<PmPositionValidationStats>;
export {};
//# sourceMappingURL=pm-position-validation.d.ts.map