feat(progress): add class progress views for teachers

- Introduced a new "התקדמות" tab for teachers to view class progress by lesson, including readiness for upcoming tests.
- Implemented API endpoint `GET /api/classes/{id}/progress` to fetch progress data, including skill states, coverage, and readiness metrics.
- Updated permissions to restrict access to class progress data to the class's teacher and developers only.
- Enhanced UI with period tabs and a class picker, ensuring a responsive design that prevents sideways scrolling.
- Added comprehensive tests for API and browser interactions to validate functionality and permissions.

docs/tasks/prd-mathly.md

@@ -78,7 +78,7 @@ reused as files (see 7.1); everything else is rebuilt.
 - As a teacher, I want to add and remove the students of my own class, so a new student can start without waiting for a manager.
 - As a teacher, I want to set a test date and the lessons it covers, so the app prepares my students for it.
 - As a teacher, I want to see who has taken the simulation test.
-- As a teacher, I want a heat map of skills per student, so I can see at a glance which skills the class struggles with.
+- As a teacher, I want each student's progress per lesson, so I can see at a glance which lessons the class struggles with.
 - As a teacher, I want to see how much of each lesson each student has covered.
 
 **Manager**
@@ -246,14 +246,14 @@ The exercise screen is where a student practices one skill.
 - **MST-3 Help does not break the run.** An answer given after opening help is skipped for mastery: it neither counts toward the 3 nor breaks the run.
   A wrong answer restarts the run.
 - **MST-4 Mastery does not decay.** A mastered skill stays mastered. It does not need re-mastering over time, even after later wrong answers.
-  The readiness meter, the exercise tests, the heat map and the coverage view all use this state.
+  The readiness meter, the exercise tests and the teacher's progress by lesson all use this state.
 - **MST-5 The server decides.** The server stores the date of every answer (the calendar day in Israel, decided by the server, never by the device) and decides mastery from it.
 - **MST-6 Daily goal and streak.** 5 correct answers in a day make a streak day. The path shows today's count and the number of days in a row.
   A streak is kept through the morning of a new day and counted up to yesterday until the new day's 5 are reached.
 - **MST-7 Collection.** A collection screen shows what the student achieved: each mastered skill as a star, each completed lesson (all of its skills mastered)
   as a constellation drawn from its stars, and the comets caught (CMT-3).
 - **MST-8 Fading stars.** A mastered skill the student has not answered for 14 days has a **faded** star: it dims and says "דועך". One answer on the skill (correct or not) relights it.
-  Fading is only a review cue: the skill is still mastered (MST-4), so the readiness meter, heat map and exercise tests are unchanged.
+  Fading is only a review cue: the skill is still mastered (MST-4), so the readiness meter, the teacher's progress and exercise tests are unchanged.
 
 ### 4.8 Comets (CMT)
 
@@ -413,14 +413,14 @@ A tab bar at the bottom of the screen leads between them: home, path, submission
   and open requests to look again (AI-5). The teacher opens each, sees the AI's suggested score and comment (AI-4) if there is one, gives a grade (0–100) and a note, or sends it back for correction.
 - **TCH-5 AI queue.** The teacher sees their classes' AI requests (AI-1), with the picture, and sends or declines each, or sends a whole batch (AI-7).
 - **TCH-6 Tests tab.** The teacher sets a test (TST-1) and sees, for each test, which students have taken the simulation test and which have not.
-- **TCH-7 Class heat map.**
-  - Rows: students. Columns: skills (grouped by lesson).
-  - Each cell shows the skill state: not started / learning / mastered, by color **and** by a symbol or word.
-  - Tabs for the period: **Sep–Dec** and **Jan–Jun**. A period shows the skills of the lessons taught in it, and states as they were at the end of the period (or today, for the current period).
-- **TCH-8 Student lesson coverage.**
+- **TCH-7 Class progress, by lesson.** The teacher sees progress **per lesson, never per skill**.
   - Rows: students. Columns: lessons.
-  - Each cell shows the % of the lesson's skills the student has mastered, and the student's best quiz (בוחן) grade for that lesson.
-  - Same period tabs.
+  - Each cell is short and shows three things only: a **progress bar** with the percent of the lesson's skills mastered written on it; the student's best quiz (בוחן) grade as a **bare number** (a dash for none, without the word); and, in the current period, a **warning mark** (⚠) when the lesson is behind the curriculum (PTH-11) and not completed. The lesson's state in words (הושלם PTH-10, בלמידה, לא התחילו, בפיגור) is the cell's accessible name, and a completed lesson's bar is gold.
+  - Tabs for the period: **Sep–Dec** and **Jan–Jun**. A period shows the lessons of that period (by the lesson's date in the curriculum, PTH-11, else the last month of the bank's month for it), and states as they were at the end of the period (or today, for the current period). The current period opens first.
+  - Where: a "התקדמות" tab on the teacher's screen (with its number: the students of the teacher's classes), also reached from a shortcut on each class card; one class at a time, with a picker when the teacher has several. Only the class's teacher and a developer can read it (never a manager or an admin).
+  - The table scrolls inside its own frame with the student column fixed; the page does not scroll sideways. A student who has not signed in yet is all "not started".
+- **TCH-8 (merged into TCH-7).** The coverage view is the progress by lesson above; there is no separate per-skill heat map.
+- **TCH-10 Readiness per student.** For the class's nearest coming test: each student's readiness number and word (RDY), mastery percent, practice-test average and simulation grade, a dash for what is missing; a class with no coming test says so.
 - **TCH-9 Roster of my class.** For each class they teach, the teacher can paste email addresses to add students and can remove a student (CLS-3, CLS-5). They cannot change the class's name, lessons, teacher or AI budget,
   and a teacher cannot add themselves as a student. Removing a student does not delete their progress.
 
@@ -441,7 +441,7 @@ A tab bar at the bottom of the screen leads between them: home, path, submission
 
 *Reference: `app/prompter.py`, `static/prompter.js`, and the management sheet in `static/math.js`.*
 
-- **DEV-1 Every permission.** A developer can open any class's progress, heat map, coverage, tests, assignments, inbox and AI queue, as the class's teacher can, and everything managers and admins can do.
+- **DEV-1 Every permission.** A developer can open any class's progress, tests, assignments, inbox and AI queue, as the class's teacher can, and everything managers and admins can do.
 - **DEV-2 Prompter (פרומפטר).** A developer writes or pastes a text and shows it full screen as a scrolling teleprompter. Saved texts (a title up to 120 characters; up to 200 texts) belong to the account and are on every device; what is being edited is also kept in the browser, so nothing is lost before it is saved.
   Keys: space starts and stops, ↑/↓ change speed, +/− change size, M mirrors, F is full screen, Esc leaves; the mouse and a presentation remote work too.
   A saved text can have an **outline (ראשי פרקים)**: on request the AI rewrites the text as the same slides with two to four very short topic reminders each, once; it is kept with the text and can be edited. Changing the text without sending an outline drops the outline, so a stale one is never shown.
@@ -462,11 +462,11 @@ A tab bar at the bottom of the screen leads between them: home, path, submission
 
 ## 6. Design Considerations
 
-- Hebrew, right-to-left. Works on phones first; the teacher, manager, admin and developer views (heat map, coverage, classes, roles) must also work well on a computer.
+- Hebrew, right-to-left. Works on phones first; the teacher, manager, admin and developer views (progress by lesson, classes, roles) must also work well on a computer.
 - The look follows the path's "sky" theme: a dark-blue night with aurora and starlight accents, gold for mastery, and an owl mascot that perches on the next skill. The app is always dark, as mathly1 is: the page background is a dark night with two soft glows and small fixed stars; it does not move. There is no light mode.
 - A button whose action takes longer than about a third of a second shows it (a spinner, a second press ignored), everywhere in the app; with reduced motion it shows "…".
 - Math is written in `$…$` text in the exercise bank; the app must render it as formulas.
-- State and result never rely on color alone: every state has a symbol or a word (stars, heat map cells, feedback).
+- State and result never rely on color alone: every state has a symbol or a word (stars, progress cells, feedback).
 - Mastered skills must look clearly different from "learning" and "not started" ones.
 - Touch targets are at least 44px. Animations (stars, celebrations, comets) respect the device's reduced-motion setting.
 - The "one task for today" on home is a single, obvious button.
@@ -530,7 +530,7 @@ Rebuilt, not copied as a whole; read the places named in each requirement group.
 - ≥ 90% of students take the simulation test before each real test.
 - On test day, students have mastered on average ≥ 80% of the covered skills.
 - ≥ 75% of students take both exercise tests before each real test.
-- Teachers open the heat map or the coverage view at least once a week.
+- Teachers open the progress view at least once a week.
 - The AI's estimated cost stays within each class's daily budget on every day.
 
 ## 9. Open Questions

mathly2/assignments.py

@@ -387,4 +387,6 @@ def teaching_counts(request: Request, user: dict = Depends(need("class.teach")))
     tests, assignments = here.tests_of_classes(ids), here.assignments_of_classes(ids)
     graded_by_student = [a["id"] for a in assignments if a["kind"] != "exercise_test"]
     waiting = sum(1 for s in store.submissions_of_assignments(graded_by_student) if s["state"] == "handed_in")
-    return {"classes": len(classes), "tests": len(tests), "assignments": len(assignments), "inbox": waiting}
+    here.prefetch(*[("members", i) for i in ids])
+    students = len({m["email"] for i in ids for m in here.members(i)})
+    return {"classes": len(classes), "tests": len(tests), "assignments": len(assignments), "inbox": waiting, "progress": students}

mathly2/main.py

@@ -15,7 +15,7 @@ from .access import RoleResolver, learner, permissions_of
 from .auth import DevAuthenticator, SupabaseAuthenticator, current_user
 from .bank import Bank, load_bank
 
-from . import accounts, assignments, classes, cleanup, quizzes, reads, realtests, skills, written
+from . import accounts, assignments, classes, cleanup, progress, quizzes, reads, realtests, skills, written
 from .config import Settings, load_settings
 from .cached import CachedStore
 from .store import InMemoryStore, StoreUnavailable, SupabaseStore
@@ -77,6 +77,7 @@ def create_app(settings: Settings | None = None, bank: Bank | None = None, store
     app.include_router(skills.router)
     app.include_router(quizzes.router)
     app.include_router(realtests.router)
+    app.include_router(progress.router)
     app.include_router(written.router)
     app.include_router(assignments.router)
 

mathly2/progress.py

@@ -0,0 +1,126 @@
+"""A class's progress for its teacher (PRD TCH-7, TCH-10): per lesson, never per skill, with the periods and the readiness per
+student. Nothing is stored: it is all read from the students' progress, quizzes and tests, the lessons' dates and the bank."""
+from __future__ import annotations
+
+from datetime import date, datetime
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+
+from . import attempts, clock, readiness, reads
+from .access import need
+from .learning import LEARNING, MASTERED, NOT_STARTED, skill_state
+from .realtests import _my_class, facts_for, prime_students, readiness_for
+from .store import _when
+
+router = APIRouter(prefix="/api/classes")
+
+MONTHS = {"ספטמבר": 9, "אוקטובר": 10, "נובמבר": 11, "דצמבר": 12, "ינואר": 1, "פברואר": 2, "מרץ": 3, "אפריל": 4, "מאי": 5, "יוני": 6}
+PERIODS = ({"id": 1, "label": "ספט׳–דצמ׳"}, {"id": 2, "label": "ינו׳–יוני"})
+
+
+def period_of_month(month: int) -> int:
+    return 1 if 9 <= month <= 12 else 2
+
+
+def school_year(today: date) -> int:
+    """The calendar year in which this school year began (it starts in September)."""
+    return today.year if today.month >= 9 else today.year - 1
+
+
+def period_end(period: int, today: date) -> date:
+    year = school_year(today)
+    return date(year, 12, 31) if period == 1 else date(year + 1, 6, 30)
+
+
+def lesson_period(lesson: dict, due: date | None) -> int:
+    """By the lesson's date in the curriculum or, without one, by the last month of the bank's month for it."""
+    if due:
+        return period_of_month(due.month)
+    month = MONTHS.get(str(lesson.get("when", "")).split("–")[-1].strip())
+    return period_of_month(month) if month else 2
+
+
+def _day(value) -> date | None:
+    if not value:
+        return None
+    try:
+        moment = value if isinstance(value, datetime) else _when(value)
+    except ValueError:
+        return None
+    return clock.school_day(moment) if moment.tzinfo else moment.date()
+
+
+def state_on(progress: dict | None, end: date, today: date) -> str:
+    """The skill's state at the end of a period (today's state while the period has not ended). Mastery never goes away, so the stored times say."""
+    if end >= today:
+        return skill_state(progress)
+    if progress:
+        mastered, started = _day(progress.get("mastered_at")), _day(progress.get("started_at"))
+        if mastered and mastered <= end:
+            return MASTERED
+        if (started and started <= end) or (mastered and mastered <= end):
+            return LEARNING
+    return NOT_STARTED
+
+
+def best_quiz(rows: list[dict], end: date, today: date) -> int | None:
+    """The best grade of the quizzes handed in by the end of the period."""
+    grades = [r["grade"] for r in rows if r.get("submitted_at") and r.get("grade") is not None and (end >= today or _day(r["submitted_at"]) <= end)]
+    return max(grades) if grades else None
+
+
+@router.get("/{class_id}/progress")
+def class_progress(class_id: int, request: Request, period: int | None = None, user: dict = Depends(need("class.teach"))) -> dict:
+    klass = _my_class(request, user, class_id)
+    store, bank, here = request.app.state.store, request.app.state.bank, reads.of(request)
+    today = clock.school_day()
+    current = period_of_month(today.month)
+    if period is None:
+        period = current
+    if period not in (1, 2):
+        raise HTTPException(422, "תקופה לא מוכרת")
+    end = period_end(period, today)
+    members = store.members(klass["id"])
+    ids = [m["user_id"] for m in members if m["user_id"]]
+    here.prefetch(("curriculum",), ("tests_of_classes", [klass["id"]]))
+    prime_students(request, ids, kinds=("exercise_test", "simulation", "quiz"))
+    dates = here.curriculum()
+    lessons = [l for l in bank.lessons_with_skills() if lesson_period(l, dates.get(l["id"])) == period]
+    now_view = end >= today
+    students = []
+    for m in members:
+        uid = m["user_id"]
+        states = {p["skill_id"]: p for p in here.progress_of(uid)} if uid else {}
+        quizzes: dict[str, list[dict]] = {}
+        for row in (here.attempts_of(uid, "quiz") if uid else []):
+            quizzes.setdefault(row["scope"], []).append(row)
+        coverage = {}
+        for lesson in lessons:
+            mine = {s["id"]: state_on(states.get(s["id"]), end, today) for s in lesson["skills"]}
+            best = best_quiz(quizzes.get(lesson["id"], []), end, today)
+            mastered = sum(1 for v in mine.values() if v == MASTERED)
+            passed = any(r.get("submitted_at") and r["grade"] is not None and r["grade"] >= attempts.PASS_GRADE and (now_view or _day(r["submitted_at"]) <= end)
+                         for r in quizzes.get(lesson["id"], []))
+            completed = passed or (bool(mine) and mastered == len(mine))
+            due = dates.get(lesson["id"])
+            started = best is not None or any(v != NOT_STARTED for v in mine.values())
+            coverage[lesson["id"]] = {"state": "completed" if completed else "learning" if started else "not_started",
+                                      "percent": round(100 * mastered / len(mine)) if mine else 0, "best": best, "completed": completed,
+                                      "behind": bool(now_view and due and due < today and not completed)}
+        students.append({"email": m["email"], "signed_in": bool(uid), "lessons": coverage})
+    nearest = next((t for t in sorted(store.tests_of_classes([klass["id"]]), key=lambda t: t["date"]) if t["date"] >= today), None)
+    test = None
+    if nearest:
+        rows = []
+        for m in members:
+            facts = facts_for(request, m["user_id"], nearest, today)
+            ready = readiness_for(facts)
+            rows.append({"email": m["email"], "signed_in": bool(m["user_id"]), "readiness": ready, "mastery": ready["parts"]["M"],
+                         "practice": ready["parts"]["E"], "simulation": ready["parts"]["S"]})
+        names = {l["id"]: l["name"] for l in bank.lessons}
+        test = {"id": nearest["id"], "date": nearest["date"].isoformat(), "days_left": (nearest["date"] - today).days,
+                "lessons": [names.get(i, i) for i in nearest["lessons"]], "students": rows}
+    return {"class": {"id": klass["id"], "name": klass["name"]}, "period": period, "current_period": current, "as_of": min(end, today).isoformat(),
+            "periods": [{**p, "current": p["id"] == current} for p in PERIODS],
+            "lessons": [{"id": l["id"], "name": l["name"], "due_date": dates[l["id"]].isoformat() if l["id"] in dates else None} for l in lessons],
+            "students": students, "test": test}

mathly2/reads.py

@@ -40,6 +40,11 @@ class Reads:
             return lambda *args: self._read(name, *args)
         raise AttributeError(name)
 
+    def prime(self, name: str, args: tuple, value) -> None:
+        """Record an answer that was fetched another way (for many students at once), so a later `name(*args)` does not ask again."""
+        with self._lock:
+            self._done.setdefault(_key(name, args), value)
+
     def prefetch(self, *calls: tuple) -> None:
         """Start the reads (each `(name, *args)`) that are not done yet, together, and wait for all of them. The first error is raised."""
         missing = []

mathly2/realtests.py

@@ -45,6 +45,24 @@ def _covered(bank, test: dict) -> list[str]:
     return [s["id"] for s in bank.skills if s["unit"] in test["lessons"] and bank.question_keys(s["id"])]
 
 
+def prime_students(request: Request, user_ids: list[str], kinds: tuple[str, ...] = ("exercise_test", "simulation")) -> None:
+    """Read what a class's students need (progress, last answers and attempts of each kind) with one call each for all of them, together,
+    and hand it to the request's reads, so asking for one student's later does not touch the database."""
+    ids = list(dict.fromkeys(user_ids))
+    if not ids:
+        return
+    store, here = request.app.state.store, reads.of(request)
+    jobs = {"progress_of": reads.POOL.submit(store.progress_of_users, ids), "last_answered": reads.POOL.submit(store.last_answered_users, ids)}
+    jobs.update({("attempts_of", kind): reads.POOL.submit(store.attempts_of_users, ids, kind) for kind in kinds})
+    for key, future in jobs.items():
+        found = future.result()
+        for uid in ids:
+            if isinstance(key, tuple):
+                here.prime(key[0], (uid, key[1]), found[uid])
+            else:
+                here.prime(key, (uid,), found[uid])
+
+
 def _student_reads(user_id: str) -> list[tuple]:
     return [("progress_of", user_id), ("last_answered", user_id), ("attempts_of", user_id, "exercise_test"), ("attempts_of", user_id, "simulation")]
 
@@ -155,7 +173,7 @@ def _checked_lessons(klass: dict, lessons: list[str]) -> list[str]:
 def teacher_view(request: Request, test: dict, klass: dict, today: date) -> dict:
     store, here = request.app.state.store, reads.of(request)
     members = store.members(klass["id"])
-    here.prefetch(*[call for m in members if m["user_id"] for call in _student_reads(m["user_id"])])      # every student's reads at once
+    prime_students(request, [m["user_id"] for m in members if m["user_id"]])                                  # every student's reads at once
     students = []
     for m in members:
         facts = facts_for(request, m["user_id"], test, today)

mathly2/static/app.css

@@ -436,3 +436,25 @@ ul.students li [dir="ltr"] { overflow-wrap: anywhere; min-width: 0; }
 .curriculum li { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 6px 12px; padding: 6px 0; border-bottom: 1px solid var(--line); }
 .curriculum label { flex: 1 1 200px; }
 .curriculum input[type=date] { flex: 0 0 auto; }
+/* the teacher's progress tab: heat map, coverage, readiness */
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+#progress select { max-width: 100%; margin-bottom: 8px; }
+.hm { border-collapse: separate; border-spacing: 0; font-size: 13px; min-width: 100%; }
+.hm th, .hm td { border-bottom: 1px solid var(--line); padding: 6px 8px; text-align: center; white-space: nowrap; }
+.hm .lesson-col { white-space: normal; min-width: 90px; max-width: 150px; font-size: 12px; border-inline-start: 1px solid var(--line); }
+.hm .skill-col { font-weight: 400; color: var(--muted); padding: 2px 4px; min-width: 28px; }
+.hm .sticky { position: sticky; inset-inline-start: 0; z-index: 1; background: var(--surface); text-align: start; border-inline-end: 1px solid var(--line); max-width: 110px; overflow: hidden; text-overflow: ellipsis; }
+.hm td.c { width: 28px; min-width: 28px; font-weight: 700; }
+.hm .c-m { background: color-mix(in srgb, var(--sky-gold) 28%, var(--surface)); color: var(--sky-gold); }
+.hm .c-l { background: color-mix(in srgb, var(--sky-accent) 22%, var(--surface)); color: var(--sky-accent); }
+.hm .c-n { color: var(--muted); }
+.legend { margin: 6px 0 0; font-size: 12px; }
+#progress, #progress .tablewrap { min-width: 0; max-width: 100%; }
+#progress .tablewrap { position: relative; }   /* so the hidden words inside it (absolute) are clipped by its scrolling, not by the page */
+.hm td.cov { min-width: 84px; padding: 6px 8px; }
+.pbar { position: relative; height: 18px; border-radius: 9px; background: var(--line); overflow: hidden; }
+.pbar i { position: absolute; inset-block: 0; inset-inline-start: 0; background: var(--sky-accent); opacity: .75; }
+.hm td.cov.done .pbar i { background: var(--sky-gold); opacity: 1; }
+.pbar span { position: relative; display: block; font-size: 11px; font-weight: 700; line-height: 18px; text-align: center; color: var(--ink); text-shadow: 0 0 3px var(--surface); }
+.qgrade { margin-top: 3px; font-size: 13px; font-weight: 600; }
+.qgrade .warn { color: var(--sky-danger); }

mathly2/static/teacher.js

@@ -9,7 +9,8 @@ const tabs = active => `<div class="subtabs" id="teacher-tabs" role="group" aria
   <button type="button" data-tab="classes" aria-pressed="${active === "classes"}">הכיתות שלי <span class="tab-count" data-count="classes"></span></button>
   <button type="button" data-tab="tests" aria-pressed="${active === "tests"}">מבחנים <span class="tab-count" data-count="tests"></span></button>
   <button type="button" data-tab="assignments" aria-pressed="${active === "assignments"}">משימות <span class="tab-count" data-count="assignments"></span></button>
-  <button type="button" data-tab="inbox" aria-pressed="${active === "inbox"}">תיבת בדיקה <span class="tab-count" data-count="inbox"></span></button></div>`;
+  <button type="button" data-tab="inbox" aria-pressed="${active === "inbox"}">תיבת בדיקה <span class="tab-count" data-count="inbox"></span></button>
+  <button type="button" data-tab="progress" aria-pressed="${active === "progress"}">התקדמות <span class="tab-count" data-count="progress"></span></button></div>`;
 
 const work = () => import("./teacher_work.js");
 const context = { draw: html => draw(html), tabs: active => tabs(active), wire: () => wireTabs() };
@@ -24,7 +25,7 @@ async function fillCounts() {
 
 function wireTabs() {
   fillCounts();
-  const screens = { classes: showClasses, tests: showTests, assignments: () => work().then(m => m.showAssignments(context)), inbox: () => work().then(m => m.showInbox(context)) };
+  const screens = { classes: showClasses, tests: showTests, assignments: () => work().then(m => m.showAssignments(context)), inbox: () => work().then(m => m.showInbox(context)), progress: () => import("./teacher_progress.js").then(m => m.show(context)) };
   document.querySelectorAll("#teacher-tabs [data-tab]").forEach(b => b.addEventListener("click", () => screens[b.dataset.tab]()));
 }
 
@@ -42,7 +43,7 @@ const showClasses = (notes = {}) => swr("/api/teaching", classes => drawClasses(
 async function drawClasses(classes, notes) {
   draw(`${tabs("classes")}<section id="teaching"><h2>הכיתות שלי</h2>
     ${classes.length ? `<div class="cards">${classes.map(c => `<article class="card class-card" data-id="${c.id}">
-      <div class="hrow"><h3 class="grow">${esc(c.name)}</h3><span class="tag">${c.students.length} תלמידים</span></div>
+      <div class="hrow"><h3 class="grow">${esc(c.name)}</h3><span class="tag">${c.students.length} תלמידים</span><button type="button" data-progress="${c.id}">התקדמות</button></div>
       <p class="muted" style="margin:0 0 8px">${c.ai_enabled ? "AI פועל" : "AI כבוי: מנהל הכיתות מפעיל"}</p>
       ${c.students.length ? `<ul class="plain students">${c.students.map(s => `<li><span dir="ltr">${esc(s.email)}</span>
         <span class="muted">${s.signed_in ? "נכנס/ה" : "עוד לא נכנס/ה"}</span>
@@ -56,6 +57,7 @@ async function drawClasses(classes, notes) {
         <p><button class="primary" type="submit">הוספה</button></p></form></article>`).join("")}</div>`
       : `<section class="card"><p class="muted">עוד לא שייכו אותך ככיתה. מנהל הכיתות קובע מי מלמד/ת כל כיתה.</p></section>`}</section>`);
   wireTabs();
+  document.querySelectorAll("[data-progress]").forEach(b => b.addEventListener("click", () => import("./teacher_progress.js").then(m => m.show(context, Number(b.dataset.progress)))));
   document.querySelectorAll(".class-card").forEach(card => {
     const id = Number(card.dataset.id);
     card.querySelector("form").addEventListener("submit", async event => {

mathly2/static/teacher_progress.js

@@ -0,0 +1,66 @@
+// A class's progress for its teacher, per lesson (never per skill), and the readiness for the coming test, with the two period tabs. One class at a time; the class is chosen here when the teacher has several.
+import { api, swr } from "./api.js";
+import { esc, fmt } from "./math.js";
+import { shortDate } from "./ui.js";
+
+const STATE = { completed: ["✓", "הושלם", "m"], learning: ["◐", "בלמידה", "l"], not_started: ["○", "לא התחילו", "n"] };
+const VIEWS = [["lessons", "לפי שיעור"], ["readiness", "מוכנות למבחן"]];
+let chosen = { classId: null, period: null, view: "lessons" };      // what the teacher last looked at
+
+const dash = value => value === null || value === undefined ? "—" : value;
+const first = email => esc(email.split("@")[0]);
+const who = s => `<th scope="row" class="sticky"><span dir="ltr" title="${esc(s.email)}">${first(s.email)}</span>${s.signed_in ? "" : ` <span class="muted">(לא נכנס/ה)</span>`}</th>`;
+
+function lessonsView(data) {
+  if (!data.lessons.length) return `<p class="muted">אין שיעורים בתקופה הזו.</p>`;
+  const head = data.lessons.map(l => `<th class="lesson-col">${fmt(l.name)}${l.due_date ? `<br><span class="muted">עד ${shortDate(l.due_date)}</span>` : ""}</th>`).join("");
+  const rows = data.students.map(s => `<tr data-student="${esc(s.email)}">${who(s)}${data.lessons.map(l => {
+    const c = s.lessons[l.id], word = (STATE[c.state] || STATE.not_started)[1];
+    return `<td class="cov${c.completed ? " done" : ""}${c.behind ? " behind" : ""}" data-lesson="${esc(l.id)}" data-state="${esc(c.state)}" aria-label="${word}${c.behind ? ", בפיגור" : ""}">
+      <div class="pbar"><i style="width:${c.percent}%"></i><span>${c.percent}%</span></div>
+      <div class="qgrade">${dash(c.best)}${c.behind ? ` <span class="warn" data-behind aria-hidden="true">⚠</span>` : ""}</div></td>`;
+  }).join("")}</tr>`).join("");
+  return `<div class="tablewrap" tabindex="0" role="region" aria-label="התקדמות לפי שיעור"><table class="hm"><thead><tr><th class="sticky">תלמיד</th>${head}</tr></thead><tbody>${rows}</tbody></table></div>
+    <p class="muted legend">הסרגל: אחוז המיומנויות שנשלטו (זהב: השיעור הושלם) · המספר: הציון בבוחן · ⚠ בפיגור</p>`;
+}
+
+function readiness(data) {
+  const t = data.test;
+  if (!t) return `<p class="muted" id="no-test">עוד לא נקבע מבחן קרוב לכיתה הזו.</p>`;
+  const rows = t.students.map(s => `<tr data-student="${esc(s.email)}">${who(s)}<td><b>${s.readiness.number}</b> · ${esc(s.readiness.label)}</td><td>${dash(s.mastery)}${s.mastery === null ? "" : "%"}</td><td>${dash(s.practice)}</td><td>${dash(s.simulation)}</td></tr>`).join("");
+  return `<p>מבחן ב־${shortDate(t.date)} (${t.days_left === 0 ? "היום" : `בעוד ${t.days_left} ימים`}): ${t.lessons.map(esc).join(", ")}</p>
+    <div class="tablewrap" tabindex="0" role="region" aria-label="מוכנות"><table class="hm"><thead><tr><th class="sticky">תלמיד</th><th>מוכנות</th><th>שליטה</th><th>תרגול</th><th>סימולציה</th></tr></thead><tbody>${rows}</tbody></table></div>`;
+}
+
+function page(ctx, classes, data) {
+  const periodTabs = chosen.view === "readiness" ? "" : `<div class="subtabs" id="period-tabs" role="group" aria-label="תקופה">${data.periods.map(p =>
+    `<button type="button" data-period="${p.id}" aria-pressed="${p.id === data.period}">${p.label}${p.current ? " (עכשיו)" : ""}</button>`).join("")}</div>`;
+  const body = chosen.view === "readiness" ? readiness(data) : lessonsView(data);
+  ctx.draw(`${ctx.tabs("progress")}<section id="progress"><h2>התקדמות</h2>
+    ${classes.length > 1 ? `<label for="class-pick">כיתה</label><select id="class-pick">${classes.map(c => `<option value="${c.id}"${c.id === data.class.id ? " selected" : ""}>${esc(c.name)}</option>`).join("")}</select>` : `<p class="muted">${esc(data.class.name)}</p>`}
+    <div class="subtabs" id="view-tabs" role="group" aria-label="תצוגה">${VIEWS.map(([id, label]) => `<button type="button" data-view="${id}" aria-pressed="${id === chosen.view}">${label}</button>`).join("")}</div>
+    ${periodTabs}${body}</section>`);
+  ctx.wire();
+  document.getElementById("class-pick")?.addEventListener("change", e => show(ctx, Number(e.target.value), null));
+  document.getElementById("view-tabs").addEventListener("click", e => {
+    const view = e.target.closest("[data-view]")?.dataset.view;
+    if (view) { chosen.view = view; page(ctx, classes, data); }                       // the same data, another view
+  });
+  document.getElementById("period-tabs")?.addEventListener("click", e => {
+    const period = Number(e.target.closest("[data-period]")?.dataset.period);
+    if (period) show(ctx, data.class.id, period);
+  });
+}
+
+/** Open the progress tab for `classId` (the one last looked at, or the first, when not given). */
+export async function show(ctx, classId = null, period = null) {
+  const classes = await api("/api/teaching");
+  if (!classes.length) {
+    ctx.draw(`${ctx.tabs("progress")}<section id="progress"><h2>התקדמות</h2><section class="card"><p class="muted">עוד לא שייכו אותך ככיתה. מנהל הכיתות קובע מי מלמד/ת כל כיתה.</p></section></section>`);
+    return ctx.wire();
+  }
+  const id = classes.some(c => c.id === (classId ?? chosen.classId)) ? (classId ?? chosen.classId) : classes[0].id;
+  if (id !== chosen.classId || (classId !== null && period === null)) chosen.period = null;
+  chosen = { ...chosen, classId: id, period: period ?? chosen.period };
+  await swr(`/api/classes/${id}/progress${chosen.period ? `?period=${chosen.period}` : ""}`, data => page(ctx, classes, data));
+}

mathly2/store.py

@@ -270,6 +270,36 @@ class InMemoryStore:
         with self._lock:
             return [dict(r) for (u, _), r in self._progress.items() if u == user_id]
 
+    # --- many students at once (a class's progress screen: one call each, not one per student) ---
+
+    def progress_of_users(self, user_ids) -> dict[str, list[dict]]:
+        wanted = set(user_ids)
+        with self._lock:
+            found: dict[str, list[dict]] = {u: [] for u in dict.fromkeys(user_ids)}
+            for (u, _), r in self._progress.items():
+                if u in wanted:
+                    found[u].append(dict(r))
+            return found
+
+    def last_answered_users(self, user_ids) -> dict[str, dict[str, date]]:
+        wanted = set(user_ids)
+        with self._lock:
+            found: dict[str, dict[str, date]] = {u: {} for u in dict.fromkeys(user_ids)}
+            for a in self._answers:
+                days = found.get(a["user_id"])
+                if days is not None and (a["skill_id"] not in days or a["day"] > days[a["skill_id"]]):
+                    days[a["skill_id"]] = a["day"]
+            return found
+
+    def attempts_of_users(self, user_ids, kind: str) -> dict[str, list[dict]]:
+        wanted = set(user_ids)
+        with self._lock:
+            found: dict[str, list[dict]] = {u: [] for u in dict.fromkeys(user_ids)}
+            for r in sorted(self._attempts.values(), key=lambda r: r["started_at"]):
+                if r["user_id"] in wanted and r["kind"] == kind:
+                    found[r["user_id"]].append(_copy_attempt(r))
+            return found
+
     def add_answer(self, user_id: str, skill_id: str, question_key: str, correct: bool, counted: bool,
                    mistake_id: str | None, day: date) -> None:
         with self._lock:
@@ -788,6 +818,36 @@ class SupabaseStore:
     def progress_of(self, user_id: str) -> list[dict]:
         return self._request("GET", "m2_skill_progress", {"user_id": self._eq(user_id), "select": "*"})
 
+    # --- many students at once ---
+
+    @staticmethod
+    def _in(ids) -> str:
+        return "in.(" + ",".join(dict.fromkeys(ids)) + ")"
+
+    def progress_of_users(self, user_ids) -> dict[str, list[dict]]:
+        ids = list(dict.fromkeys(user_ids))
+        found: dict[str, list[dict]] = {u: [] for u in ids}
+        if ids:
+            for r in self._request("GET", "m2_skill_progress", {"user_id": self._in(ids), "select": "*"}):
+                found[str(r["user_id"])].append(r)
+        return found
+
+    def last_answered_users(self, user_ids) -> dict[str, dict[str, date]]:
+        ids = list(dict.fromkeys(user_ids))
+        found: dict[str, dict[str, date]] = {u: {} for u in ids}
+        if ids:
+            for r in self._request("GET", "m2_last_answered", {"user_id": self._in(ids), "select": "user_id,skill_id,day"}):
+                found[str(r["user_id"])][r["skill_id"]] = date.fromisoformat(r["day"])
+        return found
+
+    def attempts_of_users(self, user_ids, kind: str) -> dict[str, list[dict]]:
+        ids = list(dict.fromkeys(user_ids))
+        found: dict[str, list[dict]] = {u: [] for u in ids}
+        if ids:
+            for r in self._request("GET", "m2_attempts", {"user_id": self._in(ids), "kind": self._eq(kind), "select": "*", "order": "started_at"}):
+                found[str(r["user_id"])].append(_attempt_row(r))
+        return found
+
     def add_answer(self, user_id: str, skill_id: str, question_key: str, correct: bool, counted: bool,
                    mistake_id: str | None, day: date) -> None:
         self._request("POST", "m2_answers", body={"user_id": user_id, "skill_id": skill_id, "question_key": question_key,

mathly2/tests/test_assignments_api.py

@@ -467,7 +467,7 @@ def counts(client, who=TEACHER):
 
 
 def test_the_counts_are_classes_tests_assignments_and_submissions_waiting(world):
-    assert counts(world) == {"classes": 1, "tests": 0, "assignments": 0, "inbox": 0}
+    assert counts(world) == {"classes": 1, "tests": 0, "assignments": 0, "inbox": 0, "progress": 2}
     for _ in range(3):
         world.store.create_test(world.a["id"], clock.school_day() + 10 * DAY, [world.quiz_lesson], TEACHER, created_at=clock.now())
     a = give(world, kind="quiz", quiz_lesson=world.quiz_lesson).json()
@@ -478,7 +478,7 @@ def test_the_counts_are_classes_tests_assignments_and_submissions_waiting(world)
     submit(world, a["id"], KID)
     submit(world, a["id"], KID2)
     submit(world, b["id"], KID)
-    assert counts(world) == {"classes": 1, "tests": 4, "assignments": 4, "inbox": 3}
+    assert counts(world) == {"classes": 1, "tests": 4, "assignments": 4, "inbox": 3, "progress": 2}
 
 
 def test_checking_a_submission_lowers_the_inbox_and_removed_items_are_not_counted(world):
@@ -490,13 +490,13 @@ def test_checking_a_submission_lowers_the_inbox_and_removed_items_are_not_counte
     assert counts(world)["inbox"] == 0
     world.store.remove_test(test["id"])
     world.delete(f"/api/assignments/{a['id']}", headers=auth(TEACHER))
-    assert counts(world) == {"classes": 1, "tests": 0, "assignments": 0, "inbox": 0}
+    assert counts(world) == {"classes": 1, "tests": 0, "assignments": 0, "inbox": 0, "progress": 2}
 
 
 def test_another_teachers_items_are_not_counted_and_a_developer_counts_everything(world):
     give(world, kind="quiz", quiz_lesson=world.quiz_lesson)
     world.store.create_test(world.b["id"], clock.school_day() + 10 * DAY, [world.other_quiz], OTHER_TEACHER, created_at=clock.now())
-    assert counts(world, OTHER_TEACHER) == {"classes": 1, "tests": 1, "assignments": 0, "inbox": 0}
-    assert counts(world) == {"classes": 1, "tests": 0, "assignments": 1, "inbox": 0}
-    assert counts(world, DEV) == {"classes": 2, "tests": 1, "assignments": 1, "inbox": 0}
+    assert counts(world, OTHER_TEACHER) == {"classes": 1, "tests": 1, "assignments": 0, "inbox": 0, "progress": 1}
+    assert counts(world) == {"classes": 1, "tests": 0, "assignments": 1, "inbox": 0, "progress": 2}
+    assert counts(world, DEV) == {"classes": 2, "tests": 1, "assignments": 1, "inbox": 0, "progress": 3}
     assert world.get("/api/teaching/counts", headers=auth(KID)).status_code == 403

mathly2/tests/test_permissions.py

@@ -64,6 +64,7 @@ NEEDS = {   # (method, path) -> permission
     ("POST", "/api/classes"): "classes.manage",
     ("GET", "/api/classes/{class_id}"): "classes.manage",
     ("PUT", "/api/classes/{class_id}"): "classes.manage",
+    ("GET", "/api/classes/{class_id}/progress"): "class.teach",
     ("GET", "/api/curriculum"): "classes.manage",
     ("PUT", "/api/curriculum"): "classes.manage",
     ("DELETE", "/api/classes/{class_id}"): "classes.manage",

mathly2/tests/test_progress_api.py

@@ -0,0 +1,142 @@
+"""A class's progress for its teacher (add-class-progress-views 1.2): heat map, coverage, periods, readiness and who may read them."""
+import time
+from datetime import datetime, timedelta, timezone
+
+from mathly2 import clock
+from mathly2.tests.test_assignments_api import DEV, KID, KID2, MGR, MON, OTHER_TEACHER, OUTSIDER, TEACHER, auth, bank, uid, world  # noqa: F401
+
+STAMP = "2026-10-05T10:00:00+00:00"
+
+
+def progress(client, who=TEACHER, period=None, klass=None):
+    q = f"?period={period}" if period else ""
+    return client.get(f"/api/classes/{(klass or client.a)['id']}/progress{q}", headers=auth(who))
+
+
+def lesson_of(bank, lesson_id):
+    return next(l for l in bank.lessons_with_skills() if l["id"] == lesson_id)
+
+
+def test_progress_is_per_lesson_with_a_state_and_never_per_skill(world, bank):
+    lesson = lesson_of(bank, "t")
+    first, second = lesson["skills"][0]["id"], lesson["skills"][1]["id"]
+    world.store.save_progress(uid(KID), first, started_at=STAMP, mastered_at=STAMP)
+    world.store.save_progress(uid(KID), second, started_at=STAMP)
+    world.store.add_member(world.a["id"], "new@school.test")                                  # never signed in
+    got = progress(world, period=1).json()
+    rows = {s["email"]: s for s in got["students"]}
+    assert set(rows) == {KID, KID2, "new@school.test"} and [l["id"] for l in got["lessons"]][0] == "t"
+    assert rows[KID]["lessons"]["t"]["state"] == "learning" and rows[KID2]["lessons"]["t"]["state"] == "not_started"
+    assert {c["state"] for c in rows["new@school.test"]["lessons"].values()} == {"not_started"} and rows["new@school.test"]["signed_in"] is False
+    text = str(got)
+    assert not any(k in text for k in ("states", "skills")) and first not in text                # nothing stands for a single skill
+
+
+def test_coverage_is_the_percent_mastered_and_the_best_quiz_and_completed_or_behind(world, bank):
+    lesson = lesson_of(bank, "t")
+    skills = [s["id"] for s in lesson["skills"]]
+    for s in skills[:3]:
+        world.store.save_progress(uid(KID), s, started_at=STAMP, mastered_at=STAMP)
+    q = world.store.create_attempt(uid(KID), "quiz", "t", MON - timedelta(hours=2), MON - timedelta(hours=1), [])
+    world.store.save_attempt(q["id"], submitted_at=MON - timedelta(hours=1), grade=80)
+    world.store.set_lesson_dates({"t": clock.school_day() - timedelta(days=3)})
+    got = {s["email"]: s["lessons"]["t"] for s in progress(world, period=1).json()["students"]}
+    assert got[KID] == {"state": "learning", "percent": round(300 / len(skills)), "best": 80, "completed": False, "behind": True}
+    assert got[KID2] == {"state": "not_started", "percent": 0, "best": None, "completed": False, "behind": True}
+    for s in skills[3:]:                                                                      # all mastered: completed, no longer behind
+        world.store.save_progress(uid(KID), s, started_at=STAMP, mastered_at=STAMP)
+    again = {s["email"]: s["lessons"]["t"] for s in progress(world, period=1).json()["students"]}
+    assert again[KID]["percent"] == 100 and again[KID]["state"] == "completed" and again[KID]["completed"] is True and again[KID]["behind"] is False
+    q2 = world.store.create_attempt(uid(KID2), "quiz", "t", MON - timedelta(hours=2), MON - timedelta(hours=1), [])
+    world.store.save_attempt(q2["id"], submitted_at=MON - timedelta(hours=1), grade=87)
+    assert {s["email"]: s["lessons"]["t"] for s in progress(world, period=1).json()["students"]}[KID2]["completed"] is True   # a passed quiz completes it
+
+
+def test_periods_pick_lessons_by_date_or_month_and_show_the_states_as_they_were(world, bank):
+    # "t" is a September lesson, "n" a March lesson; a date in the curriculum moves a lesson
+    first = progress(world, period=1).json()
+    second = progress(world, period=2).json()
+    ids1, ids2 = [l["id"] for l in first["lessons"]], [l["id"] for l in second["lessons"]]
+    assert "t" in ids1 and "n" in ids2 and "t" not in ids2 and not set(ids1) & set(ids2) and len(ids1) + len(ids2) == 24
+    assert first["current_period"] == 1 and first["periods"][0]["current"] is True
+    world.store.set_lesson_dates({"t": date_in(2027, 2, 15)})
+    assert "t" in [l["id"] for l in progress(world, period=2).json()["lessons"]]
+    # a skill mastered on 20 January: not mastered in the first period (ended 31 December), mastered in the second, seen in March
+    skill = lesson_of(bank, "n")["skills"][0]["id"]
+    world.store.save_progress(uid(KID), skill, started_at="2026-12-01T10:00:00+00:00", mastered_at="2027-01-20T10:00:00+00:00")
+    world.set_time(datetime(2027, 3, 10, 9, 0, tzinfo=timezone.utc))
+    pct = lambda data, lesson="n": {s["email"]: s["lessons"][lesson] for s in data["students"]}[KID]
+    assert pct(progress(world, period=2).json())["percent"] > 0 and pct(progress(world, period=2).json())["state"] == "learning"
+    world.store.set_lesson_dates({"n": date_in(2026, 12, 20)})                               # move "n" into the first period to see its past state
+    past = progress(world, period=1).json()
+    assert pct(past)["percent"] == 0 and pct(past)["state"] == "learning" and past["as_of"] == "2026-12-31"        # started by then, mastered only in January
+
+
+def date_in(y, m, d):
+    from datetime import date
+    return date(y, m, d)
+
+
+def test_readiness_per_student_for_the_nearest_coming_test_and_none_without(world, bank):
+    assert progress(world).json()["test"] is None
+    far = world.store.create_test(world.a["id"], clock.school_day() + timedelta(days=30), ["t"], TEACHER, created_at=clock.now())
+    near = world.store.create_test(world.a["id"], clock.school_day() + timedelta(days=10), ["t"], TEACHER, created_at=clock.now())
+    got = progress(world).json()["test"]
+    assert got["id"] == near["id"] and got["days_left"] == 10
+    rows = {r["email"]: r for r in got["students"]}
+    assert set(rows) == {KID, KID2} and rows[KID]["readiness"]["number"] == 0 and rows[KID]["simulation"] is None and rows[KID]["practice"] is None
+    assert far["id"] != near["id"]
+
+
+def test_only_the_classs_teacher_or_a_developer_may_read_it(world):
+    assert progress(world, TEACHER).status_code == 200 and progress(world, DEV).status_code == 200
+    assert progress(world, OTHER_TEACHER).status_code == 404                                  # another teacher's class: not found
+    assert progress(world, MGR).status_code == 403 and progress(world, KID).status_code == 403
+    assert progress(world, TEACHER, klass=world.b).status_code == 404
+    assert progress(world, period=3).status_code == 422
+    assert world.get(f"/api/classes/{world.a['id']}/progress").status_code in (401, 403)
+
+
+def test_a_class_of_twenty_five_needs_no_more_waits_in_a_row_than_a_class_of_two(bank):
+    """Every store call waits 0.1 s: the progress screen asks for all students at once, so it takes the same time for 2 as for 25."""
+    from fastapi.testclient import TestClient
+    from mathly2.config import Settings
+    from mathly2.main import create_app
+    from mathly2.tests.test_database_waits import DELAY, SlowStore
+
+    def took(n):
+        store = SlowStore()
+        klass = store.create_class("setup", "A", lessons=["t"], teacher_email=TEACHER)
+        for i in range(n):
+            email = f"s{i}@school.test"
+            store.add_member(klass["id"], email)
+            store.link_user(email, uid(email))
+        store.create_test(klass["id"], clock.school_day() + timedelta(days=10), ["t"], TEACHER, created_at=clock.now())
+        client = TestClient(create_app(Settings(), bank=bank, store=store))
+        client.get("/api/me", headers=auth(TEACHER))
+        store.slow = True
+        start = time.perf_counter()
+        assert client.get(f"/api/classes/{klass['id']}/progress", headers=auth(TEACHER)).status_code == 200
+        return time.perf_counter() - start
+
+    small, big = took(2), took(25)
+    assert big < small + 2 * DELAY, (small, big)
+
+
+def test_the_store_reads_many_students_at_once_and_does_not_mix_them():
+    from mathly2.store import InMemoryStore
+    store = InMemoryStore()
+    a, b, c = "a", "b", "c"
+    store.save_progress(a, "s1", started_at=STAMP)
+    store.save_progress(b, "s2", started_at=STAMP, mastered_at=STAMP)
+    store.save_progress(c, "s3", started_at=STAMP)
+    store.add_answer(a, "s1", "s1:k", True, True, None, clock.school_day())
+    row = store.create_attempt(a, "quiz", "t", MON, MON + timedelta(minutes=20), [])
+    store.create_attempt(c, "quiz", "t", MON, MON + timedelta(minutes=20), [])
+    store.create_attempt(a, "simulation", "1", MON, MON + timedelta(minutes=20), [])
+    got = store.progress_of_users([a, b])
+    assert set(got) == {a, b} and [r["skill_id"] for r in got[a]] == ["s1"] and got[b][0]["mastered_at"] == STAMP
+    assert store.progress_of_users([]) == {} and store.progress_of_users(["nobody"]) == {"nobody": []}
+    assert list(store.last_answered_users([a, b])) == [a, b] and "s1" in store.last_answered_users([a])[a] and store.last_answered_users([b])[b] == {}
+    quizzes = store.attempts_of_users([a, b], "quiz")
+    assert [r["id"] for r in quizzes[a]] == [row["id"]] and quizzes[b] == []

mathly2/tests/test_progress_browser.py

@@ -0,0 +1,86 @@
+"""The teacher's progress tab (add-class-progress-views 2.1), in a real browser."""
+import pytest
+
+playwright = pytest.importorskip("playwright.sync_api")
+
+from mathly2 import clock
+from mathly2.tests.serve import offline_formulas, running
+from mathly2.tests.test_written_browser import DESKTOP, KID, KID2, PHONE, TEACHER, bank, browser, day, uid, world  # noqa: F401
+
+STAMP = "2026-10-05T10:00:00+00:00"
+
+
+def open_progress(browser, url, viewport=PHONE, via="tab"):
+    page = offline_formulas(browser.new_page(viewport=viewport))
+    errors = []
+    page.on("pageerror", lambda e: errors.append(str(e)))
+    page.goto(url)
+    page.fill("#email", TEACHER)
+    page.click("#dev button")
+    page.wait_for_selector("#teaching")
+    if via == "tab":
+        page.click("#teacher-tabs [data-tab=progress]")
+    else:
+        page.click(".class-card [data-progress]")
+    page.wait_for_selector("#progress table, #progress .muted")
+    page.errors = errors
+    return page
+
+
+def no_sideways(page):
+    assert page.evaluate("document.documentElement.scrollWidth <= window.innerWidth")
+
+
+@pytest.mark.parametrize("viewport", [PHONE, DESKTOP], ids=["390px", "1280px"])
+def test_progress_is_per_lesson_each_cell_says_its_state_and_the_table_scrolls_inside_its_frame(browser, bank, viewport):
+    app, store, klass, lessons = world(bank)
+    skills = [s["id"] for s in bank.skills if s["unit"] == "t"]
+    store.save_progress(uid(KID), skills[0], started_at=STAMP, mastered_at=STAMP)
+    for s in skills:
+        store.save_progress(uid(KID2), s, started_at=STAMP, mastered_at=STAMP)
+    store.add_member(klass["id"], "new@school.test")
+    with running(app) as url:
+        page = open_progress(browser, url, viewport)
+        assert page.locator("#progress tbody tr").count() == 3 and page.locator("th.skill-col, .hm td.c").count() == 0         # no skill column or cell
+        cell = lambda who: page.locator(f"tr[data-student='{who}'] td[data-lesson=t]")
+        assert cell(KID).get_attribute("data-state") == "learning" and cell(KID).get_attribute("aria-label") == "בלמידה"
+        assert cell(KID2).get_attribute("data-state") == "completed" and cell(KID2).get_attribute("aria-label") == "הושלם" and cell(KID2).inner_text().split() == ["100%", "—"]
+        assert cell("new@school.test").get_attribute("data-state") == "not_started" and cell("new@school.test").get_attribute("aria-label") == "לא התחילו"
+        assert cell("new@school.test").inner_text().split() == ["0%", "—"]                                       # a bar with its percent and a dash: nothing else
+        assert page.locator("td.cov .pbar").count() == page.locator("td.cov").count() and "בוחן" not in page.inner_text("tbody")
+        assert page.locator("td.cov:not([data-state])").count() == 0 
+        assert page.evaluate("(() => { const w = document.querySelector('.tablewrap'); return w.scrollWidth > w.clientWidth; })()") or viewport["width"] > 800
+        no_sideways(page)
+        assert not page.errors
+
+
+def test_the_card_shortcut_the_picker_the_views_and_the_periods(browser, bank):
+    app, store, klass, lessons = world(bank)
+    other = store.create_class("setup", "B", lessons=lessons[:1], teacher_email=TEACHER)
+    store.create_test(klass["id"], day(10), ["t"], TEACHER, created_at=clock.now())
+    with running(app) as url:
+        page = open_progress(browser, url, via="card")
+        assert page.locator("#class-pick option").count() == 2 and "לפי שיעור" in page.inner_text("#view-tabs")
+        page.click("#period-tabs [data-period='2']")
+        page.wait_for_function("document.querySelector('#period-tabs [data-period=\"2\"]').getAttribute('aria-pressed') === 'true'")
+        assert page.locator("th.lesson-col").count() > 0 and page.locator("td.cov .pbar").count() > 0
+        page.click("#view-tabs [data-view=readiness]")
+        assert page.locator("#period-tabs").count() == 0 and "מוכנות" in page.inner_text("#progress table")
+        page.select_option("#class-pick", str(other["id"]))
+        page.wait_for_selector("#no-test")                                                                  # class B has no coming test
+        no_sideways(page)
+
+
+def test_the_table_marks_a_completed_and_a_behind_lesson_in_words(browser, bank):
+    app, store, klass, lessons = world(bank)
+    skills = [s["id"] for s in bank.skills if s["unit"] == "t"]
+    for s in skills:
+        store.save_progress(uid(KID), s, started_at=STAMP, mastered_at=STAMP)
+    store.set_lesson_dates({"t": day(-3)})
+    with running(app) as url:
+        page = open_progress(browser, url)
+        assert page.get_attribute(f"tr[data-student='{KID}'] td[data-lesson=t]", "aria-label") == "הושלם" and page.locator(f"tr[data-student='{KID}'] [data-behind]").count() == 0
+        assert page.get_attribute(f"tr[data-student='{KID2}'] td[data-lesson=t]", "aria-label") == "לא התחילו, בפיגור"
+        assert page.locator(f"tr[data-student='{KID2}'] td[data-lesson=t] [data-behind]").inner_text() == "⚠"           # the visual mark
+        assert page.inner_text("#teacher-tabs [data-tab=progress] .tab-count") == "2"                       # the tab's number: the students
+        no_sideways(page)

mathly2/tests/test_written_browser.py

@@ -841,11 +841,11 @@ def test_every_teacher_tab_shows_its_number_and_the_numbers_change_after_grading
         page.wait_for_selector("#teaching")
         page.wait_for_function("document.querySelector('[data-count=inbox]')?.innerText !== ''")
         numbers = lambda: {el.get_attribute("data-count"): el.inner_text() for el in page.locator("#teacher-tabs [data-count]").all()}
-        assert numbers() == {"classes": "1", "tests": "3", "assignments": "2", "inbox": "2"}
+        assert numbers() == {"classes": "1", "tests": "3", "assignments": "2", "inbox": "2", "progress": "2"}
         for tab in ("tests", "assignments", "inbox"):                                                     # on every tab
             page.click(f"#teacher-tabs [data-tab='{tab}']")
             page.wait_for_function("(t) => document.querySelector(`#teacher-tabs [data-tab='${t}'][aria-pressed='true']`) && [...document.querySelectorAll('#teacher-tabs [data-count]')].every(e => e.innerText !== '')", arg=tab)
-            assert numbers() == {"classes": "1", "tests": "3", "assignments": "2", "inbox": "2"}, tab
+            assert numbers() == {"classes": "1", "tests": "3", "assignments": "2", "inbox": "2", "progress": "2"}, tab
         page.click(f"[data-open='{monday['id']}']")
         page.fill("[name=grade]", "80")
         page.click("#give-grade")

openspec/changes/add-class-progress-views/proposal.md

@@ -2,26 +2,26 @@
 
 ## Why
 
-Teachers need a per-student picture of which skills and lessons each student has covered, to see at a glance where the class struggles (PRD Goal 3, TCH-7, TCH-8).
+A teacher cannot see where a class stands: which skills each student has covered, which lessons are done or behind the curriculum, and who is ready for the coming test (PRD Goal 3, TCH-7, TCH-8, RDY).
 
 ## What Changes
 
-- A class heat map: students by skills (grouped by lesson), each cell showing the state by color and symbol.
-- A lesson coverage table: students by lessons, % of skills mastered and the best quiz grade.
-- Period tabs (Sep–Dec, Jan–Jun) showing states as they were at the end of the period.
-- Each student's readiness for the class's upcoming test, for the teacher.
-- A developer can open these views for any class.
+- A new **"התקדמות" tab** on the teacher's screen (with its number, like the other tabs) and a "התקדמות" shortcut on each class card. It shows one class at a time, with a class picker when the teacher has several.
+- **Progress by lesson** (TCH-7, TCH-8): students by lessons, never by skills. Each cell is kept short: a progress bar with the percent of the lesson's skills mastered, the best quiz grade as a bare number, and a warning mark when the lesson is behind the curriculum (PTH-11). The state in words is the cell's accessible name.
+- **Period tabs**: ספט׳–דצמ׳ and ינו׳–יוני. A period shows the lessons of that period (by the lesson's date in the curriculum, else the bank's month) and states as they were at the end of the period, or today for the current period.
+- **Readiness** for the class's nearest coming test: each student's readiness number and word, mastery, practice average and simulation grade.
+- A developer can open all of these for any class. A manager or an admin cannot: they see no learning data.
 
-Screens: `docs/mockups/mathly2-screens.html` (teacher tab: heat map).
+No learning rule changes. Skills never lose mastery, so a state at a past date is read from the stored started/mastered times.
 
 ## Capabilities
 
 ### New Capabilities
-- `class-progress-views`: the heat map, the coverage table, period tabs and readiness per student (PRD TCH-7, TCH-8, RDY-1 for teachers).
+- `class-progress-views`: the progress by lesson, the periods and the readiness per student.
 
 ### Modified Capabilities
 
 ## Impact
 
-- Reads `skill-mastery`, `lesson-quizzes` and `readiness-meter` data; no new learning rules.
-- Needs each skill's mastered date (already stored) to show states at the end of a period.
+- New `GET /api/classes/{id}/progress`; the counts endpoint gains the number of students; two store reads that fetch many students at once (progress and attempts), so a class costs a few database waits and not one per student; `teacher.js` and a new `teacher_progress.js`; PRD TCH-1, TCH-7, TCH-8; the permissions matrix.
+- Screens: `docs/mockups/mathly2-screens.html` (teacher tab: heat map).

openspec/changes/add-class-progress-views/specs/class-progress-views/spec.md

@@ -1,49 +1,68 @@
-# Spec Delta
+## ADDED Requirements
 
-## Purpose
+### Requirement: The progress tab
+A teacher's screen SHALL have a "התקדמות" tab, with the number of students of the teacher's classes like the other tabs, and each class card SHALL have a "התקדמות" shortcut to it. The tab SHALL show one class at a time, with a way to choose the class when the teacher has several. Only a class's own teacher or a developer SHALL be able to read its progress. A manager or an admin MUST NOT, and a teacher MUST NOT read another teacher's class.
 
-Gives a teacher, and a developer, views of a class's progress by skill and by lesson, so they can see at a glance which skills the class struggles with and who needs help.
+#### Scenario: Two classes
+- **WHEN** a teacher of two classes opens the tab
+- **THEN** they see the first class and can switch to the other
 
-## ADDED Requirements
+#### Scenario: Another teacher's class
+- **WHEN** a teacher asks for the progress of a class they do not teach, or a manager asks for any class
+- **THEN** the server refuses
 
-### Requirement: Class heat map
-For a class they teach, a teacher SHALL see a heat map with a row per student and a column per skill, grouped by lesson. Each cell SHALL show the skill's state (not started, learning, mastered) by color and by a symbol, readable in light and dark mode.
+#### Scenario: A developer
+- **WHEN** a developer opens any class's progress
+- **THEN** they see it as the class's teacher would
 
-#### Scenario: Reading without color
-- **WHEN** the heat map is printed in black and white
-- **THEN** every cell's state can still be read from its symbol
+### Requirement: Progress by lesson
+The progress view SHALL list the students in rows and the lessons in columns, never the skills. Each cell SHALL show only three things: a progress bar with the percent of the lesson's skills mastered written on it, the best quiz grade as a bare number (a dash for none, without the word "בוחן"), and, in the current period, a warning mark when the lesson is behind the curriculum and not completed. The cell's accessible name SHALL still say the state in words (הושלם, בלמידה, לא התחילו, בפיגור).
 
-### Requirement: Lesson coverage
-For a class they teach, a teacher SHALL see a table with a row per student and a column per lesson; each cell SHALL show the % of the lesson's skills the student mastered and their best quiz grade for it.
+#### Scenario: Cell contents
+- **WHEN** a student has mastered 3 of 5 skills of a lesson and their best quiz grade is 80
+- **THEN** the cell shows a bar with 60% and the number 80, and nothing else
 
-#### Scenario: Half covered
-- **WHEN** a student mastered 2 of a lesson's 4 skills and scored 75 on its quiz
-- **THEN** their cell for that lesson shows 50% and 75
+#### Scenario: Behind
+- **WHEN** a lesson's date has passed and a student has neither mastered all its skills nor passed its quiz
+- **THEN** that student's cell for the lesson carries the warning mark
 
-### Requirement: Period tabs
-Both views SHALL have tabs for Sep–Dec and Jan–Jun. A period SHALL show the skills of the lessons taught in it, with states as they were at the end of the period, or today for the current period.
+#### Scenario: Completed or not started
+- **WHEN** a student has passed a lesson's quiz, or has done nothing in it
+- **THEN** the cell's accessible name says "הושלם" or "לא התחילו", and the cell shows no extra text
 
-#### Scenario: Last period
-- **WHEN** a teacher opens the Sep–Dec tab in March
-- **THEN** each cell shows the state as of 31 December
+#### Scenario: No skill columns
+- **WHEN** a teacher opens the progress view
+- **THEN** no column or cell stands for a single skill
 
-### Requirement: Readiness per student
-For each upcoming test of the class, the teacher SHALL see each student's readiness number and its parts.
+### Requirement: The progress table
+A student who has not signed in yet SHALL have every lesson not started. The table SHALL scroll inside its own frame with the student column fixed, and the page MUST NOT scroll sideways.
+
+#### Scenario: Not signed in yet
+- **WHEN** a student was added to the class and has never signed in
+- **THEN** their row shows every lesson as not started
 
-#### Scenario: Before a test
-- **WHEN** a test is 5 days away
-- **THEN** the teacher sees every student's readiness number for it
+#### Scenario: A phone
+- **WHEN** the table is wider than the screen
+- **THEN** it scrolls inside its frame and the page does not scroll sideways
 
-### Requirement: Works on a computer
-The views SHALL use the full width of a computer screen and keep student names and lesson headers visible while scrolling.
+### Requirement: Periods
+The progress by lesson SHALL have two period tabs, "ספט׳–דצמ׳" and "ינו׳–יוני". A period SHALL show the lessons of that period, by the lesson's date in the curriculum or, when it has none, by the last month of the bank's month for it, and the states as they were at the end of the period, or today for the current period. The current period SHALL be open first.
 
-#### Scenario: Wide class
-- **WHEN** a teacher scrolls the heat map sideways on a computer
-- **THEN** the student names stay visible
+#### Scenario: A past period
+- **WHEN** a skill was mastered on 20 January and the teacher opens the progress view in March
+- **THEN** that lesson's percent does not include the skill in the first period's view (which ends on 31 December), and does in the second
+
+#### Scenario: Lessons of the period
+- **WHEN** a lesson is dated 15 February
+- **THEN** it appears in the second period and not in the first
+
+### Requirement: Readiness per student
+For the class's nearest coming test the tab SHALL list each student's readiness number and its word, their mastery percent, their practice-test average and their simulation grade, with a dash for what they have not done. A class with no coming test SHALL say so.
 
-### Requirement: Developer access
-A developer SHALL be able to open these views for any class.
+#### Scenario: A coming test
+- **WHEN** a class has a test in ten days and one student has done nothing
+- **THEN** the table lists that student with a dash for what is missing
 
-#### Scenario: Any class
-- **WHEN** a developer opens the heat map of a class they do not teach
-- **THEN** it opens
+#### Scenario: No test
+- **WHEN** the class has no coming test
+- **THEN** the readiness view says no test is set

openspec/changes/add-class-progress-views/tasks.md

@@ -0,0 +1,14 @@
+# Tasks
+
+## 1. The data
+
+- [x] 1.1 Add store reads that fetch the progress rows and the attempts of many students in one call (in memory and Supabase); verify unit tests: rows of several students come back together, an empty list gives nothing, other students are not mixed in
+- [x] 1.2 Add `GET /api/classes/{id}/progress?period=1|2` returning the students, the lessons of the period with their skills and dates, each student's skill states as of the period's end, the coverage (percent, best quiz grade, completed, behind) and the readiness for the nearest coming test; add the number of students to `GET /api/teaching/counts`; verify API tests for every scenario of the progress by lesson, periods and readiness, the permissions (own teacher, other teacher, developer, manager, admin, student) and the permissions matrix; verify a timing test: a class of 25 students needs no more waits in a row than a class of 2
+
+## 2. The screens
+
+- [x] 2.1 Add the "התקדמות" tab (with its number) and the card shortcut, the class picker, the period tabs and the two views (progress by lesson, readiness); verify Playwright tests: each cell shows its state in a symbol and a word, no column stands for a skill, the table scrolls inside its frame and the page does not scroll sideways at 360px and 1280px, a student who never signed in is all not started,, the picker switches classes, the period tabs change the lessons shown
+
+## 3. Wrap-up
+
+- [x] 3.1 Update the PRD (TCH-1, TCH-7, TCH-8); run the full suite and `openspec validate add-class-progress-views --strict`; verify both pass