Feat/fireflies

CHANGELOG.md

@@ -39,12 +39,16 @@
   identical rendered output.
 * Motion segment events now trigger `SEGMENT_ENTERED` before `SEGMENT_EXITED` for segments that are completely crossed
   in a single path step, matching the documented enter/exit event semantics.
+* `Canvas._anchor_text()` now accepts an empty input-character list so whitespace-only Python API input can be handled
+  by effects as a quiet canvas instead of raising during terminal construction.
 
 #### Effects Changes (0.16.0)
 
 ---
 
 * Burn smoke now uses `ParticlePool` for pooled helper characters and event-based reclaim behavior.
+* Added Fireflies, a calm nighttime effect with independently blinking input-character lights, bounded curved
+  wandering, spatial gathering, staggered landing illumination, pooled atmospheric helpers, and a final warm pulse.
 * LaserEtch sparks now use `ParticlePool` for pooled helper characters and event-based reclaim behavior.
 
 ### Bug Fixes (0.16.0)

README.md

@@ -189,7 +189,7 @@ View the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for
   Effect:
   Name of the effect to apply. Use <effect> -h for effect specific help.
 
-  {beams,binarypath,blackhole,bouncyballs,bubbles,burn,colorshift,crumble,decrypt,errorcorrect,expand,fireworks,highlight,laseretch,matrix,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slice,slide,smoke,spotlights,spray,swarm,sweep,synthgrid,thunderstorm,unstable,vhstape,waves,wipe}
+  {beams,binarypath,blackhole,bouncyballs,bubbles,burn,colorshift,crumble,decrypt,errorcorrect,expand,fireflies,fireworks,highlight,laseretch,matrix,middleout,orbittingvolley,overflow,pour,print,rain,randomsequence,rings,scattered,slice,slide,smoke,spotlights,spray,swarm,sweep,synthgrid,thunderstorm,unstable,vhstape,waves,wipe}
                         Available Effects
     beams               Create beams which travel over the canvas illuminating the characters behind them.
     binarypath          Binary representations of each character move towards the home coordinate of the character.
@@ -202,6 +202,7 @@ View the [Documentation](https://chrisbuilds.github.io/terminaltexteffects/) for
     decrypt             Display a movie style decryption effect.
     errorcorrect        Some characters start in the wrong position and are corrected in sequence.
     expand              Expands the text from a single point.
+    fireflies           Fireflies drift through the night and gradually illuminate the text.
     fireworks           Characters launch and explode like fireworks and fall into place.
     highlight           Run a specular highlight across the text.
     laseretch           A laser etches characters onto the terminal.

docs/effects/fireflies.md

@@ -0,0 +1,18 @@
+# Fireflies
+
+Fireflies drift in from the canvas edges, blink independently, gather around hidden character positions, and gradually illuminate the original text.
+
+## Quick Start
+
+``` py title="fireflies.py"
+from terminaltexteffects.effects.effect_fireflies import Fireflies
+
+effect = Fireflies("YourTextHere")
+with effect.terminal_output() as terminal:
+    for frame in effect:
+        terminal.print(frame)
+```
+
+The effect uses input characters as its primary fireflies, so their original symbols, coordinates, and final colors are restored exactly. On tiny canvases, orbiting and atmospheric helpers are reduced while blinking and illumination remain active.
+
+::: terminaltexteffects.effects.effect_fireflies

docs/showroom.md

@@ -466,6 +466,36 @@ Characters expand from the center.
     ```
 ---
 
+## Fireflies
+
+Fireflies drift in from the canvas edges, blink independently, gather around hidden text positions, and illuminate the original text in uneven clusters.
+
+[Reference](./effects/fireflies.md){ .md-button } [Config](./effects/fireflies.md#terminaltexteffects.effects.effect_fireflies.FirefliesConfig){ .md-button }
+
+??? example "Fireflies Command Line Arguments"
+
+    ```
+    --firefly-colors (XTerm [0-255] OR RGB Hex [000000-ffffff]) [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
+                        Colors used from dimmest to brightest while fireflies blink. (default: ('6b5c20', 'd4a72c', 'fff2a1'))
+    --firefly-symbols (ASCII/UTF-8 character) [(ASCII/UTF-8 character) ...]
+                        One-cell symbols used in sequence while fireflies blink. (default: ('.', '*', 'o', '*'))
+    --movement-speed (float > 0)
+                        Base movement speed for fireflies. Individual speeds vary around this value. (default: 0.18)
+    --wander-cycles (int > 0)
+                        Maximum number of wandering waypoints before a firefly gathers near the text. (default: 3)
+    --auxiliary-count (int >= 0)
+                        Maximum number of atmospheric fireflies. Tiny canvases automatically use fewer. (default: 6)
+    --final-gradient-stops (XTerm [0-255] OR RGB Hex [000000-ffffff]) [(XTerm [0-255] OR RGB Hex [000000-ffffff]) ...]
+                        Space separated, unquoted, list of colors for the character gradient (applied across the canvas). If only one color is provided, the characters will be displayed in that color. (default: ('3f4f24', 'd6a928', 'ffe680'))
+    --final-gradient-steps (int > 0) [(int > 0) ...]
+                        Space separated, unquoted, list of the number of gradient steps to use. More steps will create a smoother and longer gradient animation. (default: 12)
+    --final-gradient-direction (diagonal, horizontal, vertical, radial)
+                        Direction of the final gradient across the text. (default: Direction.HORIZONTAL)
+
+    Example: terminaltexteffects fireflies --firefly-colors 6b5c20 d4a72c fff2a1 --firefly-symbols . '*' o '*' --movement-speed 0.18 --wander-cycles 3 --auxiliary-count 6 --final-gradient-stops 3f4f24 d6a928 ffe680 --final-gradient-steps 12 --final-gradient-direction horizontal
+    ```
+---
+
 ## Fireworks
 
 Launches characters up the screen where they explode like fireworks and fall into place.

mkdocs.yml

@@ -110,6 +110,7 @@ nav:
       - effects/decrypt.md
       - effects/errorcorrect.md
       - effects/expand.md
+      - effects/fireflies.md
       - effects/fireworks.md
       - effects/highlight.md
       - effects/laseretch.md

terminaltexteffects/effects/__init__.py

@@ -11,6 +11,7 @@
 from terminaltexteffects.effects.effect_decrypt import Decrypt
 from terminaltexteffects.effects.effect_errorcorrect import ErrorCorrect
 from terminaltexteffects.effects.effect_expand import Expand
+from terminaltexteffects.effects.effect_fireflies import Fireflies
 from terminaltexteffects.effects.effect_fireworks import Fireworks
 from terminaltexteffects.effects.effect_highlight import Highlight
 from terminaltexteffects.effects.effect_laseretch import LaserEtch