/**
 * Runtime registry singleton that controls live vs static behavior.
 * Consumers can call `registry.setDesigner(designer)` to enable live mode
 * or `registry.setStaticMode(paths)` to point to static asset modules.
 */
export interface PDSRegistry {
  /** Attach a designer instance and switch the registry to live mode. */
  setDesigner(designer: any, meta?: { presetName?: string }): void;
  /** Switch to static mode and override static paths (keys: tokens, primitives, components, utilities, styles) */
  setStaticMode(paths?: Record<string, string>): void;
  /** Return a constructable stylesheet for the requested layer or null on failure. */
  getStylesheet(layer: string): Promise<CSSStyleSheet | null>;
  /** Return a BLOB URL (live mode only) for layer imports used in CSS */
  getBlobURL(layer: string): string | null;
  /** 'live' or 'static' */
  readonly mode: string;
  /** true when a live designer instance is registered */
  readonly isLive: boolean;
  /** true when a designer instance exists */
  readonly hasDesigner: boolean;
}

/** A small shape describing component metadata used by the PDS ontology. */
export interface ComponentDef {
  /** canonical name of the component (e.g., 'Button') */
  name: string;
  /** optional HTML tag name for the component ('pds-button') */
  tag?: string;
  /** documented props and their types/metadata */
  props?: Record<string, any>;
  /** human-friendly description used by the designer */
  description?: string;
}

/**
 * Generator - programmatic API to produce tokens, layered CSS and helper modules from a config.
 * Typical usage:
 * const g = new PDS.Generator({ example: true });
 * // tokens may be returned synchronously or via a Promise
 * const tokens = await g.generateTokens?.();
 * const css = await g.generateCSS?.();
 */
export class Generator {
  constructor(options?: any);
  /** runtime options / config passed to the generator */
  options: any;
  /** generated token object */
  tokens: Record<string, any>;
  /** concatenated CSS (layered) */
  css: string;
  /** Generate the token map (may be async in some implementations) */
  generateTokens?(): Record<string, any> | Promise<Record<string, any>>;
  /** Generate the CSS string (may be async) */
  generateCSS?(): string | Promise<string>;
}

/** Public runtime surface exported as `PDS` */
export interface PDSEventMap {
  'pds:ready': CustomEvent<{ mode: 'live' | 'static'; generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
  'pds:error': CustomEvent<{ error: any }>;
  'pds:theme:changed': CustomEvent<{ theme: string; requested?: string; source: 'system' | 'programmatic' }>;
  'pds:design:updated': CustomEvent<{ config: any; designer?: any }>;
  'pds:design:field:changed': CustomEvent<{ field: string; config: any }>;
  'pds:inspector:mode:changed': CustomEvent<{ active: boolean }>;
  'pds:inspector:deactivate': CustomEvent<{}>;
  'pds:docs:view': CustomEvent<{ file: string }>;
}

export const PDS: {
  /** Generator class to produce design-system artifacts programmatically. */
  Generator: typeof Generator;
  /** Registry singleton to query/adopt styles and control live/static behavior. */
  registry: PDSRegistry;
  /** Presets keyed by id (lowercased). Includes a 'default' preset derived from the baseline config. */
  presets: Record<string, any>;
  /** Ontology metadata about components (shapes vary by implementation) */
  ontology: any;
  /** Adopt multiple named layers into a ShadowRoot. See `LAYER-ARCHITECTURE.md` for layer ordering. */
  adoptLayers: (shadowRoot: ShadowRoot, layers?: string[], additionalSheets?: CSSStyleSheet[]) => Promise<void>;
  /** Convenience to adopt only primitives/styles commonly needed by components. */
  adoptPrimitives: (shadowRoot: ShadowRoot, additionalSheets?: CSSStyleSheet[]) => Promise<void>;
  /** Create a constructable stylesheet from a CSS string. May throw on invalid CSS in some browsers. */
  createStylesheet: (css: string) => CSSStyleSheet;
  /** Utility to inspect whether runtime is running in live mode. */
  isLiveMode: () => boolean;
  /** Find a component definition for a given DOM element, or null if not matched. */
  findComponentForElement: (el: Element) => ComponentDef | null;
  /** Primary unified entry point to start PDS in live or static mode. Default mode is 'live'. */
  start: (config: {
    mode?: 'live' | 'static';
    preset?: string;
    design?: any;
    autoDefine?: {
      baseURL?: string;
      predefine?: string[];
  mapper?: (tag: string) => string | undefined | null | false;
      scanExisting?: boolean;
      observeShadows?: boolean;
      patchAttachShadow?: boolean;
      debounceMs?: number;
      onError?: (tag: string, err: any) => void;
    };
    applyGlobalStyles?: boolean;
    manageTheme?: boolean;
    themeStorageKey?: string;
    // live-only
    preloadStyles?: boolean;
    criticalLayers?: string[];
    // static-only
    staticPaths?: Record<string, string>;
    enhancers?: Array<any>;
  }) => Promise<{ generator?: Generator; config: any; theme: string; autoDefiner?: any }>;
  /** Change the current theme programmatically. Updates localStorage, data-theme attribute, and regenerates styles. */
  setTheme: (theme: 'light' | 'dark' | 'system', options?: {
    storageKey?: string;
    persist?: boolean;
  }) => Promise<string>;
  /** Preload minimal CSS to prevent flash of unstyled content. Call before DOM content renders. */
  preloadCritical: (config: any, options?: {
    theme?: string;
    layers?: string[];
  }) => void;
  /** EventTarget API (strongly typed for common PDS events). */
  addEventListener: <K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | AddEventListenerOptions) => void;
  removeEventListener: <K extends keyof PDSEventMap>(type: K, listener: (ev: PDSEventMap[K]) => any, options?: boolean | EventListenerOptions) => void;
  dispatchEvent: (event: PDSEventMap[keyof PDSEventMap] | Event) => boolean;
};

export { PDS as default };