/**
 * document-renderers.ts
 *
 * Renderer registry that turns a Sanity document into both:
 *
 *   - Markdown content for inclusion in a literacy task's grader/candidate
 *     context (existing surface, used by the doc fetcher).
 *   - A symbol-reference index for the W0197 grader-context pathway —
 *     a flat list of identifiers the doc legitimizes, with provenance.
 *     The grader prefers this over the rendered markdown when available
 *     (smaller, deterministic, harder for the grader's prior to override).
 *
 * Both surfaces dispatch through the same registry. Articles and
 * typesReference docs have hand-written renderers; everything else falls
 * through to the default walker. This keeps "what to do with a document
 * of type X" a single decision point regardless of whether the doc was
 * looked up by slug, path, perspective, or id.
 *
 * Two tiers of fidelity (rendered output):
 *
 *   1. Registered renderers (high fidelity) — `article`, `typesReference`.
 *      Hand-written for the document shapes we care about most.
 *   2. Default renderer (best effort) — walks the doc, flattens portable-text
 *      fields, surfaces top-level scalars, follows references one level deep,
 *      skips framework-internal fields. Lets pinning a `marketingPage`,
 *      `glossaryEntry`, etc. work without AILF code changes.
 *
 * Adding a new high-fidelity renderer: implement a `DocumentRenderer`
 * (both `render` and `extractSymbols`) and register it in
 * `BUILT_IN_RENDERERS` keyed by `_type`.
 */
import { type SymbolIndex } from "./symbol-index.js";
/**
 * A Sanity document plus any references we've already resolved for it.
 * The resolver fetches the doc once and may include common deref payloads
 * (e.g. `latestVersion->{...}` for typesReference) so renderers don't need
 * to issue additional client.fetch calls themselves.
 */
export interface DocumentForRender {
    _id: string;
    _type: string;
    [key: string]: unknown;
}
export interface RenderContext {
    /**
     * Async URL fetcher for renderers that need to follow `sanity.fileAsset`
     * URLs (e.g. typedoc JSON for `typesReference` docs). Returns the raw
     * body text or `null` on failure.
     */
    fetchUrl?: (url: string) => Promise<string | null>;
    /**
     * Soft cap on rendered content length, in bytes. Renderers should respect
     * this and append a truncation notice rather than blow up grader context.
     */
    maxBytes?: number;
}
export interface RenderResult {
    /** The rendered Markdown. Empty string is permitted but produces a warn. */
    content: string;
    /**
     * The fidelity tier used. Resolvers can log differently based on this:
     *   - "high"    — a registered renderer ran
     *   - "default" — fell through to the generic walker (info log)
     */
    fidelity: "high" | "default";
    /**
     * Stable display slug for this document. Articles use `slug.current`;
     * other types fall back to a `<_type>:<_id>` form when no slug exists.
     * Surfaces in `DocContext.slugs` for retrieval-metric attribution.
     */
    slug: string;
}
export interface DocumentRenderer {
    /**
     * Produce rendered Markdown for the doc's content surface (for grader
     * + candidate context inclusion).
     */
    render(doc: DocumentForRender, ctx: RenderContext): Promise<RenderResult> | RenderResult;
    /**
     * Produce a symbol-reference index for the doc — a flat list of
     * identifiers the doc legitimizes plus provenance snippets. Used by
     * the grader-context pathway (W0197) instead of injecting the full
     * rendered doc. Returning an empty index signals the caller to fall
     * back to the rendered markdown.
     */
    extractSymbols(doc: DocumentForRender, ctx: RenderContext): Promise<SymbolIndex> | SymbolIndex;
}
/**
 * Render a document using the registered renderer for its `_type`, falling
 * back to the default walker. The returned `fidelity` flag tells callers
 * whether to emit the "info: dedicated renderer would help" log.
 */
export declare function renderDocument(doc: DocumentForRender, ctx?: RenderContext): Promise<RenderResult>;
/**
 * Extract a symbol-reference index for a document using its registered
 * renderer (or the default walker for unknown types). Used by the
 * grader-context pathway (W0197) to feed the LLM judge a compact
 * deterministic recognition reference instead of the full rendered doc.
 *
 * Returns an empty `SymbolIndex` (`{ symbols: [] }`) when extraction
 * yields nothing — callers interpret this as the signal to fall back to
 * the rendered markdown.
 */
export declare function extractSymbolsForDoc(doc: DocumentForRender, ctx?: RenderContext): Promise<SymbolIndex>;
/** Exported for tests and consumers that want the registered set. */
export declare const REGISTERED_RENDERER_TYPES: string[];
