import { type ComponentCatalogSurfaceOptions, type DiscoveredComponent } from './components.js';
import type { Surface } from './runner.js';
export type ManifestJsonPrimitive = string | number | boolean | null;
export type ManifestJsonValue = ManifestJsonPrimitive | ManifestJsonValue[] | {
    [key: string]: ManifestJsonValue;
};
export type ComponentManifestVariant = {
    /** Capture-key / catalog segment suffix. Unique per component. */
    key: string;
    /** Serializable props only (JSON values). No functions or live service data. */
    props?: ManifestJsonValue;
    /** Optional committed provider/harness module path (repo-relative). */
    provider?: string;
    /** Viewport widths for this variant surface. */
    widths?: number[];
    /** Viewport height for this variant surface. */
    height?: Surface['height'];
};
export type ComponentManifestComponent = {
    /**
     * Stable component id for keying. When omitted, derived from `module` the same
     * way {@link discoverComponentFiles} slugs relative file paths.
     */
    id?: string;
    /** Component module path (repo-relative; never a remote URL). */
    module: string;
    /** Named export. Defaults to `default`. */
    export?: string;
    /** At least one explicit variant — StyleProof does not invent props. */
    variants: ComponentManifestVariant[];
};
export type ComponentManifestExclusion = {
    /** Repo-relative path of a component file intentionally left out of the catalog. */
    path: string;
    /** Human-readable reason (required; empty reasons are rejected). */
    reason: string;
};
export type ComponentManifest = {
    /** Schema version. Only `1` is accepted in this experiment. */
    version: 1;
    /** Capture-key prefix. Defaults to `component` (matches discoverComponentFiles). */
    prefix?: string;
    /**
     * Catalog URL base path (no trailing slash). Defaults to
     * `/styleproof/components` so routes plug into componentCatalogSurfaces.
     */
    catalogBasePath?: string;
    components: ComponentManifestComponent[];
    exclusions?: ComponentManifestExclusion[];
};
export type ValidateComponentManifestOptions = {
    /** When set, module and provider paths must exist as files under this root. */
    cwd?: string;
};
export declare class ComponentManifestError extends Error {
}
/**
 * True when `value` is JSON-serializable (no functions, bigint, undefined, NaN,
 * Infinity, symbols, or cyclic structures). Cycles return false instead of
 * overflowing the call stack. Repeated shared (acyclic) references are allowed,
 * matching `JSON.stringify`.
 */
export declare function isSerializableManifestValue(value: unknown): value is ManifestJsonValue;
/**
 * Slug a path or id the same way component file keys are built
 * (kebab-case, no extension, no leading/trailing hyphens).
 */
export declare function slugManifestSegment(input: string): string;
/**
 * Validate and normalize an unknown component-manifest document.
 * Throws {@link ComponentManifestError} with actionable diagnostics.
 */
export declare function validateComponentManifest(input: unknown, options?: ValidateComponentManifestOptions): ComponentManifest;
export type ComponentManifestSurfaceKeyInput = {
    prefix?: string;
    componentId: string;
    variantKey: string;
};
/** Deterministic surface key: `<prefix>-<componentId>-<variantKey>` (slugified). */
export declare function componentManifestSurfaceKey(input: ComponentManifestSurfaceKeyInput): string;
export type ComponentManifestCatalogPathOptions = {
    catalogBasePath?: string;
};
/** Catalog URL path for a surface key (default base matches componentCatalogSurfaces). */
export declare function componentManifestCatalogPath(surfaceKey: string, options?: ComponentManifestCatalogPathOptions): string;
/**
 * Expand a validated manifest into {@link DiscoveredComponent} rows (one per variant)
 * sorted by key — ready for {@link componentCatalogSurfaces}.
 */
export declare function componentManifestToDiscovered(manifest: ComponentManifest): DiscoveredComponent[];
export type ComponentManifestCatalogSurfaceOptions = ComponentCatalogSurfaceOptions & {
    /** Override manifest catalogBasePath when building default URLs. */
    catalogBasePath?: string;
};
/**
 * Build StyleProof surfaces from a validated manifest using
 * {@link componentCatalogSurfaces}. Default URL:
 * `<catalogBasePath>/<surfaceKey>`.
 *
 * Per-variant `widths` / `height` from the manifest override catalog-level
 * viewport options for the matching surface (typed variant contract).
 */
export declare function componentManifestCatalogSurfaces(manifest: ComponentManifest, options?: ComponentManifestCatalogSurfaceOptions): Surface[];