# SlideCast: AI Slide & Simulation Generation Guide
> **Purpose**: This guide provides the complete specification and prompt instructions for creating interactive, production-ready slide decks and decoupled standalone simulations that run inside the **SlideCast Sandbox Platform**.
>
> Pass this document to any AI model (Claude, ChatGPT, Gemini) to generate slide decks and physics simulations that work on the first try.
---
## 0. START HERE — The Slide Maker's Feature Catalog (Plain-English Menu)
> **For new slide makers.** This section answers three questions in plain language:
> 1. What can a slide **do** inside SlideCast?
> 2. What is **not possible yet**?
> 3. How do I **instruct an AI** to build slides using these features?
*Example: `Work_and_Potential/lecture_deck.html` presented inside `index.html`.*
### 0.1 The One-Minute Model
- **The Slider** (`index.html`) = the venue. It owns screen fitting, arrow-key navigation, pen / highlighter / laser, navigator drawer (G), frosted whiteboard sheet (O), and media sound management. It never changes for a lecture.
- **The Slide deck** (`Work_and_Potential/lecture_deck.html`) = your content. You have 100% freedom over looks and behavior.
- **The handshake**: the slider reacts to a fixed vocabulary of classes and `data-*` markers. Write a marker → get its behavior. Anything outside the vocabulary is simply ignored by the slider (which is perfectly fine for pure design and animation).
### 0.2 The Full Menu — Available Today
**A. Freedom zone (no markers needed — the slider stays out of your way):**
HTML/CSS layouts, Tailwind styling, custom fonts, hover effects, CSS keyframes, SVG, Canvas, **animation libraries (GSAP, Motion, Anime.js)**, Three.js 3D, KaTeX/MathJax formulas, **Mermaid diagrams, Chart.js graphs**, and your own buttons running their own `` + `onclick="fn()"` | Slider hoists `fn` so the button works (reserved names protected) | §3.5 |
| 12 | **Speaker notes** | `` | Hidden on stage; broadcast to the synced second window | §0.4 |
| 13 | **Jump to any slide** | `onclick="goToSlide(4)"` | Direct jump from any button or table-of-contents | §8 |
| 14 | **Simulation modal** | `openSimulation('modalId')` + `
```
---
## 5. Multi-Step Click Animations (Fragments & Inner Slide Builds)
SlideCast includes a native **Click-to-Build / Fragment Engine**. This lets you reveal bullet points, diagrams, formulas, and trigger custom JavaScript animations sequentially across multiple clicks on the **same slide** before moving to the next slide.
### How It Works
1. **On Slide 1**: Pressing →, Space, or clicking the Next button moves to Slide 2.
2. **On Slide 2**: If Slide 2 contains inner `.step` elements, clicking Next **does not** jump to Slide 3. Instead, each click triggers the next step or animation inside Slide 2.
3. **Advancing to Slide 3**: Only after all inner steps on Slide 2 are completed will the next click transition to Slide 3.
4. **Smooth Reverse**: Clicking Previous (←) undoes the inner steps in reverse order before navigating back to the previous slide. Navigating backwards to a slide automatically shows all its steps in completed state.
---
### Step HTML Syntax & Styling
#### A. Basic Sequential Reveal
Simply add `class="step"` (or `class="fragment"`). Elements will appear one-by-one in DOM order:
```html
Force & Acceleration
Step 1: Unbalanced force causes acceleration.
Step 2: Acceleration is proportional to net force: $a \propto F_{net}$.
Step 3: Final formula: $F = m \cdot a$.
```
#### B. Grouped Reveals & Custom Order (`data-step="N"`)
Use `data-step="N"` to control the exact click number. Elements that share the same step number will appear **simultaneously** on that click:
```html
Figure 1: Free body diagram with normal force and gravity.
$$\Sigma F_y = N - mg = 0$$
```
#### C. Built-in Animation Modifiers
Combine `.step` with built-in transition modifier classes:
| Class | Visual Effect |
| :--- | :--- |
| `class="step"` | Smooth upward glide + fade with Apple easing (`cubic-bezier(0.16, 1, 0.3, 1)`) |
| `class="step fade"` | Pure opacity fade with no translation |
| `class="step zoom"` | Scale pop-in from 0.88 to 1.0 |
| `class="step slide-left"` | Enters from right to left |
| `class="step slide-right"` | Enters from left to right |
| `class="step highlight"` | Starts dimmed (32% opacity) and lights up to 100% when clicked |
---
### Triggering Custom JavaScript Animations (`data-step-action`)
You can run arbitrary JavaScript code, GSAP line-draws, or Canvas physics animations on specific clicks by adding `data-step-action`:
```html
Kinetic Energy Derivation
We start with the kinematic formula: $v^2 = u^2 + 2as$
$W_{net} = \Delta KE = \frac{1}{2}m v_f^2 - \frac{1}{2}m v_i^2$
```
> [!TIP]
> You can either provide a function name (e.g. `data-step-action="animateWorkVector"`) or inline code (e.g. `data-step-action="gsap.to('#box', {x: 200})"`).
---
### D. Multi-Media Step Sequencing (Text $\to$ Video $\to$ Simulation in Steps)
You can mix different media types freely in sequential click steps on the same slide:
```
[Slide Loads] ──> Step 1: Text & Concept Question appear
│
(Click Next)
▼
Step 2: Video appears
• data-autoplay: Starts playback immediately on reveal
• OR Click-to-Play: Shows controls, teacher talks first
│
(Click Next)
▼
Step 3: Interactive Simulation canvas appears & starts running
│
(Click Next)
▼
Step 4: Takeaway Formula & Conclusion appear
```
#### Code Implementation Example:
```html
Gravitational Acceleration
Hypothesis: Do heavier objects fall faster than lighter ones in a vacuum?
Apollo 15 experiment: Hammer and feather dropped simultaneously on the Moon.
$$g = 9.8\, \text{m/s}^2 \quad \text{(Independent of mass!)}$$
```
#### Media Lifecycle Rules Handled Automatically by SlideCast:
1. **Autoplay on Step**: Videos with `data-autoplay` remain paused while hidden. They start playing the instant their `.step` becomes active.
2. **Click-to-Play on Step**: Videos without `data-autoplay` reveal in a paused state with controls, so the presenter can introduce the topic before clicking play.
3. **Step Reversal**: Pressing ← (Previous) to undo a step automatically pauses the video and resets its playback time to zero.
4. **Slide Navigation Silence**: Navigating to another slide automatically pauses and silences all videos across previous slides, preventing audio leakage.
---
## 6. Question & Quiz Slide Patterns: Solve & Reveal vs. Interactive Assessment
In technical and scientific lecturing, slides must never be purely passive lecture notes. They are active intellectual checkpoints where instructors gauge comprehension and students engage in deliberate practice.
SlideCast natively supports **two complementary question paradigms**, plus a decoupled architecture for extensive question banks:
```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│ QUESTION & QUIZ ARCHITECTURE │
│ │
│ PATTERN 1: "SOLVE & REVEAL" PATTERN 2: INTERACTIVE QUIZ │
│ (Live Pen Working Space) (Clickable Concept Check) │
│ │
│ ┌──────────────────────────────┐ ┌──────────────────────────────┐ │
│ │ ❓ Problem Statement & Data │ │ 💡 Concept Question │ │
│ ├──────────────────────────────┤ ├──────────────────────────────┤ │
│ │ ✍️ Blank Whiteboard Canvas │ │ [A] Option 1 (Red on click) │ │
│ │ (Teacher inks with [P]) │ │ [B] Option 2 (Green correct) │ │
│ ├──────────────────────────────┤ ├──────────────────────────────┤ │
│ │ ✅ Step Reveal Model Answer │ │ 💬 Instant Explanation │ │
│ │ (Next click [→] reveals) │ │ (Reveals on answer/click) │ │
│ └──────────────────────────────┘ └──────────────────────────────┘ │
│ │
│ PATTERN 3: DECOUPLED QUIZ APPS (quizzes/*.html) │
│ Multi-question assessments, randomized banks, and gamified timers launched via modal. │
└────────────────────────────────────────────────────────────────────────────────────────┘
```
---
### Pattern A: "Solve & Reveal" Question Card (Live Pen Working Space)
**Best for:** Numerical problems, physics derivations, free-body diagrams, and organic chemistry mechanisms where the instructor or student needs to work out the solution in real time.
#### How It Works:
1. **Problem Card**: Presents the problem statement, given values, and target variables at the top or left.
2. **Dedicated Inking Canvas**: A generous blank space styled with a clean white/slate background or subtle dotted grid. The presenter presses P (Vector Pen) or H (Highlighter) and writes directly onto the slide to solve the problem live in class.
3. **Model Answer Reveal**: The official step-by-step solution is marked with `class="step"`. When the presenter finishes solving or wants to show the verified answer, pressing → or Space reveals the model solution card smoothly.
#### Minimal Working Example:
```html
PRACTICE PROBLEM
Maximum Height of a Projectile
A ball is launched with initial velocity $v_0 = 20\, \text{m/s}$ at an angle $\theta = 30^\circ$.
Find the maximum height reached ($g = 10\, \text{m/s}^2$).
✍️
Instructor / Student Working Area (Press P to write)
```
---
### Pattern B: Interactive Quiz / ConcepTest Card (Clickable Options with Instant Feedback)
**Best for:** Conceptual checkpoints, Peer Instruction (Mazur method), and rapid multiple-choice sanity checks during a lecture.
#### How It Works:
1. **Interactive State in Cursor Mode (V)**: When the presenter or student is in standard Cursor mode (V or Esc), option buttons respond to clicks.
2. **Instant Visual Validation**:
- Tapping an option immediately reveals whether it is correct (turns emerald green) or incorrect (turns rose red).
- Tapping also reveals an informative explanation card explaining **why** the correct answer is right and clarifying common student misconceptions.
3. **Optional Step Sequencing**:
- The question can appear first, with options revealing one-by-one via `class="step"`.
- Or the whole question and options are visible immediately, and the explanation card is gated behind a `.step`.
#### Minimal Working Example:
```html
CONCEPT CHECK (CONCEPTEST)
A heavy truck collides head-on with a small compact car. During the collision, which vehicle experiences a greater magnitude of impact force?
✓ Correct Answer: C (Newton's Third Law)
By Newton's 3rd Law, the force exerted by the truck on the car is exactly equal and opposite to the force exerted by the car on the truck ($|F_{TC}| = |F_{CT}|$). The car sustains far more visible damage solely because of its smaller mass ($a = F/m$ causes much higher acceleration/deceleration).
```
---
### Decoupled Quiz Applications (`quizzes/` Folder)
Just as heavy Canvas simulations are kept out of slides and placed in `simulations/`, **multi-question assessments, randomized tests, or gamified quizzes** belong in a decoupled `quizzes/` folder:
```
my-lecture/
├── lecture_deck.html # Main SlideCast slides
├── simulations/ # Decoupled interactive simulations
│ ├── orbit_sim.html
│ └── friction_sim.html
├── quizzes/ # Decoupled interactive quiz apps
│ ├── motion_quiz.html # Multi-question interactive quiz
│ └── forces_exam.html # Timed practice assessment
└── assets/
└── images/
```
#### When to Decouple into `quizzes/`:
- **Single checkpoint question** $
ightarrow$ Keep inline on the slide using Pattern A (Solve & Reveal) or Pattern B (ConcepTest).
- **Multi-question bank or timed quiz (3+ questions, score tracker, randomized order)** $
ightarrow$ Place in `quizzes/.html` and open via the standard Modal Launcher:
```html
Module Knowledge Check
5 interactive concept questions with immediate scoring.
Motion Knowledge Check
```
#### Platform Rule for New Sandbox Features:
Whenever a new interactive quiz widget, scoring engine, or inking workspace is added to the SlideCast sandbox runtime, developers and AI agents must update this section to explain both:
1. How the feature renders and behaves inside the sandbox.
2. The exact slide HTML code required to utilize the feature.
---
## 7. Branching Sub-Slides & Drilldowns ("Inner Slides")
When an overview slide presents multiple sub-topics (e.g. **4 Fundamental Forces**, **3 Laws of Motion**, or **5 Case Studies**), you should use **Sub-Slides**.
A Sub-Slide is a dedicated deep-dive view that opens smoothly over the current slide **without altering the main presentation slide numbers (`1, 2, 3...`)**.
```
┌────────────────────────────────────────────────────────┐
│ MAIN SLIDE 2 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 1. Gravity │ │ 2. Electro │ │ 3. Nuclear │ │
│ │ (Click Me!) │ │ │ │ │ │
│ └──────┬───────┘ └──────────────┘ └──────────────┘ │
└─────────┼──────────────────────────────────────────────┘
│ onclick="openSubslide('sub-gravity')"
▼
┌────────────────────────────────────────────────────────┐
│ [← Back to Overview] Slide 2 • Deep Dive │
│ ↑ Only exit point │
│ SUB-SLIDE: Universal Gravitation │
│ • Full Derivation │
│ • Interactive Orbit Video / Simulation │
│ • Dedicated Whiteboard Ink Layer │
│ [→ / Space advances steps INSIDE sub-slide only] │
└────────────────────────────────────────────────────────┘
```
### Sub-Slide HTML Structure
Place `
` directly inside the parent slide:
```html
Fundamental Forces of Nature
1. Gravitational Force
Always attractive · Infinite range
Click for Deep Dive →
2. Electrostatic Force
Attractive or repulsive · Infinite range
Click for Deep Dive →
Slide 2 • Deep Dive
Newton's Law of Universal Gravitation
Every point mass attracts every other point mass by a force acting along the line intersecting both points.
```
#### Key Platform Behaviors for Sub-Slides:
- **Clean Numbering**: The bottom dock indicator displays `2 [Branch]`, preserving the global deck slide count (`Slide 2 / 5`).
- **One-Key Return**: Pressing Escape or clicking `← Back to Overview` smoothly returns you to the main overview.
- **Independent Inking**: Whiteboard ink drawn on a sub-slide stays on that sub-slide and does not bleed into the main slide.
- **Inner Step Support**: Pressing Next (→) while inside a sub-slide steps through the sub-slide's inner `.step` fragments before returning.
---
## 8. Direct Navigation: Slide Navigator with Live Miniature Previews
Presenters often need to jump directly across a presentation (e.g. from Slide 7 back to Slide 1 to review a formula, or from Slide 2 to Slide 5 for a quiz).
SlideCast provides a **Keynote / PowerPoint-style Slide Navigator**:
1. **Slide Navigator Left Rail (HotKey: G)**:
- Pressing G opens a sleek slide drawer on the left side of the screen.
- **Main Presentation Dimming**: The main presentation stage gently dims (`opacity: 0.45; filter: blur(1px)`) in the background, keeping context visible while highlighting the navigator.
- **Live Scaled Miniature Previews**: Instead of just text, each card features a **complete, pixel-perfect visual thumbnail** of the slide rendered at 0.195× scale. It displays the slide's actual layout, typography, background gradients, hero artwork, and cards!
- **Step Completion Preview**: In the thumbnail, all step fragments are revealed so the presenter can immediately identify the slide by its full contents.
- **Live Whiteboard Ink Previews**: Any annotations drawn with the pen or highlighter on a slide are dynamically rendered onto that slide's thumbnail canvas.
- **Sandboxed Safety**: Cloned thumbnails have all `
