tracpulse/docs/superpowers/plans/2026-04-30-easter-egg-plan.md

# Easter Egg Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a hidden Easter egg to the Settings screen that triggers a fun animation and opens `https://fiatcode.dev` when the user triple-taps the AppBar.

**Architecture:** A stateful overlay widget with `AnimatedOpacity` + `AnimatedScale` built-ins, triggered by a `GestureDetector` counting triple-taps on the Settings AppBar. URL launch via `url_launcher` package.

**Tech Stack:** Flutter (Dart), `url_launcher` package

---

## File Structure

- Modify: `pubspec.yaml` — add `url_launcher` dependency
- Modify: `lib/settings_screen.dart` — add `EasterEggOverlay` state, gesture detector on AppBar, animation + URL launch logic

---

### Task 1: Add url_launcher dependency

**Files:**
- Modify: `pubspec.yaml:30-40` — add `url_launcher: ^6.2.0` to dependencies

- [ ] **Step 1: Add url_launcher to pubspec.yaml**

```yaml
dependencies:
  flutter:
    sdk: flutter
  cupertino_icons: ^1.0.8
  shared_preferences: ^2.2.0
  workmanager: ^0.6.0
  sqflite: ^2.3.0
  http: ^1.1.0
  permission_handler: ^11.0.0
  flutter_local_notifications: ^18.0.0
  url_launcher: ^6.2.0      # <-- ADD THIS LINE
```

- [ ] **Step 2: Run flutter pub get**

Run: `flutter pub get`
Expected: `url_launcher` resolved and added

- [ ] **Step 3: Commit**

```bash
git add pubspec.yaml
git commit -m "chore: add url_launcher dependency"
```

---

### Task 2: Add Easter Egg Overlay and Gesture Detection to SettingsScreen

**Files:**
- Modify: `lib/settings_screen.dart` — add import, overlay state, gesture detector, animation, URL launch

- [ ] **Step 1: Add imports**

Add after existing imports (line 4):
```dart
import 'package:url_launcher/url_launcher.dart';
```

- [ ] **Step 2: Add EasterEggOverlay state to _SettingsScreenState**

Add before `late TextEditingController` (after line 19):
```dart
bool _showEasterEgg = false;
int _tapCount = 0;
DateTime? _lastTapTime;

void _handleAppBarTap() {
  const tripleTapInterval = Duration(milliseconds: 500);
  final now = DateTime.now();

  if (_lastTapTime != null && now.difference(_lastTapTime!) > tripleTapInterval) {
    _tapCount = 0;
  }

  _tapCount++;
  _lastTapTime = now;

  if (_tapCount == 3) {
    _tapCount = 0;
    setState(() => _showEasterEgg = true);
  }
}

Future<void> _triggerEasterEgg() async {
  setState(() => _showEasterEgg = false);
  await Future.delayed(const Duration(milliseconds: 1500));
  final uri = Uri.parse('https://fiatcode.dev');
  if (await canLaunchUrl(uri)) {
    await launchUrl(uri, mode: LaunchMode.externalApplication);
  }
}
```

- [ ] **Step 3: Wrap AppBar title with GestureDetector for triple-tap detection**

Replace the `title` section in AppBar (lines 119-128):
```dart
title: GestureDetector(
  onTap: _handleAppBarTap,
  child: const Text(
    'SETTINGS',
    style: TextStyle(
      fontFamily: 'monospace',
      fontSize: 14,
      fontWeight: FontWeight.w700,
      letterSpacing: 2,
      color: Color(0xFFe0e0e0),
    ),
  ),
),
```

- [ ] **Step 4: Add AnimatedOverlay at the end of Scaffold body**

Add before closing `);` of Scaffold's `body` ListView (before line 172):
```dart
if (_showEasterEgg) _buildEasterEggOverlay(),
```

- [ ] **Step 5: Add _buildEasterEggOverlay widget method**

Add after `_buildSaveButton` (after line 402, before closing `}`):
```dart
Widget _buildEasterEggOverlay() {
  return AnimatedOpacity(
    opacity: _showEasterEgg ? 1.0 : 0.0,
    duration: const Duration(milliseconds: 300),
    child: AnimatedScale(
      scale: _showEasterEgg ? 1.0 : 0.5,
      duration: const Duration(milliseconds: 300),
      curve: Curves.easeOutBack,
      child: Container(
        color: Colors.black.withValues(alpha: 0.85),
        width: double.infinity,
        height: double.infinity,
        child: Center(
          child: Text(
            '🎉 FIAT CODE! 🎉',
            style: TextStyle(
              fontFamily: 'monospace',
              fontSize: 32,
              fontWeight: FontWeight.w700,
              color: const Color(0xFF00e676),
              shadows: [
                Shadow(
                  color: const Color(0xFF00e676).withValues(alpha: 0.5),
                  blurRadius: 20,
                ),
              ],
            ),
          ),
        ),
      ),
    ),
  );
}
```

- [ ] **Step 6: Call _triggerEasterEgg when overlay visibility changes**

Modify the `if (_showEasterEgg) _buildEasterEggOverlay(),` line to pass callback:
```dart
if (_showEasterEgg) _buildEasterEggOverlay(_triggerEasterEgg),
```

And update the method signature:
```dart
Widget _buildEasterEggOverlay(VoidCallback onAnimationComplete) {
  return AnimatedOpacity(
    opacity: _showEasterEgg ? 1.0 : 0.0,
    duration: const Duration(milliseconds: 300),
    onEnd: onAnimationComplete,
    child: AnimatedScale(
      scale: _showEasterEgg ? 1.0 : 0.5,
      duration: const Duration(milliseconds: 300),
      curve: Curves.easeOutBack,
      child: Container(
        color: Colors.black.withValues(alpha: 0.85),
        width: double.infinity,
        height: double.infinity,
        child: Center(
          child: Text(
            '🎉 FIAT CODE! 🎉',
            style: TextStyle(
              fontFamily: 'monospace',
              fontSize: 32,
              fontWeight: FontWeight.w700,
              color: const Color(0xFF00e676),
              shadows: [
                Shadow(
                  color: const Color(0xFF00e676).withValues(alpha: 0.5),
                  blurRadius: 20,
                ),
              ],
            ),
          ),
        ),
      ),
    ),
  );
}
```

- [ ] **Step 7: Run flutter analyze to verify no errors**

Run: `flutter analyze`
Expected: No errors (warnings about unused imports OK)

- [ ] **Step 8: Commit**

```bash
git add lib/settings_screen.dart
git commit -m "feat: add easter egg with triple-tap AppBar and animation"
```

---

## Spec Coverage Check

- ✅ Triple-tap on Settings AppBar — Task 2, Step 2 (tap counting) + Step 3 (GestureDetector)
- ✅ Fun animation — Task 2, Steps 4-6 (AnimatedOpacity + AnimatedScale overlay)
- ✅ Opens https://fiatcode.dev — Task 2, Step 2 (_triggerEasterEgg calls launchUrl)
- ✅ url_launcher dependency — Task 1

## Placeholder Scan
- ✅ No TBD/TODO placeholders
- ✅ No vague implementation descriptions — all code blocks are concrete