Project Spellbook 🪄

A family magic workshop where kids program real smart-home hardware by inventing Harry Potter–style spells.

My kids wave an M5StickC "wand," shout an incantation, and the lights actually change. Project Spellbook is the parchment-and-ink control room behind that: an AI-powered app where children design spells (gesture + incantation + target gadget), Gemini translates them into real Arduino firmware and Home Assistant automations, and a Marauder's-Map-style quest system turns the whole house into a treasure hunt.

What's inside

The app has two faces, gated by a hidden key in the corner of the screen.

🧙 Wizard mode — what the kids see

The Lab. Pick wand movements from an illustrated gesture palette, choose a target artifact (a "Magic Bulb", a "Spirit Lock"...) and what it should do, name your spell, and brew. Behind the cauldron, Gemini writes M5StickC IMU-detection code in C++ and a matching Home Assistant automation — every spell is real, deployable firmware wearing a costume.

The Spellbook. The family grimoire. Auto-generate kid-friendly spells from whatever hardware you own, each with an AI-drawn ink sketch of the wand movement. Any spell's page folds open to reveal its technical blueprint — a gentle on-ramp from "magic" to "oh, that's code."

The Hunt. A quest map that guides wizards room to room with AI-written riddles matched to their spells and your house, ending in a real prize ("a chocolate frog is waiting in the cupboard!").

🎩 Teacher's Office — what the parents see

Behind a passphrase: a Quest Workshop (pick difficulty, rooms, and prize; publish to the map), a Merchant's Ledger (paste a receipt or upload a photo/PDF and AI extracts your hardware into inventory — you curate what the kids can see), Manual Forging (hand-add gadgets and register each kid's wand), and Arcane Insights (AI suggestions for what to build with what you own, and what to buy next).

How the magic works

flowchart LR
    subgraph House["🏠 The House"]
        W[M5StickC wand<br/>IMU gestures] -->|MQTT spell_cast| HA[Home Assistant]
        HA --> B[💡 Bulbs]
        HA --> L[🔒 Locks]
        HA --> S[🔊 Speakers]
    end
    subgraph App["📖 Project Spellbook"]
        UI[React + Vite<br/>parchment UI] --> G[Gemini 3.5 Flash<br/>structured JSON]
        UI --> IMG[Nano Banana 2<br/>spell sketches]
        G -->|generates| CPP[Arduino C++<br/>gesture firmware]
        G -->|generates| YAML[Home Assistant<br/>automation YAML]
    end
    CPP -.->|you flash| W
    YAML -.->|you deploy| HA

Loading

The app generates the deployable artifacts; you flash the wand and load the automations. Closing the loop live — the map auto-advancing when a spell is actually cast — is the top item on the roadmap.

Tech: React 19 + TypeScript + Vite, Tailwind CSS v4, @google/genai with structured-output JSON schemas (gemini-3.5-flash for logic and quests, gemini-3.1-flash-image for ink sketches). All state persists in localStorage — no backend, no accounts, nothing leaves the house except Gemini calls.

Quick start

Prerequisites: Node.js 20+

npm install
cp .env.example .env.local   # add your key from https://aistudio.google.com/apikey
npm run dev                  # http://localhost:3000

Tap the key icon (bottom-right) and enter admin to open the Teacher's Office and add your first hardware.

Tests

npm test

Runs the end-to-end suite: bundles the app with esbuild, mounts it in jsdom with a fully mocked Gemini API, and drives every screen — office login, receipt analysis, curation, spell brewing, sketch generation, the complete quest hunt, persistence, and reset. 21 checks, zero network, no API key needed.

Project structure

App.tsx                    shell, navigation, persistence
components/
  PotionsLab.tsx           spell brewing (gestures → hardware → code)
  Grimoire.tsx             the spellbook + AI spell/sketch generation
  MaraudersMap.tsx         quest hunt UI
  HeadmasterOffice.tsx     parent admin: quests, inventory, insights
  ComponentVault.tsx       manual hardware/wand registration
  Toast.tsx                parchment-themed toasts + confirm dialogs
services/geminiService.ts  all AI calls, JSON schemas, id/type hygiene
tests/e2e.test.mjs         mocked end-to-end suite

A note on keys

The Gemini key is bundled into the browser at build time — by design, for a zero-backend app that lives on your home network. Don't deploy it publicly with a real key baked in; if you ever want it on the open internet, put the key behind a small proxy (see IDEAS.md).

Roadmap

The fun stuff — live MQTT wand feedback, voice incantations, house points, printable quest scrolls — lives in IDEAS.md.

License

MIT