staticfx 2.0.0__tar.gz

staticfx-2.0.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## 2.0.0 (2026-11-07)
+
+A rewrite. Your settings, favourites, looks and Studio effects carry over
+automatically.
+
+### New
+
+- An effect browser with groups (Favourites, Recent, My Effects, Gallery,
+  seven built-in categories, Generated), search that ranks name matches first,
+  and live preview beside the list.
+- A Gallery of 47 of the best generated effects, picked by hand.
+- A settings screen (`o`): frame rate, character set, colour mode,
+  auto-cycle interval, and rebinding any key, with conflict warnings.
+- A welcome card on first run, an optional status bar (`i`), and a key hint
+  line on start-up.
+- In the Studio, every control has a real name and range, with a one-line
+  explanation of the selected setting; save as a copy (`a`); unlimited undo.
+- Subcommands: `list`, `themes`, `looks`, `new`, `import`, `export`,
+  `render`, `fetch`, `doctor`. The 1.x flags still work.
+- `staticfx doctor` checks your terminal and saved files and renders
+  every effect once.
+- 26 themes, up from 13, including takes on Dracula, Nord, Gruvbox,
+  Solarized, Catppuccin and Tokyo Night. The theme menu shows each palette.
+- Plain keys everywhere: menus no longer need Ctrl combinations: in the
+  browser `/` searches and `f`, `e`, `n`, `d` act on the highlighted effect.
+  Letters work with or without Shift, and every menu closes with `q`.
+- Built-in looks reworked into twelve, each with a description.
+- Meteor Shower has a twinkling sky; Fireworks fill large terminals.
+- Docs: usage guide, Studio guide, file format, writing effects, architecture.
+
+### Changed
+
+- One procedural engine: 1.x had two (`proc_*` and `gen_*`). The
+  `gen_*` effects are gone; favourites pointing at them are dropped
+  quietly. `proc_*` effects look the same as before.
+- One `.sfx` format (version 3) with readable keys; 1.x Studio files
+  (version 2) and 1.x plugins are converted when read; old plugins are copied
+  into My Effects once.
+- An automated quality gate removes 8 generated effects that were blank,
+  frozen, or a solid wall.
+- Strobe is hidden until you allow flashing in Settings, and the theme
+  menu never previews it unless you have.
+- The 1.x key that cycled rainbow and strobe is gone: Rainbow is a normal theme now. The old
+  "rainbow" overlay is called **recolour** (`w`) and keeps the effect's
+  shading.
+- Presets and hacker scenes are merged into **looks**.
+- The theme `monochrome` is now `mono` (the old name still works).
+- Only rows that changed are redrawn each frame.
+
+### Fixed
+
+- A deleted effect or an unknown theme in `config.json` no longer stops
+  StaticFX from starting; any bad setting is ignored with a message.
+- Ctrl-C in the Studio asks before discarding your work instead of quitting.
+- Ctrl-Z suspends cleanly and restores the screen on `fg`.
+- A user effect named like a built-in (`plasma`) no longer hides the
+  built-in on the command line.
+- Plugin effects deleted in the menu came back on restart.
+- Hand-edited config values of the wrong type were accepted silently.
+- Below 40×12, a "terminal too small" message replaces menus that used to
+  draw over each other.
+- Glyphs outside the terminal's character set could appear in ASCII mode.
+
+### Removed
+
+- The `gen_*` engine and the hidden `--plugin-dir` option.
+
+## 1.0.0
+
+First release: 50 built-in effects, 2,000 procedural effects in two
+families, themes, looks, the Effect Studio and `.sfx` sharing.

staticfx-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing
+
+Thanks for wanting to help. Bug reports, new effects and fixes are all
+welcome.
+
+## Setting up
+
+```bash
+git clone https://github.com/ethanlabs101/StaticFX && cd StaticFX
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+StaticFX itself has no dependencies; those three are only for development.
+The scripts in `tools/` also need Pillow (and `tools/demo.py` needs ffmpeg).
+
+## Before you open a pull request
+
+```bash
+pytest                       # everything, including real-terminal tests
+ruff check . && ruff format --check .
+mypy
+```
+
+CI runs the same on Linux and macOS with Python 3.10 to 3.13.
+
+## Where things go
+
+[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) maps the code. In short:
+
+- A new hand-written effect: [docs/WRITING_EFFECTS.md](docs/WRITING_EFFECTS.md).
+- A new layer, warp or filter for the engine: add a function and a `Kind`
+  entry in `staticfx/effects/engine/layers.py` (or `warps.py`,
+  `filters.py`), then run `python tools/gen_docs.py` to update the format
+  reference. The Studio picks it up by itself.
+- A new screen: subclass `Screen` in `staticfx/ui/`, give it a `help` tuple,
+  and add a test in `tests/test_ui.py`. It gets drawn at the minimum terminal
+  size and in ASCII mode automatically if you add it to `OPENERS` there.
+- A new main-view key: add the action to `ACTIONS` and a default to
+  `DEFAULT_KEYS` in `staticfx/app/keymap.py`, and its handler in
+  `PlayScreen.actions`. A test checks the three agree, and another checks the
+  usage guide mentions it.
+
+## Things that need care
+
+- **Generated effects must not change by accident.** `test_engine.py`
+  fingerprints all 1,000 recipes. If you change `generate.py` or the
+  maths behind an existing layer, warp or filter, the fingerprint changes and
+  everyone's `proc_NNN` favourites point at different pictures. Do it only on
+  purpose, update the fingerprint, rerun `python tools/curate.py`, and note it
+  in the changelog.
+- **Effect keys are forever.** They're stored in favourites, looks and
+  scripts. Rename the label, never the key.
+- **Saved files must stay readable.** If you change the `.sfx` format or
+  `config.json`, bump the version and keep reading the old one (see
+  `library/legacy.py` and `config._migrate`).
+- **Nothing may stop the app from starting.** Bad files and values are
+  reported and skipped, never raised.
+
+## Style
+
+`ruff format` decides formatting (100 columns). Beyond that: write code for
+the next person to read, keep functions short, name things for what they
+mean, and comment on *why*, not *what*. Docstrings on modules, classes and
+anything non-obvious; not on every getter.
+
+## Reporting a bug
+
+Please include the output of `staticfx doctor`, your terminal and OS, and
+what you pressed. If an effect looks wrong, `staticfx render EFFECT --ansi
+--seed 1 --out frame.txt` captures it exactly.

staticfx-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ethangrames04
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

staticfx-2.0.0/MANIFEST.in

@@ -0,0 +1,9 @@
+# The source distribution carries the tests, docs and examples so it can be
+# checked and repackaged on its own. Screenshots stay on GitHub.
+include CHANGELOG.md CONTRIBUTING.md
+graft docs
+graft examples
+graft tests
+graft tools
+prune assets
+global-exclude __pycache__ *.py[cod]

staticfx-2.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: staticfx
+Version: 2.0.0
+Summary: Animated ASCII effects for your terminal, with a studio for making your own
+Author: ethanlabs101
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ethanlabs101/StaticFX
+Project-URL: Documentation, https://github.com/ethanlabs101/StaticFX/blob/main/docs/USAGE.md
+Project-URL: Changelog, https://github.com/ethanlabs101/StaticFX/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ethanlabs101/StaticFX/issues
+Keywords: terminal,ascii,animation,cmatrix,screensaver,tui,ascii-art
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# StaticFX
+
+Animated ASCII effects for your terminal. Think `cmatrix`, but with a
+thousand more effects, live theme switching, and a studio for making your own.
+
+![StaticFX demo: Matrix rain, the effect browser, a galaxy, the Studio](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/demo.gif)
+
+Pure Python, no dependencies, runs in any modern terminal on Linux, macOS
+and WSL.
+
+## Install
+
+You need Python 3.10 or newer.
+
+```bash
+pipx install staticfx
+staticfx
+```
+
+(`pip install staticfx` works too; [pipx](https://pipx.pypa.io) just keeps it in
+its own environment.) To try it without installing anything:
+
+```bash
+git clone https://github.com/ethanlabs101/StaticFX
+cd StaticFX
+python3 -m staticfx
+```
+
+## The 30-second tour
+
+Key | Does
+--- | ---
+`←` `→` | Previous / next effect
+`m` | Browse and search every effect, with live preview
+`t` | Change the colour theme
+`l` | Looks: effect + theme + filters, saved under a name
+`n` | Make your own effect in the Studio
+`f` | Favourite
+`a` | Auto-cycle (screensaver mode)
+`?` | Every key
+`q` | Quit
+
+Everything is remappable in Settings (`o`). The full guide is in
+[docs/USAGE.md](https://github.com/ethanlabs101/StaticFX/blob/main/docs/USAGE.md).
+
+## What's inside
+
+There are 50 hand-written effects in seven groups. Rain: the classic, plus
+binary, hex and glitch versions. Particles: snow, embers, fireworks, orbits.
+Space: a starfield, a galaxy, a black hole, a wormhole. Waves and fields:
+plasma, aurora, a lava lamp, a synthwave grid. Geometry: a tumbling cube, a 4D
+tesseract, spirographs. Simulations: Game of Life, Langton's ant, fire, a maze
+that carves itself. Retro tech: boot screens, decryption, circuits, TV static.
+
+On top of those are 992 generated effects. Each one is a recipe of layered
+patterns (spirals, Julia and Mandelbrot fractals, Voronoi cells, metaballs,
+noise), warps (kaleidoscope, swirl, tile, fold) and filters. They're seeded,
+so `proc_042` is the same effect for everyone, forever. An automated quality
+check weeds out the duds, and 47 hand-picked ones live in the Gallery.
+
+Then there are your own. The Studio remixes any generated effect or starts
+from scratch, with a live preview and undo, and saves small JSON files you
+can share.
+
+You also get:
+
+- **26 colour themes**: originals like Matrix, Inferno and Vaporwave, takes on
+  popular editor schemes (Dracula, Nord, Gruvbox, Catppuccin, Tokyo Night), an
+  animated rainbow, and Strobe if you opt in (it's off by default for
+  photosensitivity reasons)
+- filters that work on anything: CRT scanlines, glitch, rainbow recolour
+- looks, which save an effect with its theme, speed and filters so you can
+  recall it with one key (a dozen come built in)
+
+![The theme menu, with a colour swatch for each theme](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/themes.png)
+
+![The effect browser](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/browser.png)
+
+## Make your own
+
+Press `n` for a new effect, or highlight a generated one in the browser and
+press `e` to remix it. Arrow keys change things; `s` saves it to
+**My Effects**.
+
+![The Effect Studio](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/studio.png)
+
+See [docs/STUDIO.md](https://github.com/ethanlabs101/StaticFX/blob/main/docs/STUDIO.md) for what every control does, and
+[docs/EFFECT_FORMAT.md](https://github.com/ethanlabs101/StaticFX/blob/main/docs/EFFECT_FORMAT.md) for the file format if you'd
+rather write recipes by hand.
+
+## Command line
+
+```bash
+staticfx -e plasma -t ocean           # start on an effect and theme
+staticfx --look "Synthwave"           # start from a look
+staticfx --auto 30 --duration 600     # screensaver: new effect every 30s, quit after 10 min
+staticfx list fire                    # search effects
+staticfx render galaxy --size 80x24   # print one frame (add --ansi for colour)
+staticfx fetch                        # fastfetch/neofetch output over an effect
+staticfx new "Night Drive"            # create a random effect in My Effects
+staticfx export my_night_drive nd.sfx # share it
+staticfx doctor                       # check your setup
+```
+
+`staticfx --help` and `staticfx COMMAND --help` list everything.
+
+## Docs
+
+- [Usage](https://github.com/ethanlabs101/StaticFX/blob/main/docs/USAGE.md): every key, the browser, themes, looks, settings,
+  command line, troubleshooting
+- [The Studio](https://github.com/ethanlabs101/StaticFX/blob/main/docs/STUDIO.md)
+- [Effect file format](https://github.com/ethanlabs101/StaticFX/blob/main/docs/EFFECT_FORMAT.md)
+- [Writing a built-in effect](https://github.com/ethanlabs101/StaticFX/blob/main/docs/WRITING_EFFECTS.md) in Python
+- [Architecture](https://github.com/ethanlabs101/StaticFX/blob/main/docs/ARCHITECTURE.md): how it fits together, and why
+- [Releasing](https://github.com/ethanlabs101/StaticFX/blob/main/docs/RELEASING.md): publishing a new version to PyPI
+
+## Development
+
+```bash
+git clone https://github.com/ethanlabs101/StaticFX && cd StaticFX
+python3 -m pip install -e '.[dev]'
+python3 -m pytest          # ~650 tests, about a minute
+ruff check . && ruff format --check . && mypy
+```
+
+See [CONTRIBUTING.md](https://github.com/ethanlabs101/StaticFX/blob/main/CONTRIBUTING.md) for how changes are made and checked.
+
+## License
+
+[MIT](https://github.com/ethanlabs101/StaticFX/blob/main/LICENSE)

staticfx-2.0.0/README.md

@@ -0,0 +1,130 @@
+# StaticFX
+
+Animated ASCII effects for your terminal. Think `cmatrix`, but with a
+thousand more effects, live theme switching, and a studio for making your own.
+
+![StaticFX demo: Matrix rain, the effect browser, a galaxy, the Studio](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/demo.gif)
+
+Pure Python, no dependencies, runs in any modern terminal on Linux, macOS
+and WSL.
+
+## Install
+
+You need Python 3.10 or newer.
+
+```bash
+pipx install staticfx
+staticfx
+```
+
+(`pip install staticfx` works too; [pipx](https://pipx.pypa.io) just keeps it in
+its own environment.) To try it without installing anything:
+
+```bash
+git clone https://github.com/ethanlabs101/StaticFX
+cd StaticFX
+python3 -m staticfx
+```
+
+## The 30-second tour
+
+Key | Does
+--- | ---
+`←` `→` | Previous / next effect
+`m` | Browse and search every effect, with live preview
+`t` | Change the colour theme
+`l` | Looks: effect + theme + filters, saved under a name
+`n` | Make your own effect in the Studio
+`f` | Favourite
+`a` | Auto-cycle (screensaver mode)
+`?` | Every key
+`q` | Quit
+
+Everything is remappable in Settings (`o`). The full guide is in
+[docs/USAGE.md](https://github.com/ethanlabs101/StaticFX/blob/main/docs/USAGE.md).
+
+## What's inside
+
+There are 50 hand-written effects in seven groups. Rain: the classic, plus
+binary, hex and glitch versions. Particles: snow, embers, fireworks, orbits.
+Space: a starfield, a galaxy, a black hole, a wormhole. Waves and fields:
+plasma, aurora, a lava lamp, a synthwave grid. Geometry: a tumbling cube, a 4D
+tesseract, spirographs. Simulations: Game of Life, Langton's ant, fire, a maze
+that carves itself. Retro tech: boot screens, decryption, circuits, TV static.
+
+On top of those are 992 generated effects. Each one is a recipe of layered
+patterns (spirals, Julia and Mandelbrot fractals, Voronoi cells, metaballs,
+noise), warps (kaleidoscope, swirl, tile, fold) and filters. They're seeded,
+so `proc_042` is the same effect for everyone, forever. An automated quality
+check weeds out the duds, and 47 hand-picked ones live in the Gallery.
+
+Then there are your own. The Studio remixes any generated effect or starts
+from scratch, with a live preview and undo, and saves small JSON files you
+can share.
+
+You also get:
+
+- **26 colour themes**: originals like Matrix, Inferno and Vaporwave, takes on
+  popular editor schemes (Dracula, Nord, Gruvbox, Catppuccin, Tokyo Night), an
+  animated rainbow, and Strobe if you opt in (it's off by default for
+  photosensitivity reasons)
+- filters that work on anything: CRT scanlines, glitch, rainbow recolour
+- looks, which save an effect with its theme, speed and filters so you can
+  recall it with one key (a dozen come built in)
+
+![The theme menu, with a colour swatch for each theme](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/themes.png)
+
+![The effect browser](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/browser.png)
+
+## Make your own
+
+Press `n` for a new effect, or highlight a generated one in the browser and
+press `e` to remix it. Arrow keys change things; `s` saves it to
+**My Effects**.
+
+![The Effect Studio](https://raw.githubusercontent.com/ethanlabs101/StaticFX/main/assets/studio.png)
+
+See [docs/STUDIO.md](https://github.com/ethanlabs101/StaticFX/blob/main/docs/STUDIO.md) for what every control does, and
+[docs/EFFECT_FORMAT.md](https://github.com/ethanlabs101/StaticFX/blob/main/docs/EFFECT_FORMAT.md) for the file format if you'd
+rather write recipes by hand.
+
+## Command line
+
+```bash
+staticfx -e plasma -t ocean           # start on an effect and theme
+staticfx --look "Synthwave"           # start from a look
+staticfx --auto 30 --duration 600     # screensaver: new effect every 30s, quit after 10 min
+staticfx list fire                    # search effects
+staticfx render galaxy --size 80x24   # print one frame (add --ansi for colour)
+staticfx fetch                        # fastfetch/neofetch output over an effect
+staticfx new "Night Drive"            # create a random effect in My Effects
+staticfx export my_night_drive nd.sfx # share it
+staticfx doctor                       # check your setup
+```
+
+`staticfx --help` and `staticfx COMMAND --help` list everything.
+
+## Docs
+
+- [Usage](https://github.com/ethanlabs101/StaticFX/blob/main/docs/USAGE.md): every key, the browser, themes, looks, settings,
+  command line, troubleshooting
+- [The Studio](https://github.com/ethanlabs101/StaticFX/blob/main/docs/STUDIO.md)
+- [Effect file format](https://github.com/ethanlabs101/StaticFX/blob/main/docs/EFFECT_FORMAT.md)
+- [Writing a built-in effect](https://github.com/ethanlabs101/StaticFX/blob/main/docs/WRITING_EFFECTS.md) in Python
+- [Architecture](https://github.com/ethanlabs101/StaticFX/blob/main/docs/ARCHITECTURE.md): how it fits together, and why
+- [Releasing](https://github.com/ethanlabs101/StaticFX/blob/main/docs/RELEASING.md): publishing a new version to PyPI
+
+## Development
+
+```bash
+git clone https://github.com/ethanlabs101/StaticFX && cd StaticFX
+python3 -m pip install -e '.[dev]'
+python3 -m pytest          # ~650 tests, about a minute
+ruff check . && ruff format --check . && mypy
+```
+
+See [CONTRIBUTING.md](https://github.com/ethanlabs101/StaticFX/blob/main/CONTRIBUTING.md) for how changes are made and checked.
+
+## License
+
+[MIT](https://github.com/ethanlabs101/StaticFX/blob/main/LICENSE)

staticfx-2.0.0/docs/ARCHITECTURE.md

@@ -0,0 +1,150 @@
+# Architecture
+
+StaticFX is about 9,000 lines of Python (nearly half of it the effects themselves) with no
+dependencies. This page is
+the map: what lives where, what happens every frame, and why it's built the
+way it is.
+
+## Layers
+
+```
+cli/            parse the command line, run a subcommand
+  │
+app/            the interactive app: settings, player, screen stack, run loop
+  │   ui/       screens (browser, Studio, settings, ...) and drawing helpers
+  │
+effects/        what can be drawn: built-ins, the procedural engine, the registry
+library/        what the user saves: settings, .sfx effects, looks
+  │
+core/           terminal plumbing: colour, frames, rendering, keys, terminal modes
+```
+
+Imports only point down this list. `core` knows nothing about effects;
+`effects` knows nothing about the app; screens reach the app only through
+the `App` object they're given. The one upward reference, `App` creating the
+first `PlayScreen`, is deliberate: the app owns its screen stack.
+
+## Modules
+
+Path | What it does
+--- | ---
+`core/color.py` | `RGB` and the few colour operations effects need.
+`core/frame.py` | `Frame`: a grid of `(char, colour)` cells. Spaces are transparent.
+`core/renderer.py` | Encodes a frame as ANSI, writing only rows that changed since the last frame.
+`core/keys.py` | Turns raw terminal bytes into key names (`up`, `ctrl-e`, `a`).
+`core/terminal.py` | Takes over the terminal (alternate screen, raw-ish input) and always gives it back: on exit, exceptions, `SIGTERM`, and around `Ctrl-Z`.
+`core/clock.py` | Frame pacing.
+`themes.py` | Colour themes as 256-entry ramps, plus the animated Rainbow and Strobe.
+`postfx.py` | The CRT, glitch and recolour filters applied to finished frames.
+`effects/base.py` | The `Effect` base class and its contract.
+`effects/builtin/` | The 50 hand-written effects, and `CATALOGUE`, which names and groups them.
+`effects/engine/` | The procedural engine: `schema.py` (parameter descriptions), `layers.py`, `warps.py`, `filters.py`, `recipe.py` (the data model and its JSON form), `generate.py` (seed → recipe), `effect.py` (drawing a recipe).
+`effects/registry.py` | Every playable effect in a stable order, and name lookup.
+`effects/curated.py` | Which generated effects are excluded, and the Gallery.
+`library/config.py` | `Settings` and a loader that never fails.
+`library/effects.py` | Reading and writing `.sfx` files.
+`library/legacy.py` | Converting StaticFX 1.x files.
+`library/looks.py` | Saved looks and the built-in ones.
+`app/app.py` | `App`: settings, library, player, screen stack, toasts, saving.
+`app/player.py` | What's on screen: the effect, theme, speed, filters, and previews.
+`app/keymap.py` | Main-view actions and their keys.
+`app/session.py` | The real-terminal loop, and headless rendering.
+`ui/screen.py` | The `Screen` base class.
+`ui/widgets.py` | Box characters, colours, panels, scrolling lists.
+`ui/play.py`, `browser.py`, `pickers.py`, `studio.py`, `settings.py`, `help.py`, `dialogs.py` | One file per screen.
+`cli/parser.py`, `cli/commands.py` | Arguments, and one function per subcommand.
+
+## One frame
+
+`session.run` loops:
+
+1. **Input.** `KeyReader` collects pending keys. `App.handle_key` gives each
+   one to the screen on top of the stack. `Ctrl-Z` is the exception: the app
+   asks the session to suspend.
+2. **Resize.** If the terminal changed size, the frame, the player and every
+   effect are resized and the screen is redrawn from scratch.
+3. **Update.** `App.update(dt)` advances the player (which advances the
+   effect, scaled by speed), every screen, the toast timer and auto-cycle.
+4. **Draw.** `App.draw(frame)` asks the player to draw the effect and apply
+   filters, then draws each screen from the bottom up.
+5. **Output.** `Renderer.diff` encodes the rows that changed; one `write`.
+6. **Save.** If settings changed, they're written, at most once a second.
+7. **Wait** for the next frame.
+
+Nothing in `App` or the screens touches the terminal, which is why the test
+suite can drive the whole app with key presses and inspect the frames.
+
+## Decisions
+
+**No curses.** `curses` would handle terminal modes, but it's not available
+on every Python build, its colour support stops at 256 colours without
+work, and it makes the app much harder to test. Writing ANSI directly is a
+few hundred lines in `core/` and gives 24-bit colour everywhere.
+
+**Signals off in the terminal.** The terminal is put in a mode where Ctrl-C
+and Ctrl-Z arrive as keys rather than signals. Each screen decides what they
+mean, so Ctrl-C in the Studio can ask before throwing away your work instead
+of killing the program. Suspend is done by hand: restore the terminal, stop,
+re-enter when resumed.
+
+**Row-level diffing.** Only rows that changed since the last frame are
+written. For busy effects that saves little (about 7% of bytes across the
+built-ins, measured at 120×36), but a paused effect or a slow one costs
+almost nothing to redraw. Cell-level diffing would save more on busy
+effects, at the price of a cursor move per changed run and noticeably more
+code in the hottest loop; it's the obvious next step if output volume ever
+becomes the bottleneck.
+
+**`RGB` is a `NamedTuple`.** Thousands of colours are created per frame;
+tuples are the cheapest immutable, hashable value Python has.
+
+**A screen stack.** Each mode (browser, Studio, a confirmation dialog) is a
+`Screen` with `handle`, `update` and `draw`. The top one gets the keys.
+Opening a dialog over the Studio is just a push; nothing else needs to know.
+This replaced a single class with a long `if menu: ... elif studio: ...`
+chain.
+
+**One parameter schema.** Each layer, warp and filter kind declares its
+parameters once (`Param` in `engine/schema.py`). That one description is used
+to validate `.sfx` files, fill in defaults, build the Studio's controls and
+generate the reference in `EFFECT_FORMAT.md`, so they can't drift apart.
+
+**Generated effects never change.** `generate(seed)` draws its random values
+in a fixed order, and a test fingerprints all 1,000 recipes. Favourites,
+saved looks and scripts that say `proc_042` keep meaning the same picture.
+Changing the generator on purpose means updating the fingerprint and saying
+so in the changelog.
+
+**A quality gate, not a hand filter.** `tools/curate.py` renders every
+generated recipe and excludes the ones that are blank, frozen or a solid
+wall. It's repeatable: rerun it after changing the engine. The Gallery, by
+contrast, is picked by eye; taste doesn't automate well.
+
+**Settings can't stop the app from starting.** Every value in `config.json`
+is checked on its own; a bad one is replaced by its default with a message.
+The same goes for `.sfx` files and looks: a broken file is skipped and
+reported, never fatal. The last effect you played may have been deleted;
+StaticFX says so and starts on Matrix Rain.
+
+**Adaptive detail.** The engine samples the pattern on a grid of blocks
+rather than every cell when the terminal is large, and in the interactive
+app it also coarsens or refines that grid based on how long frames take.
+Headless rendering (`staticfx render`) keeps full detail so output is
+deterministic.
+
+## Testing
+
+`tests/` mirrors the layers:
+
+File | Covers
+--- | ---
+`test_core.py` | Colours, frame clipping, renderer diffing, key decoding.
+`test_engine.py` | The schema, recipe validation (including a fuzz test that corrupts real recipes), and the generated-effects fingerprint.
+`test_effects.py` | Every built-in, and a sample of generated effects, at sizes from 1×1 to 250×70, with odd timesteps, in both character modes.
+`test_library.py` | Settings, `.sfx` files, looks, and real files from StaticFX 1.x.
+`test_app.py` | Startup, playing, favourites, looks, key bindings, saving.
+`test_ui.py` | Every screen driven by key presses, and drawn at the minimum size and in ASCII mode.
+`test_cli.py` | Every subcommand, and the 1.x flags.
+`test_terminal.py` | The real program in a pseudo-terminal: quitting, Ctrl-C, Ctrl-Z, resizing, `SIGTERM`, a corrupt config.
+`test_docs.py` | Generated docs are current and the README and guides match the code.
+`test_details.py` | Filters, the fetch overlay, adaptive detail, name lookup, dialogs.