First pass

.gitignore

@@ -0,0 +1,71 @@
+# ---- Internal planning / memory (do NOT push to the HF remote) ----
+secretplans/
+AGENTS.md
+CLAUDE.md
+
+# ---- Secrets / env ----
+.env
+.env.*
+*.env
+!.env.example      # keep the template tracked
+
+# ---- Local databases: session history (SQLite) + game-patterns vector store (LanceDB) ----
+db/
+*.sqlite
+*.sqlite3
+
+# ---- Python ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+*.egg-info/
+*.egg
+.installed.cfg
+wheels/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+.python-version
+
+# Test / type / lint caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Notebooks
+.ipynb_checkpoints/
+
+# ---- Gradio ----
+.gradio/
+flagged/
+gradio_cached_examples/
+
+# ---- App runtime artifacts ----
+# Generated adventures / sites, model caches, local DBs
+generated_sites/
+adventures/
+*.gguf
+*.sqlite
+*.db
+
+# ---- OS / editor ----
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp

README.md

@@ -13,3 +13,22 @@ short_description: A text based RPG built to help you fight procrastination
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+## FrogQuest
+
+Turn your real to-do list into an 8-bit pixel-art text-adventure quest log where **you** are the
+hero. Named for the "Eat That Frog" method: your hardest/most important task is the **frog** — the
+boss quest you face first.
+
+- **Nemotron Nano 4B** (text only, via llama.cpp on ZeroGPU) writes the quest JSON — Eat That Frog
+  prioritization, linked sub-task chains, and optional self-care bonus quests.
+- A fixed pixel-art frontend (`gr.Server` custom UI) renders that JSON as the quest log.
+- **FLUX.2 [klein] 4B** (diffusers) generates each quest's image using your uploaded photo as a
+  reference, then edits that same image into success / "retreat to fight another day" states.
+
+Your photo and quest state live **only in your browser** (localStorage); the photo is sent to the
+GPU transiently for generation and is never stored server-side.
+
+**Set the Space hardware to ZeroGPU.** First quest generation cold-downloads the model GGUF
+(~60-90s), then runs fast.
+

app.py

@@ -0,0 +1,55 @@
+"""FrogQuest server: gr.Server custom frontend + queued API endpoints (Off-Brand badge).
+
+The browser owns all state (localStorage, see static/storage.js). This server is stateless:
+it serves the pixel-art frontend and exposes two GPU-backed endpoints. The user's photo is
+sent transiently to generate_image and is never written to disk.
+
+Frontend calls endpoints via the Gradio JS Client:
+    client.predict("/generate_quests", { todos, theme })
+    client.predict("/generate_image",  { photo_b64, art_style, scene_prompt, seed })
+"""
+from __future__ import annotations
+
+import json
+import os
+
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from gradio import Server
+
+from schema import validate_and_clamp
+
+STATIC_DIR = os.path.join(os.path.dirname(__file__), "static")
+
+app = Server()
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+
+
+@app.get("/", response_class=HTMLResponse)
+async def homepage():
+    with open(os.path.join(STATIC_DIR, "index.html"), "r", encoding="utf-8") as f:
+        return f.read()
+
+
+@app.api(name="generate_quests")
+def generate_quests(todos: str, theme: str) -> str:
+    """Nemotron -> validated quest JSON (returned as a JSON string)."""
+    from llm import generate_quests_raw
+
+    raw = generate_quests_raw(todos, theme)
+    adventure = validate_and_clamp(raw, theme)
+    return json.dumps(adventure)
+
+
+@app.api(name="generate_image")
+def generate_image(photo_b64: str, art_style: str, scene_prompt: str, seed: int) -> str:
+    """FLUX.2 klein initial image with the user as hero -> PNG data URL."""
+    from images import b64_to_pil, initial_image, pil_to_data_url
+
+    photo = b64_to_pil(photo_b64)
+    img = initial_image(photo, art_style, scene_prompt, int(seed))
+    return pil_to_data_url(img)
+
+
+if __name__ == "__main__":
+    app.launch(show_error=True)

images.py

@@ -0,0 +1,87 @@
+"""FLUX.2 [klein] 4B image pipeline (diffusers, ZeroGPU).
+
+One model, one `image=` parameter does both jobs:
+  - initial generation: image=[user_photo]  (a LIST -> multi-reference; puts the user in the scene)
+  - edit (next pass):    image=base_image    (a single image -> instruction-guided edit)
+
+Shared art_style + a fixed per-adventure seed give every quest a cohesive look. Always EDIT
+the initial image for success/failure states (consistency) - never text-to-image from scratch.
+
+Pipeline loaded at module level; CUDA emulation makes that safe outside @spaces.GPU. The
+actual .to("cuda") + inference happen inside the GPU-decorated functions.
+"""
+from __future__ import annotations
+
+import base64
+import io
+
+import spaces
+import torch
+from diffusers import Flux2KleinPipeline
+from PIL import Image
+
+MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"
+# TODO(verify at build): klein's recommended fast step count. Default schema is 50; klein is
+# distilled for low latency, so this is intentionally lower. Tune against the model card.
+STEPS = 8
+GUIDANCE = 4.0
+MAX_SIDE = 768  # cap generated resolution for ZeroGPU speed
+
+_pipe = None
+
+
+def _get_pipe():
+    global _pipe
+    if _pipe is None:
+        _pipe = Flux2KleinPipeline.from_pretrained(MODEL_ID, torch_dtype=torch.bfloat16)
+    return _pipe
+
+
+def _gen(prompt: str, image, seed: int) -> Image.Image:
+    pipe = _get_pipe()
+    pipe.to("cuda")
+    generator = torch.Generator("cuda").manual_seed(int(seed))
+    result = pipe(
+        prompt=prompt,
+        image=image,
+        generator=generator,
+        num_inference_steps=STEPS,
+        guidance_scale=GUIDANCE,
+        height=MAX_SIDE,
+        width=MAX_SIDE,
+    )
+    return result.images[0]
+
+
+@spaces.GPU(duration=120)
+def initial_image(user_photo: Image.Image, art_style: str, scene_prompt: str, seed: int) -> Image.Image:
+    """Generate the quest's initial scene with the user as the hero (photo as reference)."""
+    prompt = (
+        f"{art_style}. {scene_prompt}. "
+        "The hero is the person shown in the reference image, in this style and scene."
+    )
+    return _gen(prompt, image=[user_photo], seed=seed)
+
+
+@spaces.GPU(duration=120)
+def edit_image(base_image: Image.Image, edit_instruction: str, art_style: str, seed: int) -> Image.Image:
+    """NEXT PASS (priority 5): edit the existing image into a success/failure state."""
+    prompt = f"{art_style}. {edit_instruction}"
+    return _gen(prompt, image=base_image, seed=seed)
+
+
+# --- base64 <-> PIL helpers (photo arrives transiently as a data URL; nothing is persisted) ---
+
+def b64_to_pil(data_url_or_b64: str) -> Image.Image:
+    s = data_url_or_b64
+    if "," in s and s.strip().startswith("data:"):
+        s = s.split(",", 1)[1]
+    raw = base64.b64decode(s)
+    return Image.open(io.BytesIO(raw)).convert("RGB")
+
+
+def pil_to_data_url(img: Image.Image) -> str:
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    b64 = base64.b64encode(buf.getvalue()).decode("ascii")
+    return f"data:image/png;base64,{b64}"

llm.py

@@ -0,0 +1,97 @@
+"""Nemotron Nano 4B (text-only) -> raw quest JSON, run via llama.cpp on ZeroGPU.
+
+Recipe (CLAUDE.md + ZeroGPU/llama.cpp reference): set HF_HUB_ENABLE_HF_TRANSFER before
+importing huggingface_hub, download the GGUF at module level, but construct the Llama
+object INSIDE the @spaces.GPU function (first call ~60-90s, then disk-cached & fast).
+
+The LLM's job is ONLY to write JSON to the contract in schema.py. Output is constrained
+with a JSON-schema response_format and then validated/clamped by the caller.
+"""
+from __future__ import annotations
+
+import json
+import os
+
+os.environ.setdefault("HF_HUB_ENABLE_HF_TRANSFER", "1")  # MUST precede huggingface_hub import
+
+import spaces  # noqa: E402
+from huggingface_hub import hf_hub_download  # noqa: E402
+
+from schema import RESPONSE_SCHEMA  # noqa: E402
+
+# TODO(verify at build): confirm exact GGUF repo/filename on HF. Llama-3.1-Nemotron is
+# Llama-architecture -> keeps Llama Champion eligibility. Q4_K_M is the recommended quant.
+GGUF_REPO = "unsloth/Llama-3.1-Nemotron-Nano-4B-v1.1-GGUF"
+GGUF_FILE = "Llama-3.1-Nemotron-Nano-4B-v1.1-Q4_K_M.gguf"
+
+N_CTX = 8192
+
+SYSTEM_PROMPT = """You are FrogQuest's quest designer. Convert the user's real to-do list into a themed text-adventure quest log and OUTPUT JSON ONLY - no prose, no markdown, no code.
+
+Apply the "Eat That Frog" method:
+- The FROG = the single most important/hardest task. Mark exactly ONE quest is_frog:true and order it FIRST.
+- Break each big/multi-step goal into an ordered chain of smaller quests sharing one goal_group label; keep simple to-dos as standalone quests.
+- Add 1-3 bonus self-care quests (type:"bonus") such as meditate 5 min, exercise 20 min, digital detox 1 hr. They are OPTIONAL and ENCOURAGING - never guilt-inducing.
+
+For EVERY quest write vivid {theme}-themed, 8-bit pixel-art image instructions where the USER is the hero:
+- initial_image_prompt: the hero facing the challenge (scene only - the renderer adds the user's face from a photo; do NOT describe their face).
+- success_edit: a SHORT edit instruction turning the initial scene victorious (same hero, same scene).
+- failure_edit: a SHORT, FORGIVING edit instruction - the hero retreats to fight another day. Never shaming.
+
+Set adventure.art_style to one shared "8-bit / 16-bit pixel-art, {theme} palette" string applied to every image, and adventure.seed to a single integer for the whole adventure. xp 10-100 by effort. All status:"active", image_state:"initial". Echo the user's real wording in each quest.task.
+/no_think"""
+
+_llm = None
+
+
+def _get_llm():
+    """Lazily construct the Llama model on the GPU (must run inside @spaces.GPU)."""
+    global _llm
+    if _llm is None:
+        from llama_cpp import Llama
+
+        model_path = hf_hub_download(repo_id=GGUF_REPO, filename=GGUF_FILE)
+        _llm = Llama(
+            model_path=model_path,
+            n_gpu_layers=-1,   # offload all layers to GPU
+            n_ctx=N_CTX,
+            verbose=False,
+        )
+    return _llm
+
+
+@spaces.GPU(duration=120)
+def generate_quests_raw(todos: str, theme: str) -> dict:
+    """Return the model's raw JSON object (UNVALIDATED - caller must validate_and_clamp)."""
+    llm = _get_llm()
+    system = SYSTEM_PROMPT.replace("{theme}", theme)
+    user = f"Theme: {theme}\nMy to-do list / goals:\n{todos.strip()}"
+
+    out = llm.create_chat_completion(
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ],
+        response_format={"type": "json_object", "schema": RESPONSE_SCHEMA},
+        temperature=0.0,
+        max_tokens=4096,
+    )
+    content = out["choices"][0]["message"]["content"]
+    return _extract_json(content)
+
+
+def _extract_json(text: str) -> dict:
+    """Parse JSON from the model output, tolerating stray prose or code fences."""
+    text = (text or "").strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+    # Fallback: grab the outermost { ... } span.
+    start, end = text.find("{"), text.rfind("}")
+    if start != -1 and end != -1 and end > start:
+        try:
+            return json.loads(text[start : end + 1])
+        except json.JSONDecodeError:
+            pass
+    return {}

requirements.txt

@@ -0,0 +1,15 @@
+# FrogQuest — HF Space (ZeroGPU) dependencies
+# NOTE: Flux2KleinPipeline lands in diffusers >= 0.38; install from git until the release wheel
+# exposing it is confirmed on the index.
+git+https://github.com/huggingface/diffusers.git
+gradio>=5.0
+spaces
+transformers>=4.44.2
+accelerate
+torch
+pillow
+hf-transfer
+huggingface-hub
+# llama-cpp-python with prebuilt CUDA wheels. cu128 = RTX Pro 6000 Blackwell (ZeroGPU).
+--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu128
+llama-cpp-python

schema.py

@@ -0,0 +1,189 @@
+"""FrogQuest data contract: the JSON schema the LLM emits + server-side validate/clamp.
+
+The LLM only ever writes DATA to this contract. Nothing it returns is trusted: every
+field is validated and clamped here before the frontend renders it, so a malformed or
+missing field can never break a quest card. See CLAUDE.md "Data contract".
+"""
+from __future__ import annotations
+
+import random
+import re
+from typing import Any
+
+THEMES = ("cyberpunk", "fantasy", "space")
+QUEST_TYPES = ("main", "bonus")
+STATUSES = ("active", "success", "failure")
+IMAGE_STATES = ("initial", "success", "failure")
+
+MAX_QUESTS = 12
+MAX_BONUS = 3
+
+# JSON Schema passed to llama-cpp-python via response_format to constrain generation.
+# Kept deliberately permissive (the strict guarantees are enforced by validate_and_clamp,
+# not the grammar) because GBNF-from-schema chokes on overly nested constraints.
+RESPONSE_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "adventure": {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string"},
+                "theme": {"type": "string", "enum": list(THEMES)},
+                "art_style": {"type": "string"},
+                "seed": {"type": "integer"},
+            },
+            "required": ["title", "theme", "art_style", "seed"],
+        },
+        "quests": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {"type": "string"},
+                    "task": {"type": "string"},
+                    "quest_title": {"type": "string"},
+                    "narrative": {"type": "string"},
+                    "type": {"type": "string", "enum": list(QUEST_TYPES)},
+                    "goal_group": {"type": "string"},
+                    "is_frog": {"type": "boolean"},
+                    "initial_image_prompt": {"type": "string"},
+                    "success_edit": {"type": "string"},
+                    "failure_edit": {"type": "string"},
+                    "xp": {"type": "integer"},
+                },
+                "required": [
+                    "task", "quest_title", "narrative", "type",
+                    "is_frog", "initial_image_prompt", "success_edit",
+                    "failure_edit", "xp",
+                ],
+            },
+        },
+    },
+    "required": ["adventure", "quests"],
+}
+
+
+def _s(value: Any, default: str = "") -> str:
+    """Coerce to a stripped string."""
+    if value is None:
+        return default
+    if isinstance(value, str):
+        return value.strip()
+    return str(value).strip()
+
+
+def _clamp_int(value: Any, lo: int, hi: int, default: int) -> int:
+    try:
+        n = int(value)
+    except (TypeError, ValueError):
+        return default
+    return max(lo, min(hi, n))
+
+
+def _slugify(text: str, fallback: str) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug or fallback
+
+
+def validate_and_clamp(raw: Any, theme: str) -> dict[str, Any]:
+    """Turn whatever the LLM returned into a safe, render-ready adventure object.
+
+    Guarantees on return:
+      - adventure has title/theme/art_style/seed (int)
+      - 1..MAX_QUESTS quests, each with all schema fields and unique non-empty id
+      - exactly one is_frog quest, and it is ordered FIRST
+      - <= MAX_BONUS bonus quests
+      - type/status/image_state are valid enum values; xp in 0..100
+    """
+    theme = theme if theme in THEMES else THEMES[0]
+    raw = raw if isinstance(raw, dict) else {}
+
+    adv_in = raw.get("adventure") if isinstance(raw.get("adventure"), dict) else {}
+    seed = adv_in.get("seed")
+    try:
+        seed = int(seed)
+    except (TypeError, ValueError):
+        seed = random.randint(0, 2**31 - 1)
+
+    adv_theme = adv_in.get("theme")
+    adv_theme = adv_theme if adv_theme in THEMES else theme
+
+    adventure = {
+        "title": _s(adv_in.get("title")) or "Your Quest Log",
+        "theme": adv_theme,
+        "art_style": _s(adv_in.get("art_style"))
+        or f"8-bit / 16-bit retro pixel art, {adv_theme} palette, NES RPG style",
+        "seed": seed,
+    }
+
+    quests_in = raw.get("quests")
+    quests_in = quests_in if isinstance(quests_in, list) else []
+
+    cleaned: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+    bonus_count = 0
+
+    for idx, q in enumerate(quests_in):
+        if len(cleaned) >= MAX_QUESTS:
+            break
+        if not isinstance(q, dict):
+            continue
+
+        qtype = q.get("type")
+        qtype = qtype if qtype in QUEST_TYPES else "main"
+        if qtype == "bonus":
+            if bonus_count >= MAX_BONUS:
+                qtype = "main"  # demote excess bonus quests to main
+            else:
+                bonus_count += 1
+
+        title = _s(q.get("quest_title")) or _s(q.get("task")) or f"Quest {idx + 1}"
+        qid = _s(q.get("id"))
+        if not qid or qid in seen_ids:
+            qid = _slugify(title, f"quest-{idx + 1}")
+            base, n = qid, 2
+            while qid in seen_ids:
+                qid, n = f"{base}-{n}", n + 1
+        seen_ids.add(qid)
+
+        cleaned.append({
+            "id": qid,
+            "task": _s(q.get("task")) or title,
+            "quest_title": title,
+            "narrative": _s(q.get("narrative")),
+            "type": qtype,
+            "goal_group": _s(q.get("goal_group")) or None,
+            "is_frog": bool(q.get("is_frog")),
+            "initial_image_prompt": _s(q.get("initial_image_prompt")),
+            "success_edit": _s(q.get("success_edit")) or "Show the hero victorious.",
+            "failure_edit": _s(q.get("failure_edit"))
+            or "The hero retreats safely to rest and try again another day.",
+            "xp": _clamp_int(q.get("xp"), 0, 100, 25),
+            # fresh-generation runtime state (never trusted from the model)
+            "status": "active",
+            "image_state": "initial",
+        })
+
+    if not cleaned:
+        # Degenerate output: synthesise a single placeholder so the UI still renders.
+        cleaned.append({
+            "id": "quest-1", "task": "Add your first task", "quest_title": "The Journey Begins",
+            "narrative": "Tell the oracle your goals to fill this log.", "type": "main",
+            "goal_group": None, "is_frog": True, "initial_image_prompt": "",
+            "success_edit": "Show the hero victorious.",
+            "failure_edit": "The hero retreats to try again.", "xp": 10,
+            "status": "active", "image_state": "initial",
+        })
+
+    # Enforce exactly one frog, ordered first. Prefer a main quest flagged by the model.
+    frog_idx = next((i for i, q in enumerate(cleaned) if q["is_frog"] and q["type"] == "main"), None)
+    if frog_idx is None:
+        frog_idx = next((i for i, q in enumerate(cleaned) if q["is_frog"]), None)
+    if frog_idx is None:
+        frog_idx = next((i for i, q in enumerate(cleaned) if q["type"] == "main"), 0)
+    for i, q in enumerate(cleaned):
+        q["is_frog"] = (i == frog_idx)
+    frog = cleaned.pop(frog_idx)
+    cleaned.insert(0, frog)
+
+    return {"adventure": adventure, "quests": cleaned}

static/app.js

@@ -0,0 +1,232 @@
+// FrogQuest frontend flow. The browser owns all state; the server is two stateless endpoints.
+import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/+esm";
+import * as store from "/static/storage.js";
+
+const $ = (sel) => document.querySelector(sel);
+const $$ = (sel) => document.querySelectorAll(sel);
+
+let state = store.load();
+let pendingPhoto = state.profile.photo; // staged during onboarding
+let pendingTheme = state.profile.theme;
+let _client = null;
+
+async function client() {
+  if (!_client) _client = await Client.connect(window.location.origin);
+  return _client;
+}
+
+function setTheme(theme) {
+  document.documentElement.dataset.theme = theme || "cyberpunk";
+}
+
+function show(id) {
+  ["screen-onboard", "screen-app"].forEach((s) => ($("#" + s).hidden = s !== id));
+  $("#settings-btn").hidden = id !== "screen-app";
+}
+
+function overlay(msg) {
+  $("#overlay-msg").textContent = msg;
+  $("#overlay").hidden = false;
+}
+function hideOverlay() {
+  $("#overlay").hidden = true;
+}
+
+// ---------------- onboarding ----------------
+
+function refreshBeginEnabled() {
+  $("#begin-btn").disabled = !(pendingPhoto && pendingTheme);
+}
+
+function initOnboarding() {
+  setTheme(pendingTheme);
+
+  if (pendingPhoto) {
+    $("#photo-preview").src = pendingPhoto;
+    $("#photo-preview").hidden = false;
+    $("#photo-placeholder").hidden = true;
+  }
+  $$("#theme-grid .theme-card").forEach((c) =>
+    c.classList.toggle("selected", c.dataset.theme === pendingTheme)
+  );
+
+  $("#photo-input").addEventListener("change", async (e) => {
+    const file = e.target.files[0];
+    if (!file) return;
+    try {
+      pendingPhoto = await store.resizePhoto(file);
+      $("#photo-preview").src = pendingPhoto;
+      $("#photo-preview").hidden = false;
+      $("#photo-placeholder").hidden = true;
+      refreshBeginEnabled();
+    } catch {
+      alert("Could not read that image — try another file.");
+    }
+  });
+
+  $$("#theme-grid .theme-card").forEach((card) =>
+    card.addEventListener("click", () => {
+      pendingTheme = card.dataset.theme;
+      setTheme(pendingTheme);
+      $$("#theme-grid .theme-card").forEach((c) =>
+        c.classList.toggle("selected", c === card)
+      );
+      refreshBeginEnabled();
+    })
+  );
+
+  $("#begin-btn").addEventListener("click", () => {
+    state = store.update({ profile: { photo: pendingPhoto, theme: pendingTheme } });
+    enterApp();
+  });
+
+  refreshBeginEnabled();
+  show("screen-onboard");
+}
+
+// ---------------- main app ----------------
+
+function enterApp() {
+  setTheme(state.profile.theme);
+  show("screen-app");
+  if (state.adventure && state.quests.length) {
+    renderAdventure();
+  }
+}
+
+async function onGenerate() {
+  const todos = $("#todos-input").value.trim();
+  if (!todos) {
+    $("#todos-input").focus();
+    return;
+  }
+  overlay("THE ORACLE IS WRITING YOUR QUEST LOG…");
+  try {
+    const c = await client();
+    const res = await c.predict("/generate_quests", {
+      todos,
+      theme: state.profile.theme,
+    });
+    const adventure = JSON.parse(res.data[0]);
+    state = store.update({
+      adventure: adventure.adventure,
+      quests: adventure.quests,
+      images: {}, // new adventure -> drop old image cache
+    });
+    renderAdventure();
+  } catch (err) {
+    console.error(err);
+    alert("The oracle stumbled. Please try again.\n\n" + (err?.message || err));
+  } finally {
+    hideOverlay();
+  }
+}
+
+function renderAdventure() {
+  const { adventure, quests, images } = state;
+  $("#adventure-header").hidden = false;
+  $("#adventure-title").textContent = adventure.title || "Your Quest Log";
+
+  const log = $("#quest-log");
+  log.innerHTML = "";
+  const tpl = $("#quest-card-tpl");
+
+  quests.forEach((q) => {
+    const node = tpl.content.firstElementChild.cloneNode(true);
+    node.dataset.questId = q.id;
+    if (q.is_frog) node.classList.add("is-frog");
+    if (q.type === "bonus") node.classList.add("is-bonus");
+
+    node.querySelector(".frog-badge").hidden = !q.is_frog;
+    node.querySelector(".bonus-badge").hidden = q.type !== "bonus";
+    const group = node.querySelector(".group-badge");
+    if (q.goal_group) {
+      group.hidden = false;
+      group.textContent = "⛓ " + q.goal_group;
+    }
+
+    node.querySelector(".quest-title").textContent = q.quest_title;
+    node.querySelector(".quest-narrative").textContent = q.narrative;
+    node.querySelector(".quest-task").textContent = q.task;
+    node.querySelector(".xp").textContent = q.xp + " XP";
+
+    const img = node.querySelector(".quest-img");
+    const empty = node.querySelector(".quest-art-empty");
+    const cached = images[q.id]?.initial;
+    if (cached) {
+      img.src = cached;
+      img.hidden = false;
+      empty.hidden = true;
+    } else {
+      node
+        .querySelector(".gen-img-btn")
+        .addEventListener("click", () => generateScene(q, node));
+    }
+
+    log.appendChild(node);
+  });
+}
+
+async function generateScene(quest, node) {
+  if (!state.profile.photo) {
+    alert("Add a photo in Settings first so you can star in the scene.");
+    return;
+  }
+  const btn = node.querySelector(".gen-img-btn");
+  btn.disabled = true;
+  btn.textContent = "DRAWING…";
+  try {
+    const c = await client();
+    const res = await c.predict("/generate_image", {
+      photo_b64: state.profile.photo,
+      art_style: state.adventure.art_style,
+      scene_prompt: quest.initial_image_prompt,
+      seed: state.adventure.seed,
+    });
+    const dataUrl = res.data[0];
+    state = store.cacheImage(quest.id, "initial", dataUrl);
+    const img = node.querySelector(".quest-img");
+    img.src = dataUrl;
+    img.hidden = false;
+    node.querySelector(".quest-art-empty").hidden = true;
+  } catch (err) {
+    console.error(err);
+    btn.disabled = false;
+    btn.textContent = "RETRY SCENE";
+    alert("The artist's pixels jammed. Try again.\n\n" + (err?.message || err));
+  }
+}
+
+// ---------------- settings ----------------
+
+function initSettings() {
+  $("#settings-btn").addEventListener("click", () => {
+    pendingPhoto = state.profile.photo;
+    pendingTheme = state.profile.theme;
+    // re-seed onboarding UI with current values
+    $("#photo-preview").src = pendingPhoto || "";
+    $("#photo-preview").hidden = !pendingPhoto;
+    $("#photo-placeholder").hidden = !!pendingPhoto;
+    $$("#theme-grid .theme-card").forEach((c) =>
+      c.classList.toggle("selected", c.dataset.theme === pendingTheme)
+    );
+    refreshBeginEnabled();
+    show("screen-onboard");
+  });
+}
+
+// ---------------- boot ----------------
+
+function boot() {
+  $("#generate-btn").addEventListener("click", onGenerate);
+  initSettings();
+  initOnboarding();
+
+  if (state.profile.photo && state.profile.theme) {
+    enterApp();
+  } else {
+    show("screen-onboard");
+  }
+}
+
+boot();

static/index.html

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="cyberpunk">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>FrogQuest</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="/static/style.css" />
+</head>
+<body>
+  <div class="scanlines" aria-hidden="true"></div>
+
+  <header class="topbar">
+    <h1 class="logo">FROG<span>QUEST</span></h1>
+    <button id="settings-btn" class="pix-btn small" hidden>SETTINGS</button>
+  </header>
+
+  <!-- FIRST RUN: photo + theme -->
+  <main id="screen-onboard" class="screen" hidden>
+    <div class="panel">
+      <h2 class="panel-title">NEW HERO</h2>
+      <p class="hint">Upload a photo so you become the hero of every quest. It stays in your
+        browser — sent to the GPU only to draw your scenes, never stored on a server.</p>
+
+      <label class="uploader" id="photo-drop">
+        <input type="file" id="photo-input" accept="image/*" hidden />
+        <img id="photo-preview" alt="" hidden />
+        <span id="photo-placeholder">▣ CLICK TO UPLOAD PHOTO</span>
+      </label>
+
+      <h3 class="panel-subtitle">CHOOSE YOUR WORLD</h3>
+      <div class="theme-grid" id="theme-grid">
+        <button class="theme-card" data-theme="cyberpunk">
+          <span class="theme-emoji">🌃</span><span>CYBERPUNK</span>
+        </button>
+        <button class="theme-card" data-theme="fantasy">
+          <span class="theme-emoji">🏰</span><span>FANTASY</span>
+        </button>
+        <button class="theme-card" data-theme="space">
+          <span class="theme-emoji">🚀</span><span>SPACE</span>
+        </button>
+      </div>
+
+      <button id="begin-btn" class="pix-btn primary" disabled>BEGIN ADVENTURE ▶</button>
+    </div>
+  </main>
+
+  <!-- MAIN: goals -> quest log -->
+  <main id="screen-app" class="screen" hidden>
+    <section class="panel compose">
+      <h2 class="panel-title">TELL THE ORACLE YOUR PLANS</h2>
+      <textarea id="todos-input" rows="5"
+        placeholder="e.g. Finish the quarterly report (due Friday), reply to 3 emails, book dentist, start gym routine, learn one chord on guitar..."></textarea>
+      <button id="generate-btn" class="pix-btn primary">⚔ FORGE QUEST LOG</button>
+    </section>
+
+    <section id="adventure-header" class="adventure-header" hidden>
+      <h2 id="adventure-title"></h2>
+    </section>
+
+    <section id="quest-log" class="quest-log" aria-live="polite"></section>
+  </main>
+
+  <!-- status / loading overlay -->
+  <div id="overlay" class="overlay" hidden>
+    <div class="overlay-box">
+      <div class="loader"></div>
+      <p id="overlay-msg">LOADING…</p>
+    </div>
+  </div>
+
+  <!-- card template -->
+  <template id="quest-card-tpl">
+    <article class="quest-card">
+      <div class="quest-art">
+        <img class="quest-img" alt="" hidden />
+        <div class="quest-art-empty">
+          <span class="art-glyph">🗺</span>
+          <button class="pix-btn small gen-img-btn">GENERATE SCENE</button>
+        </div>
+      </div>
+      <div class="quest-body">
+        <div class="quest-badges">
+          <span class="badge frog-badge" hidden>🐸 THE FROG</span>
+          <span class="badge bonus-badge" hidden>✦ BONUS · OPTIONAL</span>
+          <span class="badge group-badge" hidden></span>
+        </div>
+        <h3 class="quest-title"></h3>
+        <p class="quest-narrative"></p>
+        <p class="quest-task"></p>
+        <div class="quest-foot">
+          <span class="xp"></span>
+        </div>
+      </div>
+    </article>
+  </template>
+
+  <script type="module" src="/static/app.js"></script>
+</body>
+</html>

static/storage.js

@@ -0,0 +1,82 @@
+// FrogQuest browser-only persistence. Everything lives in localStorage under one key.
+// The photo is resized client-side BEFORE storing so it fits the ~5MB localStorage cap.
+
+const KEY = "frogquest:v1";
+const PHOTO_MAX_SIDE = 512;
+const PHOTO_QUALITY = 0.8;
+
+const EMPTY = {
+  version: 1,
+  profile: { photo: null, theme: null },
+  adventure: null,
+  quests: [],
+  images: {}, // questId -> { initial, success, failure } (data URLs; best-effort cache)
+};
+
+export function load() {
+  try {
+    const raw = localStorage.getItem(KEY);
+    if (!raw) return structuredClone(EMPTY);
+    const parsed = JSON.parse(raw);
+    return { ...structuredClone(EMPTY), ...parsed };
+  } catch {
+    return structuredClone(EMPTY);
+  }
+}
+
+export function save(state) {
+  // Try to persist everything; if the image cache blows the quota, drop it and keep the
+  // reproducible core (seed + prompts regenerate the images on demand).
+  try {
+    localStorage.setItem(KEY, JSON.stringify(state));
+  } catch (e) {
+    if (e && e.name === "QuotaExceededError") {
+      const lean = { ...state, images: {} };
+      try {
+        localStorage.setItem(KEY, JSON.stringify(lean));
+      } catch {
+        /* give up on persistence; in-memory state still works this session */
+      }
+    }
+  }
+  return state;
+}
+
+export function update(patch) {
+  return save({ ...load(), ...patch });
+}
+
+export function cacheImage(questId, slot, dataUrl) {
+  const state = load();
+  state.images[questId] = { ...(state.images[questId] || {}), [slot]: dataUrl };
+  return save(state);
+}
+
+export function clear() {
+  localStorage.removeItem(KEY);
+}
+
+// Read an uploaded File, downscale so the longest side <= PHOTO_MAX_SIDE, return a JPEG data URL.
+export function resizePhoto(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error("Could not read file"));
+    reader.onload = () => {
+      const img = new Image();
+      img.onerror = () => reject(new Error("Could not decode image"));
+      img.onload = () => {
+        let { width, height } = img;
+        const scale = Math.min(1, PHOTO_MAX_SIDE / Math.max(width, height));
+        width = Math.round(width * scale);
+        height = Math.round(height * scale);
+        const canvas = document.createElement("canvas");
+        canvas.width = width;
+        canvas.height = height;
+        canvas.getContext("2d").drawImage(img, 0, 0, width, height);
+        resolve(canvas.toDataURL("image/jpeg", PHOTO_QUALITY));
+      };
+      img.src = reader.result;
+    };
+    reader.readAsDataURL(file);
+  });
+}

static/style.css

@@ -0,0 +1,171 @@
+/* FrogQuest — 8-bit / NES-RPG pixel-art theme. */
+
+:root {
+  --bg: #0d0b1a;
+  --bg2: #161228;
+  --panel: #1d1733;
+  --ink: #e8e6ff;
+  --dim: #9b95c9;
+  --accent: #00e5ff;
+  --accent2: #ff2e88;
+  --gold: #ffd23f;
+  --frog: #4ade5b;
+  --shadow: #000;
+  --border: 4px;
+  font-family: "Press Start 2P", monospace;
+}
+
+/* ---- per-theme palettes (set on <html data-theme>) ---- */
+[data-theme="cyberpunk"] { --bg:#0d0b1a; --bg2:#161228; --panel:#1d1733; --accent:#00e5ff; --accent2:#ff2e88; --gold:#ffd23f; }
+[data-theme="fantasy"]   { --bg:#10180f; --bg2:#172414; --panel:#1d2e1a; --accent:#7bdc5a; --accent2:#ffae34; --gold:#ffe066; --ink:#eafbe2; --dim:#9ec48c; }
+[data-theme="space"]     { --bg:#070914; --bg2:#0d1124; --panel:#141a36; --accent:#7c5cff; --accent2:#36c5ff; --gold:#ffd23f; --ink:#e6ecff; --dim:#8d97c9; }
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  image-rendering: pixelated;
+}
+
+body {
+  min-height: 100vh;
+  padding-bottom: 48px;
+  font-size: 11px;
+  line-height: 1.7;
+  background-image:
+    repeating-linear-gradient(0deg, transparent 0 38px, rgba(255,255,255,0.015) 38px 39px),
+    repeating-linear-gradient(90deg, transparent 0 38px, rgba(255,255,255,0.015) 38px 39px);
+}
+
+/* faint CRT scanlines */
+.scanlines {
+  position: fixed; inset: 0; pointer-events: none; z-index: 9000;
+  background: repeating-linear-gradient(0deg, rgba(0,0,0,0.16) 0 2px, transparent 2px 4px);
+  mix-blend-mode: multiply;
+}
+
+/* ---------- top bar ---------- */
+.topbar {
+  display: flex; align-items: center; justify-content: space-between;
+  padding: 16px 20px; border-bottom: var(--border) solid var(--accent);
+  background: var(--bg2);
+}
+.logo { margin: 0; font-size: 20px; letter-spacing: 2px; color: var(--accent); text-shadow: 3px 3px 0 var(--shadow); }
+.logo span { color: var(--accent2); }
+
+/* ---------- screens / panels ---------- */
+.screen { max-width: 860px; margin: 0 auto; padding: 24px 16px; }
+.panel {
+  background: var(--panel);
+  border: var(--border) solid var(--ink);
+  box-shadow: 8px 8px 0 var(--shadow);
+  padding: 22px; margin-bottom: 22px;
+}
+.panel-title { margin: 0 0 14px; font-size: 13px; color: var(--gold); text-shadow: 2px 2px 0 var(--shadow); }
+.panel-subtitle { margin: 22px 0 12px; font-size: 11px; color: var(--accent); }
+.hint { color: var(--dim); font-size: 10px; line-height: 1.9; }
+
+/* ---------- buttons ---------- */
+.pix-btn {
+  font-family: inherit; font-size: 11px; color: var(--ink); cursor: pointer;
+  background: var(--bg2); border: var(--border) solid var(--ink);
+  box-shadow: 4px 4px 0 var(--shadow); padding: 12px 16px;
+  text-transform: uppercase; transition: transform .05s, box-shadow .05s;
+}
+.pix-btn:hover { background: var(--accent); color: var(--bg); }
+.pix-btn:active { transform: translate(4px, 4px); box-shadow: 0 0 0 var(--shadow); }
+.pix-btn:disabled { opacity: .4; cursor: not-allowed; }
+.pix-btn.primary { background: var(--accent2); color: #fff; border-color: #fff; width: 100%; margin-top: 18px; font-size: 12px; padding: 16px; }
+.pix-btn.primary:hover { background: var(--gold); color: var(--bg); }
+.pix-btn.small { font-size: 9px; padding: 9px 10px; box-shadow: 3px 3px 0 var(--shadow); }
+
+/* ---------- uploader ---------- */
+.uploader {
+  display: flex; align-items: center; justify-content: center;
+  width: 100%; min-height: 200px; cursor: pointer;
+  border: var(--border) dashed var(--accent); background: var(--bg2);
+  color: var(--dim); font-size: 10px; text-align: center; overflow: hidden;
+}
+.uploader:hover { border-color: var(--gold); color: var(--ink); }
+#photo-preview { width: 100%; height: 240px; object-fit: cover; display: block; }
+
+/* ---------- theme picker ---------- */
+.theme-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+.theme-card {
+  font-family: inherit; font-size: 9px; color: var(--ink); cursor: pointer;
+  display: flex; flex-direction: column; align-items: center; gap: 10px;
+  padding: 18px 8px; background: var(--bg2);
+  border: var(--border) solid var(--dim); box-shadow: 4px 4px 0 var(--shadow);
+}
+.theme-card:hover { border-color: var(--accent); }
+.theme-card.selected { border-color: var(--gold); background: var(--panel); box-shadow: 4px 4px 0 var(--accent2); }
+.theme-emoji { font-size: 26px; line-height: 1; }
+
+/* ---------- compose ---------- */
+.compose textarea {
+  width: 100%; resize: vertical; font-family: inherit; font-size: 10px; line-height: 1.8;
+  color: var(--ink); background: var(--bg2); border: var(--border) solid var(--accent);
+  padding: 14px; box-shadow: inset 3px 3px 0 var(--shadow);
+}
+.compose textarea:focus { outline: none; border-color: var(--gold); }
+
+/* ---------- adventure header ---------- */
+.adventure-header { max-width: 860px; margin: 0 auto 6px; padding: 0 16px; }
+.adventure-header h2 { font-size: 14px; color: var(--gold); text-shadow: 2px 2px 0 var(--shadow); }
+
+/* ---------- quest log ---------- */
+.quest-log { display: flex; flex-direction: column; gap: 20px; }
+
+.quest-card {
+  display: grid; grid-template-columns: 200px 1fr;
+  background: var(--panel); border: var(--border) solid var(--ink);
+  box-shadow: 8px 8px 0 var(--shadow); overflow: hidden;
+}
+.quest-card.is-frog { border-color: var(--frog); box-shadow: 8px 8px 0 var(--frog); }
+.quest-card.is-bonus { border-style: dashed; }
+.quest-card.done { opacity: .85; }
+
+.quest-art { position: relative; background: var(--bg2); border-right: var(--border) solid var(--ink); min-height: 200px; }
+.quest-img { width: 100%; height: 100%; object-fit: cover; image-rendering: pixelated; }
+.quest-art-empty {
+  position: absolute; inset: 0; display: flex; flex-direction: column;
+  align-items: center; justify-content: center; gap: 14px; color: var(--dim);
+}
+.art-glyph { font-size: 40px; opacity: .6; }
+
+.quest-body { padding: 16px 18px; }
+.quest-badges { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 10px; }
+.badge { font-size: 8px; padding: 5px 7px; border: 2px solid currentColor; }
+.frog-badge { color: var(--frog); }
+.bonus-badge { color: var(--accent); }
+.group-badge { color: var(--gold); }
+.quest-title { margin: 4px 0 10px; font-size: 12px; color: var(--ink); line-height: 1.6; }
+.quest-narrative { margin: 0 0 12px; font-size: 9px; color: var(--dim); line-height: 1.9; }
+.quest-task { margin: 0 0 14px; font-size: 9px; color: var(--accent); line-height: 1.8; }
+.quest-task::before { content: "▸ TASK: "; color: var(--dim); }
+.quest-foot { display: flex; align-items: center; justify-content: space-between; }
+.xp { font-size: 9px; color: var(--gold); }
+.xp::before { content: "★ "; }
+
+/* ---------- overlay ---------- */
+.overlay {
+  position: fixed; inset: 0; z-index: 9500; display: flex; align-items: center; justify-content: center;
+  background: rgba(5,4,12,0.86);
+}
+.overlay-box { text-align: center; color: var(--ink); }
+.overlay-box p { font-size: 11px; margin-top: 18px; color: var(--accent); }
+.loader {
+  width: 36px; height: 36px; margin: 0 auto; background: var(--accent2);
+  animation: blink 0.6s steps(2, end) infinite;
+}
+@keyframes blink { 0% { opacity: 1; transform: scale(1); } 50% { opacity: .3; transform: scale(.7); } 100% { opacity: 1; transform: scale(1); } }
+
+/* ---------- responsive ---------- */
+@media (max-width: 620px) {
+  .quest-card { grid-template-columns: 1fr; }
+  .quest-art { border-right: none; border-bottom: var(--border) solid var(--ink); }
+  .theme-grid { grid-template-columns: 1fr; }
+  .logo { font-size: 16px; }
+}