import type { TokenReferenceSpan, TokenValue } from './contracts.js';
export interface TokenReferenceFormatContext {
    readonly reference: Readonly<TokenReferenceSpan>;
    /** The exact original UTF-16 slice, unaffected by replacements of other spans. */
    readonly original: string;
}
export declare class TokenReferenceFormatError extends Error {
    readonly code: 'invalid-range' | 'invalid-replacement';
    constructor(code: TokenReferenceFormatError['code'], message: string);
}
/** Validate every span before invoking a syntax-specific replacement callback. */
export declare function formatTokenReferences(value: Pick<TokenValue, 'text' | 'references'>, replace: (context: TokenReferenceFormatContext) => string): string;