@5even7/dlc-ui 0.2.17 → 0.2.19

package/types/index.d.ts

@@ -1,417 +1,581 @@
-export type Quality = 'auto' | 'low' | 'medium' | 'high';
-export type PowerPreference = 'default' | 'high-performance' | 'low-power';
-export type ColorTuple = [string, string, string, string];
-
-export type MiaoPartColorKey =
-  | 'leftEye'
-  | 'rightEye'
-  | 'mouth'
-  | 'mouthFill'
-  | 'sleepBreath'
-  | 'shuttlecock'
-  | 'meditationFigure'
-  | 'meditationBubble'
-  | 'musicNotes'
-  | 'leftEyeOverlay'
-  | 'questionMark'
-  | 'leftBlush'
-  | 'rightBlush'
-  | 'sighBreath'
-  | 'particles';
-
-/**
- * Per-part color overrides for a Miao emoji. Values are any CSS color
- * (#fff / #rrggbb / named / rgb() / rgba(), alpha ignored); null or missing
- * keys keep the asset's original color, and keys the current animation does
- * not support are ignored.
- */
-export type MiaoPartColors = Partial<Record<MiaoPartColorKey, string | null>>;
-
-export interface CapsulePreset {
-  id: string;
-  code: string;
-  name: string;
-  group: 'warm' | 'cold';
-  theme?: 'light' | 'dark';
-  subtitle?: string;
-  seed: number;
-  speed: number;
-  colors: ColorTuple;
-}
-
-export interface ProgressPreset {
-  id: string;
-  code: string;
-  name: string;
-  group: 'progress';
-  subtitle?: string;
-  initialProgress: number;
-  edgeStyle: 'flow' | 'tide';
-  colors: ColorTuple;
-}
-
-export interface EmoPreset {
-  type: string;
-  name: string;
-  label: string;
-  category: string;
-  width: number;
-  height: number;
-  frames: number;
-  fps: number;
-}
-
-export interface EmoTypeDefinition {
-  type: string;
-  label: string;
-  names: string[];
-  partColors: string[];
-}
-
-export interface Copy {
-  brandName: string;
-  valueSuffix: string;
-  progressAria: string;
-  capsuleAria: string;
-}
-
-export interface CapsuleOptions {
-  preset?: string;
-  width?: number | string;
-  height?: number | string;
-  colors?: string[];
-  seed?: number;
-  speed?: number;
-  textRatio?: number;
-  text?: string | Node | Node[];
-  colorContent?: string | Node | Node[];
-  label?: string;
-  mouseColor?: boolean;
-  renderer?: 'auto' | 'webgl2' | 'canvas2d';
-  quality?: Quality;
-  renderScale?: number;
-  powerPreference?: PowerPreference;
-  fps?: number;
-  paused?: boolean;
-  static?: boolean;
-  respectReducedMotion?: boolean;
-  cssVars?: Record<string, string>;
-  [key: string]: unknown;
-}
-
-export interface ProgressOptions {
-  preset?: string;
-  width?: number | string;
-  height?: number | string;
-  value?: number;
-  modelValue?: number;
-  min?: number;
-  max?: number;
-  step?: number | 'any';
-  draggable?: boolean;
-  keyboard?: boolean;
-  disabled?: boolean;
-  readonly?: boolean;
-  valueSuffix?: string;
-  precision?: number;
-  formatValue?: (value: number, context: { min: number; max: number; suffix: string }) => string;
-  direction?: 'ltr' | 'rtl';
-  edgeStyle?: 'flow' | 'tide';
-  colors?: string[];
-  textRatio?: number;
-  text?: string | Node | Node[];
-  colorContent?: string | Node | Node[];
-  label?: string;
-  showValue?: boolean;
-  renderer?: 'auto' | 'webgl2' | 'canvas2d';
-  quality?: Quality;
-  renderScale?: number;
-  powerPreference?: PowerPreference;
-  fps?: number;
-  paused?: boolean;
-  static?: boolean;
-  respectReducedMotion?: boolean;
-  cssVars?: Record<string, string>;
-  [key: string]: unknown;
-}
-
-export interface ColorBackgroundOptions {
-  preset?: string;
-  colors?: string[];
-  seed?: number;
-  speed?: number;
-  renderer?: 'auto' | 'webgl2' | 'canvas2d';
-  quality?: Quality;
-  renderScale?: number;
-  powerPreference?: PowerPreference;
-  fps?: number;
-  paused?: boolean;
-  static?: boolean;
-  mouseColor?: boolean;
-  respectReducedMotion?: boolean;
-  opacity?: number;
-  fallbackColor?: boolean | string;
-  [key: string]: unknown;
-}
-
-export interface EmoOptions {
-  type?: string;
-  name?: string;
-  width?: number | string;
-  height?: number | string;
-  partColors?: MiaoPartColors;
-  speed?: number;
-  loop?: boolean;
-  autoplay?: boolean;
-  direction?: 'forward' | 'reverse' | 1 | -1;
-  opacity?: number;
-  fit?: 'contain' | 'cover' | 'fill';
-  renderer?: 'svg' | 'canvas';
-  paused?: boolean;
-  segment?: [number, number] | null;
-  background?: string;
-  label?: string;
-  instanceName?: string;
-  respectReducedMotion?: boolean;
-  [key: string]: unknown;
-}
-
-export interface Emitter {
-  on(event: string, handler: (...args: any[]) => void): () => void;
-  off(event: string, handler: (...args: any[]) => void): boolean;
-}
-
-export interface CapsuleController extends Emitter {
-  element: HTMLElement;
-  canvas: HTMLCanvasElement;
-  preset: CapsulePreset;
-  setPreset(ref: string): this;
-  setColors(colors: string[]): this;
-  setSeed(seed: number): this;
-  setSpeed(speed: number): this;
-  setMouseColor(value: boolean): this;
-  setText(content: string | Node | Node[]): this;
-  setColorContent(content: string | Node | Node[]): this;
-  setTextRatio(ratio: number): this;
-  setCssVars(vars: Record<string, string>): this;
-  setLabel(label: string): this;
-  setSize(width?: number | string, height?: number | string): this;
-  randomize(): this;
-  pause(): this;
-  resume(): this;
-  setQuality(quality: Quality): this;
-  setRenderScale(value: number): this;
-  setPaused(value: boolean): this;
-  setStatic(value: boolean): this;
-  setFps(value: number): this;
-  readonly paused: boolean;
-  readonly static: boolean;
-  readonly fps: number;
-  readonly quality: Quality;
-  readonly renderScale: number;
-  readonly mouseColor: boolean;
-  dispose(): void;
-}
-
-export interface ProgressController extends Emitter {
-  element: HTMLElement;
-  canvas: HTMLCanvasElement;
-  preset: ProgressPreset;
-  setValue(value: number, source?: string): this;
-  getValue(): number;
-  setRange(min: number, max: number): this;
-  setStep(step: number | 'any'): this;
-  setPreset(ref: string): this;
-  setColors(colors: string[]): this;
-  setEdgeStyle(style: 'flow' | 'tide'): this;
-  setText(content: string | Node | Node[]): this;
-  setColorContent(content: string | Node | Node[]): this;
-  setTextRatio(ratio: number): this;
-  setCssVars(vars: Record<string, string>): this;
-  setLabel(label: string): this;
-  setValueSuffix(suffix: string): this;
-  setPrecision(precision: number): this;
-  setFormatValue(formatter: ProgressOptions['formatValue'] | null): this;
-  setDirection(direction: 'ltr' | 'rtl'): this;
-  setShowValue(show: boolean): this;
-  setSize(width?: number | string, height?: number | string): this;
-  randomize(): this;
-  pause(): this;
-  resume(): this;
-  setQuality(quality: Quality): this;
-  setRenderScale(value: number): this;
-  setPaused(value: boolean): this;
-  setStatic(value: boolean): this;
-  setFps(value: number): this;
-  readonly min: number;
-  readonly max: number;
-  readonly step: number | 'any';
-  readonly precision: number;
-  readonly formatValue: ProgressOptions['formatValue'] | null;
-  readonly direction: 'ltr' | 'rtl';
-  readonly showValue: boolean;
-  readonly valueSuffix: string;
-  readonly paused: boolean;
-  readonly static: boolean;
-  readonly fps: number;
-  readonly quality: Quality;
-  readonly renderScale: number;
-  dispose(): void;
-}
-
-export interface ColorBackgroundController extends Emitter {
-  element: HTMLElement;
-  layer: HTMLElement;
-  canvas: HTMLCanvasElement;
-  preset: CapsulePreset;
-  setPreset(ref: string): this;
-  setColors(colors: string[]): this;
-  setSeed(seed: number): this;
-  setSpeed(speed: number): this;
-  setFallbackColor(value: boolean | string): this;
-  setMouseColor(value: boolean): this;
-  setQuality(quality: Quality): this;
-  setRenderScale(value: number): this;
-  setPaused(value: boolean): this;
-  setStatic(value: boolean): this;
-  setFps(value: number): this;
-  setOpacity(value: number): this;
-  randomize(): this;
-  pause(): this;
-  resume(): this;
-  dispose(): void;
-  readonly paused: boolean;
-  readonly static: boolean;
-  readonly fps: number;
-  readonly quality: Quality;
-  readonly renderScale: number;
-  readonly opacity: number;
-  readonly fallbackColor: boolean | string;
-  readonly mouseColor: boolean;
-}
-
-export interface EmoController extends Emitter {
-  element: HTMLElement;
-  readonly animation: any;
-  readonly preset: EmoPreset;
-  play(): this;
-  pause(): this;
-  stop(): this;
-  setPaused(value: boolean): this;
-  setSpeed(value: number): this;
-  setDirection(value: EmoOptions['direction']): this;
-  setSegment(value: EmoOptions['segment']): this;
-  setName(value: string): this;
-  setType(value: string): this;
-  setPartColors(value: MiaoPartColors): this;
-  setOpacity(value: number): this;
-  setBackground(value: string): this;
-  setSize(width?: number | string, height?: number | string): this;
-  setFit(value: EmoOptions['fit']): this;
-  setRenderer(value: EmoOptions['renderer']): this;
-  setLoop(value: boolean): this;
-  setAutoplay(value: boolean): this;
-  setLabel(value: string): this;
-  dispose(): void;
-  readonly speed: number;
-  readonly loop: boolean;
-  readonly autoplay: boolean;
-  readonly direction: 1 | -1;
-  readonly opacity: number;
-  readonly fit: 'contain' | 'cover' | 'fill';
-  readonly renderer: 'svg' | 'canvas';
-  readonly paused: boolean;
-  readonly segment: [number, number] | null;
-  readonly partColors: MiaoPartColors;
-  readonly background: string;
-}
-
-export declare class ProgressCapsuleController {
-  value: number;
-  min: number;
-  max: number;
-  step: number | 'any';
-  webglActive: boolean;
-  setProgress(nextValue: number, source?: string): boolean;
-  setRange(min: number, max: number): this;
-  setStep(step: number | 'any'): this;
-  setPrecision(precision: number): this;
-  setFormatValue(formatter: ProgressOptions['formatValue'] | null): this;
-  setDirection(direction: 'ltr' | 'rtl'): this;
-  setValueSuffix(suffix: string): this;
-  setShowValue(show: boolean): this;
-  update(delta: number, paused: boolean, now: number): void;
-  draw(): void;
-  randomize(): number;
-  dispose(): void;
-}
-
-export declare function createCapsule(container: HTMLElement, options?: CapsuleOptions): CapsuleController;
-export declare function createProgressCapsule(container: HTMLElement, options?: ProgressOptions): ProgressController;
-export declare function createColorBackground(host: HTMLElement, options?: ColorBackgroundOptions): ColorBackgroundController;
-export declare function createEmo(container: HTMLElement, options?: EmoOptions): EmoController;
-
-export declare const PRESETS: CapsulePreset[];
-export declare const PROGRESS_PRESETS: ProgressPreset[];
-export declare const ALL_PRESETS: Array<CapsulePreset | ProgressPreset>;
-export declare function getPreset(kind: 'capsule' | 'progress', ref: string): CapsulePreset | ProgressPreset;
-export declare const EMO_TYPES: EmoTypeDefinition[];
-export declare const EMO_PRESETS: EmoPreset[];
-export declare const EMO_CATEGORIES: Record<string, string>;
-export declare function getEmoPreset(type?: string, name?: string): EmoPreset;
-export declare function getEmoAnimation(type?: string, name?: string): any;
-
-export declare const DEFAULTS: {
-  capsule: Required<Pick<CapsuleOptions, 'width' | 'height' | 'quality' | 'respectReducedMotion' | 'mouseColor' | 'renderer' | 'textRatio' | 'renderScale' | 'powerPreference' | 'fps' | 'paused' | 'static'>>;
-  progress: Required<Pick<ProgressOptions, 'width' | 'height' | 'min' | 'max' | 'step' | 'draggable' | 'keyboard' | 'disabled' | 'readonly' | 'direction' | 'precision' | 'valueSuffix' | 'edgeStyle' | 'quality' | 'respectReducedMotion' | 'renderer' | 'textRatio' | 'showValue' | 'renderScale' | 'powerPreference' | 'fps' | 'paused' | 'static'>>;
-  emo: Required<Pick<EmoOptions, 'type' | 'name' | 'width' | 'height' | 'partColors' | 'speed' | 'loop' | 'autoplay' | 'direction' | 'opacity' | 'fit' | 'renderer' | 'paused' | 'background' | 'respectReducedMotion'>> & Pick<EmoOptions, 'segment'>;
-};
-
-export declare const COPY: Copy;
-export declare function parseSize(value: number | string): string;
-export declare const QUALITY_TIERS: Record<'low' | 'medium' | 'high', { dpr: number }>;
-export declare function dprCapFor(quality: Quality): number;
-export declare function effectiveDprCap(quality: Quality, renderScale?: number): number;
-export declare function pauseAll(): void;
-export declare function resumeAll(): void;
-export declare function hexToRgb01(hex: string): [number, number, number];
-export declare function hexToRgba(hex: string, alpha?: number): string;
-export declare function normalizeColor(color: string): string | null;
-export declare function validateColors(colors: unknown): boolean;
-
-export declare class CosmicRenderer {
-  constructor(canvas: HTMLCanvasElement, preset: CapsulePreset, options?: {
-    dprCap?: number;
-    mouseColor?: boolean;
-    eventTarget?: HTMLElement;
-    powerPreference?: PowerPreference;
-    onContextLost?: (event: Event) => void;
-    onContextRestored?: () => void;
-  });
-  draw(elapsedSeconds: number, paused?: boolean): void;
-  setPreset(preset: CapsulePreset): void;
-  setDprCap(cap: number): void;
-  randomize(): void;
-  resize(): void;
-  dispose(): void;
-}
-
-export declare class FallbackRenderer {
-  constructor(canvas: HTMLCanvasElement, preset: CapsulePreset, options?: { dprCap?: number });
-  draw(elapsedSeconds: number): void;
-  setPreset(preset: CapsulePreset): void;
-  setDprCap(cap: number): void;
-  resize(): void;
-  dispose(): void;
-}
-
-export declare class ProgressFlowRenderer {
-  constructor(canvas: HTMLCanvasElement, preset: ProgressPreset, options?: {
-    powerPreference?: PowerPreference;
-    onContextLost?: (event: Event) => void;
-    onContextRestored?: () => void;
-  });
-  draw(time: number, progress: number, effectImage?: CanvasImageSource | null): void;
-  resize(width: number, height: number, dpr: number): void;
-  dispose(): void;
-}
+export type Quality = 'auto' | 'low' | 'medium' | 'high';
+export type PowerPreference = 'default' | 'high-performance' | 'low-power';
+export type ColorTuple = [string, string, string, string];
+
+export type MiaoPartColorKey =
+  | 'leftEye'
+  | 'rightEye'
+  | 'mouth'
+  | 'mouthFill'
+  | 'sleepBreath'
+  | 'shuttlecock'
+  | 'meditationFigure'
+  | 'meditationBubble'
+  | 'musicNotes'
+  | 'leftEyeOverlay'
+  | 'questionMark'
+  | 'leftBlush'
+  | 'rightBlush'
+  | 'sighBreath'
+  | 'particles';
+
+/**
+ * Per-part color overrides for a Miao emoji. Values are any CSS color
+ * (#fff / #rrggbb / named / rgb() / rgba(), alpha ignored); null or missing
+ * keys keep the asset's original color, and keys the current animation does
+ * not support are ignored.
+ */
+export type MiaoPartColors = Partial<Record<MiaoPartColorKey, string | null>>;
+
+export type EmoType = 'miao' | 'grok';
+export type EmoEngine = 'lottie' | 'grok';
+
+export type GrokPartColorKey = 'body' | 'eyes';
+
+/**
+ * Per-part color overrides for a Grok emoji. Values are any CSS color;
+ * null or missing keys keep the original color.
+ */
+export type GrokPartColors = Partial<Record<GrokPartColorKey, string | null>>;
+
+export type EmoPartColors = MiaoPartColors | GrokPartColors;
+
+export type GrokShape =
+  | 'blob'
+  | 'pebble'
+  | 'squircle'
+  | 'capsule'
+  | 'triangle'
+  | 'hex'
+  | 'cloud'
+  | 'drop';
+
+export type MiaoName =
+  | 'angry'
+  | 'cry'
+  | 'sad'
+  | 'sigh'
+  | 'investigate'
+  | 'mute'
+  | 'ponder'
+  | 'question'
+  | 'static'
+  | 'asleep'
+  | 'yawn'
+  | 'badminton'
+  | 'confident'
+  | 'laugh'
+  | 'leisure'
+  | 'music'
+  | 'smile'
+  | 'yummy'
+  | 'mock'
+  | 'shy'
+  | 'snigger'
+  | 'panic'
+  | 'shocked';
+
+export type GrokName =
+  | 'sleeping'
+  | 'idle'
+  | 'listening'
+  | 'thinking'
+  | 'searching'
+  | 'working'
+  | 'happy'
+  | 'surprised'
+  | 'angry'
+  | 'sad'
+  | 'loading'
+  | 'confused'
+  | 'receiving';
+
+/**
+ * Grok state presentation categories. Only organizes Docs / Playground
+ * display; all 13 public names stay valid regardless of category.
+ */
+export type GrokStateCategory = 'emotion' | 'agent' | 'lifecycle';
+
+/**
+ * Presentation metadata for one Grok state. A Grok `name` is a dynamic state
+ * module (expression pool + cadence + blink + body motion), so its static
+ * first frame may look similar to other states even when the dynamics differ.
+ */
+export interface GrokStateMeta {
+  category: GrokStateCategory;
+  /** Chinese display name. */
+  label: string;
+  /** Short usage note shown on Docs cards. */
+  description?: string;
+  /** 'upstream' = ported from LaoA-GrokBot; 'dlc' reserved for DLC extensions. */
+  source: 'upstream' | 'dlc';
+}
+
+export interface GrokCategoryDef {
+  key: GrokStateCategory;
+  label: string;
+}
+
+export interface EmoPreviewCardOptions {
+  container: HTMLElement;
+  options: EmoOptions;
+  /** Auto-pause after this many ms of preview (default 2800). */
+  playFor?: number;
+  /** Keep the card static when the user prefers reduced motion (default true). */
+  respectReducedMotion?: boolean;
+  /** Pause the preview when the card leaves the viewport (default false). */
+  trackViewport?: boolean;
+}
+
+export interface EmoPreviewCardController {
+  element: HTMLElement;
+  controller: EmoController;
+  start(): void;
+  stop(): void;
+  setViewportVisible(visible: boolean): void;
+  dispose(): void;
+}
+
+export interface CapsulePreset {
+  id: string;
+  code: string;
+  name: string;
+  group: 'warm' | 'cold';
+  theme?: 'light' | 'dark';
+  subtitle?: string;
+  seed: number;
+  speed: number;
+  colors: ColorTuple;
+}
+
+export interface ProgressPreset {
+  id: string;
+  code: string;
+  name: string;
+  group: 'progress';
+  subtitle?: string;
+  initialProgress: number;
+  edgeStyle: 'flow' | 'tide';
+  colors: ColorTuple;
+}
+
+export interface EmoPreset {
+  type: EmoType;
+  name: string;
+  label: string;
+  category: string;
+  width: number;
+  height: number;
+  engine: EmoEngine;
+  frames?: number;
+  fps?: number;
+}
+
+export interface EmoTypeDefinition {
+  type: EmoType;
+  label: string;
+  defaultName: string;
+  engine: EmoEngine;
+  names: string[];
+  partColors: string[];
+  shapes?: string[];
+}
+
+export interface Copy {
+  brandName: string;
+  valueSuffix: string;
+  progressAria: string;
+  capsuleAria: string;
+}
+
+export interface CapsuleOptions {
+  preset?: string;
+  width?: number | string;
+  height?: number | string;
+  colors?: string[];
+  seed?: number;
+  speed?: number;
+  textRatio?: number;
+  text?: string | Node | Node[];
+  colorContent?: string | Node | Node[];
+  label?: string;
+  mouseColor?: boolean;
+  renderer?: 'auto' | 'webgl2' | 'canvas2d';
+  quality?: Quality;
+  renderScale?: number;
+  powerPreference?: PowerPreference;
+  fps?: number;
+  paused?: boolean;
+  static?: boolean;
+  respectReducedMotion?: boolean;
+  cssVars?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface ProgressOptions {
+  preset?: string;
+  width?: number | string;
+  height?: number | string;
+  value?: number;
+  modelValue?: number;
+  min?: number;
+  max?: number;
+  step?: number | 'any';
+  draggable?: boolean;
+  keyboard?: boolean;
+  disabled?: boolean;
+  readonly?: boolean;
+  valueSuffix?: string;
+  precision?: number;
+  formatValue?: (value: number, context: { min: number; max: number; suffix: string }) => string;
+  direction?: 'ltr' | 'rtl';
+  edgeStyle?: 'flow' | 'tide';
+  colors?: string[];
+  textRatio?: number;
+  text?: string | Node | Node[];
+  colorContent?: string | Node | Node[];
+  label?: string;
+  showValue?: boolean;
+  renderer?: 'auto' | 'webgl2' | 'canvas2d';
+  quality?: Quality;
+  renderScale?: number;
+  powerPreference?: PowerPreference;
+  fps?: number;
+  paused?: boolean;
+  static?: boolean;
+  respectReducedMotion?: boolean;
+  cssVars?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+export interface ColorBackgroundOptions {
+  preset?: string;
+  colors?: string[];
+  seed?: number;
+  speed?: number;
+  renderer?: 'auto' | 'webgl2' | 'canvas2d';
+  quality?: Quality;
+  renderScale?: number;
+  powerPreference?: PowerPreference;
+  fps?: number;
+  paused?: boolean;
+  static?: boolean;
+  mouseColor?: boolean;
+  respectReducedMotion?: boolean;
+  opacity?: number;
+  fallbackColor?: boolean | string;
+  [key: string]: unknown;
+}
+
+export interface EmoCommonOptions {
+  width?: number | string;
+  height?: number | string;
+  speed?: number;
+  loop?: boolean;
+  autoplay?: boolean;
+  paused?: boolean;
+  opacity?: number;
+  fit?: 'contain' | 'cover' | 'fill';
+  background?: string;
+  label?: string;
+  instanceName?: string;
+  respectReducedMotion?: boolean;
+  [key: string]: unknown;
+}
+
+export interface MiaoEmoOptions extends EmoCommonOptions {
+  type?: 'miao';
+  name?: MiaoName;
+  partColors?: MiaoPartColors;
+  renderer?: 'svg' | 'canvas';
+  direction?: 'forward' | 'reverse' | 1 | -1;
+  segment?: [number, number] | null;
+}
+
+export interface GrokEmoOptions extends EmoCommonOptions {
+  type: 'grok';
+  name?: GrokName;
+  partColors?: GrokPartColors;
+  shape?: GrokShape;
+  interactive?: boolean;
+}
+
+export type EmoOptions = MiaoEmoOptions | GrokEmoOptions;
+
+export interface Emitter {
+  on(event: string, handler: (...args: any[]) => void): () => void;
+  off(event: string, handler: (...args: any[]) => void): boolean;
+}
+
+export interface CapsuleController extends Emitter {
+  element: HTMLElement;
+  canvas: HTMLCanvasElement;
+  preset: CapsulePreset;
+  setPreset(ref: string): this;
+  setColors(colors: string[]): this;
+  setSeed(seed: number): this;
+  setSpeed(speed: number): this;
+  setMouseColor(value: boolean): this;
+  setText(content: string | Node | Node[]): this;
+  setColorContent(content: string | Node | Node[]): this;
+  setTextRatio(ratio: number): this;
+  setCssVars(vars: Record<string, string>): this;
+  setLabel(label: string): this;
+  setSize(width?: number | string, height?: number | string): this;
+  randomize(): this;
+  pause(): this;
+  resume(): this;
+  setQuality(quality: Quality): this;
+  setRenderScale(value: number): this;
+  setPaused(value: boolean): this;
+  setStatic(value: boolean): this;
+  setFps(value: number): this;
+  readonly paused: boolean;
+  readonly static: boolean;
+  readonly fps: number;
+  readonly quality: Quality;
+  readonly renderScale: number;
+  readonly mouseColor: boolean;
+  dispose(): void;
+}
+
+export interface ProgressController extends Emitter {
+  element: HTMLElement;
+  canvas: HTMLCanvasElement;
+  preset: ProgressPreset;
+  setValue(value: number, source?: string): this;
+  getValue(): number;
+  setRange(min: number, max: number): this;
+  setStep(step: number | 'any'): this;
+  setPreset(ref: string): this;
+  setColors(colors: string[]): this;
+  setEdgeStyle(style: 'flow' | 'tide'): this;
+  setText(content: string | Node | Node[]): this;
+  setColorContent(content: string | Node | Node[]): this;
+  setTextRatio(ratio: number): this;
+  setCssVars(vars: Record<string, string>): this;
+  setLabel(label: string): this;
+  setValueSuffix(suffix: string): this;
+  setPrecision(precision: number): this;
+  setFormatValue(formatter: ProgressOptions['formatValue'] | null): this;
+  setDirection(direction: 'ltr' | 'rtl'): this;
+  setShowValue(show: boolean): this;
+  setSize(width?: number | string, height?: number | string): this;
+  randomize(): this;
+  pause(): this;
+  resume(): this;
+  setQuality(quality: Quality): this;
+  setRenderScale(value: number): this;
+  setPaused(value: boolean): this;
+  setStatic(value: boolean): this;
+  setFps(value: number): this;
+  readonly min: number;
+  readonly max: number;
+  readonly step: number | 'any';
+  readonly precision: number;
+  readonly formatValue: ProgressOptions['formatValue'] | null;
+  readonly direction: 'ltr' | 'rtl';
+  readonly showValue: boolean;
+  readonly valueSuffix: string;
+  readonly paused: boolean;
+  readonly static: boolean;
+  readonly fps: number;
+  readonly quality: Quality;
+  readonly renderScale: number;
+  dispose(): void;
+}
+
+export interface ColorBackgroundController extends Emitter {
+  element: HTMLElement;
+  layer: HTMLElement;
+  canvas: HTMLCanvasElement;
+  preset: CapsulePreset;
+  setPreset(ref: string): this;
+  setColors(colors: string[]): this;
+  setSeed(seed: number): this;
+  setSpeed(speed: number): this;
+  setFallbackColor(value: boolean | string): this;
+  setMouseColor(value: boolean): this;
+  setQuality(quality: Quality): this;
+  setRenderScale(value: number): this;
+  setPaused(value: boolean): this;
+  setStatic(value: boolean): this;
+  setFps(value: number): this;
+  setOpacity(value: number): this;
+  randomize(): this;
+  pause(): this;
+  resume(): this;
+  dispose(): void;
+  readonly paused: boolean;
+  readonly static: boolean;
+  readonly fps: number;
+  readonly quality: Quality;
+  readonly renderScale: number;
+  readonly opacity: number;
+  readonly fallbackColor: boolean | string;
+  readonly mouseColor: boolean;
+}
+
+export interface EmoController extends Emitter {
+  element: HTMLElement;
+  readonly animation: any;
+  readonly preset: EmoPreset;
+  play(): this;
+  pause(): this;
+  stop(): this;
+  setPaused(value: boolean): this;
+  setSpeed(value: number): this;
+  setDirection(value: MiaoEmoOptions['direction']): this;
+  setSegment(value: [number, number] | null): this;
+  setName(value: string): this;
+  setType(value: EmoType): this;
+  setPartColors(value: EmoPartColors): this;
+  setOpacity(value: number): this;
+  setBackground(value: string): this;
+  setSize(width?: number | string, height?: number | string): this;
+  setFit(value: EmoCommonOptions['fit']): this;
+  setRenderer(value: 'svg' | 'canvas'): this;
+  setLoop(value: boolean): this;
+  setAutoplay(value: boolean): this;
+  setShape(value: GrokShape): this;
+  setInteractive(value: boolean): this;
+  setLabel(value: string): this;
+  dispose(): void;
+  readonly speed: number;
+  readonly loop: boolean;
+  readonly autoplay: boolean;
+  readonly direction: 1 | -1;
+  readonly opacity: number;
+  readonly fit: 'contain' | 'cover' | 'fill';
+  readonly renderer: 'svg' | 'canvas';
+  readonly paused: boolean;
+  readonly segment: [number, number] | null;
+  readonly partColors: EmoPartColors;
+  readonly background: string;
+  readonly shape: GrokShape;
+  readonly interactive: boolean;
+}
+
+export declare class ProgressCapsuleController {
+  value: number;
+  min: number;
+  max: number;
+  step: number | 'any';
+  webglActive: boolean;
+  setProgress(nextValue: number, source?: string): boolean;
+  setRange(min: number, max: number): this;
+  setStep(step: number | 'any'): this;
+  setPrecision(precision: number): this;
+  setFormatValue(formatter: ProgressOptions['formatValue'] | null): this;
+  setDirection(direction: 'ltr' | 'rtl'): this;
+  setValueSuffix(suffix: string): this;
+  setShowValue(show: boolean): this;
+  update(delta: number, paused: boolean, now: number): void;
+  draw(): void;
+  randomize(): number;
+  dispose(): void;
+}
+
+export declare function createCapsule(container: HTMLElement, options?: CapsuleOptions): CapsuleController;
+export declare function createProgressCapsule(container: HTMLElement, options?: ProgressOptions): ProgressController;
+export declare function createColorBackground(host: HTMLElement, options?: ColorBackgroundOptions): ColorBackgroundController;
+export declare function createEmo(container: HTMLElement, options?: EmoOptions): EmoController;
+export declare function createEmoPreviewCard(options: EmoPreviewCardOptions): EmoPreviewCardController;
+
+export {
+  AvatarProviderId,
+  AvatarControl,
+  AvatarStyleDefinition,
+  AvatarProviderDefinition,
+  AvatarOptions,
+  AvatarRenderResult,
+  AvatarState,
+  AvatarController,
+  createAvatarSvg,
+  createAvatarCreator,
+  getStyleDefinitions,
+  getProviders,
+  getProvider,
+  getStyleDefinition,
+  hashSeed,
+  fnv1a,
+  createPrng,
+  escapeXml,
+  applySize,
+  svgToDataUri,
+  sanitizeSvg,
+  cleanText,
+  validateProviderOptions,
+  buildControlsFromSchema
+} from './avatar-creator.js';
+
+export declare const PRESETS: CapsulePreset[];
+export declare const PROGRESS_PRESETS: ProgressPreset[];
+export declare const ALL_PRESETS: Array<CapsulePreset | ProgressPreset>;
+export declare function getPreset(kind: 'capsule' | 'progress', ref: string): CapsulePreset | ProgressPreset;
+export declare const EMO_TYPES: EmoTypeDefinition[];
+export declare const EMO_PRESETS: EmoPreset[];
+export declare const EMO_CATEGORIES: Record<string, string>;
+export declare function getEmoType(type?: string): EmoTypeDefinition;
+export declare function getEmoPreset(type?: string, name?: string): EmoPreset;
+export declare function getEmoAnimation(type?: string, name?: string): any;
+export declare const GROK_CATEGORIES: GrokCategoryDef[];
+export declare const GROK_NAMES: GrokName[];
+export declare const GROK_STATE_META: Record<GrokName, GrokStateMeta>;
+export declare function getGrokNamesFor(tab: GrokStateCategory | 'all' | string): GrokName[];
+export declare function getGrokStateMeta(name: string): GrokStateMeta;
+
+export declare const DEFAULTS: {
+  capsule: Required<Pick<CapsuleOptions, 'width' | 'height' | 'quality' | 'respectReducedMotion' | 'mouseColor' | 'renderer' | 'textRatio' | 'renderScale' | 'powerPreference' | 'fps' | 'paused' | 'static'>>;
+  progress: Required<Pick<ProgressOptions, 'width' | 'height' | 'min' | 'max' | 'step' | 'draggable' | 'keyboard' | 'disabled' | 'readonly' | 'direction' | 'precision' | 'valueSuffix' | 'edgeStyle' | 'quality' | 'respectReducedMotion' | 'renderer' | 'textRatio' | 'showValue' | 'renderScale' | 'powerPreference' | 'fps' | 'paused' | 'static'>>;
+  emo: Required<Pick<EmoCommonOptions, 'width' | 'height' | 'speed' | 'loop' | 'autoplay' | 'paused' | 'opacity' | 'fit' | 'background' | 'respectReducedMotion'>> & Pick<MiaoEmoOptions, 'type' | 'name' | 'partColors' | 'direction' | 'renderer' | 'segment'>;
+};
+
+export declare const COPY: Copy;
+export declare function parseSize(value: number | string): string;
+export declare const QUALITY_TIERS: Record<'low' | 'medium' | 'high', { dpr: number }>;
+export declare function dprCapFor(quality: Quality): number;
+export declare function effectiveDprCap(quality: Quality, renderScale?: number): number;
+export declare function pauseAll(): void;
+export declare function resumeAll(): void;
+export declare function hexToRgb01(hex: string): [number, number, number];
+export declare function hexToRgba(hex: string, alpha?: number): string;
+export declare function normalizeColor(color: string): string | null;
+export declare function validateColors(colors: unknown): boolean;
+
+export declare class CosmicRenderer {
+  constructor(canvas: HTMLCanvasElement, preset: CapsulePreset, options?: {
+    dprCap?: number;
+    mouseColor?: boolean;
+    eventTarget?: HTMLElement;
+    powerPreference?: PowerPreference;
+    onContextLost?: (event: Event) => void;
+    onContextRestored?: () => void;
+  });
+  draw(elapsedSeconds: number, paused?: boolean): void;
+  setPreset(preset: CapsulePreset): void;
+  setDprCap(cap: number): void;
+  randomize(): void;
+  resize(): void;
+  dispose(): void;
+}
+
+export declare class FallbackRenderer {
+  constructor(canvas: HTMLCanvasElement, preset: CapsulePreset, options?: { dprCap?: number });
+  draw(elapsedSeconds: number): void;
+  setPreset(preset: CapsulePreset): void;
+  setDprCap(cap: number): void;
+  resize(): void;
+  dispose(): void;
+}
+
+export declare class ProgressFlowRenderer {
+  constructor(canvas: HTMLCanvasElement, preset: ProgressPreset, options?: {
+    powerPreference?: PowerPreference;
+    onContextLost?: (event: Event) => void;
+    onContextRestored?: () => void;
+  });
+  draw(time: number, progress: number, effectImage?: CanvasImageSource | null): void;
+  resize(width: number, height: number, dpr: number): void;
+  dispose(): void;
+}