Blitter docs (draft)

Working draft of the Blitter help content, written as plain Markdown for review — this will be adapted into the actual documentation website once the content itself is settled.

Contents

1. Overview — what Blitter is and what it's for.
2. Exporting — the export formats, and which one to pick for what.
3. Library — saving, naming, browsing, and deleting your setups.
4. Preview & Playback — the live preview area, zoom, and playback controls.
5. Controls — every sidebar control, in detail, with examples:
   • Tile — Sequence, Checkerboard, Tile size
   • Timing — Duration, Frame count, Easing
   • Playback — Mode, Start/End delay
   • Time shift — Pattern, Stagger, per-pattern settings
   • Grid — Shape, grid size
   • Colors — Foreground/Background, gradients, Invert
6. Glossary — every term flagged as jargon, defined in one place.

How the examples were made

Every animated example is a real GIF, generated by a small standalone Node script in ../tools that re-implements the exact field/time-shift/easing/playback math from BlitterEngine (hand-ported and spot-checked against the Swift source, not guessed at). It's genuinely rendering these configurations, not describing them — see tools/build-examples.js for the full list of examples and their exact settings, and tools/engine.js / tools/shapes.js for the math itself. Regenerate everything with:

cd help-content/tools
npm install
node build-examples.js

This tooling is docs-only — it doesn't touch or depend on the actual app, and isn't meant to ship anywhere.

Open items / known TODOs before this is final

• Naming: these docs already use "Library" (app currently: "Gallery") and "Stagger" (app currently: "Phase"). Both renames are planned as separate, small app changes — full-name rename for Library, docs-first for Stagger — tracked outside this docs branch.
• Format decision: examples are GIF, per the earlier discussion (universal, needs no JavaScript, and it's already one of the app's own export formats).
• Screenshots: the UI-facing sections (Library, Preview & Playback, Exporting) are currently text-only. Real app screenshots still need to be captured and dropped in.
• Scope: Controls coverage is intentionally curated (a few representative examples per control, plus a "family tour" for the big enumerated pickers) rather than exhaustive — see the note at the top of Controls.