/** A single timestamped data point on a {@link TracingGraph}. */
export declare class TracingPoint {
    /** Unix time in seconds. */
    timestamp: number;
    /** Arbitrary point data (typically `{ value }`). */
    data: Record<string, any>;
    /** Optional label for the point. */
    label: string;
    constructor(timestamp: number, data: Record<string, any>, label?: string);
}
/** A named, timestamped event recorded on a tracing handle. */
export declare class TracingEvent {
    /** Unix time in seconds. */
    timestamp: number;
    /** Event name. */
    name: string;
    /** Optional event data. */
    data: Record<string, any> | null;
    constructor(timestamp: number, name: string, data?: Record<string, any> | null);
}
/** Options for {@link Tracing.addGraph}. */
export type TracingGraphOptions = {
    /** X-axis label. Default: `'time'`. */
    xLabel?: string;
    /** Y-axis label. Default: `'value'`. */
    yLabel?: string;
    /** X-axis value type, e.g. `'time'`. Default: `'time'`. */
    xType?: string;
    /** Fixed Y-axis range `[min, max]`. Default: `[0, 100]`. */
    yRange?: [number, number];
    /** Maximum retained points before the oldest are dropped. Default: `1000`. */
    maxDataPoints?: number;
};
/** Serialized form of a {@link TracingGraph} for the debug dashboard. */
export type ExportedGraph = {
    title: string;
    x_label: string;
    y_label: string;
    x_type: string;
    y_range: [number, number];
    data: Array<[number, number]>;
};
/** A time-series graph rendered in the debug dashboard. */
export declare class TracingGraph {
    title: string;
    xLabel: string;
    yLabel: string;
    xType: string;
    yRange: [number, number];
    maxDataPoints: number;
    data: TracingPoint[];
    constructor(title: string, xLabel: string, yLabel: string, opts?: {
        xType?: string;
        yRange?: [number, number];
        maxDataPoints?: number;
    });
    /** Append a data point at the current time, dropping the oldest if over capacity. */
    addPoint(value: number, label?: string): void;
    /** Serialize this graph to an {@link ExportedGraph}. */
    export(): ExportedGraph;
}
/** Serialized snapshot of a tracing handle's key/values, events, and graphs. */
export type HandleExport = {
    name: string;
    kv: Record<string, any>;
    events: Array<{
        timestamp: number;
        name: string;
        data: Record<string, any> | null;
    }>;
    graphs: Record<string, ExportedGraph>;
};
/** Collects debug telemetry (key/values, events, graphs) under named handles for the debug dashboard; state is shared statically. */
export declare class Tracing {
    private static _graphs;
    private static _handles;
    private static _events;
    private static _kvData;
    /** Handle name this tracing instance records under. */
    name: string;
    constructor(name: string);
    private static _eventsFor;
    private static _kvFor;
    /** Get (or create) the shared tracing handle for `name`. */
    static withHandle(name: string): Tracing;
    /** Register a new {@link TracingGraph} under `title` and return it. */
    static addGraph(title: string, opts?: TracingGraphOptions): TracingGraph;
    /** Look up a registered graph by `title`, or `null` if none. */
    static getGraph(title: string): TracingGraph | null;
    /** Append a point to the graph named `graphTitle` (no-op if it doesn't exist). */
    addPoint(graphTitle: string, value: number, label?: string): void;
    /** Record a named event on this handle at the current time. */
    addEvent(name: string, data?: Record<string, any> | null): void;
    /** Set a key/value pair on this handle. */
    setKv(key: string, value: any): void;
    /** Read a key/value pair from this handle. */
    getKv(key: string): any;
    /** @internal Serialize this handle's state. */
    _export(): HandleExport;
    /** Serialize every global graph and every tracing handle. */
    static exportAll(): {
        global_graphs: Record<string, ExportedGraph>;
        handles: Record<string, HandleExport>;
    };
    /** Serialize the handle named `handleName`, or an empty snapshot if it doesn't exist. */
    static exportForHandle(handleName: string): HandleExport | {
        kv: Record<string, any>;
        events: any[];
        graphs: any[];
    };
}