import { type PayloadField } from "@metaobjectsdev/render";
/**
 * An enriched payload-field node. Structurally a verify `PayloadField` (so the
 * shared resolver walks it), plus the per-field doc metadata the annotator needs
 * to emit a `ResolvedField` + link: `owner` (the VO that declares the field),
 * `type`, and `required`. Container fields (object / array-of-object) carry
 * `fields` whose nodes are owned by the nested VO.
 */
export interface AnnotatePayloadField extends PayloadField {
    owner: string;
    type: string;
    required: boolean;
    fields?: AnnotatePayloadField[];
}
/** The field a `{{variable}}` / `{{#section}}` resolves to. */
export interface ResolvedField {
    owner: string;
    name: string;
    type: string;
    required: boolean;
}
/** One ordered token of the annotated template. `raw` is the verbatim source
 *  span of the tag (text tokens carry `text`), so the source round-trips. */
export type TplToken = {
    kind: "text";
    text: string;
} | {
    kind: "var" | "unescaped";
    raw: string;
    path: string;
    field?: ResolvedField;
    href?: string;
    valid: boolean;
} | {
    kind: "section" | "inverted" | "close";
    raw: string;
    path: string;
    field?: ResolvedField;
    href?: string;
} | {
    kind: "partial";
    raw: string;
    ref: string;
    href?: string;
} | {
    kind: "comment";
    raw: string;
};
export interface AnnotateOptions {
    /** The root payload VO's short name (owner of the root-context fields). Used
     *  only for diagnostics / callers; per-field owner comes off the tree node. */
    ownerVoName: string;
    /**
     * Resolve a partial `{{>ref}}` to a doc-page href, if the ref names a
     * documented template. Returns the href or undefined (highlight-only).
     * Optional — when absent, partials are captured ref-only (no href).
     */
    resolvePartialHref?: (ref: string) => string | undefined;
    /**
     * Override how a resolved field's doc-page href is built (owner page + the
     * shared `#field-<name>` fragment). Optional — when absent, the flat default
     * `./<owner>.md#field-<name>` is used (byte-identical to today). A caller with
     * the output layout + page placement in scope injects a layout-aware resolver
     * (the SAME `docPageHref(layout, …)` the Payload cross-link uses) so the link
     * resolves under package layout too.
     */
    fieldHref?: (owner: string, name: string) => string;
}
/**
 * Parse `source` into an annotated IR, resolving each variable/section against
 * the enriched `payload` tree using verify's shared resolution.
 */
export declare function annotateTemplate(source: string, payload: AnnotatePayloadField[], opts: AnnotateOptions): TplToken[];
//# sourceMappingURL=template-source-annotate.d.ts.map