Animation System

class Animation:
    """
    Base class for all animations providing timing control and interpolation framework.
    
    Defines how mobjects change over time with precise mathematical interpolation
    and customizable rate functions for natural motion.
    """
    
    def __init__(
        mobject: Mobject = None,
        run_time: float = 1.0,
        rate_func: Callable[[float], float] = smooth,
        lag_ratio: float = 0.0,
        reverse_rate_function: bool = False,
        name: str = None,
        remover: bool = False,
        suspend_mobject_updating: bool = True,
        **kwargs
    ) -> None:
        """
        Initialize animation with timing and behavior parameters.
        
        Parameters:
        - mobject: The mobject to animate
        - run_time: Animation duration in seconds
        - rate_func: Function mapping time progress [0,1] to animation progress [0,1]
        - lag_ratio: Delay factor for submobject animations (0=simultaneous, 1=sequential)
        - reverse_rate_function: Whether to reverse the rate function
        - name: Animation name for debugging and display
        - remover: Whether to remove mobject from scene after animation
        - suspend_mobject_updating: Whether to pause mobject updaters during animation
        """
    
    def interpolate(alpha: float) -> None:
        """
        Define the animation at progress alpha ∈ [0,1].
        
        Parameters:
        - alpha: Animation progress from 0 (start) to 1 (end)
        """
    
    def update_mobjects(dt: float) -> None:
        """Update mobjects for current animation frame."""
    
    def copy() -> Animation:
        """Create a copy of this animation."""

class Wait(Animation):
    """
    Animation that waits for a specified duration without changing mobjects.
    
    Used for creating pauses in animation sequences and timing control.
    """
    
    def __init__(
        duration: float = 1.0,
        stop_condition: Callable[[], bool] = None,
        frozen_frame: bool = True,
        **kwargs
    ) -> None:
        """
        Parameters:
        - duration: Wait time in seconds
        - stop_condition: Function to end wait early when it returns True
        - frozen_frame: Whether to freeze the current frame or continue updating
        """

def Create(
    mobject: VMobject,
    lag_ratio: float = 0.0,
    introduce_loop_index: bool = False,
    **kwargs
) -> Animation:
    """
    Incrementally reveal a VMobject by tracing its path from start to end.
    
    Simulates drawing the mobject's outline progressively, following the
    natural path structure of the object.
    
    Parameters:
    - mobject: VMobject to be created/drawn
    - lag_ratio: Delay between submobject creation starts
    - introduce_loop_index: Whether to handle closed path loops specially
    """

def Uncreate(
    mobject: VMobject,
    rate_func: Callable = lambda t: smooth(1-t),
    remover: bool = True,
    **kwargs
) -> Animation:
    """
    Reverse of Create - incrementally hide a VMobject by reversing its path.
    
    Parameters:
    - mobject: VMobject to be uncreated
    - rate_func: Rate function (defaults to reverse of smooth)
    - remover: Whether to remove mobject after animation
    """

def Write(
    mobject: VMobject,
    rate_func: Callable = linear,
    reverse: bool = False,
    **kwargs
) -> Animation:
    """
    Simulate hand-writing text or hand-drawing a VMobject with natural timing.
    
    Combines path tracing with stroke drawing to create realistic writing motion,
    particularly effective for text and mathematical expressions.
    
    Parameters:
    - mobject: Text or VMobject to write
    - rate_func: Rate function controlling writing speed
    - reverse: Whether to write in reverse order
    """

def Unwrite(
    mobject: VMobject,
    rate_func: Callable = lambda t: smooth(1-t),
    reverse: bool = True,
    remover: bool = True,
    **kwargs
) -> Animation:
    """
    Reverse of Write - simulate erasing text or drawings.
    
    Parameters:
    - mobject: Text or VMobject to unwrite
    - rate_func: Rate function for erasing motion
    - reverse: Direction of unwriting
    - remover: Whether to remove after completion
    """

def DrawBorderThenFill(
    vmobject: VMobject,
    run_time: float = 2,
    rate_func: Callable = double_smooth,
    stroke_width: float = 2,
    stroke_color: str = None,
    draw_border_animation_config: dict = None,
    fill_animation_config: dict = None,
    **kwargs
) -> Animation:
    """
    First draw the border/outline, then fill the interior of a shape.
    
    Creates a two-phase animation: first traces the outline, then fills
    the interior, simulating natural drawing workflow.
    
    Parameters:
    - vmobject: VMobject to draw and fill
    - run_time: Total animation duration
    - rate_func: Overall timing function
    - stroke_width: Border line thickness during drawing
    - stroke_color: Border color during drawing
    - draw_border_animation_config: Config for border drawing phase
    - fill_animation_config: Config for filling phase
    """

def ShowIncreasingSubsets(
    group: Group,
    suspend_mobject_updating: bool = False,
    **kwargs
) -> Animation:
    """
    Progressively reveal submobjects one by one in sequence.
    
    Shows first submobject, then first two, then first three, etc.
    until all submobjects are visible.
    
    Parameters:
    - group: Group containing submobjects to reveal
    - suspend_mobject_updating: Whether to pause updates during animation
    """

def ShowSubmobjectsOneByOne(
    group: Group,
    **kwargs
) -> Animation:
    """
    Show submobjects one at a time with each fully appearing before the next.
    
    Each submobject gets its full creation animation before the next begins,
    creating a sequential presentation effect.
    
    Parameters:
    - group: Group containing submobjects to show sequentially
    """

# Text-specific creation animations
def AddTextLetterByLetter(
    text: Text,
    time_per_char: float = 0.06,
    **kwargs
) -> Animation:
    """
    Reveal text one letter at a time from left to right.
    
    Parameters:
    - text: Text object to reveal progressively
    - time_per_char: Time to spend revealing each character
    """

def AddTextWordByWord(
    text: Text,
    time_per_word: float = 0.2,
    **kwargs
) -> Animation:
    """
    Reveal text one word at a time.
    
    Parameters:
    - text: Text object to reveal progressively  
    - time_per_word: Time to spend revealing each word
    """

def RemoveTextLetterByLetter(
    text: Text,
    time_per_char: float = 0.06,
    remover: bool = True,
    **kwargs
) -> Animation:
    """
    Remove text one letter at a time from right to left.
    
    Parameters:
    - text: Text object to remove progressively
    - time_per_char: Time to spend removing each character
    - remover: Whether to remove text after animation
    """

def Transform(
    mobject: Mobject,
    target_mobject: Mobject, 
    path_func: Callable = None,
    path_arc: float = 0,
    path_arc_axis: np.ndarray = OUT,
    replace_mobject_with_target_in_scene: bool = False,
    **kwargs
) -> Animation:
    """
    Transform one mobject into another by morphing their point structures.
    
    The original mobject is modified to match the target mobject's shape,
    position, and properties through smooth interpolation.
    
    Parameters:
    - mobject: Mobject to transform (will be modified)
    - target_mobject: Target shape and properties
    - path_func: Function defining transformation path for each point
    - path_arc: Arc angle for circular transformation paths
    - path_arc_axis: Axis for circular path rotation
    - replace_mobject_with_target_in_scene: Whether to replace mobject with target
    """

def ReplacementTransform(
    mobject: Mobject,
    target_mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Transform mobject into target, replacing the original with the target.
    
    Unlike Transform, this removes the original mobject and adds the target
    mobject to the scene after transformation.
    
    Parameters:
    - mobject: Mobject to be replaced
    - target_mobject: Mobject to replace it with
    """

def TransformFromCopy(
    mobject: Mobject,
    target_mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Transform a copy of mobject into target, leaving original unchanged.
    
    Creates transformation animation without modifying the source mobject,
    useful when the original needs to remain in its current state.
    
    Parameters:
    - mobject: Source mobject (unchanged)
    - target_mobject: Target to transform copy into
    """

def ClockwiseTransform(
    mobject: Mobject,
    target_mobject: Mobject,
    path_arc: float = -np.pi,
    **kwargs
) -> Animation:
    """
    Transform with clockwise rotation path.
    
    Parameters:
    - mobject: Mobject to transform
    - target_mobject: Transformation target
    - path_arc: Arc angle (negative for clockwise)
    """

def CounterclockwiseTransform(
    mobject: Mobject,
    target_mobject: Mobject,
    path_arc: float = np.pi,
    **kwargs
) -> Animation:
    """
    Transform with counter-clockwise rotation path.
    
    Parameters:
    - mobject: Mobject to transform
    - target_mobject: Transformation target  
    - path_arc: Arc angle (positive for counter-clockwise)
    """

def FadeTransform(
    mobject: Mobject,
    target_mobject: Mobject,
    stretch: bool = True,
    dim_to_match: int = 1,
    **kwargs
) -> Animation:
    """
    Transform with fade transition between mobjects.
    
    Combines transformation with opacity changes for smooth transitions
    when point structures don't align well for direct morphing.
    
    Parameters:
    - mobject: Source mobject
    - target_mobject: Target mobject
    - stretch: Whether to stretch mobjects for better alignment
    - dim_to_match: Dimension to match when stretching (0=width, 1=height)
    """

def FadeTransformPieces(
    mobject: Mobject,
    target_mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Transform by fading between individual pieces/submobjects.
    
    Parameters:
    - mobject: Source mobject with submobjects
    - target_mobject: Target mobject with submobjects
    """

# Direct mobject method transformations
def MoveToTarget(mobject: Mobject, **kwargs) -> Animation:
    """
    Move mobject to its .target attribute position/state.
    
    Requires mobject to have a .target attribute set beforehand.
    
    Parameters:
    - mobject: Mobject with .target attribute
    """

def ApplyMethod(
    method: Callable,
    *args,
    **kwargs
) -> Animation:
    """
    Animate the result of calling a method on a mobject.
    
    Parameters:
    - method: Bound method to call on mobject
    - *args: Arguments to pass to method
    """

def ApplyFunction(
    func: Callable,
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Apply function to mobject's points/properties.
    
    Parameters:
    - func: Function to apply to mobject
    - mobject: Mobject to transform
    """

def ApplyMatrix(
    matrix: np.ndarray,
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Apply matrix transformation to mobject.
    
    Parameters:
    - matrix: Transformation matrix
    - mobject: Mobject to transform
    """

def ApplyComplexFunction(
    complex_func: Callable,
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Apply complex function to mobject coordinates.
    
    Treats mobject points as complex numbers and applies the function.
    
    Parameters:
    - complex_func: Function taking complex input
    - mobject: Mobject to transform
    """

# Specialized transforms
def ScaleInPlace(
    mobject: Mobject,
    scale_factor: float,
    **kwargs
) -> Animation:
    """
    Scale mobject around its center point.
    
    Parameters:
    - mobject: Mobject to scale
    - scale_factor: Scaling factor
    """

def ShrinkToCenter(
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Shrink mobject to its center point.
    
    Parameters:
    - mobject: Mobject to shrink
    """

def Restore(mobject: Mobject, **kwargs) -> Animation:
    """
    Restore mobject to its saved state.
    
    Requires mobject.save_state() to have been called previously.
    
    Parameters:
    - mobject: Mobject with saved state
    """

def Swap(*mobjects: Mobject, **kwargs) -> Animation:
    """
    Swap positions of two mobjects.
    
    Parameters:
    - *mobjects: Two mobjects to swap positions
    """

def CyclicReplace(*mobjects: Mobject, **kwargs) -> Animation:
    """
    Cyclically replace mobjects (A→B, B→C, C→A, etc).
    
    Parameters:
    - *mobjects: Mobjects to cycle through positions
    """

def FadeIn(
    *mobjects: Mobject,
    shift: np.ndarray = None,
    target_position: np.ndarray = None,
    scale: float = 1,
    **kwargs
) -> Animation:
    """
    Fade mobjects into visibility with optional movement and scaling.
    
    Parameters:
    - *mobjects: Mobjects to fade in
    - shift: Vector displacement during fade-in
    - target_position: End position for fade-in movement
    - scale: Scale factor during fade-in
    """

def FadeOut(
    *mobjects: Mobject,
    shift: np.ndarray = None,
    target_position: np.ndarray = None,
    scale: float = 1,
    **kwargs
) -> Animation:
    """
    Fade mobjects out of visibility with optional movement and scaling.
    
    Parameters:
    - *mobjects: Mobjects to fade out
    - shift: Vector displacement during fade-out
    - target_position: Target position for fade-out movement
    - scale: Scale factor during fade-out
    """

def FadeToColor(
    mobject: Mobject,
    color: str,
    **kwargs
) -> Animation:
    """
    Animate color change of mobject with smooth transition.
    
    Parameters:
    - mobject: Mobject to recolor
    - color: Target color
    """

def GrowFromPoint(
    mobject: Mobject,
    point: np.ndarray,
    **kwargs
) -> Animation:
    """
    Grow mobject from a specific point outward.
    
    Parameters:
    - mobject: Mobject to grow
    - point: Point to grow from
    """

def GrowFromCenter(
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Grow mobject from its center outward.
    
    Parameters:
    - mobject: Mobject to grow from center
    """

def GrowFromEdge(
    mobject: Mobject,
    edge: np.ndarray,
    **kwargs
) -> Animation:
    """
    Grow mobject from one of its edges.
    
    Parameters:
    - mobject: Mobject to grow
    - edge: Edge direction (UP, DOWN, LEFT, RIGHT, etc.)
    """

def GrowArrow(
    arrow: Arrow,
    **kwargs
) -> Animation:
    """
    Grow arrow from start point to end point.
    
    Specialized growth animation for arrows that grows along the arrow's direction.
    
    Parameters:
    - arrow: Arrow object to grow
    """

def SpinInFromNothing(
    mobject: Mobject,
    angle: float = TAU,
    **kwargs
) -> Animation:
    """
    Spin mobject into existence from invisible state.
    
    Parameters:
    - mobject: Mobject to spin in
    - angle: Total rotation angle during appearance
    """

def Indicate(
    mobject: Mobject,
    scale_factor: float = 1.2,
    color: str = YELLOW,
    **kwargs
) -> Animation:
    """
    Briefly emphasize mobject by scaling and recoloring.
    
    Temporarily enlarges and changes color of mobject to draw attention,
    then returns to original state.
    
    Parameters:
    - mobject: Mobject to indicate
    - scale_factor: Temporary scale multiplier
    - color: Temporary highlight color
    """

def Flash(
    point: np.ndarray | Mobject,
    line_length: float = 0.2,
    num_lines: int = 12,
    color: str = YELLOW,
    flash_radius: float = 0.3,
    time_width: float = 0.1,
    **kwargs
) -> Animation:
    """
    Create radial flash effect at a point.
    
    Displays radiating lines that expand outward from a central point,
    creating an attention-grabbing flash effect.
    
    Parameters:
    - point: Center point or mobject center for flash
    - line_length: Length of flash lines
    - num_lines: Number of radiating lines
    - color: Color of flash lines
    - flash_radius: Radius of flash effect
    - time_width: Duration of flash peak intensity
    """

def FocusOn(
    focus_point: np.ndarray | Mobject,
    opacity: float = 0.2,
    color: str = GREY,
    **kwargs
) -> Animation:
    """
    Dim everything except focus area to draw attention.
    
    Creates spotlight effect by dimming the background while highlighting
    a specific area or mobject.
    
    Parameters:
    - focus_point: Point or mobject to focus on
    - opacity: Background dimming level
    - color: Background overlay color
    """

def Circumscribe(
    mobject: Mobject,
    shape: VMobject = None,
    fade_in: bool = True,
    fade_out: bool = True,
    time_width: float = 0.3,
    buff: float = 0.1,
    color: str = YELLOW,
    **kwargs
) -> Animation:
    """
    Draw shape around mobject to highlight it.
    
    Creates a temporary outline shape (circle, rectangle, etc.) around
    the mobject to emphasize its boundaries.
    
    Parameters:
    - mobject: Mobject to circumscribe
    - shape: Shape to draw around mobject (auto-detected if None)
    - fade_in: Whether shape fades in
    - fade_out: Whether shape fades out
    - time_width: Duration of full visibility
    - buff: Buffer space around mobject
    - color: Circumscription color
    """

def ShowPassingFlash(
    vmobject: VMobject,
    time_width: float = 0.1,
    **kwargs
) -> Animation:
    """
    Create passing flash effect along mobject's path.
    
    A bright highlight travels along the mobject's path from start to end,
    useful for showing direction or flow.
    
    Parameters:
    - vmobject: Path to flash along
    - time_width: Width of the traveling flash
    """

def ShowPassingFlashWithThinningStrokeWidth(
    vmobject: VMobject,
    n_segments: int = 10,
    time_width: float = 0.1,
    **kwargs
) -> Animation:
    """
    Passing flash with gradually thinning stroke width.
    
    Similar to ShowPassingFlash but with stroke that thins as it travels,
    creating a more dynamic visual effect.
    
    Parameters:
    - vmobject: Path for flash
    - n_segments: Number of flash segments
    - time_width: Width of flash effect
    """

def ApplyWave(
    mobject: Mobject,
    direction: np.ndarray = UP,
    amplitude: float = 0.2,
    wave_func: Callable = np.sin,
    **kwargs
) -> Animation:
    """
    Apply wave distortion effect to mobject.
    
    Creates ripple or wave effect that travels across the mobject,
    temporarily distorting its shape.
    
    Parameters:
    - mobject: Mobject to apply wave to
    - direction: Direction of wave propagation
    - amplitude: Wave amplitude
    - wave_func: Function defining wave shape
    """

def Wiggle(
    mobject: Mobject,
    scale_value: float = 1.1,
    rotation_angle: float = 0.01*TAU,
    n_wiggles: int = 6,
    **kwargs
) -> Animation:
    """
    Make mobject wiggle back and forth.
    
    Creates attention-grabbing wiggle motion by rapidly alternating
    small rotations and scale changes.
    
    Parameters:
    - mobject: Mobject to wiggle
    - scale_value: Maximum scale factor during wiggle
    - rotation_angle: Maximum rotation angle during wiggle
    - n_wiggles: Number of wiggle cycles
    """

def Blink(
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Make mobject blink by rapidly toggling opacity.
    
    Creates attention-getting effect by making object flash on and off.
    
    Parameters:
    - mobject: Mobject to make blink
    """

def MoveAlongPath(
    mobject: Mobject,
    path: VMobject,
    suspend_mobject_updating: bool = False,
    **kwargs
) -> Animation:
    """
    Move mobject along a specified path curve.
    
    Animates smooth movement following the exact shape of a path,
    maintaining constant speed or using custom rate functions.
    
    Parameters:
    - mobject: Mobject to move along path
    - path: VMobject defining the movement path
    - suspend_mobject_updating: Whether to pause mobject updaters during movement
    """

def Homotopy(
    homotopy_function: Callable,
    mobject: Mobject,
    run_time: float = 3.0,
    apply_function_kwargs: dict = None,
    **kwargs
) -> Animation:
    """
    Apply homotopy transformation function to mobject over time.
    
    A homotopy smoothly deforms space using a function that varies
    continuously from identity to target transformation.
    
    Parameters:
    - homotopy_function: Function (x, y, z, t) -> (x', y', z') where t ∈ [0,1]
    - mobject: Mobject to transform via homotopy
    - run_time: Duration of homotopy transformation
    - apply_function_kwargs: Additional arguments for transformation function
    """

def SmoothedVectorizedHomotopy(
    homotopy_function: Callable,
    mobject: VMobject,
    **kwargs
) -> Animation:
    """
    Smoothed version of homotopy for vectorized mobjects.
    
    Provides enhanced smoothness for VMobject transformations
    by considering Bézier curve properties during deformation.
    
    Parameters:
    - homotopy_function: Smooth homotopy transformation function
    - mobject: VMobject to transform smoothly
    """

def ComplexHomotopy(
    complex_homotopy: Callable,
    mobject: Mobject,
    **kwargs
) -> Animation:
    """
    Apply complex number homotopy transformation.
    
    Treats coordinates as complex numbers and applies complex
    function transformations smoothly over time.
    
    Parameters:
    - complex_homotopy: Function (z, t) -> z' for complex coordinates
    - mobject: Mobject to transform via complex homotopy
    """

def PhaseFlow(
    function: Callable,
    mobject: Mobject,
    virtual_time: float = 1.0,
    suspend_mobject_updating: bool = False,
    **kwargs
) -> Animation:
    """
    Move mobject according to vector field flow.
    
    Animates motion following streamlines of a vector field,
    simulating particle flow in mathematical field visualization.
    
    Parameters:
    - function: Vector field function (x, y, z) -> (vx, vy, vz)
    - mobject: Mobject to move according to field flow
    - virtual_time: Virtual time parameter for flow simulation
    - suspend_mobject_updating: Whether to pause mobject updaters during flow
    """

def Rotate(
    mobject: Mobject,
    angle: float,
    axis: np.ndarray = OUT,
    about_point: np.ndarray = None,
    **kwargs
) -> Animation:
    """
    Rotate mobject by specified angle around axis.
    
    Single rotation transformation with precise angular control
    and customizable rotation center and axis.
    
    Parameters:
    - mobject: Mobject to rotate
    - angle: Rotation angle in radians
    - axis: Rotation axis vector (default: OUT for 2D rotation)
    - about_point: Center point for rotation (default: mobject center)
    """

def Rotating(
    mobject: Mobject,
    angle: float = TAU,
    axis: np.ndarray = OUT,
    about_point: np.ndarray = None,
    run_time: float = 1.0,
    rate_func: Callable = linear,
    **kwargs
) -> Animation:
    """
    Continuous rotation animation for specified duration.
    
    Creates smooth, continuous rotation motion that can represent
    spinning objects, orbital motion, or other rotational effects.
    
    Parameters:
    - mobject: Mobject to rotate continuously
    - angle: Total rotation angle (default: full rotation)
    - axis: Rotation axis vector
    - about_point: Center point for rotation
    - run_time: Duration of rotation animation
    - rate_func: Rate function controlling rotation speed variation
    """

def ChangingDecimal(
    decimal_number_mobject: DecimalNumber,
    number_update_func: Callable[[float], float],
    **kwargs
) -> Animation:
    """
    Smoothly animate changes in decimal number display.
    
    Updates decimal number mobject continuously based on a function
    that maps animation progress to numerical values.
    
    Parameters:
    - decimal_number_mobject: DecimalNumber mobject to animate
    - number_update_func: Function mapping animation progress [0,1] to number values
    """

def ChangeDecimalToValue(
    decimal_number_mobject: DecimalNumber,
    target_number: float,
    **kwargs
) -> Animation:
    """
    Animate decimal number to specific target value.
    
    Smoothly transitions displayed number from current value
    to target value with interpolated intermediate values.
    
    Parameters:
    - decimal_number_mobject: DecimalNumber mobject to change
    - target_number: Target numerical value to reach
    """

def Broadcast(
    focal_point: np.ndarray | Mobject,
    n_mobs: int = 5,
    lag_ratio: float = 0.2,
    run_time: float = 3.0,
    **kwargs
) -> AnimationGroup:
    """
    Create expanding broadcast/ripple effect from focal point.
    
    Generates concentric expanding shapes that simulate broadcasting,
    sound waves, or signal propagation effects.
    
    Parameters:
    - focal_point: Center point or mobject for broadcast origin
    - n_mobs: Number of expanding broadcast rings
    - lag_ratio: Delay between successive rings
    - run_time: Total duration of broadcast effect
    """

def ShowPartial(
    mobject: VMobject,
    a: float = 0.0,
    b: float = 1.0,
    **kwargs
) -> Animation:
    """
    Show partial rendering of VMobject from fraction a to b.
    
    Reveals portion of path-based mobject, useful for drawing
    curves progressively or highlighting specific segments.
    
    Parameters:
    - mobject: VMobject to show partially
    - a: Starting fraction of path to show [0, 1]
    - b: Ending fraction of path to show [0, 1]
    """

def SpiralIn(
    mobject: Mobject,
    scale_factor: float = 8,
    **kwargs
) -> Animation:
    """
    Create spiraling appearance animation.
    
    Object appears while following an inward spiral path,
    creating dramatic entrance effect.
    
    Parameters:
    - mobject: Mobject to spiral in
    - scale_factor: Initial spiral radius multiplier
    """

def AnimatedBoundary(
    vmobject: VMobject,
    boundary_color: str = WHITE,
    boundary_width: float = 3,
    **kwargs
) -> Animation:
    """
    Create animated boundary around VMobject.
    
    Displays moving boundary that traces the perimeter
    of the object, useful for emphasis and highlighting.
    
    Parameters:
    - vmobject: VMobject to create animated boundary around
    - boundary_color: Color of animated boundary
    - boundary_width: Width of boundary line
    """

def TracedPath(
    mobject: Mobject,
    traced_point_func: Callable = None,
    stroke_width: float = 2,
    stroke_color: str = WHITE,
    **kwargs
) -> Animation:
    """
    Create trail following mobject's movement path.
    
    Draws persistent trail that shows the path taken by
    a moving object, useful for trajectory visualization.
    
    Parameters:
    - mobject: Mobject whose path to trace
    - traced_point_func: Function determining which point of mobject to trace
    - stroke_width: Width of traced path line
    - stroke_color: Color of traced path
    """

def AnimationGroup(
    *animations: Animation,
    group: Group = None,
    run_time: float = None,
    rate_func: Callable = None,
    lag_ratio: float = 0,
    **kwargs
) -> Animation:
    """
    Play multiple animations simultaneously with coordinated timing.
    
    All animations start together but can have different durations and
    rate functions. The group completes when all animations finish.
    
    Parameters:
    - *animations: Animations to play together
    - group: Group containing mobjects for all animations
    - run_time: Override run time for all animations
    - rate_func: Rate function applied to all animations
    - lag_ratio: Stagger start times between animations
    """

def Succession(
    *animations: Animation,
    **kwargs
) -> Animation:
    """
    Play animations one after another in sequence.
    
    Each animation completes before the next begins, creating
    a linear sequence of animation events.
    
    Parameters:
    - *animations: Animations to play in sequence
    """

def LaggedStart(
    *animations: Animation,
    lag_ratio: float = 0.05,
    **kwargs
) -> Animation:
    """
    Start animations with staggered delays for cascade effect.
    
    Each subsequent animation starts after a delay, creating
    a wave-like or cascade animation pattern.
    
    Parameters:
    - *animations: Animations to stagger
    - lag_ratio: Delay factor between animation starts
    """

def LaggedStartMap(
    AnimationClass: type,
    mobjects: list[Mobject],
    arg_creator: Callable = None,
    run_time: float = 2,
    **kwargs
) -> Animation:
    """
    Apply same animation type to multiple mobjects with staggered starts.
    
    Convenient way to create coordinated effects across multiple objects
    without manually creating individual animations.
    
    Parameters:
    - AnimationClass: Type of animation to apply
    - mobjects: List of mobjects to animate
    - arg_creator: Function to create custom args for each mobject
    - run_time: Duration for the complete sequence
    """

from manim import *

class AnimationExample(Scene):
    def construct(self):
        circle = Circle()
        square = Square()
        
        # Creation animations
        self.play(Create(circle))
        self.wait(0.5)
        
        # Transform animations
        self.play(Transform(circle, square))
        self.wait(0.5)
        
        # Indication animations
        self.play(Indicate(square, scale_factor=1.5))
        self.wait(1)

class CompositionExample(Scene):
    def construct(self):
        shapes = VGroup(*[Circle().shift(i*RIGHT) for i in range(5)])
        
        # Simultaneous animations
        self.play(
            AnimationGroup(
                *[Create(shape) for shape in shapes],
                lag_ratio=0.1
            )
        )
        
        # Sequential animations
        self.play(
            Succession(
                *[Indicate(shape) for shape in shapes]
            )
        )
        
        # Staggered animations
        self.play(
            LaggedStart(
                *[FadeOut(shape) for shape in shapes],
                lag_ratio=0.2
            )
        )

class TransformExample(Scene):
    def construct(self):
        equation1 = MathTex("x^2 + 2x + 1")
        equation2 = MathTex("(x + 1)^2")
        
        self.play(Write(equation1))
        self.wait(1)
        
        # Transform with custom path
        self.play(
            ReplacementTransform(
                equation1, equation2,
                path_arc=PI/2,
                run_time=2
            )
        )
        
        # Apply function transformation
        self.play(
            ApplyFunction(
                lambda mob: mob.scale(2).set_color(RED),
                equation2
            )
        )