ChrisBuilds/terminaltexteffects release-0.15.0

0.15.0 - Go Fetch

on GitHub

0.15.0

New Features (0.15.0)

• Added effect discovery support for user provided effects. Effects should be Python files located at
  XDG_CONFIG_HOME/terminaltexteffects/effects. (e.g. /home/me/.config/terminaltexteffects/effects/effect_custom.py)
• Added shell completion generation for bash and zsh via tte --print-completion {bash,zsh}.

Application Changes (0.15.0)

• The CLI parser is now built through a shared parser-construction path so runtime argument parsing, help text, and generated shell completions all use the same discovered effect and option definitions.
• Generated shell completions now include user-provided effects discovered from XDG_CONFIG_HOME/terminaltexteffects/effects at completion-generation time.
• The zsh completion script now self-initializes compinit and bashcompinit when needed so eval "$(tte --print-completion zsh)" works with less shell setup friction.
• The CLI version flag now falls back to the local pyproject.toml version when running from a source checkout without installed package metadata.

Engine Changes (0.15.0)

• Added shared gradient argument helpers (FinalGradientStopsArg, FinalGradientStepsArg, FinalGradientFramesArg, FinalGradientDirectionArg) for effect configs to standardize CLI defaults and parsing.
• Updated all effects to use gradient argument helpers.
• Updated all effects parser epilog example help text to reflect up to date defaults.
• SpanningTreeGenerator.get_neighbors() now honors unlinked_only=False by returning linked and unlinked neighbors, matching the documented API.
• Added focused unit test coverage for spanning-tree generators, including SpanningTreeGenerator, RecursiveBacktracker, PrimsSimple, PrimsWeighted, BreadthFirst, and AldousBroder.
• Clarified RecursiveBacktracker documentation to describe the depth-first spanning-tree behavior, initialized state, and delayed completion semantics accurately.
• PrimsSimple now applies limit_to_text_boundary consistently when deciding whether a newly linked character remains in the edge set, and its documentation now reflects the generator's actual state transitions.
• PrimsWeighted now limits random starting-character selection to the text boundary when requested, and its documentation now explains the per-character weighting model and completion behavior more accurately.
• BreadthFirst now initializes correctly when starting_char is omitted, records each discovered character only once with the correct parent frontier node, and has updated traversal documentation.
• AldousBroder now returns immediately once all characters are linked, and its documentation now matches the generator's state transitions and project docstring style.
• existing_color_handling="always" is now applied consistently by the animation engine for input-derived characters, including when the parsed input has no colors. Helper and fill characters remain effect-colored instead of being cleared by the engine.
• Terminal input preprocessing now supports common fetch-application layout sequences by interpreting cursor movement CSI sequences (A, B, C, D, E, F, G, H, and f) into TTE's virtual input canvas instead of rendering the escape sequences as text.
• Terminal input preprocessing now accepts common fetch-application DEC private mode toggles for cursor visibility and line wrapping (?25h, ?25l, ?7h, and ?7l) as no-op input state while continuing to reject unsupported terminal control sequences.
• Existing ANSI color parsing now supports 3-bit and 4-bit SGR foreground/background colors, reset sequences, and mixed style/color SGR sequences used by applications such as neofetch and fastfetch.
• Parsed input bold state is now preserved for existing_color_handling="always", and bold standard ANSI foreground colors now resolve to their bright color equivalents for closer visual parity with normal terminal-rendered fetch output.
• Added manual visual sequence tests for mixed ANSI color input and fetch-style layout/style input across existing_color_handling modes dynamic, always, and ignore, with printed parameter headers to make captured visual output easier to identify.
• Updated engine.motion documentation to accurately describe waypoint fields, bezier control handling, path runtime state, activation-side path mutation, looping behavior, and documented exceptions.
• Updated engine.animation documentation to accurately describe scene lookup behavior, scene sync and completion semantics, frame/color override rules, activation/reset expectations, and current TODO-backed gaps around dim formatting, duplicate scene IDs, and unused scene-step tracking.
• Updated engine.terminal documentation to better describe canvas sizing and anchoring, input preprocessing, character/fill tracking, rendering state, cursor management, and sort/lookup behavior, and hardened enforce_framerate() so a configured frame rate of 0 safely disables frame limiting even when the method is called directly.
• Updated engine.base_effect documentation to clarify iterator creation semantics, frame retrieval and active-character lifecycle behavior, preexisting input-color detection, and terminal-output restoration behavior, plus fixed a small module docstring typo.
• motion.deactivate_path() now accepts a Path, a path ID string, or no argument, with the no-argument form deactivating the current active path when present.
• EventHandler.Action.DEACTIVATE_PATH event registrations now support a Path, a path ID string, or None, and focused engine tests cover the expanded deactivation behavior.
• animation.deactivate_scene() now accepts a Scene, a scene ID string, or no argument, with the no-argument form deactivating the current active scene when present.
• EventHandler.Action.DEACTIVATE_SCENE event registrations now support a Scene, a scene ID string, or None, and focused engine tests cover the expanded deactivation behavior.
• Updated engine.base_character documentation to reflect object-based event registration, expanded path and scene deactivation behavior, EffectCharacter runtime state, and the current ordering and reset semantics used during character updates and event handling.
• Updated engine.base_config documentation to clarify parser_spec requirements, ArgSpec-based config construction, and _build_config() fallback and error behavior.
• Updated utils.argutils documentation to remove stale module references and better describe parser specs, argument specs, tuple normalization, range validators, symbol validation, canvas dimensions, and easing parser return values.
• Updated utils.ansitools documentation to clarify ANSI color parsing normalization and cursor movement indexing and relative movement behavior.
• Updated utils.colorterm documentation to clarify RGB tuple conversion, ANSI selector meanings, and accepted XTerm and hex color inputs.
• Updated utils.easing documentation to remove stale motion-specific wording and better describe sequence-prefix easing, clamp behavior, and stepwise added/removed slice tracking.
• Updated utils.geometry documentation to clarify zero-size rectangle behavior, ray extrapolation wording, sampled bezier-length approximation, and the module's public helper list.
• Updated utils.graphics documentation to align Color, ColorPair, and Gradient docs with stored Color objects, discrete spectrum lookup behavior, color normalization, and color-shift interpolation and extrapolation semantics.
• Updated utils.hexterm documentation to clarify accepted color types, nearest-color matching behavior, return types, and the module's mapping-focused summary.
• Color.__str__() and ColorPair.__str__() now correctly include valid XTerm color 0 in their output, and focused utility tests cover the regression.
• shift_color_towards() now uses an LRU cache to avoid recomputing repeated color transitions during effect rendering.
• Updated the terminaltexteffects.__main__ entry-point documentation to describe effect discovery, plugin loading, duplicate-command validation, and the CLI's input and exit behavior more accurately.

Effects Changes (0.15.0)

• BouncyBalls - Added existing_color_handling="dynamic" support. Balls still fall using the effect's ball colors, and on settle they now transition to the input symbol plus any parsed input ANSI fg/bg colors. Characters without parsed input colors settle with no explicit final color so they render using the terminal default color.
• Beams - Fixed existing_color_handling="dynamic" final-state handling so characters with parsed input ANSI fg/bg colors settle back to those input colors, while characters without parsed input colors now finish with no explicit color and render using the terminal default color.
• BinaryPath - Fixed existing_color_handling="dynamic" final-state handling so characters now settle back to any parsed input ANSI fg/bg colors on a per-channel basis, and characters without parsed input colors finish with no explicit color and render using the terminal default color.
• Bubbles - Added existing_color_handling="dynamic" support. Bubbles still float and pop using the effect's own colors, and after popping characters now transition to the input symbol plus any parsed input ANSI fg/bg colors. Characters without parsed input colors settle with no explicit final color so they render using the terminal default color.
• Burn - Added existing_color_handling="dynamic" support. Characters still ignite and burn using the effect's own colors, and after the burn scene completes they now transition to the input symbol plus any parsed input ANSI fg/bg colors. Characters without parsed input colors settle with no explicit final color so they render using the terminal default color. Burn now processes input spaces that carry parsed ANSI colors in dynamic and always modes, preserving background-colored swatch cells.
• ColorShift - Added existing_color_handling="dynamic" support for the final settle transition. Characters still play the effect's shifting gradient animation, and when the final gradient runs they now transition to the input symbol plus any parsed input ANSI fg/bg colors. Characters without parsed input colors settle with no explicit final color so they render using the terminal default color.
• Crumble - Added existing_color_handling="dynamic" support for the faded intro and post-flash settle scenes. Characters with parsed input ANSI fg/bg colors now crumble using faded versions of those colors and settle back to their input colors, while characters without parsed input colors start from a neutral gray and settle with no explicit final color.
• Decrypt - Added existing_color_handling="dynamic" support in the discovered scene. Characters keep the effect's ciphertext colors during typing and decryption, then transition to any parsed input ANSI fg/bg colors when discovered. Characters without parsed input colors finish with no explicit color so they render using the terminal default color.
• ErrorCorrect - Added existing_color_handling="dynamic" support. Characters that are never swapped now use parsed input ANSI fg/bg colors from the start, while swapped characters keep the effect's error/correction colors until the final block wipe and settle scene, where they now resolve to their input colors or no explicit color if none were parsed.
• Expand - Added existing_color_handling="dynamic" support in the synced final gradient scene, so characters now expand outward using the effect's starting settle color and resolve to any parsed input ANSI fg/bg colors or no explicit color if none were parsed. The effect's --final-gradient-frames option was removed because the synced scene now progresses by path distance rather than frame duration.
• Fireworks - Added existing_color_handling="dynamic" support in fall_scn. Firework launch and bloom phases remain effect-colored, and when characters fall into place they now transition to any parsed input ANSI fg/bg colors or to no explicit color if none were parsed.
• Highlight - Added existing_color_handling="dynamic" support based on parsed input foreground colors. Characters with input fg colors now use that color as the highlight base and return color, while characters without input fg colors remain in terminal default color and receive no visible highlight effect. Highlight now preserves parsed input background colors on base and highlight frames, including bg-only input spaces used by the visual swatches.
• LaserEtch - Added existing_color_handling="dynamic" support in the etched character cooling scene. Characters with parsed input ANSI fg/bg colors now cool directly from the effect's heat colors into those input colors, while characters without parsed input colors cool to white and then finish with no explicit color so they render using the terminal default color. LaserEtch now etches input spaces that carry parsed ANSI colors instead of skipping them, preserving background-colored swatch cells.
• Matrix - Added existing_color_handling="dynamic" support in the resolve scene. Matrix rain, fill, highlight, and symbol-swapping phases remain effect-colored, and when characters resolve they now transition to any parsed input ANSI fg/bg colors or to no explicit color if none were parsed. Matrix now resolves input spaces that carry parsed ANSI colors instead of hiding them, preserving background-colored swatch cells.
• MiddleOut - Added existing_color_handling="dynamic" support in the full scene after the center phase completes. Characters still begin from the effect's starting_color, then transition to any parsed input ANSI fg/bg colors or to no explicit color if none were parsed.
• OrbittingVolley - Added existing_color_handling="dynamic" support for launched input characters. The orbiting launcher visuals remain effect-colored, while launched characters now use any parsed input ANSI fg/bg colors immediately or no explicit color if none were parsed.
• Pour - Added existing_color_handling="dynamic" support in the pour gradient scene. Characters still begin from the effect's starting_color, then transition to any parsed input ANSI fg/bg colors or to no explicit color if none were parsed.
• Print - Added existing_color_handling="dynamic" support in the typed animation scene. Characters still show the print-head block symbols and color while being typed, then resolve to any parsed input ANSI fg/bg colors or to no explicit color if none were parsed.
• Rain - Added existing_color_handling="dynamic" support in fade_scn. Characters still fall as rain-colored rain symbols, and when they reach their input coordinates they now fade into any parsed input ANSI fg/bg colors or to no explicit color if none were parsed.
• RandomSequence - Added existing_color_handling="dynamic" support in the fade-in scene. Characters with parsed input ANSI fg/bg colors now fade in to those input colors, while uncolored characters fade through neutral gray and then finish with no explicit color applied.
• Rings - Added existing_color_handling="dynamic" support that uses parsed input ANSI fg/bg colors or no color throughout the entire effect. In dynamic mode, the start, ring, and disperse phases no longer apply effect-owned ring colors.
• Scattered - Added existing_color_handling="dynamic" support that uses parsed input ANSI fg/bg colors or no color for the entire synced movement scene. In dynamic mode, no effect-owned gradient colors are applied during the effect.
• Slice - Added existing_color_handling="dynamic" support that uses parsed input ANSI fg/bg colors or no color for the entire effect. In dynamic mode, no effect-owned final gradient colors are applied while the sliced groups move into place.
• Slide - Added existing_color_handling="dynamic" support that uses parsed input ANSI fg/bg colors or no color for the entire effect. In dynamic mode, no effect-owned gradient colors are applied while character groups slide into place.
• Smoke - Added existing_color_handling="dynamic" support that starts characters in black, then reveals them using parsed input ANSI fg/bg colors or no color. In dynamic mode, the smoke and paint phases no longer use effect-owned colors.
• Spotlights - Completed existing_color_handling="dynamic" support with per-channel bright and dim input-color handling. Colored characters now start as faded input colors, uncolored characters start as faded neutral gray, and the final spotlight expand clears temporary fallback foreground color so bg-only or uncolored characters finish without an unintended fg color. Spotlights now illuminates input spaces that carry parsed ANSI colors, preserving background-colored swatch cells during illumination and final expand.
• Spray - Added existing_color_handling="dynamic" support that uses parsed input ANSI fg/bg colors or no color for the entire effect. In dynamic mode, the spray scene no longer applies effect-owned gradient colors.
• Swarm - Added existing_color_handling="dynamic" support in the landing input_scn. Swarm and flash motion remain effect-colored, and settling characters now transition to parsed input ANSI fg/bg colors or to no explicit color if none were parsed.
• Sweep - Added existing_color_handling="dynamic" support in the second sweep scene. The first sweep remains unchanged, the second sweep shimmer now draws from parsed input ANSI fg/bg colors when available, and characters finish in their input colors or with no explicit color if none were parsed.
• SynthGrid - Added existing_color_handling="dynamic" support at the end of dissolve_scn. The dissolve shimmer remains effect-colored, and the final dissolve frame now resolves to parsed input ANSI fg/bg colors or to no explicit color if none were parsed. SynthGrid now applies final input colors to input spaces as well as visible symbols, preserving background-colored swatch cells.
• Thunderstorm - Added existing_color_handling="dynamic" support from the beginning of the effect. Text characters now start from parsed input ANSI colors or neutral gray, fade down for the storm, still use the normal lightning flash/glow behavior, and return after the storm to normal input brightness or to no explicit color for originally uncolored text.
• Unstable - Added existing_color_handling="dynamic" support from the start of the effect. Characters now begin in parsed input ANSI fg/bg colors or neutral gray, still shift toward the effect's unstable color during rumble, and then coalesce back to their input colors or to no explicit color if none were parsed.
• VHSTape - Added existing_color_handling="dynamic" support for the stable text phases and final redraw. Characters now rest in parsed input ANSI fg/bg colors or neutral gray, effect-colored glitch and noise scenes remain unchanged, and the final redraw resolves to input colors or to no explicit color if none were parsed.
• Waves - Added existing_color_handling="dynamic" support for the steady state and final settle. Characters now start and end in parsed input ANSI fg/bg colors or with no explicit color if none were parsed, while the animated wave itself continues to use the effect's own symbols and colors unchanged.
• Wipe - Added existing_color_handling="dynamic" support for the entire wipe scene. In dynamic mode, all wipe frames now use parsed input ANSI fg/bg colors or no explicit color, and the effect-owned wipe gradient is no longer applied.
• Overflow - Fixed existing_color_handling="dynamic" final-row handling so uncolored characters no longer pick up the final gradient color and instead remain uncolored. Final rows with parsed input ANSI fg/bg colors continue to preserve those input colors.