import { EsmBackendConfig, IifeBackendConfig, IifeBundleRetryStatus, ItemEntity, createPieLogger } from '@pie-players/pie-players-shared';
export type IifeBundleRetryStatusHandler = (status: IifeBundleRetryStatus) => void;
/**
 * Narrow string union of section-preload pipeline stages reported on
 * `element-preload-retry` and `element-preload-error` events. Hosts use
 * this to disambiguate "the renderable's PIE config is invalid" from
 * "the IIFE bundle won't load" from "the ESM module won't import" from
 * "the host claimed strategy='preloaded' but didn't pre-register".
 */
export type PreloadStage = "validate-config" | "iife-load" | "esm-load" | "preloaded-assert";
export type ElementPreloadRetryDetail = {
    componentTag: string;
    stage: PreloadStage;
    attempt: number;
    maxRetries: number;
    error: string;
    strategy: string;
    bundleType: string | null;
    bundleHost: string;
    renderablesCount: number;
};
export type ElementPreloadErrorDetail = {
    componentTag: string;
    stage: PreloadStage;
    error: string;
    strategy: string;
    bundleType: string | null;
    bundleHost: string;
    renderablesCount: number;
};
/**
 * Carries which stage of `warmupSectionElements` rejected, so the
 * `SectionItemsPane.svelte` `usePromise` rejection effect can surface
 * the right `stage` on the host's `element-preload-error` event.
 *
 * Catastrophic adapter rejections (network freeze, bundle timeout) bubble
 * up through `ensureRegistered` as `ElementLoaderError` and get wrapped
 * in `PreloadStageError` with stage `"iife-load"` or `"esm-load"`
 * depending on the requested strategy. Config-contract failures wrap
 * with stage `"validate-config"`.
 */
export declare class PreloadStageError extends Error {
    readonly name = "PreloadStageError";
    readonly stage: PreloadStage;
    readonly cause: unknown;
    constructor(stage: PreloadStage, cause: unknown);
}
export declare function getPreloadLogger(componentTag: string): import('@pie-players/pie-players-shared').PieLogger;
export declare function getLoaderView(env: Record<string, unknown>): "author" | "delivery";
/**
 * Stable string signature of a list of renderables, used as a react-key
 * hint for the composition snapshot plumbed through the layout tree.
 *
 * The signature is *not* used for preload dedup anymore — the deep
 * `ElementLoader` primitive handles that internally. It is retained only
 * because downstream template props still pass a string identifier
 * through the customElement boundary.
 */
export declare function getRenderablesSignature(renderables: unknown[]): string;
export declare function formatElementLoadError(stage: string, error: unknown): string;
export declare function toErrorMessage(error: unknown): string;
/**
 * Translate a section-player's resolved props into an `ElementLoader`
 * backend config. Throws when required host-supplied values (bundle host
 * for IIFE) are missing — callers should surface this as a preload error.
 *
 * `onBundleRetryStatus` is wired through to `IifeBackendConfig` for IIFE
 * strategy so hosts can render "bundle still building" UI while the
 * adapter polls the bundle service. ESM ignores it.
 */
export declare function buildBackendConfigFromProps(args: {
    strategy: string;
    resolvedPlayerProps: Record<string, unknown>;
    resolvedPlayerEnv: Record<string, unknown>;
    iifeBundleHost?: string | null;
    onBundleRetryStatus?: IifeBundleRetryStatusHandler;
}): IifeBackendConfig | EsmBackendConfig;
/**
 * Returns the bundle type (IIFE) or `null` (ESM, preloaded, empty) that
 * should be reported on `element-preload-error` events. Host telemetry
 * needs this as a string to distinguish editor bundles from player bundles.
 */
export declare function describeBundleType(backend: IifeBackendConfig | EsmBackendConfig | null): string | null;
/**
 * Return the bundle host (IIFE only) for telemetry. Empty string for any
 * other backend so the host event shape stays stable.
 */
export declare function describeBundleHost(backend: IifeBackendConfig | EsmBackendConfig | null): string;
/**
 * Pre-warm the aggregate element set for a section before items mount.
 *
 * Contract:
 * - `renderables.length === 0` — no-op. Nothing to load.
 * - `strategy === "preloaded"` — assert every aggregate tag is already
 *   registered with `customElements`. Throws `ElementAssertionError`
 *   (wrapped in `PreloadStageError` with stage `"preloaded-assert"`) on
 *   any missing tag, surfacing one section-level diagnostic instead of
 *   N small per-item rejections.
 * - Otherwise: aggregate tags, build backend, await `ensureRegistered`.
 *
 * On any validation or load failure, rejects with a descriptive Error.
 * The caller (section-player widget) is expected to surface the failure
 * through an `element-preload-error` event; item-players then attempt
 * their own registration and typically get a clean per-tag error.
 */
export declare function warmupSectionElements(args: {
    strategy: string;
    renderables: ItemEntity[];
    resolvedPlayerProps: Record<string, unknown>;
    resolvedPlayerEnv: Record<string, unknown>;
    iifeBundleHost?: string | null;
    logger?: ReturnType<typeof createPieLogger>;
    onBundleRetryStatus?: IifeBundleRetryStatusHandler;
}): Promise<void>;
