three-katex-shader

Live at aiship.lol.

Animated math sketches in the browser. Each sketch is a mathematically defined transformation playing on a loop (Hopf fibrations, minimal surfaces, fractals, reaction–diffusion, splines, …), with its equation shown live in KaTeX, using the same numbers the animation is using on that frame.

Built with three.js, KaTeX and Vite.

Using it

The landing page (/) has a gallery of every sketch, each sketch has its own address, /s/<sketch-id>, and each person a profile, /u/<name>. On a phone or tablet, swipe up and down through sketches; tap the animation to hide or show everything, and use the hand button to touch the sketch itself (rotate, drag) instead of swiping. In a sketch, tap its name in the top bar to pick another one. The dock at the bottom has previous/next, Explain, Params, Comments, Code, and More (music and recording, microphone, hide controls, fullscreen). On a computer, scroll (or swipe a trackpad) to flip to the next sketch, and hold Ctrl while scrolling to zoom. It all works on phones too; panels open as sheets from the bottom.

Key	Does
← / →, ↑ / ↓, or the scroll wheel	previous / next sketch
E	Explain panel: every symbol in the current equation, what it means and how to type it, plus a walkthrough of the sketch
H	cycle view: everything → equation only → clean
Esc	close panels
F	fullscreen
R	record video

New to the math or the code? Start with docs/guide.md. It's a field guide to the symbols, LaTeX, JavaScript loops, shaders and the math behind the sketches. It's also what the Explain panel shows.

Running it locally

You need Node.js 20 or newer.

git clone <this repository's URL>
cd three-katex-shader
npm install
npm run dev          # the app, at http://localhost:5173

When running locally, sketches you create or edit in the code panel are saved as real files in src/sketches/, so you can commit them.

Project layout

src/sketches/   one file per sketch (the part to read and write)
src/lib/        shared math and geometry helpers (motion.js: lerp, smooth, phaseOf, …)
src/core/       app engine: sketch runner, LaTeX, audio, recording
src/ui/         the panels
docs/guide.md   the learning guide, also shown in the Explain panel
server/         an old local-only comments API (used by server/example-bot.mjs); not needed by the site
supabase/       database schema and access rules for sign-in, comments, notes, shared sketches

Contributing

• Explanations: add symbols, fix explanations or write a sketch walkthrough in docs/guide.md. Section 9 shows the format for a walkthrough; a new table row in sections 3–4 shows up in the Explain panel automatically.
• Sketches: copy an existing sketch in src/sketches/. A sketch should be a transformation defined by an equation (motion(t)), with its latex showing the live values. The guide covers the anatomy of a sketch. With npm run dev running, run npm run thumbs -- <sketch-id> to capture its gallery thumbnail into public/thumbs/ (needs Firefox; set FIREFOX=/path/to/firefox if it isn't found).

Open a pull request with your change.

Deploying

The app builds to plain static files:

npm run build        # output in dist/

On Vercel, import the repository as a new project and keep the detected Vite settings. Every push to the main branch redeploys.

Community features (Supabase)

Signing in (with GitHub, Google or Discord) gives everyone a profile at /u/<name> and lets them:

• comment on any sketch (💬 Comments),
• add notes to a sketch's explanation (📖 Explain → Community notes),
• share sketches from the code editor (⇪ Share).

Notes and shared sketches are reviewed before anyone else sees them. A shared sketch is JavaScript that runs in every viewer's browser, so the admin reads it first in the 🛡 Review panel, which only the admin can see. Until it's approved, a sketch only runs for the person who shared it.

The data lives in Supabase. The access rules are in supabase/migrations/0001_community.sql. To run your own copy with your own database:

1. Create a Supabase project and run the SQL files in supabase/migrations/ in order in its SQL Editor. First change the GitHub user id in handle_new_user() to your own (gh api user --jq .id), so that you become the admin, and SITE_OWNER in src/core/authors.js to your username.
2. For each sign-in provider you want (GitHub, Google, Discord), create an OAuth app with the provider whose callback / redirect URL is https://<your-project>.supabase.co/auth/v1/callback, and enable that provider in Supabase with its client id and secret. The sign-in menu only lists enabled ones.
3. In Supabase → Authentication → URL Configuration, set your site's address and add http://localhost:5173/** as a redirect URL.
4. Set VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY (in .env.local, or in Vercel's environment variables). Without them the app uses this project's database.

License

MIT