/**
 * snapDOM – ultra-fast DOM-to-image capture
 * TypeScript definitions (v1.9.14)
 *
 * Notes:
 * - Style compression is internal (no public option).
 * - Icon fonts are always embedded; `embedFonts` controls non-icon fonts only.
 * - This file preserves backward compatibility with earlier 1.9.x defs.
 */

/* =========================
 * Basic MIME / type aliases
 * ========================= */

export type RasterMime = "png" | "jpg" | "jpeg" | "webp";
export type BlobType = "svg" | RasterMime;

export type IconFontMatcher = string | RegExp;
export type CachePolicy = "disabled" | "full" | "auto" | "soft";

/* =========================
 * Font & proxy declarations
 * ========================= */

export interface LocalFont {
  family: string;
  src: string;            // URL or data: URL
  weight?: string | number;
  style?: string;
}

export interface ExcludeFonts {
  /** Case-insensitive family names to skip (non-icon only). */
  families?: string[];
  /** Host substrings to skip (e.g., "fonts.gstatic.com"). */
  domains?: string[];
  /** Unicode-range subset tags to skip (e.g., "cyrillic-ext"). */
  subsets?: string[];
}

/* =========================
 * Capture options
 * ========================= */

export interface SnapdomOptions {
  /** Fast path: skip small idle delays where safe. */
  fast?: boolean;
  /** Output scale multiplier. Takes precedence over width/height. */
  scale?: number;
  /** Device pixel ratio to use for rasterization (defaults to `devicePixelRatio`). */
  dpr?: number;
  /** Target width of the export (keeps aspect if only one dimension is provided). */
  width?: number;
  /** Target height of the export (keeps aspect if only one dimension is provided). */
  height?: number;

  /** Background fallback color (used esp. for JPEG). Default "#fff". */
  backgroundColor?: string;
  /** Quality for JPEG/WebP (0..1). Default 1. */
  quality?: number;

  /** Cross-origin proxy prefix (used as a fallback when CORS blocks). */
  useProxy?: string;

  /** Default Blob type for toBlob() when unspecified. */
  type?: BlobType;

  /** CSS selector list to filter nodes. */
  exclude?: string[];
  /** How to apply `exclude` ("hide" keeps layout via visibility:hidden; "remove" drops nodes). Default "hide". */
  excludeMode?: "hide" | "remove";

  /**
   * Custom predicate: return true to keep node, false to exclude.
   * Runs in document order; pairs with `filterMode`.
   */
  filter?: (el: Element) => boolean;
  /** How to apply `filter` ("hide" or "remove"). Default "hide". */
  filterMode?: "hide" | "remove";

  /** outerTransforms the root: remove translate/rotate, keep scale/skew. */
  outerTransforms?: boolean;
  /**
   * Do not expand root bbox for shadows/blur/outline; also strip shadows/outline
   * from the cloned root to get a tight capture box.
   */
  outerShadows?: boolean;

  /** Inline non-icon fonts actually used within the subtree. */
  embedFonts?: boolean;
  /** Provide fonts explicitly to avoid remote discovery. */
  localFonts?: LocalFont[];
  /** Additional matchers for icon font families (strings or regex). */
  iconFonts?: IconFontMatcher | IconFontMatcher[];
  /** Skip specific non-icon fonts (by family/domain/subset). */
  excludeFonts?: ExcludeFonts;

  /**
   * Fallback image when <img> fails to load.
   * Can be a fixed URL or a callback that receives measured dimensions.
   */
  fallbackURL?:
    | string
    | ((dims: { width?: number; height?: number }) => string);

  /** Cache policy for resources and style maps. Default "soft". */
  cache?: CachePolicy;

  /** Show placeholders when resources are missing. Default true. */
  placeholders?: boolean;

  /**
   * Resolve lazy `<picture>` placeholders / `data-src` patterns before clone (default true).
   * Set false to skip; register the `picture-resolver` plugin explicitly if you need overrides while core is off.
   */
  resolvePicturePlaceholders?: boolean;
  /** Fine-tune the built-in picture/lazy resolver (timeout, concurrency, etc.). */
  pictureResolver?: {
    timeout?: number;
    concurrency?: number;
    resolveLazySrc?: boolean;
    silent?: boolean;
  };

  /** Arbitrary plugin configuration at call-site (see PluginUse). */
  plugins?: PluginUse[];
}

/* =========================
 * Capture context (hook state)
 * ========================= */

export interface CaptureContext extends SnapdomOptions {
  /** Input element being captured. */
  element: Element;

  /** Cloned root (detached), available after `beforeClone`/`afterClone`. */
  clone?: HTMLElement | SVGElement | null;

  /** Internal style/class caches (opaque to user). */
  classCSS?: string;
  styleCache?: unknown;
  fontsCSS?: string;
  baseCSS?: string;

  /** Serialized artifacts, available after render. */
  svgString?: string;
  dataURL?: string;

  /** Current export info during beforeExport/afterExport. */
  export?: {
    /** Export key (e.g., "png", "jpeg", "svg", or any custom key). */
    type: string;
    /** Options passed to the exporter. */
    options?: any;
    /** Canonical SVG data URL of this capture. */
    url: string;
  };
}

/* =========================
 * Exporter signatures
 * ========================= */

export type Exporter = (ctx: CaptureContext, opts?: any) => Promise<any>;

/** Map returned by `defineExports`: keys are exposed on the result (e.g., `pdf` → `result.toPdf()` as well as `result['pdf']()`). */
export type ExportMap = Record<string, Exporter>;

/* =========================
 * Plugin system
 * ========================= */

export interface SnapdomPlugin {
  /** Unique name for de-dupe/overrides. */
  name: string;

  /** Hook order follows registration order. All hooks may be async. */
  beforeSnap?(context: CaptureContext): void | Promise<void>;
  beforeClone?(context: CaptureContext): void | Promise<void>;
  afterClone?(context: CaptureContext): void | Promise<void>;
  beforeRender?(context: CaptureContext): void | Promise<void>;
  afterRender?(context: CaptureContext): void | Promise<void>;

  /** Runs before EACH export. */
  beforeExport?(context: CaptureContext): void | Promise<void>;
  /**
   * Runs after EACH export; returning a value will be chained to the next plugin
   * (transform pipeline). If undefined is returned, the prior result is preserved.
   */
  afterExport?(context: CaptureContext, result: any): any | Promise<any>;

  /**
   * Provide custom exporters (e.g., { pdf: async (ctx, opts) => Blob }).
   * Keys are exposed on the capture result as helpers (toPdf()) and as index access (result['pdf']()).
   */
  defineExports?(context: CaptureContext): ExportMap | Promise<ExportMap>;

  /** Runs ONCE after the FIRST successful export of this capture (good for cleanup). */
  afterSnap?(context: CaptureContext): void | Promise<void>;
}

export type PluginFactory = (options?: any) => SnapdomPlugin;
/** You can pass a plugin instance, a factory, or a tuple with options. */
export type PluginUse =
  | SnapdomPlugin
  | PluginFactory
  | [PluginFactory, any]
  | { plugin: PluginFactory; options?: any };

/* =========================
 * Capture result API
 * ========================= */

export interface DownloadOptions {
  filename?: string;
  /** Override default blob type for this download. */
  type?: BlobType;
  /** Quality hint for raster formats. */
  quality?: number;
  /** Target width/height for this export. */
  width?: number;
  height?: number;
}

export interface BlobOptions {
  type?: BlobType;
  quality?: number;
  width?: number;
  height?: number;
}

export interface CaptureResult {
  /** Canonical data URL of the SVG snapshot (when available). */
  url: string;

  /**
   * @deprecated Use `toSvg()` for an <img> that renders the SVG snapshot.
   * Historical alias kept for compatibility.
   */
  toImg(): Promise<HTMLImageElement>;

  /** Returns an HTMLImageElement that renders the SVG snapshot. */
  toSvg(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;

  /** Returns a Canvas with the rasterized snapshot. */
  toCanvas(options?: Partial<SnapdomOptions>): Promise<HTMLCanvasElement>;

  /** Returns a Blob of the chosen type (svg/png/jpeg/webp). */
  toBlob(options?: BlobOptions & Partial<SnapdomOptions>): Promise<Blob>;

  /** Convenience raster exports returning an HTMLImageElement. */
  toPng(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
  toJpeg(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
  /** Alias for `toJpeg()`. */
  toJpg(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;
  toWebp(options?: Partial<SnapdomOptions>): Promise<HTMLImageElement>;

  /** Trigger a client-side download of the snapshot using current/default settings. */
  download(options?: DownloadOptions & Partial<SnapdomOptions>): Promise<void>;

  /**
   * Custom exporters exposed by plugins:
   * - As helpers: a plugin returning { pdf: (...) => ... } also enables result.toPdf(...)
   * - As index access: result["pdf"](...)
   *
   * Since keys are not known ahead of time, we allow index access.
   */
  [key: string]: any;
}

/* =========================
 * Main callable & static helpers
 * ========================= */

/** Overload: main callable returns a reusable exporter object for the element. */
export declare function snapdom(
  element: Element,
  options?: SnapdomOptions
): Promise<CaptureResult>;

/**
 * Global plugin registration (chainable).
 * - De-duplicates by `name`.
 * - Execution order = registration order.
 * - Per-capture plugins run before globals and override by `name`.
 */
export declare namespace snapdom {
  function plugins(...defs: PluginUse[]): typeof snapdom;

  /** Shortcut helpers that run a one-off capture+export. */

  /** @deprecated Returns an SVG <img>; prefer `toSvg`. */
  function toImg(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLImageElement>;

  function toSvg(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLImageElement>;

  function toCanvas(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLCanvasElement>;

  function toBlob(
    element: Element,
    options?: SnapdomOptions & BlobOptions
  ): Promise<Blob>;

  function toPng(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLImageElement>;

  function toJpeg(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLImageElement>;

  /** Alias for `toJpeg`. */
  function toJpg(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLImageElement>;

  function toWebp(
    element: Element,
    options?: SnapdomOptions
  ): Promise<HTMLImageElement>;

  function download(
    element: Element,
    options?: SnapdomOptions & DownloadOptions
  ): Promise<void>;
}

/* =========================
 * preCache helper
 * ========================= */

export interface PreCacheOptions {
  /** Root to scan (defaults to `document`). */
  root?: Element | Document;
  /** Try to embed non-icon fonts used under root (see also localFonts). */
  embedFonts?: boolean;
  /** Provide fonts explicitly to avoid remote discovery. */
  localFonts?: LocalFont[];
  /** Additional matchers for icon fonts (strings or regex). */
  iconFonts?: IconFontMatcher | IconFontMatcher[];
  /** Cross-origin proxy prefix (as in SnapdomOptions.useProxy). */
  useProxy?: string;
  /** Cache policy for this preload operation. */
  cache?: CachePolicy;

  /** Back-compat fields (no-ops if present) */
  /**
   * @deprecated Use `cache` instead.
   */
  cacheOpt?: CachePolicy;
}

/**
 * Preload external resources for a subtree to avoid first-capture stalls.
 * Uses the same discovery heuristics as the main capture path.
 */
export declare function preCache(
  root?: Element | Document,
  options?: PreCacheOptions
): Promise<void>;

export {};