From 6b20b75ef38432a1866e9495bf775ff0ebbbef06 Mon Sep 17 00:00:00 2001
From: Eddy <eddy@MacMini.local>
Date: Sat, 9 May 2026 01:10:08 +0200
Subject: [PATCH] docs: add design spec for bouncing Hello World ball

---
 ...-05-09-bouncing-hello-world-ball-design.md | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-09-bouncing-hello-world-ball-design.md

diff --git a/docs/superpowers/specs/2026-05-09-bouncing-hello-world-ball-design.md b/docs/superpowers/specs/2026-05-09-bouncing-hello-world-ball-design.md
new file mode 100644
index 0000000..3116af5
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-09-bouncing-hello-world-ball-design.md
@@ -0,0 +1,37 @@
+# Bouncing "Hello World" Ball — Design Spec
+
+## Goal
+Modify the existing M5StickC Plus2 firmware so that the text "Hello World" bounces around the screen **inside a filled circle** (ball), changing color every time it hits an edge.
+
+## Hardware
+- **Board:** M5StickC Plus2 (ESP32-PICO-V3-02)
+- **Display:** 1.14" TFT, 135×240 pixels, ST7789V
+- **Framework:** Arduino (via PlatformIO)
+
+## Behaviour
+
+1. A filled circle (ball) appears on screen with "Hello World" text centred inside.
+2. The ball starts at the centre of the screen and moves with velocity `(vx, vy)` — initial values ~2–3 px/frame in both axes.
+3. When the ball reaches any screen edge, its velocity on that axis is reversed (bounce) and the ball colour changes to the next colour in a predefined palette.
+4. The screen is filled black each frame before drawing (no motion trails).
+5. The text is drawn in white for contrast against the coloured ball.
+6. Frame rate is controlled by a `delay(15)` in `loop()`.
+
+## Colour Palette
+Cycle through: `RED` (0xF800), `GREEN` (0x07E0), `BLUE` (0x001F), `YELLOW` (0xFFE0), `MAGENTA` (0xF81F), `CYAN` (0x07FF).
+
+## Ball Size
+- Radius: ~15 pixels (fits on the small screen while leaving room for the text).
+
+## Implementation Notes
+- Replace `drawCircle` with `fillCircle` for a solid ball.
+- Add `fillScreen(TFT_BLACK)` at the start of every frame.
+- Use `M5.Lcd.setTextColor(TFT_WHITE)` and draw the text centred at the ball position using `M5.Lcd.getTextBounds()` or manual centering with `setCursor(x - textWidth/2, y - fontHeight/2)`.
+- Remove the static "Hello World" from `setup()` — it is now part of the animated ball.
+
+## Files Changed
+- `src/main.cpp` — rewrite loop and rendering logic.
+
+## Out of Scope
+- Touch input, accelerometer, sound — not required.
+- Multiple balls or additional text.