/**
 * TrailLibrary — load + index a set of Trails, look up by id/family/chain.
 *
 * Two construction paths:
 *   • `TrailLibrary.fromArray(trails)`        — pass in already-parsed Trail objects (browser-friendly)
 *   • `TrailLibrary.fromDirectory(path)`      — read *.trail.json from a directory (Node-only)
 *
 * Validation happens at construction time; an invalid file throws with the field path. Once
 * loaded, lookups are O(1) by id and O(N) by family/chain (acceptable for libraries up to
 * ~thousands).
 *
 * Authoring rule of thumb: one Trail per file, filename matches `id` with dots → dashes
 * (`trail.morpho.supply` → `trail.morpho.supply.json`, OR `trail-morpho-supply.json`; the loader
 * doesn't care, only the contents matter).
 */
import { Trail, type ChainName } from "./trail.js";
export interface TrailLibraryStats {
    total: number;
    byFamily: Record<string, number>;
    byChain: Record<string, number>;
}
export interface TrailFilter {
    family?: string;
    chain?: ChainName;
    /** Substring match against id, name, or summary (case-insensitive). */
    query?: string;
}
export declare class TrailLibrary {
    private readonly trails;
    private constructor();
    /** Build a library from an array of already-parsed trails. Throws on duplicate ids. */
    static fromArray(trails: Trail[]): TrailLibrary;
    /**
     * Build a library from an array of raw JSON objects — runs them all through `parseTrail` so
     * each one is fully validated. Useful when loading from a bundle / fetch / static import.
     */
    static fromJsonArray(items: unknown[]): TrailLibrary;
    /**
     * Load all *.trail.json files from a directory (Node-only — uses dynamic import of fs).
     * The async import keeps the SDK browser-safe; callers that don't use fromDirectory will not
     * pull node:fs at runtime.
     */
    static fromDirectory(dir: string): Promise<TrailLibrary>;
    /** O(1) lookup by id. Returns undefined if not present. */
    get(id: string): Trail | undefined;
    /** Strict variant — throws if the id isn't in the library. */
    require(id: string): Trail;
    /** All trails. */
    all(): Trail[];
    /** Number of trails in the library. */
    get size(): number;
    /** Filter trails by family / chain / substring query. */
    filter(opts: TrailFilter): Trail[];
    /** Quick stats — useful for `trail.list` MCP/CLI tools + dashboards. */
    stats(): TrailLibraryStats;
    /** Closest-prefix suggestions for typos — used in `require()` error messages. */
    private suggest;
}