/**
 * V4 ref codec — encodes and decodes versioned text refs.
 *
 * Text refs are opaque handles that identify a resolved position or range
 * within a specific story. They embed the story key, revision, scope, and
 * segment data needed for mutation targeting.
 *
 * ## Wire formats
 *
 * | Version | Prefix           | Payload shape       |
 * |---------|------------------|---------------------|
 * | V3      | `text:`          | `{ v: 3, ... }`     |
 * | V4      | `text:v4:`       | `{ v: 4, ... }`     |
 *
 * The `text:v4:` prefix allows V4 refs to be distinguished from V3 refs
 * without parsing the JSON payload, enabling fast version checks.
 *
 * ## Backward compatibility
 *
 * V3 refs are decoded with an implicit `storyKey: 'body'` since V3 did
 * not support multi-story addressing — all V3 refs are body-scoped.
 */
/** V3 ref payload — body-scoped, no story key. */
export interface StoryRefV3 {
    v: 3;
    rev: string;
    matchId: string;
    scope: 'match' | 'block' | 'run';
    segments: Array<{
        blockId: string;
        start: number;
        end: number;
    }>;
    blockIndex?: number;
    runIndex?: number;
}
/** Node descriptor embedded in a V4 ref for node-scoped targeting. */
export interface StoryRefV4Node {
    kind: 'block' | 'inline';
    nodeType: string;
    nodeId?: string;
}
/** V4 ref payload — story-aware, supports all story types. */
export interface StoryRefV4 {
    v: 4;
    rev: string;
    storyKey: string;
    scope: 'match' | 'block' | 'run' | 'node';
    matchId?: string;
    segments?: Array<{
        blockId: string;
        start: number;
        end: number;
    }>;
    node?: StoryRefV4Node;
    blockIndex?: number;
    runIndex?: number;
}
/**
 * Encodes a V4 ref payload into its wire format.
 *
 * The output is a string with the `text:v4:` prefix followed by a
 * base64-encoded JSON payload.
 *
 * @param payload - The V4 ref data to encode.
 * @returns The encoded ref string.
 *
 * @example
 * ```ts
 * const ref = encodeV4Ref({
 *   v: 4,
 *   rev: '7',
 *   storyKey: 'fn:12',
 *   scope: 'match',
 *   segments: [{ blockId: 'p1', start: 0, end: 5 }],
 * });
 * // => 'text:v4:eyJ2Ijo0LCJyZXYiOi...'
 * ```
 */
export declare function encodeV4Ref(payload: StoryRefV4): string;
/**
 * Decodes a text ref string into its typed payload.
 *
 * Supports both V3 and V4 formats:
 * - V4 refs (`text:v4:...`) are decoded directly.
 * - V3 refs (`text:...`) are decoded with `storyKey: 'body'` implied.
 *
 * Returns `null` for malformed refs, non-text refs, or unknown versions.
 *
 * @param ref - The encoded ref string.
 * @returns The decoded payload, or `null` if the ref is invalid.
 *
 * @example
 * ```ts
 * const v4 = decodeRef('text:v4:eyJ2Ijo0Li4ufQ==');
 * // => { v: 4, storyKey: 'fn:12', ... }
 *
 * const v3 = decodeRef('text:eyJ2IjozLi4ufQ==');
 * // => { v: 3, matchId: '...', ... }
 * ```
 */
export declare function decodeRef(ref: string): StoryRefV3 | StoryRefV4 | null;
/**
 * Returns `true` if the ref string uses the V4 wire format.
 *
 * This is a prefix check only — it does NOT validate the payload.
 *
 * @param ref - The ref string to test.
 */
export declare function isV4Ref(ref: string): boolean;
//# sourceMappingURL=story-ref-codec.d.ts.map