# 📚 Feature Reference — HMG ACADEMY CLASS DECK v9 Enterprise

Every feature in v9, in detail, with code references. Each feature is **free**, works **offline**, and uses **free-tier services only**.

---

## 📑 Index

- [A. Workspace & Pane Apps](#a-workspace--pane-apps)
- [B. Live Classroom](#b-live-classroom)
- [C. Activities & Formative Assessment](#c-activities--formative-assessment)
- [D. Assignments & Gradebook](#d-assignments--gradebook)
- [E. Calendar & Standards](#e-calendar--standards)
- [F. Badges, Portfolios, Parent Portal](#f-badges-portfolios-parent-portal)
- [G. Discussions & Voice Notes](#g-discussions--voice-notes)
- [H. Reach & Inclusion](#h-reach--inclusion)
- [I. Reliability & DevOps](#i-reliability--devops)
- [J. Auth & Licensing](#j-auth--licensing)

---

## A. Workspace & Pane Apps

### A1. Split-screen dual-pane

The teacher sees two app panes side-by-side, resizable via a draggable gutter.

**Source:** `teach.html` + `js/teach.js` (`mountApp`).

**How to use:** Tap a tab on the left or right pane head. Drag the centre divider to resize.

**Saved to localStorage** (`pane_L`, `pane_R`) so it persists across sessions.

### A2. Whiteboard (`board`)

Pen, highlighter, eraser, laser pointer, line, rectangle, circle, text. Multi-page decks. Undo. PNG export. Palm rejection.

**Source:** `js/whiteboard.js` (`WB.init`).

**Why it matters:** The same whiteboard is also used by each *student* — they get a personal board only the teacher can see (see C1).

### A3. PDF (`pdf`)

Loads any PDF (file upload or URL). Zoom, page nav.

**Source:** `js/whiteboard.js` (`PDF.init`) + `vendor/pdf.min.js`.

**Caveat:** Cross-origin PDFs often fail to load in the browser due to CORS. The workaround is to download the PDF first.

### A4. Web (`web`)

Loads any URL into a sandboxed iframe. "Reader Cast" mode wraps the page in a magazine-style chrome (white background, big serif font, narrow column).

**Source:** `js/webcast.js` + `js/teach.js` event hooks.

**Bundled library:** the dropdown contains 40+ vetted education sites (Desmos, GeoGebra, PhET, Ducksters, etc.).

### A5. Notes (`notes`)

A side-pane plain-text notepad. Auto-saves per side.

### A6. Image (`image`)

Upload any image (PNG/JPG). Broadcasts the image URL to all students.

### A7. Graph (`graph`)

Plot any single-variable function. Pure SVG, no chart library.

**Source:** `js/teach.js` (`initGraph`). Try `sin(x)`, `x*x`, `exp(-x)*cos(2*x)`.

### A8. Video (`video`)

Plays local video files. (YouTube embeds work via the Browser pane for many sites.)

### A9. Toolkit (`toolkit`)

SVG geometry construction tools — compass, straightedge, protractor, polygons.

**Source:** `js/toolkit.js`.

### A10. Flashcards (`flash`)

Multi-card deck. Tap to flip. ✏ Edit to add your own cards. Editor accepts `question | answer` per line.

**Source:** `js/teach.js` (`initFlash`).

### A11. Timer (`stopwatch`)

Stopwatch + countdown with lap times. When countdown hits 0, an announcement pops on every student screen.

**Source:** `js/teach.js` (`initStopwatch`).

---

## B. Live Classroom

### B1. Go Live (PeerJS WebRTC P2P)

**Source:** `js/teach.js` (`goLive`) + `js/rtc.js`.

The teacher presses **▶ Go Live** → a 6-character room code is generated → students join by typing it in `join.html`.

### B2. Roster

The teacher sees every joined student with: name, hand-raised icon, points, mic mute, spotlight, kick buttons.

**Source:** `js/teach.js` (`renderRoster`).

### B3. Chat

Public chat to all. Teacher's messages appear with a "Teacher" prefix.

**Source:** `js/teach.js` (`Chat.send`).

### B4. Behaviour points

⭐ +1 (participation), 🤝 +1 (teamwork), 💡 +2 (great answer), ⚠ −1 (off-task). Each award broadcasts to all students with the name in big text.

**Source:** `js/teach.js` (`Chat.award`).

### B5. Waiting room / PIN / Lock / Mute-all

Implemented in v8. See `docs/USER_GUIDE.md`.

### B6. Auto-reconnect (v9 new)

The `js/rtc.js` module watches the PeerJS connection every 25 s. If a heartbeat is missed for 60 s, it drops the peer cleanly and tries to reconnect — silently, with exponential backoff (1 s → 2 s → 4 s → 8 s, capped at 15 s, 3 retries).

If all retries fail, the teacher sees a toast: "Cloud signaling unavailable — use QR/URL fallback."

### B7. QR / URL backup signaling (v9 new)

If PeerJS cloud is blocked on the school's firewall, the teacher presses **📡 QR Join**. The app generates a QR code containing a compressed SDP offer. The student scans it (or pastes the URL), and the connection establishes *pure P2P*, no server.

**Source:** `js/p2pcode.js` + `js/rtc.js`.

Compression uses the browser's built-in `CompressionStream("gzip")` API — present in all modern browsers.

---

## C. Activities & Formative Assessment

### C1. 🎨 Personal student whiteboards (Whiteboard.fi parity)

Tap **Tools → 🎨 → ▶ Start boards**. Every student instantly gets a personal whiteboard on their device. Only the teacher sees them. Live thumbnails stream into the roster grid; tap one to enlarge.

**Source:** `js/join.js` (`Join.initMyWhiteboard`) + `js/teach.js` (`Activities`).

### C2. 🧩 Open question (Pear Deck parity)

Press **Tools → 💬 Open question**. Type the prompt. All students get a text input. Responses stream into the chat tab with names.

**Source:** `Activities.openQuestion` → `Join.onData` → `handleAnswer`.

### C3. ☁ Word cloud (Mentimeter parity)

Press **Tools → ☁ Word cloud**. Each student submits one word. Live aggregation renders a word cloud (sized by frequency) on every student's screen.

**Source:** `Activities.wordCloud` + `js/polls.js` (`renderPollLiveTally`).

### C4. 🎟 Exit ticket (Pear Deck parity)

Press **Tools → 🎟 Exit ticket**. Each student submits: "1 thing learned" + "1 thing still confusing" + a 1–5 star understanding rating. Collected privately for the teacher.

**Source:** `Activities.exitTicket` + `handleExitTicket`.

### C5. 👥 Random group maker (ClassDojo parity)

Press **Tools → 👥 Random groups**. Enter the number of groups. Students are shuffled fairly into groups; each student sees a green banner announcing their group number.

**Source:** `Activities.makeGroups`.

### C6. 🔊 Noise meter (ClassDojo parity)

Press **Tools → 🔊 Noise meter**. Students see a class-volume gauge using their device microphone. Green→amber→red arc. Set threshold via tap-and-drag. When crossed, screen flashes red with "TOO LOUD!". Nothing is recorded or transmitted.

### C7. 🗳 Polls (Mentimeter parity)

Press **Tools → 🗳 Polls** or **Tools → 😊 Mood poll**. Choose question type: multiple-choice, scale, open-text, ranking, yes/no, or **confusion-meter** (anonymous "I'm lost" vote).

**Source:** `js/polls.js` (`Polls.create`, `Polls.respond`, `Polls.tally`).

### C8. 🏆 Quick quiz (Kahoot! parity)

Press **Tools → 🏆 Quick quiz**. Type `What is 7 × 8?|54|56!|64|72`. The `!` marks the correct answer. Students answer; teacher sees live tally.

**Source:** `Activities.quickQuiz`.

---

## D. Assignments & Gradebook

### D1. Create assignment (Schoology parity)

Dashboard → **Assignments** tab → fill in title / category / weight / due date → **Create**.

**Source:** `js/assignments.js` (`Assignments.create`).

Each assignment has:
- **title, description**
- **category** (General / Homework / Quiz / Project / Exam)
- **weight** (used in weighted overall %)
- **dueDate** (late = automatic badge)
- **rubric** (per-criterion descriptor + max points)
- **standards** (alignment — see E2)

### D2. Submit assignment

Students submit from their `join.html` (or any class view). Late submissions flagged automatically.

**Source:** `Assignments.submit`.

### D3. Grade with rubric

Dashboard → Assignments → click an assignment → click a submission → **Grade**. Per-criterion score inputs with descriptors + comment.

**Source:** `Gradebook.grade`.

### D4. Gradebook

Dashboard → **Gradebook** tab → see per-student, per-assignment matrix with weighted overall %.

**Source:** `Gradebook.classReport`.

**Export:** click **📥 Export CSV** to download a gradebook that opens in Excel / Sheets.

### D5. Rubric templates

Three built-in templates: Writing, Math problem, Lab report. Customise per assignment.

**Source:** `RUBRIC_TEMPLATES` in `js/assignments.js`.

---

## E. Calendar & Standards

### E1. Weekly planner / calendar (Moodle parity)

Dashboard → **Calendar** tab → navigate months → click any date → add an event (Lesson / Exam / Holiday / Assignment). Recurring weekly lessons supported.

**Source:** `js/calendar.js` + `renderMonthGrid`.

### E2. Standards alignment (Schoology parity)

Dashboard → click **📊 Standards** in top nav → browse 16 built-in standards across 5 frameworks.

| Framework | Coverage |
|---|---|
| NERDC (Nigeria) | Primary 3, Primary 5, JSS1 |
| WAEC (Nigeria) | SS1 Algebra, SS2 Mechanics, SS3 Equilibrium |
| CCSS-Math | Grades 3, 5, 7, HS |
| CCSS-ELA | Grades 5, 7 |
| NGSS | MS matter, HS biology |
| UK National Curriculum | Year 5 fractions, Year 7 cells |

**Source:** `js/standards.js` + `STANDARDS_SEED` in `js/storage.js`.

**Add more standards:** edit `STANDARDS_SEED` and re-deploy, or programmatically:
```js
Storage.saveStandards([{ code: "MY-STD-1", framework: "Custom", subject: "Math", grade: "5", strand: "Algebra", description: "…" }]);
```

**Export coverage:** click **📥 Export CSV** on the Standards page.

---

## F. Badges, Portfolios, Parent Portal

### F1. 8 built-in badges (Kahoot!/Duolingo parity)

Auto-awarded by a rule engine after every graded action:

| Badge | Rule |
|---|---|
| 🎯 First Perfect Score | Got 100% on any quiz or assignment |
| 🔥 7-Day Streak | Joined a live class 7 days in a row |
| 🤝 Helper | Helped 3 classmates (peer assist) |
| 🧙 Math Wizard | Scored 100% on 5 different math quizzes |
| ⭐ Rising Star | Improved overall grade by 20% in a week |
| 🐦 Early Bird | Joined class 5+ min early, 5 times |
| 🎤 Polished Presenter | Shared 3 great open answers |
| 🏅 First Badge | Earned your very first badge (meta-badge) |

**Source:** `js/badges.js` (`BADGE_RULES`, `Badges.evaluate`).

**Manual award:** Dashboard → **Badges** tab → click any locked badge tile to award it.

### F2. Student portfolios (Seesaw/ClassDojo parity)

A permanent archive of best work, badges, and progress charts. Each portfolio item has a title, body, and timestamp.

**Add to portfolio:** from the Dashboard, click any graded submission → **＋ Add to portfolio**.

**View:** `portfolio.html` → type your name → see all your badges, grades, and portfolio items.

### F3. Parent portal (ClassDojo/Brightwheel parity)

Each student has a unique 6-character parent code (auto-generated). Parents open `parent.html` → enter code → see:

- Overall %
- Recent grades
- Badges earned
- Portfolio highlights
- Teacher's note (optional)

**Source:** `js/parent.js` (`Parent.view`).

### F4. Weekly report (PDF)

Dashboard → any student's row → **📥 Print / Save as PDF** → the parent's browser converts the parent portal view to a PDF for emailing/WhatsApp'ing.

---

## G. Discussions & Voice Notes

### G1. Class discussion forum (Edmodo parity)

Dashboard → **Discussions** tab → post a thread → students reply. Teacher can pin / lock / grade posts. Threaded rendering.

**Source:** `js/discussion.js` (`Discussion.post`, `Discussion.thread`).

### G2. Voice notes + auto-transcription (Showbie parity)

Studio → **Tools → 🎙 Voice note** → record → auto-transcribe using the browser's Web Speech API.

**Source:** `js/voice-notes.js` (`VoiceNotes.start`, `VoiceNotes.save`).

**Note:** Web Speech API is free and built into every modern browser. It does *not* call any cloud AI service.

---

## H. Reach & Inclusion

### H1. 10-language UI (ClassDojo's 35+ langs parity)

EN, FR, ES, PT, AR (RTL), HI, SW, HA, YO, IG.

**Switch:** Top-right 🌐 button on any page, or open `index.html` → click any language pill.

**Source:** `js/i18n.js` + `locales/*.json`.

**Add a new language:** copy `locales/en.json` → translate → save as `locales/<code>.json` → reload. No build step.

### H2. Accessibility suite

- **Full keyboard navigation** — every control reachable via Tab.
- **Screen-reader labels** — `aria-label` everywhere.
- **Live region announcer** — `HMG_A11Y.announce()`.
- **High-contrast mode** — `Alt+C`.
- **Dyslexia-friendly font** — `Alt+D` (loads OpenDyslexic from Google Fonts).
- **Adjustable text size** — `Alt+S` cycles S → L → XL.
- **Reduced-motion respect** — automatic via `prefers-reduced-motion`.
- **Keyboard shortcuts overlay** — `Shift+?` or `F1`.

**Source:** `js/accessibility.js`.

### H3. RTL support

Arabic (`ar.json`) flips to RTL automatically — top bar reverses, toasts swap side, fonts use Noto Sans Arabic.

---

## I. Reliability & DevOps

### I1. Service worker v9.0.0

Cache-first for assets, network-first for HTML pages, SWR for JSON config. Cache key bumped on every release for instant invalidation.

**Source:** `sw.js`.

### I2. Multi-tenant school branding

`?school=XYZ` query param customises the title bar + recording watermark.

### I3. Analytics dashboard (Canvas parity)

Dashboard → **Analytics** tab → see:
- Per-class engagement KPIs
- Grade distribution bar chart (pure SVG)
- Top badge earners

All from local data. Never uploaded anywhere.

**Source:** `js/analytics.js` + `barChart`.

### I4. Teacher-grade export

Dashboard → top-right **📥 Export all** → downloads a single CSV containing students, assignments, grades, poll responses — importable into Excel / Sheets / PowerSchool.

**Source:** `exportAllCSV` in `js/storage.js`.

---

## J. Auth & Licensing

### J1. Teacher signup + 3-day trial

`teach.html` → **Create account** tab → fill name/email/phone/password (≥8 chars) → **Start my 3-day free trial**.

Password is hashed with **PBKDF2-SHA-256, 200,000 iterations**, plus a per-account random salt. Never stored as plaintext.

**Source:** `js/auth.js` (`signupTeacher`).

### J2. 3-day expiry → license gate

After 3 days, the Studio locks. Teacher must paste a valid HMG ACCESS KEY (generated on `admin.html`).

**Source:** `js/auth.js` (`requireTeacherAccess`).

### J3. License key validation (offline)

`HMG-YYYYMM-XXXXXXXXXX` — name-bound, expiry-bound, signed with the deployment's secret (stored in `localStorage["hmgcd_auth_secret"]`).

**Source:** `js/auth.js` (`validateKey`).

### J4. Account tampering protection

Every account record is SHA-256-signed. If anyone modifies localStorage, the signature fails and the account is wiped.

**Source:** `js/auth.js` (`_signAccount`).

### J5. Central revocation (optional)

Add a key to `revoked.json` → push to GitHub → every install blocks it within ~30 minutes (next refresh). Or use a Cloudflare Worker for instant revocation (see [DEPLOYMENT.md §6](DEPLOYMENT.md)).

### J6. Per-deployment AUTH_SECRET

On first run, the app generates a unique 40-character secret and pins it to that deployment. Two teachers on different deployments cannot share account data.

**Source:** `getAuthSecret` in `js/auth.js`.

---

## K. Keyboard shortcuts

| Shortcut | Action |
|---|---|
| `Alt+C` | Toggle high-contrast |
| `Alt+D` | Toggle dyslexia-friendly font |
| `Alt+S` | Cycle text size (S → L → XL) |
| `Shift+?` or `F1` | Open shortcut overlay |
| `Esc` | Close any modal |
| `Tab` / `Shift+Tab` | Move focus forward / back |
| `Enter` | Activate the focused button |

---

## L. What's preserved from v8

Every original feature is intact:

- True split-screen workspace
- Built-in live classroom (camera/chat/attendance)
- 175+ teaching tools
- Quizzes & leaderboards (Kahoot! style)
- YouTube-ready recording
- Professional whiteboard
- Classroom control (waiting room, PIN, lock, mute-all, spotlight)
- Individual student whiteboards
- Pear Deck-style activities
- ClassDojo-style behaviour points
- Random group maker + noise meter
- Reader Cast (40+ vetted library)
- Installable PWA, fully offline

v9 **adds** without removing. See `CHANGELOG.md` for the exact delta.