A macOS desktop app that delivers reminders like an aerial advertising plane: a flat 2D cartoon plane flies across your screen towing a banner with your reminder text.

Runs quietly in the macOS menu bar (no Dock icon). Add one-time reminders with a date and time. When due, a plane flies across the screen three times, then disappears.

• macOS (the overlay window requires macOS window features)
• Node.js 20+

npm install

npm start

This compiles TypeScript (wiping stale dist/ first) and launches the app.

If you pull new changes while the app is running, fully quit via tray menu → Quit (not just close the window) before npm start again. The scheduler interval keeps ticking on old compiled code otherwise.

The full headless test suite includes Vitest unit tests and Playwright browser tests.

npm test

This runs:

• Unit tests (Vitest): storage, scheduler, fly-by queue — no display required
• Browser tests (Playwright): fly-by animation renderer, management panel — headless Chromium

On Ubuntu 26.04 ARM64, Playwright doesn't officially support the platform. The test script includes workarounds:

• PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-arm64 — uses the closest supported build
• LD_LIBRARY_PATH pointing to extracted system libraries
• FONTCONFIG_FILE for headless text rendering

First-time setup:

# Install Chromium browser (override platform)
PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-arm64 npx playwright install chromium

# Download required system libraries
mkdir -p /tmp/chromium-deps ~/.local/lib
cd /tmp/chromium-deps
apt-get download libglib2.0-0t64 libnspr4 libnss3 libatk1.0-0t64 \
  libatk-bridge2.0-0t64 libcups2t64 libxkbcommon0 libasound2t64 \
  libgbm1 libcairo2 libpango-1.0-0 libxcomposite1 libxdamage1 \
  libxfixes3 libxrandr2 libatspi2.0-0t64 libxrender1 libdrm2 libxi6 libxres1
for deb in *.deb; do dpkg-deb -x "$deb" ~/.local/lib/; done

# Download fonts for headless text rendering
apt-get download fonts-liberation
dpkg-deb -x fonts-liberation*.deb /tmp/fonts-deb/
mkdir -p /tmp/fonts
cp /tmp/fonts-deb/usr/share/fonts/truetype/liberation/*.ttf /tmp/fonts/

src/
  main/           # Electron main process
    main.ts       # Tray, panel, overlay, scheduler, IPC
    preload.ts    # contextBridge: exposes storage API to renderers
    storage.ts    # Reminder CRUD with JSON persistence
    scheduler.ts  # Periodic check for due reminders (injectable time)
    flybyQueue.ts # Sequential fly-by queue (one at a time)
  renderer/       # Web pages loaded in Electron windows
    panel.html    # Management panel (list, add, edit, delete)
    flyby.html    # Fly-by animation (plane + banner, 3 passes)
  shared/
    constants.ts  # PASS_COUNT, PASS_DURATION_MS, MAX_TEXT_LENGTH, SCHEDULER_TICK_MS
tests/
  unit/           # Vitest unit tests (pure logic, no display)
  browser/        # Playwright headless browser tests

Some features cannot be auto-tested in a headless environment. Run through the checklist in MANUAL-MAC-CHECKLIST.md on a real Mac after building.

• macOS overlay window flags (transparency, click-through, always-on-top, screen-saver level, visible-on-all-workspaces)
• Menu-bar tray icon appearance and behavior
• Dock icon hiding
• Launch-at-login toggle

These are verified manually on macOS. See MANUAL-MAC-CHECKLIST.md.