import type { DebugMetadataAsset, UiSourceMapData } from './types.js';
/**
 * Source location recovered for a single UI node, in the shape the
 * reverse-resolved tree gains alongside its original fields.
 *
 * @public
 */
export interface UiSourceLocation {
    /** `owner/repo` derived from the build's git remote, or `null`. */
    repo: string | null;
    /** Authored source path (relative to the project root), or `null`. */
    source: string | null;
    /** 1-based source line. */
    line: number;
    /** 1-based source column. */
    column: number;
}
/**
 * One UI node of the tree the Lynx engine dumps — the input to
 * {@link remapUiTree}. Three fields are read: `nodeIndex` and
 * `debugMetadataUrl` drive reverse-resolution, and `children` is walked
 * recursively. All three are optional because the engine emits nodes that
 * carry no source mapping (e.g. raw-text nodes have no `nodeIndex`); such
 * nodes pass through untouched. Every other field is opaque.
 *
 * @public
 */
export interface UiNode {
    /** Compile-time node identity, looked up in the UI source map. */
    nodeIndex?: number;
    /** URL/path of the `debug-metadata.json` covering this node. */
    debugMetadataUrl?: string;
    /** Child nodes, walked recursively. */
    children?: UiNode[];
    [field: string]: unknown;
}
/**
 * A {@link UiNode} after reverse-resolution. Nodes whose `nodeIndex` is
 * known to their `debugMetadataUrl`'s UI source map gain the
 * {@link UiSourceLocation} fields; all others are returned verbatim.
 *
 * @public
 */
export interface RemappedUiNode extends UiNode {
    children?: RemappedUiNode[];
    repo?: string | null;
    source?: string | null;
    line?: number;
    column?: number;
}
/**
 * Assert that a parsed value is a {@link UiNode} tree. Use it at trust
 * boundaries — e.g. right after `JSON.parse`-ing an engine dump — so
 * malformed input fails fast with a located error (`$.children[1]`-style
 * path) instead of crashing deep inside resolution.
 *
 * `nodeIndex`, `debugMetadataUrl` and `children` are all optional (the
 * engine emits nodes with no source mapping, such as raw text); they are
 * only rejected when present with the wrong type. A non-object, or a
 * `children` that is not an array, is always rejected.
 *
 * @public
 */
export declare function assertUiNode(value: unknown, path?: string): asserts value is UiNode;
/**
 * Runtime check that a parsed value matches {@link UiSourceMapData}'s
 * load-bearing shape — an object with `sources`, `mappings` and `uiMaps`
 * arrays. Guards against `debugMetadataUrl`s that resolve to JSON of a
 * different (or older) format.
 *
 * @public
 */
export declare function isUiSourceMapData(value: unknown): value is UiSourceMapData;
/**
 * Build a `nodeIndex -> {source, line, column}` lookup from a
 * {@link UiSourceMapData}. The payload is column-oriented: `uiMaps[i]`
 * is the nodeIndex, and the matching `mappings[i]` entry holds
 * `[sourceIndex, line, column]`, with `sourceIndex` indexing `sources`.
 *
 * @public
 */
export declare function buildUiSourceMapLookup(uiSourceMap: UiSourceMapData): Map<number, Omit<UiSourceLocation, 'repo'>>;
/**
 * Normalize a git remote URL (SSH or HTTP form) to an `owner/repo`
 * identifier, dropping any trailing `.git`. Returns `null` for empty
 * input and the original string when it matches no known form.
 *
 * @public
 */
export declare function normalizeRepo(remoteUrl: string | null | undefined): string | null;
/**
 * Loads the {@link DebugMetadataAsset} a node's `debugMetadataUrl` points
 * at. Supplied by the caller so the core stays free of I/O (the CLI wires
 * up `fetch` / `fs`); only called once per distinct URL.
 *
 * @public
 */
export type DebugMetadataLoader = (debugMetadataUrl: string) => Promise<DebugMetadataAsset>;
/**
 * Reverse-resolve a UI node tree dumped by the Lynx engine.
 *
 * Every node carrying both a `nodeIndex` and a `debugMetadataUrl` whose
 * `uiSourceMap` knows that index is annotated with {@link UiSourceLocation}
 * fields (`repo`, `source`, `line`, `column`). All other fields — and nodes
 * that cannot be resolved — pass through verbatim. The input is not
 * mutated; a new tree is returned.
 *
 * @public
 */
export declare function remapUiTree(root: UiNode, loadMetadata: DebugMetadataLoader): Promise<RemappedUiNode>;