Product Specification: Story Bible Builder (YAML Quiz App)

Overview

The Story Bible Builder is an interactive, single-page web application designed to teach YAML syntax through a narrative-driven exercise. Users learn to format data by building components of a fictional "Story Bible" (characters, inventories, and lore).

The app alternates between read-only Lessons (Examples) and interactive Challenges, providing immediate, highly specific feedback on the user's code.

Tech Stack

• Structure: Single-file HTML5 (index.html).
• Styling: Tailwind CSS (loaded via CDN) for responsive, modern UI.
• Code Editor: CodeMirror v5.65.13 (loaded via CDN). Provides the text area, YAML syntax highlighting, line numbers, and keyboard shortcut handling.
• Animations: Canvas Confetti (loaded via CDN) for success state celebrations.
• Logic: Vanilla JavaScript (ES6+). No build tools or frontend frameworks required.

Core Features

1. Dual-Mode Progression: * Examples: Read-only CodeMirror instances showing correct YAML formatting.
   • Challenges: Editable CodeMirror instances where users must write or modify YAML to pass.
2. Smart Validation: Custom Regex-based validation that checks for common YAML mistakes (e.g., missing colons, using tabs instead of spaces, missing hyphens) and returns targeted error messages instead of generic "Wrong" alerts.
3. Pre-filled States: Challenges can start with existing code that the user must modify, simulating real-world editing.
4. Keyboard Accessibility: Users can press Shift-Enter inside the editor to submit their answer or proceed to the next step, while standard Enter preserves the ability to create new lines in the YAML code.
5. Visual Feedback: Dynamic UI updates including progress tracking (e.g., "1 / 6"), color-coded success/error alert boxes, and SVG icons.

Data Structure

The application state is driven by a steps array containing objects. Each object represents one screen in the app.

Step Object Schema

{
  type: String,         // "example" or "challenge"
  title: String,        // Main heading (e.g., "Lesson 1: Character Basics")
  text: String,         // Instructions or lore context
  mode: String,         // UI hint (e.g., "Challenge (Editable)")
  code: String,         // (Example only) The text to display in the editor
  initialCode: String,  // (Challenge only) Starting code for the user to edit
  validate: Function,   // (Challenge only) Takes user string, returns { isCorrect: Boolean, message: String }
  successMsg: String    // (Challenge only) Message shown on correct answer
}