/** A complete token proposal — Tier-2 override of the canonical
 *  `var(--bl-*)` palette. All values are hex strings (#rrggbb).
 *
 *  This is intentionally a flat, JSON-serialisable shape so the
 *  proposal can be persisted, transported via SSE, or stored in the
 *  `platform-service` per-product theme document.
 */
export interface ThemeProposal {
  /** Optional human-readable name (e.g. `'midnight-citrus'`). */
  name?: string;
  /** Required: primary brand accent. */
  accent: string;
  /** Required: page background — paired against `text` for contrast. */
  surface: string;
  /** Required: card / elevated surface. */
  surfaceCard: string;
  /** Required: muted/divider background. */
  surfaceMuted: string;
  /** Required: primary text. Should pass AA against `surface`. */
  textPrimary: string;
  /** Required: secondary / muted text. */
  textSecondary: string;
  /** Optional semantic colours. */
  success?: string;
  warning?: string;
  danger?: string;
  info?: string;
  /** Optional border colour (default derived from `surfaceMuted`). */
  border?: string;
}

export interface ContrastReport {
  /** WCAG ratio `(L1+0.05)/(L2+0.05)` — higher is better. */
  ratio: number;
  /** Passes WCAG AA (≥ 4.5 for normal text). */
  aa: boolean;
  /** Passes WCAG AAA (≥ 7 for normal text). */
  aaa: boolean;
}

export interface ContrastCheck {
  textPrimaryOnSurface: ContrastReport;
  textSecondaryOnSurface: ContrastReport;
  textPrimaryOnSurfaceCard: ContrastReport;
  accentOnSurface: ContrastReport;
}

export interface GenerationOptions {
  /**
   * Optional async hook — host wires its own LLM here. Falls back to
   * the local deterministic generator when absent.
   */
  generate?: (prompt: string) => Promise<ThemeProposal>;
  /**
   * Enforce AAA on text pairings. When violated, the contrast helper
   * darkens / lightens the affected colour until AAA passes (or until
   * we hit the rail at black / white).
   */
  enforce?: 'aa' | 'aaa' | 'off';
}
