# CBT Mock & Timestamp Studio - Complete Master Architecture Guide

## 1. System Overview
This repository contains a full-stack offline-first CBT (Computer Based Test) generation and annotation suite. It transforms YouTube lectures, screenshots, timestamps, and study notes into 100% standalone, zero-dependency interactive HTML mock tests with built-in drawing tools, video synchronization, offline QR codes, and print layouts.

---

## 2. Core Modules & Architecture

### Module 1: Studio Player & Android / Mobile Engine (`timestamp-studio.html`)
1. **YouTube IFrame Controller**:
   - Integrates YouTube IFrame API with custom responsive controls.
   - Quick Minute Jump (`jumpToMinuteInput`), Frame-accurate Seek (`seekFrame(-1/+1)`), and relative skips (`seekRelative(-10/+10, -30/+30, -60/+60)`).
2. **Turbo Scan Playback Engine**:
   - Native YouTube speeds: 0.75x, 1.0x, 1.25x, 1.5x, 2.0x.
   - Fast Scan Turbo Mode: 4.0x and 6.0x utilizing interval-based forward seek pulses (`startTurboPulse`) while playing at 2.0x base rate.
3. **Focus Question & Zoom Engine (Distraction-Free)**:
   - Removes YouTube title bars and header overlays (`focus-mode`).
   - Multi-level zoom: 100%, 115%, 130% to fit question content edge-to-edge.
   - Automatically saves state to `localStorage` (`yt_focus_question`, `yt_player_zoom`).
4. **Android & Mobile Touch Optimization**:
   - Dedicated touch control bar (`.footer-player-controls`) below slides.
   - Touch drag handlers (`touchstart`, `touchmove`, `touchend`) with `passive: false` on floating toolbars and modals.
   - `touch-action: none` on annotation canvases to eliminate mobile scroll collision while drawing.
5. **Keyboard Shortcuts**:
   - Space/K: Play/Pause | J/L: -10s/+10s | Shift+Left/Right: -30s/+30s | PageUp/Down: +60s/-60s | ,/.: Frame seek | Shift+F: Toggle Focus.

---

### Module 2: Standalone HTML Generator (`constructMasterStudyHTML`)
- **Location**: `timestamp-studio.html` & `html-notes-updater.html` (both at root and `Builder tools/`).
- **Functionality**:
  - Compiles questions array, base64 images, syllabus sections, custom links, and offline QR codes into a single `.html` file.
  - Zero network dependencies: runs seamlessly via `file://` protocol without CORS blocks or server requirements.
- **Notes Updater Engine (Tab 3)**:
  - Drag-and-drop existing `.html` study notes file.
  - Re-order questions, edit titles/timestamps, replace individual slide images, and re-export updated master file.

---

### Module 3: 8-Tool Vector Canvas Annotation Engine
Every standalone file and studio preview features an embedded vector drawing engine:
1. **Overlay Resolution**:
   - `<canvas class="anno-canvas" id="canvas-{idx}" width="1920" height="1080">` layered directly over slide images.
2. **State Management**:
   ```javascript
   var annoState = {
     active: false,
     tool: "pen",
     penColor: "#000000",
     highlighterColor: "#FFEB3B",
     penSize: 4,
     highlighterSize: 22,
     eraserSize: 20,
     activeCardIndex: null,
     isDrawing: false,
     currentStroke: null
   };
   ```
3. **8 Toolset Implementation**:
   - **👆 View (`#toolView` / `data-tool="view"`)**: Sets canvas `pointer-events: none` and `cursor: default`. Allows native clicking, scrolling, and video playback.
   - **🖊️ Pen (`#toolPen` / `data-tool="pen"`)**: Smooth quadratic bezier curve drawing with `annoState.penColor` and `annoState.penSize`.
   - **🖍️ Highlighter (`#toolHigh` / `data-tool="highlighter"`)**: Wide transparent stroke (`opacity: 0.38`) using `annoState.highlighterColor` and `annoState.highlighterSize`.
   - **🧹 Smart Stroke Eraser (`#toolErase` / `data-tool="eraser"`)**: Mathematical point-to-stroke distance calculation (`findStrokeAtPoint`) detects and removes the specific clicked or dragged stroke without corrupting other drawings.
   - **➡️ Arrow (`#toolArrow` / `data-tool="arrow"`)**: Vector arrow with live drag preview and calculated arrowhead tip wings.
   - **⭕ Circle (`#toolCircle` / `data-tool="circle"`)**: Bounding-box ellipse drawing with live drag preview.
   - **⬜ Box / Rect (`#toolRect` / `data-tool="rect"`)**: Bounding-box rectangle outline with live drag preview.
   - **🔠 On-Slide Text Tool (`#toolText` / `data-tool="text"`)**: Spawns floating in-place input (`showTextInputAt`), allowing typed notes at exact slide coordinates; bakes into vector strokes on Enter.
4. **Toolbar Controls**:
   - **8-Color Palette (`.color-dot`)**: #FFEB3B, #FF3B30, #4CD964, #007AFF, #FFFFFF, #000000, #AF52DE, #FF9500. Automatically syncs with current tool and updates live preview dot.
   - **Dynamic Size Slider (`#annoSizeSlider`)**: Live updates width/diameter of active tool and adjusts preview dot.
   - **Draggable Floating Panel**: Header dragging via mouse (`mousedown`) and mobile touch (`touchstart`) on `#annoPanelHeader`.
   - **Active Card Indicator (`#activeCardIndicator`)**: Dynamically shows `(Active: Q{x})` whenever a slide is clicked, drawn on, or activated via `window.startCardAnno(idx)`.
   - **Actions**:
     - Undo (`#annoUndoBtn` / `Ctrl+Z`): Removes last stroke from active card.
     - Clear Card (`#annoClearCardBtn`): Clears strokes on active card.
     - Clear All (`#annoClearAllBtn`): Clears all annotations across all cards with user confirmation.
     - Save Slide PNG (`#annoSnapCardBtn`): Exports 1080p high-resolution PNG combining original slide + drawn notes.
     - Bake HTML (`#annoSaveBtn` / `window.exportAnnotatedHTML`): Permanently serializes live notes into `/*__CARD_STROKES_DATA_START__*/` block in the HTML document so drawings remain permanently preserved upon reopening.

---

### Module 4: Offline Client-Side QR Engine
- 100% pure client-side QR generation using embedded `qrcode` engine without third-party API dependencies.
- Embeds direct video timestamp URLs (`https://youtu.be/{id}?t={sec}`).
- Draggable QR stamps: users can drag QR codes directly from the browser into Word, PowerPoint, or Desktop.
- Toggle visibility: `#toggleQrStampsBtn` hides/shows QR codes across all slides.

---

### Module 5: Print & PDF Export Engine
- Layout selector:
  - Single Column: 1, 2, 3, 4, 6 slides per page.
  - Double Column: 2, 4, 6, 8, 10, 12 slides per page (Compact Booklet layout).
- Orientation: Portrait & Landscape.
- Range Filter: All slides, Only annotated slides, Custom slide range.
- Preserves high-resolution vector text, formulas, and clickable interactive links in the final exported PDF.

---

## 3. Maintenance & Extension Rules
When editing or adding new features to this project or related exam tools:
1. **Always Sync Mirror Files**: Ensure changes in `timestamp-studio.html` and `html-notes-updater.html` are mirrored to their counterparts in `Builder tools/`.
2. **Never Break Generator Template**: Inside `constructMasterStudyHTML`, always preserve the complete 8-tool annotation scripts, draggable panel handlers, and `/*__CARD_STROKES_DATA_START__*/` marker.
3. **Preserve Base64 Assets**: Standalone test files in `CBT/` contain thousands of base64 images; use selective patching to update scripts without rewriting image data.
4. **Offline First**: Never introduce external CDN scripts that fail without internet or fail on the `file://` protocol.