TotoFX Animation Engine

TotoFX is a physics-based animation engine that makes task management feel tangible. Cards glow when work is active, spring into existence when created, and dissolve with particle effects on completion. Every transition uses real physics — spring dynamics, momentum, fluid simulation — instead of CSS easing curves.

This isn't decoration. When you watch a task animate on completion, your brain registers the accomplishment differently than checking a box. TotoFX exists because the feeling of finishing matters.

The engine ships as the open-source toto-fx npm package. Toto consumes it as a dependency and serves the built bundle from app/ui/static/vendor/toto-fx/. Toto-local plugin overrides live in app/ui/static/toto-plugins/.

What It Can Do

60+ Animation Variants

The current app/ui/static/animations/animations-manifest.json registers 68 variants across the thud, cute, and death families:

Category	Family	Variants
Completion — Thud (10)	impact-style lift-and-slam	anime-slam, low-bounce, stratosphere, orbit-slam, crater, deep-crater, meteor, detonation, nuclear, shatter
Completion — Cute (12)	whimsical particle effects	confetti, sparkle, shootingstar, butterflies, rainbow, fireworks, hearts, cat, dog, snowfall, ocean, fireflies
Completion — Death (11)	dramatic destruction	explode, incinerate, shredder, guillotine, heartbeat, sniper, eaten, lightning, steamroller, piranhas, woodchipper
Deletion — Death (35)	reuses + extends the death family for deletion	(mirrors completion-death plus deletion-only variants)

A curated subset is surfaced in the production FX sidebar (the controls visible to every user). The full set is reachable from /playground and via the manifest API. Counts will drift as plugins are added — the /api/animations endpoint is the source of truth.

In addition, the engine drives in-progress glow (persistent state shown on in_progress cards) and list transitions (cascade entry, stagger exit, reorder flow).

Particle Systems

Completion animations spawn physics-simulated particles — gravity, velocity, angular momentum, lifetime decay, and trail effects (smoke, fire). Character sets and colors are theme-aware: switching themes changes particle visuals across every animation. Particles render to a dedicated canvas layer for GPU-accelerated compositing.

Dotgrid — Reactive ASCII Background

The dashboard background is a 2D fluid simulation backed by Float32Array density and velocity fields, rendered as a grid of text characters. Glyphs are selected by brightness (each character is rendered to a hidden canvas, its pixel density measured, sorted into a 256-entry lookup table for O(1) density-to-character mapping). When an animation fires, effects propagate through the grid: craters, shockwaves, vortices, fire/scorch, ripples. The architecture is derived from Cheng Lou's pretext and the pretext-demos fluid-smoke techniques.

Spring Physics

All motion in TotoFX uses spring dynamics. Cards don't slide from A to B on a timer — they accelerate, overshoot, and settle based on spring constants (stiffness, damping, mass). Per-variant tunables include lift height, fall duration, fall curve, particle count, particle spread, and color palette.

Composable FX Layers

Every animation automatically inherits independently toggleable layers:

Speed lines — radial anime-style motion blur
Black flash — full-screen impact flash on slam
Color inversion — CSS filter inversion on impact (disabled on mobile for perf)
Screen shake — CSS transform shake on the viewport
Dotgrid shockwave — physics-propagated ripple through the background grid
Card squash — scale compression before impact

Responsive Quality

The engine detects device capabilities and adjusts: particle counts capped on mobile, color inversion + dotgrid shockwave disabled on low-power devices, speed lines biased vertically for portrait screens, all transforms restricted to GPU-safe properties (transform, opacity). prefers-reduced-motion is fully respected — every animation suppressed when set.

FX Sidebar

The FX sidebar is a real-time animation control panel docked on every page. Toggle it from the FX pill in the header (or \ keyboard shortcut).

Controls

Control	What It Does
Category tabs	Switch between completion / deletion / creation / in-progress / list animations
Variant picker	Select which variant fires for the active category
Intensity slider (`fx-intensity`)	Scale particle counts, spring forces, and effect duration
Speed slider	Global time multiplier for all animations
FX layer toggles	Enable/disable speed lines, flash, inversion, shake, shockwave, squash
Ground FX picker	Bind a dotgrid effect (ripple, crater, vortex, nuclear, scorch) to the active animation
Reset to Default	Return the active category or all settings to factory defaults

Settings persist in localStorage for anonymous users. Authenticated users can save the configuration server-side via /api/user-animations so it follows them across devices.

Saving Presets

After tuning, save a complete snapshot (animation + dotgrid + theme) as a preset via the FX sidebar's preset menu. Presets persist locally and (for logged-in users) server-side.

Playground

/playground is the design surface for the engine. It exposes every variant, dotgrid effect, and theme on a single page with click-to-trigger test cards (philosophy quote cards by default — Camus, Sartre, Kierkegaard, Kafka). Use it to audition variants, tune parameters, compare configurations side by side, and export production defaults (admin only).

The standalone /sandbox admin page that previously held this functionality was retired in the toto-fx migration; everything it did is now part of the FX sidebar + playground combination.

Animation Categories in Detail

Completion Animations

Triggered when a task is marked done (via the dashboard, API, or slash commands). The default is a particle burst that explodes outward from the card's center.

Standout variants:

Confetti — colored rectangles with rotation and gravity
Shatter — the card fractures into ASCII shrapnel that falls with physics
Incinerate — the card burns with heat distortion, leaving scorch glyphs
Fireworks — radial bursts in theme palette

In-Progress Glow

When a task is set to in_progress, its card begins glowing. The glow pulses with a breathing rhythm — visible from across the room on a dashboard display. Color, intensity, and pulse speed are configurable.

This is the visual anchor of the workflow: set a task to in-progress, glance at the dashboard, see exactly what you're working on.

Creation Animations

New items spring into the list with physics-based entry. The default is a spring-in from zero scale.

List Transitions

Reordering, expanding sub-lists, and showing/hiding lists all use animated transitions. List entry uses a staggered cascade — items appear one by one with slight delays for a waterfall effect.

Themes

Six built-in themes (warm, cyber, midnight, mono, cute, spring) plus user-defined themes via the API. Themes affect particle palettes, glow hues, dotgrid colors, and card highlights.

Custom themes are persisted via POST /api/user-themes. Themes are saved per-user; the active theme is stored in the toto_theme cookie + the User.theme_id column.

Animation API

Endpoint	Purpose
`GET /api/animations`	Full manifest — categories, styles, variants, params, dotgrid effects, settings schema, themes
`GET /api/animations/settings/schema`	Just the settings schema for the FX sidebar
`GET /api/animations/themes`	Available themes
`GET /api/user-animations`	List your saved animation presets
`POST /api/user-animations`	Create a saved animation preset
`GET /api/user-themes`	List your saved themes
`POST /api/user-themes`	Create a saved theme

All endpoints return JSON. Read-only manifest endpoints don't require auth; user-scoped endpoints require a session cookie or API key.