Screenshots Skill

Captures the 26 numbered gallery screenshots from a connected Android device using scripts/screenshot-gallery.sh --auto, saving them to docs/wiki/screenshots/. The script header lists every file; each file number is its step number.

In --auto mode the script runs fully non-interactively: the agent executes it directly via the Bash tool. No manual terminal steps needed.

New in v2: Screenshots 16 and 17 show the "add button" (FAB) in the top-right corner of Routes and Favorites screens. Screenshots 14 and 15 (overlays) now include service startup verification to improve reliability.

New in v3: Use --steps to run only specific steps instead of the full suite:

• --steps 16,17 — run steps 16 and 17 only
• --steps 14-17 — run steps 14 through 17
• --steps 01,03,05 — run steps 1, 3, 5 Seeding (routes, favorites) still runs automatically before the first selected step.

---

Step 1 — Pre-flight checks (agent runs these)

# Device connected?
adb devices | grep -v "List of" | grep "device$"

# App installed?
adb shell pm list packages | grep com.locationjoystick

If device not found: tell the user to connect their Android device with USB debugging enabled, wait for it to appear under adb devices, then proceed.

If app not installed: run make install-on-phone (not make install) to build and install the debug APK, then follow the onboarding section below before running the script.

---

Step 1b — Complete onboarding autonomously (if needed)

The script requires onboarding to be complete. If the app lands on the onboarding screen after install, do not ask the user to complete it manually — do it via adb:

# Grant location permissions
adb shell pm grant com.locationjoystick.app android.permission.ACCESS_FINE_LOCATION
adb shell pm grant com.locationjoystick.app android.permission.ACCESS_COARSE_LOCATION

# Grant overlay (draw over other apps) permission
adb shell appops set com.locationjoystick.app SYSTEM_ALERT_WINDOW allow

# Grant mock location permission (replaces "Select mock location app" in Developer Options)
# The app checks OPSTR_MOCK_LOCATION via AppOpsManager — this satisfies it:
adb shell appops set com.locationjoystick.app android:mock_location allow

# Verify mock location is allowed
adb shell appops get com.locationjoystick.app android:mock_location
# Expected output: MOCK_LOCATION: allow

Then restart the app and dismiss the notification permission dialog (tap Allow):

adb shell am force-stop com.locationjoystick.app
sleep 1
adb shell am start -n com.locationjoystick.app/.MainActivity
sleep 3
# Tap "Allow" on the notification permission dialog (coordinates ~540,1400 on Pixel 7)
adb shell input tap 540 1400
sleep 1

Verify onboarding is past by dumping the UI — you should see app content (e.g. "Favorites", "Map", "Routes") rather than "Set up locationjoystick":

adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml /tmp/ui.xml
grep -o 'text="[^"]*"' /tmp/ui.xml | sort -u

Once past onboarding, proceed to Step 1c.

---

Step 1c — Seed realistic data (agent runs this, after onboarding)

Do this before running the script. The script skips seeding steps if data already exists.

Enable Hot Locations

Navigate to Settings and enable the "Show hot locations" toggle:

# Open the app (should already be on Idle screen)
adb shell am start -n com.locationjoystick.app/.MainActivity
sleep 2

# Dump UI and find the Settings card
adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml /tmp/ui.xml
grep -o 'text="[^"]*"' /tmp/ui.xml | sort -u

If on the Idle screen, tap Settings card (find its bounds from the dump, typically around 540,900):

# Tap Settings card on Idle screen — find exact coords from dump
adb shell input tap 540 900
sleep 2

In Settings, scroll down to find "Show hot locations" toggle and enable it:

adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml /tmp/ui.xml
grep -i "hot" /tmp/ui.xml

Locate the toggle bounds from the XML (bounds="[x1,y1][x2,y2]"), compute center, and tap:

# Example — use actual bounds from dump:
adb shell input tap <CENTER_X> <CENTER_Y>
sleep 1

Verify the toggle is now checked:

adb shell uiautomator dump /sdcard/ui.xml && adb pull /sdcard/ui.xml /tmp/ui.xml
grep -A2 -i "hot" /tmp/ui.xml

Create 3 Routes

Navigate back to Idle, then to Routes, and create three routes with realistic names. Use the "Add route → from map" flow. Two waypoints per route is sufficient.

Route 1 — "Morning Walk" (e.g. Central Park area, NYC):

• Waypoint A: tap map near 40.7829° N, 73.9654° W
• Waypoint B: tap map ~500 m north

Route 2 — "Riverside Jog" (e.g. along the Seine, Paris):

• Waypoint A: near 48.8566° N, 2.3522° E
• Waypoint B: tap map ~600 m east

Route 3 — "Harbor Stroll" (e.g. Sydney Harbour):

• Waypoint A: near -33.8688° S, 151.2093° E
• Waypoint B: tap map ~400 m southeast

For each route, use the RouteCreator UI via adb taps derived from uiautomator dump. The "Add route" FAB is at the bottom right of the Routes screen. After adding both waypoints, tap the save button (checkmark in the top bar).

Once all 3 routes exist, the script's seed phase will detect non-empty Routes and skip auto-creation. Proceed to Step 2.

---

Step 2 — Run the script (agent runs this)

cd /path/to/project && ./scripts/screenshot-gallery.sh --auto --output docs/wiki/screenshots

The --auto flag replaces all manual pause points with adb automation:

Phase	What --auto does
Seed (pre-screenshots)	Navigates to Routes — if empty, creates "Morning Walk" and "City Loop" routes (2 waypoints each). Then navigates to Favorites — if empty, adds Tokyo, Paris, London via coordinates dialog. Ensures steps 03, 04, 06, 07, 10 all show populated lists.
A (step 02: map)	Navigates to Map, taps the "start simulation" FAB to start spoofing so the map screenshot shows the running state (stop button visible, location marker active). go_idle between steps force-stops the app, ending spoofing cleanly before step 03.
B (step 10: route detail)	Routes already seeded; opens overflow menu on first route and taps Edit
C (step 14: joystick overlay)	Navigates to Map, taps "Start location simulation" FAB (content-desc substring "location simulation"), starts FloatingWidgetService, expands the widget panel (tap master FAB), taps JOYSTICK_TOGGLE (2nd feature icon after MAP_FLOATING), then collapses the panel so the joystick is the screenshot focus. Widget window position is read from dumpsys window to handle user drags. Improved: Service startup now verified via dumpsys window with retries; 3 failed attempts fall back gracefully.
D (step 15: widget overlay)	Widget service already running from step 14; expands the panel (tap master FAB again) for the screenshot. Improved: Service startup now verified via dumpsys window with retries.
E (step 16: routes add button)	Navigates to Routes list and captures the FAB (plus button) in the top-right corner. Shows the entry point for creating new routes.
F (step 17: favorites add button)	Navigates to Favorites list and captures the FAB (plus button) in the top-right corner. Shows the entry point for adding new favorites.

The script will print progress for every step. Total runtime ~2–3 minutes.

Running specific steps only

To update only certain screenshots, add --steps:

# Capture steps 16 and 17 (Routes and Favorites add buttons)
./scripts/screenshot-gallery.sh --auto --steps 16,17

# Capture step 14 only (joystick overlay)
./scripts/screenshot-gallery.sh --auto --steps 14

# Capture steps 14–17 (overlays and add buttons)
./scripts/screenshot-gallery.sh --auto --steps 14-17

# Capture steps 01, 03, 05 (specific screens)
./scripts/screenshot-gallery.sh --auto --steps 01,03,05

Format:

• Single step: --steps 16
• Multiple steps: --steps 16,17,18 (comma-separated, no spaces)
• Range: --steps 14-17 (inclusive)
• Mixed: --steps 01,03,06-09

Seeding: Routes and Favorites are still seeded automatically before the first selected step if they don't exist (for steps that need populated lists). This ensures steps 03–10 always show data if selected.

---

Step 3 — Script output (automatic)

The script automatically:

1. Captures the numbered screenshots to docs/wiki/screenshots/ (26 PNGs; the script header comment is the list of files and the step each one comes from)
2. Re-saves any PNG over 1 MB as a 256-colour palette PNG (needs Pillow; skipped if absent)
3. Generates the Play Store images: marketing/feature_graphic.png and the 8 marketing/gallery/ images, built from the captures above
4. Displays a summary table

If any file is missing:

• 13_joystick_overlay.png: joystick overlay service failed to start after 3 retries. Troubleshoot: verify the app is running, mock location is active, and FloatingWidgetService started. Fallback: manually start joystick via widget panel, position on screen, then capture with adb exec-out screencap -p > docs/wiki/screenshots/13_joystick_overlay.png
• 14_widget_overlay.png: widget overlay service failed to start after 3 retries. Troubleshoot: verify the app is running and FloatingWidgetService bound correctly. Fallback: manually expand the widget panel, then capture with adb exec-out screencap -p > docs/wiki/screenshots/14_widget_overlay.png
• 15_routes_add_button.png / 16_favorites_add_button.png: navigation failed. Verify routes or favorites screen loaded, re-run step only with adb shell am force-stop com.locationjoystick.app && sleep 1 && adb shell am start -n com.locationjoystick.app/.MainActivity
• 18_debug_stats.png: the widget FAB tap fell through to the map underneath (opens "Move to this location?" instead of the panel) — a known overlay-timing flake, same class as steps 13/14. The script retries up to 3 times with an 8s settle each time; if it still fails, enable Settings → Menus → Debug → "Debug stats", start spoofing, expand the widget panel by hand, then capture with adb exec-out screencap -p > docs/wiki/screenshots/18_debug_stats.png
• Any other file: report which step failed and suggest re-running.

---

Step 4 — Stage for commit (agent runs this)

git add docs/wiki/screenshots/
git diff --cached --name-only | grep screenshots/

This will include the raw *.png captures and the marketing/ images.

Report how many files changed. Offer to commit alongside the user's next code change, or commit immediately if requested.

---

Manual mode (fallback)

If --auto fails or device state requires human intervention, drop the flag:

./scripts/screenshot-gallery.sh --output docs/wiki/screenshots

The script will pause at steps 10, 14, and 15 and print instructions. Tell the user what to do at each pause before they start — the pause descriptions are in the script output itself.