Handles the two-step AI generation pipeline — the core differentiator of LessonPlay. Gemini processes lesson content + learning objectives to produce (1) structured questions and (2) a self-contained HTML game that runs in a sandboxed iframe.

Overview

SDK: @google/genai npm package (GoogleGenAI class)
Input: Lesson text content + learning objective + objective type
Step 1 Output: 8-10 structured questions as JSON (for scoring/analytics)
Step 2 Output: Self-contained HTML game (inline CSS/JS, no external deps) that renders the questions
Key: Questions test understanding, not recall. Games are unique every time.
Format: Step 1 uses structured JSON output; Step 2 uses plain text (HTML string)

When to Use This Skill

Building or modifying the two-step generation pipeline
Engineering or iterating on the question generation prompt
Engineering or iterating on the HTML game generation prompt
Parsing and validating Gemini's structured output
Validating generated HTML (postMessage protocol, no external URLs)
Handling generation errors or retries
Mapping objective types to question/game formats

Key Concepts

SDK Usage

import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({ apiKey });
const response = await ai.models.generateContent({ model, contents, config });
const text = response.text; // property, NOT a method

Structured Output

Use config.responseMimeType: "application/json" and config.responseSchema to enforce JSON structure. The SDK handles schema validation — no need to manually parse or hope for correct formatting.

Objective Type → Question Format Mapping

Objective Type	Preferred Question Types
Understand	Multiple choice (concept questions)
Explain	Multiple choice (why/how questions)
Apply	Multiple choice (scenario-based)
Distinguish	Categorization (sort into groups)
Perform	Ordering (sequence steps)
Analyze	Multiple choice + categorization

Calling from Convex

Gemini calls MUST happen in a Convex action (not query or mutation). Use ctx.runMutation(internal.xxx.yyy, args) to store results in the database.

Question Quality Markers

Tests understanding over recall
Wrong answers are plausible misconceptions, not random
Explanation teaches, not just confirms
Question maps to the stated learning objective

HTML Game Generation Requirements

The generated HTML must:

Be a complete <!DOCTYPE html> document with inline <style> and <script>
Include <meta name="viewport" content="width=device-width, initial-scale=1.0">
Use no external dependencies (no CDN scripts, no external CSS, no images via URL)
Implement the postMessage communication protocol (GAME_READY, ANSWER_SUBMITTED, GAME_OVER)
Use CSS relative units (%, vh, vw, rem) and pointer events (not click-only)
Have touch targets >= 44px
Not use localStorage, sessionStorage, fetch, or XMLHttpRequest (sandbox blocks these)

HTML Validation

Before storing, validate:

Contains postMessage or port.postMessage code
No external src= or href= pointing to other domains
Contains the question data
Is structurally valid HTML

Related Files

convex/generate.ts — Gemini API action (two-step: questions + HTML game)
docs/PRD.md — Architecture and AI generation sections

Reference Files

reference.md — Prompt templates, API examples, HTML generation