🪔 Wishmaster

A family wish list app with an Aladdin / Arabian Nights theme. Each family member has their own wish list for birthdays and gifts. Accounts are managed in-app with parent/child types — parent accounts are PIN-protected so kids can't peek at what's being bought for them.

Built with vanilla HTML/CSS/JS wrapped in Capacitor for Android. Designed and built with AJ (age 9).

---

Features

• 🧞 Each family member has their own wish list
• ⭐ Rate how badly you want each wish (1–5 stars)
• 💰 Add price and a link to the item
• ✅ Mark wishes as "Got It!" when received
• 🔒 Parent accounts are PIN-protected — kids can't log in as parents
• 🛍️ Secretly mark items as "being bought" — visible to other family members but hidden from the wish owner (no spoilers!)
• 📱 Native Android app — all data stored on-device, no server needed
• ⚙️ Add/remove accounts in-app — no config files to edit
• 💵 Savings tracking — parents record cash gifts (birthday money, gift cards etc.) for each child; children see their total balance and a breakdown of where it came from
• 🎁 Grant wishes with savings — when a parent grants a wish, they can choose to deduct the cost from the child's savings (FIFO — oldest gifts spent first); if savings fall short, the parent is warned of the gap and asked to confirm they'll cover the difference
• 🏷️ Can-afford badge — wishes the child has enough savings to buy are highlighted
• ✏️ Edit wishes — tap any wish card to edit its name, link, price, or star rating (the wish owner or any parent can edit)
• 📜 Granted wish history — granted wishes are hidden by default and revealed with a toggle; each one can be tapped to see when it was granted and exactly which savings contributions paid for it

---

How It Works

Two Versions of the App

The repo contains two separate versions:

Version	Files	Storage	Use Case
Android app	www/	IndexedDB (on-device)	The real app — no internet needed
Web/Express app	index.html + server.js	CSV file on disk	Local development / testing only

The Android app in www/ is the primary version. It is entirely self-contained — no server, no internet connection, no account required.

Architecture (Android version)

www/
  index.html   — Full SPA: all UI, routing, and business logic in one file
  db.js        — IndexedDB wrapper (accounts, wishes, settings, savings stores)
  pin.js       — PIN hashing (Web Crypto SHA-256) + lockout logic

Capacitor bundles these files as static assets inside the Android APK and renders them in a native WebView. The JavaScript in www/ calls Capacitor plugin APIs for native features (haptic feedback, status bar, splash screen).

Data Model

All data lives in an IndexedDB database called wishmaster_db (schema version 2) with four object stores:

• accounts — family members (name, emoji, colour, type child|parent, hashed PIN)
• wishes — wish items (owner account key, name, link, price, star rating 1–5, status active|got_it, being_bought_by, grantedAt, savingsAllocations)
• settings — app title, first-run flag
• savings — cash gift contributions per child (owner key, original amount, remaining amount, optional note, date added)

Savings & Spending

Each savings contribution tracks how much of the original gift amount remains unspent (remainingAmount). When a parent grants a wish and chooses to deduct from savings, contributions are spent oldest first (FIFO). The portions used are recorded on the wish as savingsAllocations so the full payment history is preserved even if a contribution is later deleted.

User Flow

1. App opens → User select screen (tap your avatar)
2. Child accounts → straight into the app
3. Parent accounts → PIN entry (4 digits, SHA-256 hashed, 3 attempts before 30s lockout)
4. Main app → bottom tab bar shows every family member's list
5. Children see their available savings balance at the top of their list; tapping it shows a breakdown of each gift
6. Parents see a "💰 Manage" button on each child's list to add or remove cash contributions
7. "Cast a Wish" FAB → modal to add a new wish to the current user's list; tapping any active wish card opens the same modal pre-filled for editing
8. Other users can claim "I'm buying this!" — hidden from the wish owner; parents also get a "Grant Wish!" button to mark a wish as received
9. When a parent grants a child's wish and the child has savings, a dialog asks whether to deduct from savings; if savings don't fully cover the price, a warning shows the shortfall and asks the parent to confirm they'll cover the rest
10. Granted wishes are collapsed by default; the toggle reveals them newest-first; tapping one shows the grant date and a savings breakdown

---

Project Structure

wishmaster/
  www/                   — Android app (self-contained, no server)
    index.html           — Full SPA (HTML + CSS + JS)
    db.js                — IndexedDB storage layer
    pin.js               — PIN hashing + lockout logic
  android/               — Capacitor-generated Android project
    app/build.gradle     — App config: package ID, SDK versions, signing config
    variables.gradle     — SDK versions (min 26, target 36)
  assets/
    icon.png             — App icon source (used by Capacitor assets tool)
  server.js              — Express server (for local web development only)
  index.html             — Web version entry point (requires server.js)
  config.json            — Web version config (family members, port)
  capacitor.config.json  — Capacitor config (appId, webDir, plugins)
  package.json           — npm scripts and dependencies

---

Testing in a Browser (Quick Start)

The Android app runs fine in a desktop browser for rapid development:

npm install
cd www && npx serve .
# Open http://localhost:3000

Open Chrome DevTools → Application → IndexedDB → wishmaster_db to inspect stored data.

Test Checklist

• First launch (empty DB) → redirects to account management with welcome title
• Add child account → login works without PIN
• Add parent account with PIN → login prompts for PIN
• Correct PIN → access granted
• Wrong PIN × 3 → 30-second lockout with countdown timer
• After lockout expires → can try again
• Add wish with all fields (name, link, price, stars) → saves correctly
• Tap an active wish card → edit modal opens pre-filled; update saves correctly
• "I'm buying this!" shows to other users but hides from the wish owner
• Parent sees "Grant Wish!" button on a child's active wishes
• Grant wish with sufficient savings → deduction dialog → savings deducted FIFO → wish moved to granted
• Grant wish with insufficient savings → warning shows shortfall → confirm covers rest → partial deduction recorded
• Grant wish choosing "No, keep savings" → wish granted, savings unchanged
• Grant wish with no price set → dialog offers to deduct full savings balance
• Granted wishes hidden by default; toggle reveals them newest-first
• Tap a granted wish → detail modal shows grant date and savings breakdown
• Savings balance bar shows correct total; tap opens breakdown modal
• Can-afford badge appears on wish when savings ≥ price; disappears when savings drop below price
• Parent adds savings contribution → balance updates immediately; note and date shown in breakdown
• Parent deletes savings contribution → balance updates; already-recorded allocations unchanged
• "Got it!" moves wish to completed section
• Delete removes wish permanently
• Switch user returns to user select screen
• Data persists across full browser page reload

---

Building and Running on an Android Phone

Prerequisites

• Node.js 18+
• Android Studio — developer.android.com/studio
  • During install: include Android SDK and API 36 build tools
• Java JDK 17+ — bundled with Android Studio

First-Time Setup

# Install Node dependencies (Capacitor CLI, Android bridge)
npm install

# Copy www/ assets into the Android project
npx cap sync android

# Open the Android project in Android Studio
npx cap open android

Running on a Physical Device (Recommended)

1. On your phone: Settings → About Phone → tap Build Number 7 times (enables Developer Options)
2. Settings → Developer Options → enable USB Debugging
3. Connect via USB and accept the debugging permission dialog on the phone
4. In Android Studio: select your device in the toolbar, then click Run ▶ (or Shift+F10)

First build takes 5–10 minutes while Gradle downloads dependencies. Subsequent builds are fast.

Running on an Emulator

In Android Studio: Tools → Device Manager → Create Device → choose Pixel, select API 36 system image.

Live Reload During Development

To see www/ changes instantly on your phone without rebuilding, add this to capacitor.config.json temporarily (remove before a release build):

"server": {
  "url": "http://YOUR_LOCAL_IP:8080",
  "cleartext": true
}

Then serve the web files:

npx serve www

Your Android device will now load from your machine live.

On-Device Test Checklist

• App icon appears in launcher
• Splash screen is dark purple (no white flash)
• Status bar colour matches theme
• Content does not appear under notch or Android navigation bar
• Bottom tab bar sits above the Android nav bar
• FAB clears the bottom tab bar
• Haptic feedback fires on wish add, delete, and "Got it!"
• PIN keypad is comfortable to use one-handed
• Data survives force-close and device restart
• Portrait orientation only (no landscape breakage)

---

Building a Release APK / AAB

Step 1 — Generate a signing keystore (one time only)

keytool -genkey -v -keystore wishmaster-upload.jks \
  -alias wishmaster -keyalg RSA -keysize 2048 -validity 10000

Store this file securely. Never commit it to git. If you lose it you cannot update the app on the Play Store.

Step 2 — Create android/keystore.properties (gitignored)

storeFile=../wishmaster-upload.jks
storePassword=YOUR_STORE_PASSWORD
keyAlias=wishmaster
keyPassword=YOUR_KEY_PASSWORD

The signing config is already wired up in android/app/build.gradle — it reads from this file automatically.

Step 3 — Sync latest web assets

npx cap sync android

Step 4 — Build

Play Store (AAB — recommended):

cd android && ./gradlew bundleRelease
# Output: android/app/build/outputs/bundle/release/app-release.aab

Direct-install APK (sideloading / testing):

cd android && ./gradlew assembleRelease
# Output: android/app/build/outputs/apk/release/app-release.apk

Install directly on your phone

adb install android/app/build/outputs/apk/release/app-release.apk

Or copy the APK to your phone and open it (enable "Install from unknown sources" in settings).

---

Submitting to Google Play Store

One-Time Account Setup

1. Go to play.google.com/console
2. Create a developer account — one-time fee of USD $25
3. Accept the developer distribution agreement

Store Listing Assets

Asset	Size	Notes
App icon	512 × 512 px PNG	Arabian lamp design
Feature graphic	1024 × 500 px PNG/JPG	Banner at top of store listing
Phone screenshots	At least 2, up to 8	9:16 portrait recommended

Recommended screenshot scenes:

1. Account selection screen (lamp animation + account cards)
2. Wish list view with savings balance bar and can-afford badge
3. "Cast a Wish" modal open
4. Savings breakdown modal (child view)
5. Grant wish deduction dialog (parent view)
6. Granted wish detail with savings allocation breakdown
7. PIN entry screen
8. Account management screen

Privacy Policy

Google Play requires a privacy policy even for apps with no network access. Host a simple page (GitHub Pages works). Sample text:

Wishmaster stores all data locally on your device using IndexedDB.
No data is transmitted to any server. No personal information is collected.
No analytics, advertisements, or external network requests are made.

Content Rating

• Category: Entertainment or Utility
• Targets mixed audience (children and parents)
• No violence, sexual content, or controlled substances
• Complies with Google Families policy (no ads, no external data collection)

Submission Steps

1. Create a new app in Play Console (select Free)
2. Fill in the store listing: title, short description (≤80 chars), full description (≤4000 chars)
3. Upload icon and feature graphic
4. Add at least 2 phone screenshots
5. Add your privacy policy URL
6. Complete the content rating questionnaire
7. Set target countries
8. Upload the signed .aab file
9. Submit for review — first-time submissions typically take 3–7 days

Suggested Store Listing Copy

Title: Wishmaster 🪔

Short description: Tell your family what you really want. No more socks. No more duplicates. No more wrong gifts.

Full description:

🪔 Got a birthday coming up? Christmas? A random Tuesday?

Wishmaster is the magical wish list app that makes sure everyone in your family knows exactly what you want — with zero chance of getting the wrong thing.

No more socks. No more duplicates. No more "oh you shouldn't have" (but secretly you agree).

✨ FOR THE WISHERS
• Write your wishes. All of them. Go wild.
• Rate how badly you want each one with 1–5 stars (you know which ones get 5 ⭐)
• Add the link so there's absolutely no excuse for getting the wrong one
• Watch your wishes get ticked off one by one 🎯

🕵️ FOR THE BUYERS (the grown-ups)
• Secretly claim "I'm buying this!" so no one else buys the same thing
• The wish owner can't see who's getting them what — no spoilers!
• Parent accounts are PIN-locked so nosy kids stay out 🔒
• Grant a wish with one tap when it arrives

💰 YOUR MONEY, TRACKED
• Got birthday money? Gift cards? Grandma's annual fiver?
• Parents log every contribution — you see your balance and where it came from
• Wishes you can already afford get a shiny "Can afford!" badge ✅
• Parents can spend your savings to grant a wish automatically

📱 NO INTERNET? NO PROBLEM
• Everything lives on your device — no account, no cloud, no nonsense
• Works on planes, in the middle of nowhere, absolutely anywhere

🎨 LOOKS PRETTY GREAT TOO
• Magic lamp. Flying carpet. Stars. Gold. You get it. 🌟

---

Built By

Designed by AJ (age 9) and built with Dad (Trev) using Claude Code. 🪄