@clypra/engine 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,892 @@
+declare const SCENE_VERSION: 1;
+type EffectLayerType = "panel" | "glow" | "shadow" | "extrusion" | "duplicateStack" | "stroke" | "fill" | "mask" | "filter" | "customEngine";
+type LayerTarget = "text" | "panel" | "scene" | "previous";
+type CustomEngineId = "ink";
+declare const CUSTOM_ENGINE_IDS: CustomEngineId[];
+declare const LEGACY_RENDERER_MAP: Record<string, CustomEngineId>;
+declare const ENGINE_ID_TO_LEGACY: Record<CustomEngineId, string>;
+interface SceneCanvas {
+    width: number;
+    height: number;
+    background: string;
+}
+interface SceneText {
+    content: string;
+    fontFamily: string;
+    fontWeight: number;
+    fontStyle: "normal" | "italic";
+    fontSize: number;
+    letterSpacing: number;
+    lineHeight: number;
+    textPosX: "left" | "center" | "right";
+    textPosY: "top" | "middle" | "bottom";
+    wrapText?: boolean;
+    autoFitText?: boolean;
+    perCharFillEnabled?: boolean;
+    charFillColors?: string[];
+}
+interface EffectLayer {
+    id: string;
+    type: EffectLayerType;
+    name: string;
+    enabled: boolean;
+    opacity: number;
+    blendMode: GlobalCompositeOperation;
+    target: LayerTarget;
+    params: Record<string, unknown>;
+}
+interface CompositorSettings {
+    blur: number;
+    bloom: number;
+    bloomThreshold?: number;
+}
+interface Keyframe {
+    time: number;
+    value: number;
+    easing?: "linear" | "easeIn" | "easeOut" | "easeInOut";
+}
+interface AnimTrack {
+    layerId: string;
+    paramPath: string;
+    keyframes: Keyframe[];
+}
+interface Timeline {
+    duration: number;
+    fps: number;
+    loop: boolean;
+    tracks: AnimTrack[];
+}
+interface SceneDocument {
+    version: typeof SCENE_VERSION;
+    effectName: string;
+    canvas: SceneCanvas;
+    text: SceneText;
+    effectLayers: EffectLayer[];
+    customEngineId: CustomEngineId | null;
+    engineParams?: Record<string, unknown>;
+    compositor: CompositorSettings;
+    timeline: Timeline;
+    /** Legacy flat config cache for gradual UI migration */
+    legacyConfig?: TextEffectConfig;
+    /** Deep Research extension snippet (not executed until sandboxed) */
+    extensionCode?: string | null;
+}
+interface StyleRecipe {
+    id: string;
+    name: string;
+    category?: string;
+    layers: EffectLayer[];
+    exposed: string[];
+    tags: string[];
+    customEngineId?: CustomEngineId | null;
+    scene?: SceneDocument;
+}
+declare function createEmptyScene(overrides?: Partial<SceneDocument>): SceneDocument;
+declare function newLayerId(): string;
+
+interface GradientStop {
+    color: string;
+    offset: number;
+}
+interface GlowLayer {
+    enabled: boolean;
+    color: string;
+    blur: number;
+    opacity: number;
+    type: "outer" | "inner";
+    strength?: number;
+    spread?: number;
+}
+interface TextEffectConfig {
+    text: string;
+    effectName: string;
+    fontFamily: string;
+    fontWeight: number;
+    fontStyle: "normal" | "italic";
+    fontSize: number;
+    letterSpacing: number;
+    lineHeight: number;
+    fillType: "solid" | "linear" | "radial" | "pattern" | "none";
+    fillColor: string;
+    fillGradientAngle: number;
+    fillGradientStops: GradientStop[];
+    patternType?: "chalk" | "noise" | "grunge" | "carbon" | "stripes" | "film" | "brushed" | "marble" | "halftone" | "paper";
+    /** Pro: independent solid fill color per visible character (reading order) */
+    perCharFillEnabled?: boolean;
+    charFillColors?: string[];
+    strokeEnabled: boolean;
+    strokeColor: string;
+    strokeWidth: number;
+    strokePosition: "outside" | "center" | "inside";
+    strokeOpacity: number;
+    strokeLineJoin: "round" | "miter" | "bevel";
+    strokeBlur?: number;
+    strokeType?: "single" | "double" | "neon";
+    strokeColorSecondary?: string;
+    strokeWidthSecondary?: number;
+    strokeFadeRange?: number;
+    glowLayers: GlowLayer[];
+    shadowEnabled: boolean;
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowOpacity: number;
+    shadowType: "drop" | "inner";
+    bevelEnabled: boolean;
+    bevelDepth: number;
+    bevelHighlight: string;
+    bevelShadow: string;
+    bevelDirection: "bottom-right" | "bottom" | "right";
+    bevelCoreColor?: string;
+    bevelEdgeColor?: string;
+    bevelEdgeWidth?: number;
+    bevelBlur?: number;
+    bevelBlurColor?: string;
+    bevelPerspectiveEnabled?: boolean;
+    bevelVanishingPointX?: number;
+    bevelVanishingPointY?: number;
+    bevelFocalLength?: number;
+    stackEnabled?: boolean;
+    stackCount?: number;
+    stackOffsetX?: number;
+    stackOffsetY?: number;
+    stackOpacityDecay?: number;
+    stackColor1?: string;
+    stackColor2?: string;
+    stackColor3?: string;
+    stackColor4?: string;
+    panelEnabled: boolean;
+    panelColor: string;
+    panelOpacity: number;
+    panelRadius: number;
+    panelPaddingX: number;
+    panelPaddingY: number;
+    panelStrokeEnabled: boolean;
+    panelStrokeColor: string;
+    panelStrokeWidth: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    textPosX: "left" | "center" | "right";
+    textPosY: "top" | "middle" | "bottom";
+    /** Scale type to fit safe area inside canvas */
+    autoFitText?: boolean;
+    /** Wrap long lines to composition safe width */
+    wrapText?: boolean;
+    inkColor?: string;
+    bristleDensity?: number;
+    bristleSkipRate?: number;
+    dripRate?: number;
+    dripMaxLength?: number;
+    grainDensity?: number;
+    skewX?: number;
+    customRenderer?: string;
+}
+interface Preset {
+    id: string;
+    name: string;
+    config: TextEffectConfig;
+    /** Cached scene graph (optional; built-ins use recipes cache) */
+    scene?: SceneDocument;
+    isCustom?: boolean;
+    category?: "3d" | "Neon" | "Metallic" | "Glitch" | "Retro" | "Gradient" | "Grunge" | "Outline" | "Shadow" | "Elements" | "Luxury" | "Classic" | "Experimental" | string;
+    createdAt?: number;
+}
+
+declare function renderTextEffectCore(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, cfg: TextEffectConfig): void;
+declare class TextEffectRenderer {
+    static draw(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, cfg: TextEffectConfig, _time?: number): void;
+}
+
+/** Style recipes (layer graphs): see `builtInRecipes` in src/engine/recipes.ts */
+declare const defaultConfig: TextEffectConfig;
+declare const builtInPresets: Preset[];
+
+/**
+ * Font Loader for Lottie-web
+ *
+ * This module ensures that font variant names (like "Poppins-Italic") work correctly
+ * with lottie-web by dynamically creating @font-face rules that map variant names
+ * to the actual loaded fonts with proper styling.
+ */
+interface FontVariant {
+    variantName: string;
+    baseFontFamily: string;
+    weight: number;
+    style: "normal" | "italic";
+}
+/**
+ * Injects @font-face rules dynamically to create font variant aliases
+ * This ensures lottie-web can find fonts by their variant names
+ */
+declare function injectFontVariantRules(): void;
+/**
+ * Waits for base fonts to load, then injects variant rules
+ */
+declare function initializeFontSystem(): Promise<void>;
+/**
+ * Checks if a font variant is available for rendering
+ */
+declare function checkFontVariant(variantName: string): boolean;
+
+declare function resolveCustomEngineId(cfg: TextEffectConfig): CustomEngineId | null;
+/** Lossless migration from flat TextEffectConfig to SceneDocument */
+declare function textEffectConfigToScene(cfg: TextEffectConfig): SceneDocument;
+/** Flatten SceneDocument back to TextEffectConfig for legacy controls and renderer */
+declare function sceneToConfig(doc: SceneDocument): TextEffectConfig;
+declare function syncCompositorFromScene(doc: SceneDocument): CompositorFromScene;
+interface CompositorFromScene {
+    blur: number;
+    bloom: number;
+    bloomThreshold: number;
+}
+/** Apply engine params from scene onto config without require() */
+declare function mergeSceneIntoConfig(doc: SceneDocument, base: TextEffectConfig): TextEffectConfig;
+
+declare class WebGLCompositor {
+    private gl;
+    private program;
+    private vao;
+    private texture;
+    readonly isSupported: boolean;
+    constructor();
+    private initProgram;
+    private compileShader;
+    renderToContext(targetCtx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, source: HTMLCanvasElement | OffscreenCanvas, settings: CompositorSettings): void;
+    dispose(): void;
+}
+
+interface EvaluateOptions {
+    compositor?: WebGLCompositor | null;
+    skipPostFx?: boolean;
+}
+/**
+ * Single source of truth for rendering a scene at time t.
+ */
+declare function evaluateScene(doc: SceneDocument, time: number, ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, options?: EvaluateOptions): void;
+declare function evaluateConfig(cfg: TextEffectConfig, time: number, ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, options?: EvaluateOptions): void;
+declare function advanceSceneTime(doc: SceneDocument, steps: number): number;
+declare function getSceneTime(doc: SceneDocument): number;
+declare function setSceneTime(doc: SceneDocument, time: number): void;
+declare function resetSceneTime(doc: SceneDocument): void;
+
+declare function ease(t: number, kind?: Keyframe["easing"]): number;
+/** Resolve animated scalar at time (seconds) */
+declare function resolveAnimatedScalar(doc: SceneDocument, layerId: string, paramPath: string, baseValue: number, time: number): number;
+/** Apply timeline to scene (returns shallow clone with updated layer params) */
+declare function applyTimelineAtTime(doc: SceneDocument, time: number): SceneDocument;
+declare function createDefaultRevealTrack(layerId: string): SceneDocument["timeline"]["tracks"][0];
+declare function createPulseOpacityTrack(layerId: string): SceneDocument["timeline"]["tracks"][0];
+
+interface TextLayoutBounds {
+    xMin: number;
+    yMin: number;
+    xMax: number;
+    yMax: number;
+    maxLineWidth: number;
+    textBlockHeight: number;
+}
+interface TextLayoutResult {
+    lines: string[];
+    fontSize: number;
+    startX: number;
+    startY: number;
+    align: CanvasTextAlign;
+    lineWidths: number[];
+    bounds: TextLayoutBounds;
+    safeRect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+interface CompositionPreset {
+    id: string;
+    label: string;
+    width: number;
+    height: number;
+    description?: string;
+}
+declare const COMPOSITION_PRESETS: CompositionPreset[];
+/** Soft-wrap paragraphs to fit safe width */
+declare function wrapTextToWidth(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, text: string, maxWidth: number, letterSpacing: number): string[];
+declare function measureTextFits(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, cfg: TextEffectConfig, fontSize: number, lines: string[]): boolean;
+declare function computeAutoFitFontSize(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, cfg: TextEffectConfig, wrappedLines: string[]): number;
+/**
+ * Layout text for a composition: safe margins, optional wrap + auto-fit.
+ */
+declare function computeTextLayout(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, cfg: TextEffectConfig, options?: {
+    wrap?: boolean;
+    autoFit?: boolean;
+}): TextLayoutResult;
+/** Preview zoom: fit composition inside viewport */
+declare function computeFitZoom(viewportWidth: number, viewportHeight: number, compositionWidth: number, compositionHeight: number, padding?: number): number;
+
+declare function getPresetScene(preset: Preset): SceneDocument;
+declare function presetToRecipe(preset: Preset): StyleRecipe;
+declare const builtInRecipes: StyleRecipe[];
+declare function applyRecipeToScene(base: SceneDocument, recipe: StyleRecipe): SceneDocument;
+declare function clearRecipeCache(): void;
+
+/** Visible glyph count (newlines excluded). */
+declare function countTextGlyphs(text: string): number;
+declare function resizeCharFillColors(text: string, colors: string[] | undefined, fallback: string): string[];
+declare function setCharFillColor(colors: string[], glyphIndex: number, color: string): string[];
+declare function applyFillColorToAll(colors: string[], color: string): string[];
+/** Simple hue sweep for quick previews */
+declare function rainbowCharFillColors(text: string): string[];
+interface DrawPerCharTextOptions {
+    lines: string[];
+    startX: number;
+    startY: number;
+    lineAdvance: number;
+    align: CanvasTextAlign;
+    letterSpacing: number;
+    charFillColors: string[];
+    defaultColor: string;
+    mode: "fill" | "stroke";
+    offsetX?: number;
+    offsetY?: number;
+}
+/**
+ * Draw text one glyph at a time with per-index fill/stroke colors.
+ * Letter spacing is applied manually (canvas letterSpacing reset to 0).
+ */
+declare function drawPerCharText(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, opts: DrawPerCharTextOptions): void;
+declare function shouldUsePerCharFill(cfg: TextEffectConfig): boolean;
+
+/**
+ * Programmatic Lottie Animation Builder and Mutation Engine (Bodymovin Schema)
+ * Supports creating compositions from scratch, layer insertions, and visual keyframe timeline tracking.
+ *
+ * Font Handling:
+ * Lottie-web uses the 'fName' property to look up fonts in the browser's CSS.
+ * Each font variant (Regular, Bold, Italic, BoldItalic) is registered as a separate
+ * font-family name (e.g., "Poppins-Italic") that maps to the actual font with
+ * appropriate font-weight and font-style via @font-face rules in index.css.
+ */
+interface EasingControlPoint {
+    x: number[];
+    y: number[];
+}
+interface LottieKeyframe {
+    t: number;
+    s: number[] | number;
+    i?: EasingControlPoint;
+    o?: EasingControlPoint;
+}
+type LottiePropertyPath = "ks.a" | "ks.p" | "ks.s" | "ks.r" | "ks.o";
+/**
+ * Creates a valid minimum blank slate Lottie composition
+ */
+declare function createBlankLottie(w: number, h: number, fps: number, durationFrames: number): any;
+/**
+ * Re-indexes layer indices (ind) in a Lottie composition to ensure ordering integrity
+ */
+declare function reindexLayers(lottieData: any): void;
+/**
+ * Adds a solid background layer (ty === 1) to the composition
+ */
+declare function addSolidLayer(lottieData: any, name: string, color: string, w: number, h: number): any;
+/**
+ * Adds a standard vector text layer (ty === 5) to the composition
+ */
+declare function addTextLayer(lottieData: any, name: string, text: string): any;
+/**
+ * Adds an empty shape layer (ty === 4) to the composition
+ */
+declare function addShapeLayer(lottieData: any, name: string): any;
+/**
+ * Appends a basic vector shape (Rectangle or Ellipse) to a shape layer
+ */
+declare function addVectorShape(lottieData: any, layerIndex: number, shapeType: "rect" | "ellipse", colorHex: string): any;
+/**
+ * Updates a static property on a Lottie layer
+ */
+declare function updateStaticProperty(lottieData: any, layerIndex: number, path: LottiePropertyPath, value: number | number[]): any;
+/**
+ * Converts a static property to an animated keyframed track, inserting a default start keyframe
+ */
+declare function enableKeyframing(lottieData: any, layerIndex: number, path: LottiePropertyPath): any;
+/**
+ * Inserts or updates a keyframe in an animated Lottie property track
+ */
+declare function addOrUpdateKeyframe(lottieData: any, layerIndex: number, path: LottiePropertyPath, frame: number, value: number | number[], easing?: "linear" | "easeIn" | "easeOut" | "easeInOut"): any;
+/**
+ * Removes a keyframe from an animated Lottie property track
+ */
+declare function deleteKeyframe(lottieData: any, layerIndex: number, path: LottiePropertyPath, frame: number): any;
+/**
+ * Adds an image asset and corresponding Image Layer (ty === 2) to the composition
+ */
+declare function addImageLayer(lottieData: any, name: string, base64Data: string, w: number, h: number): any;
+/**
+ * Sets or clears the track matte mask setting of a layer
+ * matteType: 0 = None, 1 = Alpha Matte, 2 = Alpha Inverted Matte
+ */
+declare function updateTrackMatte(lottieData: any, layerIndex: number, matteType: number): any;
+
+/**
+ * Lottie JSON Parser
+ * Auto-extracts dimensions, length, framerate, and all text layers.
+ */
+interface ParsedTextLayer {
+    layerName: string;
+    defaultText: string;
+}
+interface LottieFileInfo {
+    width: number;
+    height: number;
+    fps: number;
+    durationFrames: number;
+    textLayers: ParsedTextLayer[];
+}
+/**
+ * Extracts the default text string from a Lottie layer.t.d.k structure
+ */
+declare function getDefaultText(layer: any): string;
+/**
+ * Recursively scans layers (including nested precompositions) for text layers (ty === 5)
+ */
+declare function scanTextLayers(lottieData: any): ParsedTextLayer[];
+/**
+ * Parse an uploaded Lottie JSON object to extract metadata and text layers
+ */
+declare function parseLottieJson(lottieData: any): LottieFileInfo;
+
+/**
+ * Lottie Customization & Injections Engine
+ * Implements real-time text, color, and full per-layer style mutations.
+ */
+interface TextLayerConfig {
+    layerName: string;
+    defaultText: string;
+    maxCharacters: number;
+    role: "primary" | "secondary" | "accent";
+}
+type TextCustomization = {
+    primary: string;
+    secondary: string;
+    accent: string;
+};
+/** Full per-layer text style override — all fields optional */
+interface TextStyleOverride {
+    text?: string;
+    fontName?: string;
+    fontSize?: number;
+    fillColor?: string;
+    strokeColor?: string;
+    strokeWidth?: number;
+    tracking?: number;
+    lineHeight?: number;
+    align?: 0 | 1 | 2 | 3;
+    opacity?: number;
+    scaleX?: number;
+    scaleY?: number;
+    posX?: number;
+    posY?: number;
+    rotation?: number;
+}
+/**
+ * Convert #RRGGBB to Lottie normalized [r, g, b] (0–1).
+ */
+declare function hexToLottieRgb(hex: string): [number, number, number];
+/**
+ * Inject text content into mapped text layers by role.
+ */
+declare function injectText(lottieData: any, customization: TextCustomization, textLayers: TextLayerConfig[]): any;
+/**
+ * Inject a full style override into a specific named text layer.
+ */
+declare function injectTextStyle(lottieData: any, layerName: string, override: TextStyleOverride): any;
+/**
+ * Inject style overrides into ALL text layers at once.
+ * Useful for applying a global font/color change.
+ */
+declare function injectGlobalTextStyle(lottieData: any, override: Omit<TextStyleOverride, "text" | "posX" | "posY">): any;
+/**
+ * Inject fill color into shape layers (ty === "fl") within a named layer.
+ */
+declare function injectColor(lottieData: any, layerName: string, hexColor: string): any;
+/**
+ * Inject solid layer background color (ty === 1).
+ */
+declare function injectSolidColor(lottieData: any, layerName: string, hexColor: string): any;
+/**
+ * Batch inject multiple overrides in one pass — most efficient for live preview.
+ */
+interface BatchInjection {
+    textCustomization?: {
+        customization: TextCustomization;
+        layers: TextLayerConfig[];
+    };
+    styleOverrides?: Array<{
+        layerName: string;
+        override: TextStyleOverride;
+    }>;
+    colorOverrides?: Array<{
+        layerName: string;
+        color: string;
+    }>;
+    solidOverrides?: Array<{
+        layerName: string;
+        color: string;
+    }>;
+    hiddenLayers?: Set<number>;
+}
+declare function injectBatch(lottieData: any, batch: BatchInjection): any;
+
+/**
+ * Lottie Text Animation Presets — CapCut-grade entrance, exit, and loop animations.
+ * Each preset returns a set of Lottie keyframe tracks to bake into a text layer.
+ */
+type AnimationCategory = "entrance" | "exit" | "loop" | "emphasis";
+interface LottieAnimPreset {
+    id: string;
+    name: string;
+    category: AnimationCategory;
+    icon: string;
+    description: string;
+    /** Duration in frames this animation occupies */
+    defaultDurationFrames: number;
+    /** Build keyframes for a given layer, start frame, total frames, and comp size */
+    buildTracks: (opts: AnimBuildOpts) => AnimTrackDef[];
+}
+interface AnimBuildOpts {
+    layerIndex: number;
+    startFrame: number;
+    endFrame: number;
+    totalFrames: number;
+    compW: number;
+    compH: number;
+    /** For exit animations, the frame at which exit begins */
+    exitStartFrame?: number;
+}
+interface AnimKeyframe {
+    t: number;
+    s: number[] | number;
+    i?: {
+        x: number[];
+        y: number[];
+    };
+    o?: {
+        x: number[];
+        y: number[];
+    };
+}
+interface AnimTrackDef {
+    /** Lottie property path e.g. "ks.p", "ks.s", "ks.o", "ks.r" */
+    path: string;
+    keyframes: AnimKeyframe[];
+}
+declare const LOTTIE_ANIM_PRESETS: LottieAnimPreset[];
+declare const ENTRANCE_PRESETS: LottieAnimPreset[];
+declare const EXIT_PRESETS: LottieAnimPreset[];
+declare const LOOP_PRESETS: LottieAnimPreset[];
+declare const EMPHASIS_PRESETS: LottieAnimPreset[];
+declare function getAnimPreset(id: string): LottieAnimPreset | undefined;
+/**
+ * Bake an animation preset into a Lottie layer's keyframe tracks.
+ * Merges with existing keyframes rather than replacing them.
+ */
+declare function bakeAnimationIntoLayer(lottieData: any, layerIndex: number, preset: LottieAnimPreset, opts: Omit<AnimBuildOpts, "layerIndex">): any;
+/**
+ * Remove all animation keyframes from a layer property, reverting to static.
+ */
+declare function clearAnimationFromLayer(lottieData: any, layerIndex: number, paths?: string[]): any;
+
+/**
+ * Lottie Per-Layer Text Style Engine
+ * Provides rich text styling (font, fill, gradient, stroke, shadow, glow, tracking)
+ * that maps directly to Lottie JSON text document properties.
+ */
+type TextAlign = "left" | "center" | "right" | "justify";
+type FillType = "solid" | "gradient";
+type GradientDir = "horizontal" | "vertical" | "diagonal" | "radial";
+interface LottieGradientStop {
+    color: string;
+    position: number;
+}
+interface TextLayerStyle {
+    fontName: string;
+    fontFamily: string;
+    fontWeight: number;
+    fontStyle: "normal" | "italic";
+    fontSize: number;
+    tracking: number;
+    lineHeight: number;
+    align: TextAlign;
+    fillType: FillType;
+    fillColor: string;
+    gradientStops: LottieGradientStop[];
+    gradientDir: GradientDir;
+    strokeEnabled: boolean;
+    strokeColor: string;
+    strokeWidth: number;
+    strokeOpacity: number;
+    shadowEnabled: boolean;
+    shadowColor: string;
+    shadowBlur: number;
+    shadowOffsetX: number;
+    shadowOffsetY: number;
+    shadowOpacity: number;
+    glowEnabled: boolean;
+    glowColor: string;
+    glowBlur: number;
+    glowOpacity: number;
+    posX: number;
+    posY: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    opacity: number;
+}
+declare const DEFAULT_TEXT_STYLE: TextLayerStyle;
+/** Convert #RRGGBB to Lottie normalized [r, g, b] (0–1) */
+declare function hexToLottieColor(hex: string): [number, number, number];
+/** Convert Lottie [r,g,b] (0–1) back to #RRGGBB */
+declare function lottieColorToHex(rgb: number[]): string;
+/** Map CSS font-weight + style to a Lottie fName */
+declare function buildLottieFontName(family: string, weight: number, style: "normal" | "italic"): string;
+/** Lottie text alignment: 0=left, 1=center, 2=right, 3=justify */
+declare function alignToLottieJ(align: TextAlign): number;
+declare function lottieJToAlign(j: number): TextAlign;
+/**
+ * Extract a TextLayerStyle from an existing Lottie text layer (ty === 5).
+ * Falls back to defaults for any missing properties.
+ */
+declare function readStyleFromLottieLayer(layer: any): TextLayerStyle;
+/**
+ * Apply a TextLayerStyle to a Lottie text layer (ty === 5).
+ * Returns a new deep-cloned layer with all style properties applied.
+ */
+declare function applyStyleToLottieLayer(layer: any, style: TextLayerStyle): any;
+/**
+ * Apply a TextLayerStyle to a full Lottie composition at a given layer index.
+ */
+declare function applyStyleToLottie(lottieData: any, layerIndex: number, style: TextLayerStyle): any;
+interface LottieFontEntry {
+    fName: string;
+    fFamily: string;
+    fWeight: string;
+    fStyle: string;
+    asName: string;
+    googleFont?: boolean;
+}
+/** Ensure a font is registered in the Lottie fonts list */
+declare function ensureFontInLottie(lottieData: any, entry: LottieFontEntry): any;
+/** Full set of supported fonts with all variants */
+declare const SUPPORTED_FONT_FAMILIES: string[];
+declare const FONT_WEIGHT_OPTIONS: {
+    label: string;
+    value: number;
+}[];
+/** Build all Lottie font entries for a given family */
+declare function buildFontEntries(family: string): LottieFontEntry[];
+
+/**
+ * Built-in CapCut-style Lottie text template presets.
+ * Each preset is a complete Lottie JSON composition ready to use.
+ */
+type TemplatePresetCategory = "lower-third" | "title-card" | "callout" | "caption" | "kinetic" | "social" | "cinematic" | "sports" | "minimal" | "bold";
+interface LottieTemplatePreset {
+    id: string;
+    name: string;
+    category: TemplatePresetCategory;
+    description: string;
+    tags: string[];
+    aspectRatio: "16:9" | "9:16" | "1:1" | "4:5";
+    /** Build and return the Lottie JSON for this preset */
+    build: () => any;
+}
+declare const LOTTIE_TEMPLATE_PRESETS: LottieTemplatePreset[];
+declare function getTemplatePreset(id: string): LottieTemplatePreset | undefined;
+declare function getTemplatesByCategory(category: TemplatePresetCategory): LottieTemplatePreset[];
+declare const TEMPLATE_CATEGORIES: TemplatePresetCategory[];
+
+/**
+ * Lottie Export Engine
+ * Supports:
+ *  - .lottie (dotLottie) — ZIP containing animation.json + manifest.json
+ *  - .json  — raw Lottie JSON
+ *  - PNG sequence ZIP
+ *  - Animated GIF (via canvas frame capture)
+ */
+interface DotLottieManifest {
+    version: string;
+    generator: string;
+    animations: Array<{
+        id: string;
+        speed?: number;
+        themeColor?: string;
+        loop?: boolean;
+        autoplay?: boolean;
+        direction?: 1 | -1;
+    }>;
+}
+/**
+ * Build a .lottie file (ZIP containing animation.json + manifest.json).
+ * The .lottie format is the standard used by LottieFiles and dotlottie-player.
+ */
+declare function buildDotLottie(lottieData: object, animationId: string, opts?: {
+    loop?: boolean;
+    autoplay?: boolean;
+    speed?: number;
+}): Promise<Blob>;
+/**
+ * Download a .lottie file.
+ */
+declare function downloadDotLottie(lottieData: object, filename: string, animationId?: string, opts?: {
+    loop?: boolean;
+    autoplay?: boolean;
+    speed?: number;
+}): Promise<void>;
+/**
+ * Download raw Lottie JSON.
+ */
+declare function downloadLottieJson(lottieData: object, filename: string): void;
+interface GifExportOptions {
+    fps?: number;
+    duration?: number;
+    width?: number;
+    height?: number;
+    quality?: number;
+    loop?: boolean;
+}
+interface GifFrame {
+    imageData: ImageData;
+    delay: number;
+}
+/**
+ * Capture frames from a Lottie animation rendered via lottie-web into a canvas.
+ * Returns raw ImageData frames ready for GIF encoding.
+ *
+ * NOTE: Requires lottie-web to be loaded and the container to be in the DOM.
+ */
+declare function captureLottieFrames(lottieInstance: any, canvas: HTMLCanvasElement, opts?: GifExportOptions): Promise<GifFrame[]>;
+/**
+ * Encode frames to an animated GIF using a pure-JS GIF encoder.
+ * Uses the omggif library approach (inline minimal encoder).
+ */
+declare function encodeGif(frames: GifFrame[], width: number, height: number, opts?: {
+    loop?: boolean;
+    quality?: number;
+}): Uint8Array;
+
+interface PngSequenceOptions {
+    fps?: number;
+    duration?: number;
+    width?: number;
+    height?: number;
+}
+interface PngSequenceFrame {
+    index: number;
+    time: number;
+    dataUrl: string;
+}
+/** Render all frames in-memory (browser) */
+declare function renderPngSequence(doc: SceneDocument, options?: PngSequenceOptions): PngSequenceFrame[];
+/** Build a minimal ZIP (store only, no compression) for PNG frames */
+declare function buildPngSequenceZip(frames: PngSequenceFrame[]): Blob;
+declare function downloadPngSequenceZip(doc: SceneDocument, filename: string, options?: PngSequenceOptions): void;
+declare const WEBM_EXPORT_MAX_FRAMES = 900;
+interface WebMExportOptions extends PngSequenceOptions {
+    videoBitsPerSecond?: number;
+    /** Pace frame capture so clip duration matches timeline (recommended) */
+    realtimePacing?: boolean;
+}
+declare function getSupportedWebMMimeType(): string | null;
+declare function isWebMExportSupported(): boolean;
+declare function getWebMFrameCount(doc: SceneDocument, options?: WebMExportOptions): number;
+/**
+ * Encode timeline frames to WebM via MediaRecorder + canvas.captureStream(0).
+ * Browser-only; transparent backgrounds may flatten to black in the recording.
+ */
+declare function renderSceneWebM(doc: SceneDocument, options?: WebMExportOptions): Promise<Blob>;
+declare function downloadSceneWebM(doc: SceneDocument, filename: string, options?: WebMExportOptions): Promise<void>;
+
+/**
+ * Google Fonts loader for the Lottie Studio.
+ * Scans a Lottie composition for all font families used, then injects
+ * the appropriate Google Fonts stylesheet + @font-face rules so
+ * lottie-web can resolve them by fName.
+ */
+interface LottieFontUsage {
+    fName: string;
+    fFamily: string;
+    fWeight: number;
+    fStyle: "normal" | "italic";
+}
+/**
+ * Scan a Lottie JSON object and return all unique font usages.
+ */
+declare function scanLottieFonts(lottieData: any): LottieFontUsage[];
+/**
+ * Inject Google Fonts stylesheets for all non-system fonts found in a Lottie.
+ * Also injects @font-face rules that map Lottie fName → CSS font-family.
+ * Safe to call multiple times — deduplicates by family.
+ */
+declare function loadLottieFonts(lottieData: any): void;
+/**
+ * Wait for all fonts currently in the document to be loaded.
+ * Useful before capturing thumbnails or exporting frames.
+ */
+declare function waitForFontsReady(): Promise<void>;
+/**
+ * Preload a specific Google Font family with given weights.
+ * Useful for the Style Editor font picker.
+ */
+declare function preloadGoogleFont(family: string, weights?: number[]): void;
+/**
+ * Clear the font loading cache (useful for testing).
+ */
+declare function clearFontCache(): void;
+
+interface AnimatableParamDef {
+    path: string;
+    label: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    unit?: string;
+}
+declare function getAnimatableParamsForLayer(layer: EffectLayer): AnimatableParamDef[];
+declare function getAnimatableParamDef(layer: EffectLayer, paramPath: string): AnimatableParamDef | undefined;
+declare function readLayerScalar(layer: EffectLayer, paramPath: string): number;
+
+/** Blend two scenes by layer params (Lab preset blend) */
+declare function blendScenes(sceneA: SceneDocument, sceneB: SceneDocument, ratio: number): SceneDocument;
+declare function blendConfigs(cfgA: TextEffectConfig, cfgB: TextEffectConfig, ratio: number): TextEffectConfig;
+
+declare function parseHistorySnapshot(raw: string): {
+    scene: SceneDocument;
+    config: TextEffectConfig;
+};
+declare function snapshotScene(scene: SceneDocument): string;
+
+/** Apply rectangular wipe reveal (MVP mask) on composed canvas */
+declare function applyMaskReveal(ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, doc: SceneDocument, width: number, height: number): void;
+
+/** Attach MVP demo animation tracks (shadow drift + optional mask reveal) */
+declare function ensureDefaultTimeline(doc: SceneDocument): SceneDocument;
+declare function cloneSceneWithNewIds(doc: SceneDocument): SceneDocument;
+
+declare function trackId(track: AnimTrack): string;
+declare function findTrackIndex(doc: SceneDocument, layerId: string, paramPath: string): number;
+declare function getLayerById(doc: SceneDocument, layerId: string): EffectLayer;
+declare function updateTimeline(doc: SceneDocument, patch: Partial<SceneDocument["timeline"]>): SceneDocument;
+declare function setTracks(doc: SceneDocument, tracks: AnimTrack[]): SceneDocument;
+declare function pruneTracksForLayer(doc: SceneDocument, layerId: string): SceneDocument;
+declare function addTrack(doc: SceneDocument, layerId: string, paramPath: string, initialKeyframes?: Keyframe[]): SceneDocument;
+declare function removeTrack(doc: SceneDocument, trackIndex: number): SceneDocument;
+declare function updateTrack(doc: SceneDocument, trackIndex: number, updater: (track: AnimTrack) => AnimTrack): SceneDocument;
+declare function sortKeyframes(keyframes: Keyframe[]): Keyframe[];
+declare function upsertKeyframe(track: AnimTrack, time: number, value?: number, easing?: Keyframe["easing"]): AnimTrack;
+declare function addKeyframeAtTime(doc: SceneDocument, trackIndex: number, time: number, value?: number): SceneDocument;
+declare function moveKeyframe(doc: SceneDocument, trackIndex: number, keyframeIndex: number, time: number, duration: number): SceneDocument;
+declare function updateKeyframe(doc: SceneDocument, trackIndex: number, keyframeIndex: number, patch: Partial<Keyframe>): SceneDocument;
+declare function removeKeyframe(doc: SceneDocument, trackIndex: number, keyframeIndex: number): SceneDocument;
+declare function duplicateTrackAtPlayhead(doc: SceneDocument, trackIndex: number, previewTime: number): SceneDocument;
+
+export { type AnimBuildOpts, type AnimKeyframe, type AnimTrack, type AnimTrackDef, type AnimatableParamDef, type AnimationCategory, type BatchInjection, COMPOSITION_PRESETS, CUSTOM_ENGINE_IDS, type CompositionPreset, type CompositorFromScene, type CompositorSettings, type CustomEngineId, DEFAULT_TEXT_STYLE, type DotLottieManifest, type DrawPerCharTextOptions, EMPHASIS_PRESETS, ENGINE_ID_TO_LEGACY, ENTRANCE_PRESETS, EXIT_PRESETS, type EasingControlPoint, type EffectLayer, type EffectLayerType, type EvaluateOptions, FONT_WEIGHT_OPTIONS, type FillType, type FontVariant, type GifExportOptions, type GifFrame, type GlowLayer, type GradientDir, type GradientStop, type Keyframe, LEGACY_RENDERER_MAP, LOOP_PRESETS, LOTTIE_ANIM_PRESETS, LOTTIE_TEMPLATE_PRESETS, type LayerTarget, type LottieAnimPreset, type LottieFileInfo, type LottieFontEntry, type LottieFontUsage, type LottieGradientStop, type LottieKeyframe, type LottiePropertyPath, type LottieTemplatePreset, type ParsedTextLayer, type PngSequenceFrame, type PngSequenceOptions, type Preset, SCENE_VERSION, SUPPORTED_FONT_FAMILIES, type SceneCanvas, type SceneDocument, type SceneText, type StyleRecipe, TEMPLATE_CATEGORIES, type TemplatePresetCategory, type TextAlign, type TextCustomization, type TextEffectConfig, TextEffectRenderer, type TextLayerConfig, type TextLayerStyle, type TextLayoutBounds, type TextLayoutResult, type TextStyleOverride, type Timeline, WEBM_EXPORT_MAX_FRAMES, WebGLCompositor, type WebMExportOptions, addImageLayer, addKeyframeAtTime, addOrUpdateKeyframe, addShapeLayer, addSolidLayer, addTextLayer, addTrack, addVectorShape, advanceSceneTime, alignToLottieJ, applyFillColorToAll, applyMaskReveal, applyRecipeToScene, applyStyleToLottie, applyStyleToLottieLayer, applyTimelineAtTime, bakeAnimationIntoLayer, blendConfigs, blendScenes, buildDotLottie, buildFontEntries, buildLottieFontName, buildPngSequenceZip, builtInPresets, builtInRecipes, captureLottieFrames, checkFontVariant, clearAnimationFromLayer, clearFontCache, clearRecipeCache, cloneSceneWithNewIds, computeAutoFitFontSize, computeFitZoom, computeTextLayout, countTextGlyphs, createBlankLottie, createDefaultRevealTrack, createEmptyScene, createPulseOpacityTrack, defaultConfig, deleteKeyframe, downloadDotLottie, downloadLottieJson, downloadPngSequenceZip, downloadSceneWebM, drawPerCharText, duplicateTrackAtPlayhead, ease, enableKeyframing, encodeGif, ensureDefaultTimeline, ensureFontInLottie, evaluateConfig, evaluateScene, findTrackIndex, getAnimPreset, getAnimatableParamDef, getAnimatableParamsForLayer, getDefaultText, getLayerById, getPresetScene, getSceneTime, getSupportedWebMMimeType, getTemplatePreset, getTemplatesByCategory, getWebMFrameCount, hexToLottieColor, hexToLottieRgb, initializeFontSystem, injectBatch, injectColor, injectFontVariantRules, injectGlobalTextStyle, injectSolidColor, injectText, injectTextStyle, isWebMExportSupported, loadLottieFonts, lottieColorToHex, lottieJToAlign, measureTextFits, mergeSceneIntoConfig, moveKeyframe, newLayerId, parseHistorySnapshot, parseLottieJson, preloadGoogleFont, presetToRecipe, pruneTracksForLayer, rainbowCharFillColors, readLayerScalar, readStyleFromLottieLayer, reindexLayers, removeKeyframe, removeTrack, renderPngSequence, renderSceneWebM, renderTextEffectCore, resetSceneTime, resizeCharFillColors, resolveAnimatedScalar, resolveCustomEngineId, scanLottieFonts, scanTextLayers, sceneToConfig, setCharFillColor, setSceneTime, setTracks, shouldUsePerCharFill, snapshotScene, sortKeyframes, syncCompositorFromScene, textEffectConfigToScene, trackId, updateKeyframe, updateStaticProperty, updateTimeline, updateTrack, updateTrackMatte, upsertKeyframe, waitForFontsReady, wrapTextToWidth };