feat: add AI queue for math requests, including database migration and tests

- Implemented a new table `math_ai_requests` to handle student requests for AI assistance in math problems.
- Created tests for the AI queue functionality, ensuring proper request handling and state management.
- Added browser tests to verify the user guide's accessibility and functionality for both students and teachers.
- Developed a class report feature for teachers to view student progress and grades.

README.md

@@ -18,6 +18,10 @@ Photographed problems are sent to the configured AI provider for solving and are
 
 When the computer asks for a photo of a handwritten answer, the student's phone can get a notification, even with the app closed. The phone offers it after its first photo is sent. It needs `VAPID_PRIVATE_KEY` (make one with `python -m app.push`) and the migration `supabase/migrations/20261103180000_math_push_subs.sql`. On an iPhone it works only from the app added to the home screen.
 
+## User guide
+
+The **?** button on the sign-in screen and in the app's header opens a short guide in Hebrew, with a tab for students and one for teachers. Its text is in `static/guide.js`; update it there when a feature changes.
+
 ## Science riddles (class vote)
 
 The **מדעים** subject has a unit **חידות** with the skill **טיל**: the class guesses how much fuel a rocket needs. The teacher opens a vote and shows its 4-digit code; students join with the code on their own devices and vote. Votes stay hidden until the teacher presses check; the answer most students chose is launched, and the rocket flies, falls back (too little fuel) or stays on the pad (too heavy). A tie is not launched: students can change their vote and the teacher checks again. Riddles are in `app/science.json`. Votes live in the server's memory (the app runs as one process), so a restart ends the votes in progress. No sign-in or migration is needed.
@@ -72,6 +76,18 @@ Checks and feedback are stored privately against the original attempt and photo,
 
 For rollback, turn `MATHLY_ANSWER_SCANS_ENABLED` off and restart; preserve the new tables and private bucket. The skills API serves the original multiple-choice geometry sample while scanning is disabled, including for guest practice and older frontends. Enabling scanning again restores open-ended presentation and access to saved answers. Keep stored answer records for recovery. No destructive down migration is needed.
 
+### Class teacher
+
+Each class has one teacher, chosen from its students in the class editor (**ניהול → כיתות → עריכה → מורה הכיתה**). That account gets a **הכיתה שלי** button that opens the class report: for every other student, the skills finished in the class's units, the mistakes that keep coming back, the **בוחן מסכם** grade per unit, and the **מבחני תרגול** results, plus the mistakes most common across the class. Managers open the same report from a class's card (**מעקב**). The report reads the students' saved progress (`math_progress`) and Supabase's user list with the server's secret key; it needs no new migration. A student's numbers show up once they have signed in and practised on the current version of the app.
+
+### The teacher's AI queue
+
+Students never call the AI themselves. When a student saves an open answer (or hands in a **בוחן מסכם**, or sends a photographed problem), the request goes to their class teacher's **תור AI** instead of to Claude. The teacher sees each waiting request with the student's photo and the question, then presses **שליחה ל-AI** or **דחייה** (with an optional note for the student). The student's page shows the answer as waiting for the teacher, then the grade and feedback once it is sent, or the teacher's note if it was declined (the student can ask again). A failed send stays in the queue for the teacher to retry. Managers see every class's requests.
+
+Accounts with the teacher, admin or developer role, and every class teacher, still send to the AI directly. A student can have at most 5 requests waiting; the daily limits on checks and photos still apply. A photographed problem is kept (as a clean JPEG) only until the teacher sends or declines it.
+
+Apply [the additive queue migration](supabase/migrations/20261104090000_math_ai_requests.sql) before deploying this code: it adds the service-only `math_ai_requests` table. Without it, students cannot have answers checked (they see that checking is unavailable); teachers are not affected.
+
 ### Lesson resources (teachers)
 
 A teacher taps a unit's title on the path (for example **טכניקה אלגברית 1**), photographs an exercise or an explanation, and saves it to that lesson's resources. Each photo is marked as **תרגיל חדש**, **הסבר תיאורטי**, or **אחר** (with a short free-text description), and can optionally name the topic it belongs to (for example **פילוג מורחב**). Apply [the additive resources migration](supabase/migrations/20261101090000_math_unit_resources.sql); it adds the `math_unit_resources` table and the private `mathly-resources` bucket. Only accounts with the teacher role see, add, or open resources, and only the teacher who added a photo (or a manager) can delete it. Students do not see resources yet.

app/ai_queue.py

@@ -0,0 +1,291 @@
+"""The teacher's AI queue: a student never calls Claude. A teacher reviews each request and sends it.
+
+A student's photographed problem (POST /api/math/photo) or the answer they want checked
+(POST /api/math/answer-attempts/{id}/grade, and the automatic check after an upload) becomes a request in the
+Supabase table `math_ai_requests`. The class's teacher (the account chosen in the class editor) sees the requests of
+their class's students, and a manager sees every request. The teacher looks at the photo and either sends it to the
+AI or declines it with an optional note. The student's page shows the request waiting, and then its result.
+
+Who sends straight to the AI, with no queue: accounts with the teacher, admin or developer role, a class's
+teacher, and everyone when sign-in is off (local development: there are no students to hold back).
+"""
+from __future__ import annotations
+
+import base64
+import logging
+import urllib.parse
+from datetime import datetime, timedelta, timezone
+
+from fastapi import Depends
+from fastapi.responses import JSONResponse, Response
+
+from .access import has_permission
+from .answer_scans import ScanError, uuid_text
+from .auth import AuthUnavailable, ClassConflict
+from .math_photo import PhotoUnavailable
+
+log = logging.getLogger("mathly.ai_queue")
+MIGRATION = "supabase/migrations/20261104090000_math_ai_requests.sql"
+TABLE = "/rest/v1/math_ai_requests"
+FIELDS = ("id,created_at,user_id,email,kind,state,attempt_id,label,question,result,note,error,"
+          "reviewed_by,sent_at,finished_at")
+OPEN = ("pending", "sending")
+MAX_OPEN = 5                          # a student's requests waiting at once
+STALE_SEND = timedelta(minutes=5)     # a send that never finished (a restart) may be sent again after this
+RECENT = timedelta(hours=24)          # handled requests stay on the teacher's list this long
+DIRECT_ROLES = frozenset({"teacher", "admin", "developer"})
+
+
+def may_send(user: dict | None) -> bool:
+    """Whether this account calls the AI itself. Everyone else asks their teacher."""
+    if user is None:
+        return True   # sign-in is off
+    if DIRECT_ROLES & set(user.get("roles", ())) or "*" in user.get("permissions", ()):
+        return True
+    email = str(user.get("email", "")).lower()
+    return any(email in row.get("teachers", ()) for row in user.get("classes", ()))
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def stamp(when: datetime) -> str:
+    return urllib.parse.quote(when.isoformat())
+
+
+class AiQueue:
+    def __init__(self, auth):
+        self.auth = auth
+        self._warned = False
+
+    @property
+    def configured(self) -> bool:
+        return bool(self.auth is not None and getattr(self.auth, "secret", None))
+
+    def _rest(self, query: str = "", method: str = "GET", body=None):
+        if not self.configured:
+            raise ScanError(503, "queue_unavailable")
+        try:
+            return self.auth._admin(TABLE + query, method, body)
+        except ClassConflict as exc:
+            raise ScanError(409, "already_queued") from exc
+        except AuthUnavailable as exc:
+            if "answered 404" in str(exc) and not self._warned:
+                log.warning("the math_ai_requests table is missing; apply %s", MIGRATION)
+                self._warned = True
+            else:
+                log.warning("AI queue: %s", exc)
+            raise ScanError(503, "queue_unavailable") from exc
+
+    # ---- the student's side
+    def add(self, row: dict) -> dict:
+        """A new pending request. For an answer that already has one open, that one."""
+        try:
+            return self._rest("?select=" + FIELDS, "POST", row)[0]
+        except ScanError as exc:
+            if exc.code == "already_queued" and row.get("attempt_id"):
+                found = self.for_attempt(row["user_id"], row["attempt_id"])
+                if found:
+                    return found
+            raise
+
+    def for_attempt(self, user_id: str, attempt_id: str) -> dict | None:
+        rows = self._rest(f"?select={FIELDS}&user_id=eq.{user_id}&attempt_id=eq.{attempt_id}"
+                          "&order=created_at.desc&limit=1")
+        return rows[0] if rows else None
+
+    def open_count(self, user_id: str) -> int:
+        return len(self._rest(f"?select=id&user_id=eq.{user_id}&state=in.({','.join(OPEN)})&limit={MAX_OPEN + 1}"))
+
+    def mine(self, user_id: str, limit: int = 20) -> list[dict]:
+        return self._rest(f"?select={FIELDS}&user_id=eq.{user_id}&kind=eq.photo&order=created_at.desc&limit={limit}")
+
+    def cancel(self, user_id: str, request_id: str) -> dict | None:
+        rows = self._rest(f"?id=eq.{request_id}&user_id=eq.{user_id}&state=eq.pending&select={FIELDS}", "PATCH",
+                          {"state": "cancelled", "image": None, "finished_at": now()})
+        return rows[0] if rows else None
+
+    def reopen(self, request_id: str) -> dict:
+        """A failed request the student asks for again goes back to pending, instead of a second request."""
+        rows = self._rest(f"?id=eq.{request_id}&state=in.(failed,declined)&select={FIELDS}", "PATCH",
+                          {"state": "pending", "error": "", "note": "", "finished_at": None})
+        if not rows:
+            raise ScanError(409, "request_taken")
+        return rows[0]
+
+    # ---- the teacher's side
+    def listing(self, emails: set[str] | None, limit: int = 100) -> list[dict]:
+        """Open requests, and the ones handled in the last day. `emails`: only these students (None: all)."""
+        if emails is not None and not emails:
+            return []
+        who = ""
+        if emails is not None:
+            names = ",".join('"' + e.replace('"', "") + '"' for e in sorted(emails))
+            who = "&email=in." + urllib.parse.quote(f"({names})", safe="(),")
+        since = stamp(datetime.now(timezone.utc) - RECENT)
+        return self._rest(f"?select={FIELDS}{who}&or=(state.in.(pending,sending,failed),finished_at.gte.{since})"
+                          f"&order=created_at.desc&limit={limit}")
+
+    def get(self, request_id: str, image: bool = False) -> dict | None:
+        rows = self._rest(f"?select={FIELDS}{',image' if image else ''}&id=eq.{request_id}")
+        return rows[0] if rows else None
+
+    def claim(self, request_id: str, reviewer: str) -> dict:
+        """Takes the request for sending. Two teachers clicking at once: one gets it, the other 409."""
+        stale = stamp(datetime.now(timezone.utc) - STALE_SEND)
+        rows = self._rest(f"?id=eq.{request_id}&or=(state.in.(pending,failed),and(state.eq.sending,sent_at.lt.{stale}))"
+                          f"&select={FIELDS},image", "PATCH",
+                          {"state": "sending", "sent_at": now(), "reviewed_by": reviewer, "error": ""})
+        if not rows:
+            raise ScanError(409, "request_taken")
+        return rows[0]
+
+    def finish(self, request_id: str, state: str, **fields) -> dict:
+        rows = self._rest(f"?id=eq.{request_id}&select={FIELDS}", "PATCH",
+                          {"state": state, "finished_at": now(), **fields})
+        return rows[0] if rows else {}
+
+    def decline(self, request_id: str, reviewer: str, note: str) -> dict:
+        rows = self._rest(f"?id=eq.{request_id}&state=in.(pending,failed)&select={FIELDS}", "PATCH",
+                          {"state": "declined", "image": None, "note": note, "reviewed_by": reviewer,
+                           "finished_at": now()})
+        if not rows:
+            raise ScanError(409, "request_taken")
+        return rows[0]
+
+
+def for_student(row: dict | None) -> dict | None:
+    """What the student's page reads of a request: no teacher email, no other student's data."""
+    if not row:
+        return None
+    return {k: row.get(k) for k in ("id", "created_at", "kind", "state", "label", "result", "note", "finished_at")}
+
+
+def install_ai_queue_routes(app, signed_in):
+    if not hasattr(app.state, "ai_queue"):
+        app.state.ai_queue = AiQueue(app.state.auth)
+
+    def queue() -> AiQueue:
+        return app.state.ai_queue
+
+    def account(user=Depends(signed_in)) -> dict:
+        if not user or not user.get("id"):
+            raise ScanError(401, "sign_in_required")
+        return user
+
+    def watched(user: dict) -> set[str] | None:
+        """The students whose requests this account reviews; None: everyone's (a manager)."""
+        if has_permission(user, "management.access"):
+            return None
+        email = str(user.get("email", "")).lower()
+        try:
+            classes = app.state.auth.classes()
+        except AuthUnavailable as exc:
+            raise ScanError(503, "queue_unavailable") from exc
+        out: set[str] = set()
+        for row in classes:
+            if email in row.get("teachers", ()):
+                out |= set(row.get("emails", ())) - set(row.get("teachers", ()))
+        return out
+
+    def reviewer(user=Depends(account)) -> dict:
+        if not may_send(user) or watched(user) == set():   # a teacher with no class has no one to review
+            raise ScanError(403, "teacher_required")
+        return user
+
+    def reviewed(user: dict, request_id: str, image: bool = False) -> dict:
+        row = queue().get(uuid_text(request_id), image=image)
+        emails = watched(user)
+        if not row or (emails is not None and row["email"] not in emails):
+            raise ScanError(404, "not_found")
+        return row
+
+    def failure(code: str, reason: str = "", detail: str = "") -> str:
+        """A failed send's `error`: "code|reason|detail", read by the teacher's error details (math.js)."""
+        return "|".join([code, reason or "", " ".join((detail or "").split())])[:300]
+
+    def reply(value, status=200):
+        return JSONResponse(value, status_code=status, headers={"Cache-Control": "no-store"})
+
+    def note(user, kind, row):
+        actions = getattr(app.state, "actions", None)
+        if actions is not None:
+            what = row.get("label") or ("תרגיל מצולם" if row.get("kind") == "photo" else "")
+            actions.record(user, kind, " · ".join(filter(None, [what, row.get("email", "")])))
+
+    # ---- the student
+    @app.get("/api/math/ai-requests")
+    def my_requests(user=Depends(account)):
+        return reply({"direct": may_send(user), "requests": [for_student(r) for r in queue().mine(user["id"])]})
+
+    @app.post("/api/math/ai-requests/{request_id}/cancel")
+    def cancel_request(request_id: str, user=Depends(account)):
+        row = queue().cancel(user["id"], uuid_text(request_id))
+        if row is None:
+            raise ScanError(409, "request_taken")
+        return reply(for_student(row))
+
+    # ---- the teacher
+    @app.get("/api/ai-queue")
+    def listing(user=Depends(reviewer)):
+        rows = queue().listing(watched(user))
+        return reply({"requests": rows, "all": has_permission(user, "management.access")})
+
+    @app.get("/api/ai-queue/{request_id}/image")
+    def request_image(request_id: str, user=Depends(reviewer)):
+        row = reviewed(user, request_id, image=True)
+        if row["kind"] == "photo":
+            if not row.get("image"):
+                raise ScanError(404, "not_found")
+            data = base64.b64decode(row["image"])
+        else:
+            answer = app.state.answers.action(row["user_id"], "get", attempt_id=row["attempt_id"])
+            if not answer.get("attachment"):
+                raise ScanError(404, "not_found")
+            data = app.state.answers.read(answer["attachment"]["object_key"])
+        return Response(data, media_type="image/jpeg",
+                        headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"})
+
+    @app.post("/api/ai-queue/{request_id}/send")
+    def send(request_id: str, user=Depends(reviewer)):
+        reviewed(user, request_id)   # visibility first: another class's request is "not found"
+        row = queue().claim(uuid_text(request_id), user.get("email", ""))
+        if row["kind"] == "photo":
+            row = send_photo(row)
+        else:
+            row = send_answer(row)
+        note(user, "ai_sent" if row.get("state") == "done" else "ai_failed", row)
+        return reply(row)
+
+    def send_photo(row: dict) -> dict:
+        from . import ai_usage
+        try:
+            result = app.state.solve_photo(base64.b64decode(row.get("image") or ""), "image/jpeg")
+        except PhotoUnavailable as exc:
+            return queue().finish(row["id"], "failed", error=failure("photo_failed", exc.reason, exc.detail))
+        except Exception as exc:
+            log.error("AI queue photo failed: %s", type(exc).__name__)
+            return queue().finish(row["id"], "failed", error=failure(
+                "photo_failed", "server_error", f"{type(exc).__name__}: {str(exc)[:200]}"))
+        ai_usage.record(app.state.auth, row["user_id"], "photo", result.pop("usage", None))
+        return queue().finish(row["id"], "done", result=result, image=None)
+
+    def send_answer(row: dict) -> dict:
+        try:
+            result = app.state.grade_attempt(row["user_id"], row["attempt_id"])
+        except ScanError as exc:
+            return queue().finish(row["id"], "failed", error=failure(exc.code, exc.reason, exc.detail))
+        grading = (result or {}).get("grading") or {}
+        if grading.get("state") == "completed":
+            return queue().finish(row["id"], "done", result={"verdict": grading["result"].get("verdict"),
+                                                            "score": grading["result"].get("score")})
+        return queue().finish(row["id"], "failed", error=failure(grading.get("error") or "grading_failed"))
+
+    @app.post("/api/ai-queue/{request_id}/decline")
+    def decline(request_id: str, body: dict | None = None, user=Depends(reviewer)):
+        reviewed(user, request_id)
+        text = " ".join(str((body or {}).get("note") or "").split())[:500]
+        row = queue().decline(uuid_text(request_id), user.get("email", ""), text)
+        note(user, "ai_declined", row)
+        return reply(row)

app/answer_grading.py

@@ -6,7 +6,7 @@ import json
 import logging
 
 from .ai_usage import usage_of
-from .math_photo import PhotoUnavailable, math_model, photo_client
+from .math_photo import PhotoUnavailable, failure_reason, math_model, photo_client
 
 log = logging.getLogger("mathly.answer_grading")
 BOOLEAN_FIELDS = ("readable", "confident", "answer_correct", "reasoning_correct",
@@ -89,13 +89,19 @@ class AnswerGrader:
             )
         except anthropic.APIError as exc:
             # Do not log student work or provider response bodies.
-            log.warning("answer grading provider failed: %s", type(exc).__name__)
-            raise PhotoUnavailable("הבדיקה אינה זמינה כרגע. נסו שוב בעוד דקה.") from exc
+            reason, detail = failure_reason(exc)
+            log.warning("answer grading provider failed: %s (%s)", reason, detail)
+            raise PhotoUnavailable("הבדיקה אינה זמינה כרגע. נסו שוב בעוד דקה.", reason, detail) from exc
         if response.stop_reason != "end_turn":
-            raise PhotoUnavailable("הבדיקה לא הושלמה. נסו שוב.")
+            raise PhotoUnavailable("הבדיקה לא הושלמה. נסו שוב.", "refused" if response.stop_reason == "refusal"
+                                   else "incomplete", f"stop_reason={response.stop_reason} ({response.model})")
         try:
             value = json.loads(next(b.text for b in response.content if b.type == "text"))
         except (ValueError, StopIteration) as exc:
-            raise PhotoUnavailable("הבדיקה לא הושלמה. נסו שוב.") from exc
+            raise PhotoUnavailable("הבדיקה לא הושלמה. נסו שוב.", "bad_output", "the answer was not JSON") from exc
+        try:
+            checked = validate_assessment(value)
+        except PhotoUnavailable as exc:
+            raise PhotoUnavailable(str(exc), "bad_output", "the answer did not pass the rubric's checks") from exc
         # The route pops "usage" before storing the result and records it (ai_usage.py).
-        return {**validate_assessment(value), "model": response.model, "usage": usage_of(response)}
+        return {**checked, "model": response.model, "usage": usage_of(response)}

app/answer_routes.py

@@ -10,6 +10,7 @@ from fastapi.responses import JSONResponse, Response
 from starlette.concurrency import run_in_threadpool
 
 from . import ai_usage
+from .ai_queue import AiQueue, for_student, may_send
 from .answer_scans import AnswerScans, MAX_IMAGE, ScanError, clean_image, public_result, uuid_text
 from .answer_grading import AnswerGrader
 from .math_photo import PhotoUnavailable
@@ -35,10 +36,15 @@ def grading_key():
 def install_answer_routes(app, signed_in):
     if not hasattr(app.state, "answers"):
         app.state.answers = AnswerScans(app.state.auth)
+    if not hasattr(app.state, "ai_queue"):
+        app.state.ai_queue = AiQueue(app.state.auth)
 
     @app.exception_handler(ScanError)
     async def scan_error(_request, exc):
-        return JSONResponse({"detail": exc.code}, status_code=exc.status,
+        body = {"detail": exc.code}
+        if exc.reason:
+            body.update(reason=exc.reason, error_detail=exc.detail)
+        return JSONResponse(body, status_code=exc.status,
                             headers={"Cache-Control": "no-store"})
 
     def student(user=Depends(signed_in)):
@@ -58,6 +64,12 @@ def install_answer_routes(app, signed_in):
                 # A staged deployment must not block saved images or upload receipt.
                 result["grading"] = None
                 result["grading_available"] = False
+            result["ai_request"] = None   # the teacher's queue (ai_queue.py): this answer's latest request
+            if app.state.ai_queue.configured and (result.get("grading") or {}).get("state") != "completed":
+                try:
+                    result["ai_request"] = for_student(app.state.ai_queue.for_attempt(user, result["attempt"]["id"]))
+                except ScanError:
+                    pass
         return result
 
     def note(user, kind, result, extra=""):
@@ -110,10 +122,13 @@ def install_answer_routes(app, signed_in):
         return reply(call(user, "get", attempt_id=uuid_text(attempt_id)))
 
     @app.post("/api/math/answer-attempts/{attempt_id}/grade")
-    def grade_answer(attempt_id: str, body: dict | None = None, user=Depends(student)):
-        return evaluate_answer(user, uuid_text(attempt_id), automatic=bool(body and body.get("automatic") is True))
+    def grade_answer(attempt_id: str, body: dict | None = None, user=Depends(student), account=Depends(signed_in)):
+        return evaluate_answer(user, uuid_text(attempt_id), automatic=bool(body and body.get("automatic") is True),
+                               account=account)
 
-    def evaluate_answer(user, aid, *, automatic=False):
+    def evaluate_answer(user, aid, *, automatic=False, account=None):
+        """Checks the answer with the AI. `account`: the signed-in student asking; one who may not call the AI
+        (ai_queue.may_send) puts the answer in their teacher's queue instead. None: the teacher's queue sending it."""
         if open_ended_locked():
             raise ScanError(403, "open_ended_locked")   # before any storage read or provider call
         result = app.state.answers.action(user, "get", attempt_id=aid)
@@ -124,7 +139,9 @@ def install_answer_routes(app, signed_in):
             return reply(call(user, "get", attempt_id=aid))
         key = grading_key()
         if not key:
-            raise ScanError(503, "grading_unavailable")
+            raise ScanError(503, "grading_unavailable", "missing_key", "ANTHROPIC_API_KEY is not set")
+        if account is not None and not may_send(account):
+            return ask_teacher(user, account, aid, result, automatic)
         lease = str(uuid.uuid4())
         grading = app.state.answers.grade(user, "start", attempt_id=aid, lease_id=lease)
         if grading["state"] != "grading" or grading["lease_id"] != lease:
@@ -144,14 +161,43 @@ def install_answer_routes(app, signed_in):
                 pass  # an uncertain commit may already have stored the successful check
             if isinstance(exc, ScanError):
                 raise
-            if not isinstance(exc, PhotoUnavailable):
+            if isinstance(exc, PhotoUnavailable):
+                reason, detail = exc.reason or "provider_error", exc.detail
+            else:
                 log.error("answer grader failed: %s", type(exc).__name__)
-            raise ScanError(503, "grading_failed") from exc
+                reason, detail = "server_error", f"{type(exc).__name__}: {' '.join(str(exc).split())[:200]}"
+            raise ScanError(503, "grading_failed", reason, detail) from exc
         return reply(call(user, "get", attempt_id=aid))
 
-    def automatic_grade(user, attempt_id):
+    def ask_teacher(user, account, aid, result, automatic):
+        queue = app.state.ai_queue
+        if not queue.configured:
+            raise ScanError(503, "grading_unavailable")
+        latest = queue.for_attempt(user, aid)
+        if latest and latest["state"] in ("pending", "sending"):
+            pass   # already waiting
+        elif latest and automatic:
+            pass   # declined, failed or done before: only the student's own click asks again
+        elif latest and latest["state"] in ("failed", "declined"):
+            queue.reopen(latest["id"])
+            note(user, "ai_request", result)
+        else:
+            snapshot = result["attempt"].get("snapshot") or {}
+            queue.add({"user_id": user, "email": str(account.get("email", "")).lower(), "kind": "grading",
+                       "attempt_id": aid, "label": str(snapshot.get("name", ""))[:300],
+                       "question": str(snapshot.get("question", ""))[:4000]})
+            note(user, "ai_request", result)
+        return reply(call(user, "get", attempt_id=aid))
+
+    # the teacher's queue sends a student's answer: the same check, with no queue in front of it
+    def grade_for_queue(user_id, aid):
+        evaluate_answer(user_id, aid)
+        return call(user_id, "get", attempt_id=aid)
+    app.state.grade_attempt = grade_for_queue
+
+    def automatic_grade(user, attempt_id, account=None):
         try:
-            evaluate_answer(user, attempt_id, automatic=True)
+            evaluate_answer(user, attempt_id, automatic=True, account=account)
         except ScanError as exc:
             # Upload is already committed. Keep failures separate and retryable.
             log.info("automatic answer grading stopped: %s", exc.code)
@@ -205,7 +251,7 @@ def install_answer_routes(app, signed_in):
 
     @app.post("/api/math/answer-scans/{scan_id}/uploads/{lease_id}")
     async def upload(scan_id: str, lease_id: str, background_tasks: BackgroundTasks,
-                     photo: UploadFile = File(...), user=Depends(student)):
+                     photo: UploadFile = File(...), user=Depends(student), account=Depends(signed_in)):
         sid, lease = uuid_text(scan_id), uuid_text(lease_id)
         data = await photo.read(MAX_IMAGE + 1)
         result = await run_in_threadpool(submit, user, sid, lease, data, photo.content_type)
@@ -213,7 +259,7 @@ def install_answer_routes(app, signed_in):
         # a quiz answer is graded only once the quiz is handed in (the page asks for it then)
         quiz = str(result.get("attempt", {}).get("question_id", "")).startswith("quiz:")
         if result.get("grading_available") and not result.get("grading") and not quiz:
-            background_tasks.add_task(automatic_grade, user, result["attempt"]["id"])
+            background_tasks.add_task(automatic_grade, user, result["attempt"]["id"], account)
         return reply(result)
 
     def submit(user, sid, lease, data, content_type):

app/answer_scans.py

@@ -38,6 +38,8 @@ log = logging.getLogger("mathly.answers")
 class ScanError(Exception):
     status: int
     code: str
+    reason: str = ""   # why an AI check failed (math_photo.failure_reason), for the teacher's error details
+    detail: str = ""   # the technical line behind it
 
 
 def clean_image(data: bytes, content_type: str) -> bytes:

app/auth.py

@@ -160,6 +160,22 @@ class SupabaseAuth:
             grades = []
         return {"attempts": attempts, "grades": grades}
 
+    def user_ids(self, emails: list[str]) -> dict[str, str]:
+        """The account id of each email that has signed in at least once (Supabase's admin user list), by email."""
+        wanted, found = {email.lower() for email in emails}, {}
+        page = 1
+        while wanted - found.keys():
+            data = self._admin(f"/auth/v1/admin/users?page={page}&per_page=1000") or {}
+            users = data.get("users") if isinstance(data, dict) else data
+            for user in users or []:
+                email = str(user.get("email") or "").lower()
+                if email in wanted and user.get("id"):
+                    found[email] = user["id"]
+            if len(users or []) < 1000 or page >= 50:
+                break
+            page += 1
+        return found
+
     def access_for(self, user_id: str, fresh: bool = False) -> dict | None:
         if not self.secret:
             return None

app/class_report.py

@@ -0,0 +1,83 @@
+"""The class teacher's view of the class: each student's path progress, difficulties and grades.
+
+A class has one teacher, chosen from its students (`classes.teachers`). That account, and any manager, can read
+GET /api/classes/{id}/report: for each other student of the class, the parts of their saved progress
+(app/progress.py) the teacher's page shows. The page works out the rest (stars, mistake patterns) the same way the
+student's own page does.
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import Depends, HTTPException
+from fastapi.responses import JSONResponse
+
+from .access import has_permission
+from .auth import AuthUnavailable
+
+log = logging.getLogger("mathly.class_report")
+TABLE = "/rest/v1/math_progress"
+SLIPS_SENT = 300
+
+
+def report_part(data: dict) -> dict:
+    """What the teacher's page reads from a student's progress: finished skills, mistakes, and both kinds of tests."""
+    def obj(key):
+        value = data.get(key)
+        return value if isinstance(value, dict) else {}
+
+    def items(key):
+        value = data.get(key)
+        return [x for x in value if isinstance(x, dict)] if isinstance(value, list) else []
+
+    quizzes = [{k: q.get(k) for k in ("at", "n", "right", "ms", "units")} for q in items("quizzes")]
+    unit_quizzes = {}
+    for unit, state in obj("uq").items():
+        history = state.get("history") if isinstance(state, dict) else None
+        sitting = state.get("sitting") if isinstance(state, dict) else None
+        unit_quizzes[unit] = {
+            "history": [{k: h.get(k) for k in ("at", "score", "timeUp")} for h in history or [] if isinstance(h, dict)],
+            "going": bool(isinstance(sitting, dict) and sitting.get("started") and not sitting.get("submitted"))}
+    return {"done": obj("done"), "gold": obj("gold"), "days": obj("days"), "missed": obj("missed"),
+            "slips": items("slips")[-SLIPS_SENT:], "quizzes": quizzes, "uq": unit_quizzes,
+            "updated": data.get("updated")}
+
+
+def install_class_report_routes(app, signed_in, units_of):
+    def class_of(class_id: int, user) -> dict:
+        try:
+            row = next((r for r in app.state.auth.classes() if r.get("id") == class_id), None)
+        except AuthUnavailable as exc:
+            raise HTTPException(503, str(exc)) from exc
+        if row is None:
+            raise HTTPException(404, "class not found")
+        email = str((user or {}).get("email", "")).lower()
+        if email not in row.get("teachers", ()) and not has_permission(user, "management.access"):
+            raise HTTPException(403, "only the class's teacher can see its report")
+        return row
+
+    @app.get("/api/classes/{class_id}/report")
+    def class_report(class_id: int, user=Depends(signed_in)):
+        if app.state.auth is None:
+            raise HTTPException(404, "classes need sign-in")
+        row = class_of(class_id, user)
+        teachers = set(row.get("teachers", ()))
+        students = [email for email in row.get("emails", ()) if email not in teachers]
+        auth = app.state.auth
+        try:
+            ids = auth.user_ids(students) if students else {}
+            rows = auth._admin(f"{TABLE}?select=user_id,data,updated_at&user_id=in.({','.join(ids.values())})") \
+                if ids else []
+        except AuthUnavailable as exc:
+            log.error("class report failed: %s", exc)
+            raise HTTPException(503, "report_unavailable") from exc
+        by_id = {r["user_id"]: r for r in rows or []}
+        out = []
+        for email in students:
+            saved = by_id.get(ids.get(email, ""))
+            data = saved.get("data") if saved else None
+            out.append({"email": email, "signed_in": email in ids,
+                        "progress": report_part(data) if isinstance(data, dict) else None,
+                        "saved_at": saved.get("updated_at") if saved else None})
+        return JSONResponse({"class": {"id": row["id"], "name": row["name"], "lessons": units_of(row)},
+                             "students": out}, headers={"Cache-Control": "no-store"})

app/main.py

@@ -1,6 +1,7 @@
 """Math-only HTTP service for the Mathly algebra path."""
 from __future__ import annotations
 
+import base64
 import logging
 import os
 import time
@@ -15,12 +16,15 @@ from fastapi.staticfiles import StaticFiles
 from starlette.concurrency import run_in_threadpool
 
 from . import ai_usage
+from .ai_queue import MAX_OPEN, for_student, install_ai_queue_routes, may_send
 from .access import has_permission, resolve_access
 from .answer_routes import install_answer_routes, open_ended_locked
+from .answer_scans import ScanError, clean_image
 from .auth import AuthUnavailable, ClassConflict, SupabaseAuth, load_auth
 from .math_photo import (DAILY_PHOTOS, MAX_PHOTO, MEDIA_TYPES as PHOTO_TYPES,
                          PhotoSolver, PhotoUnavailable, math_model, photo_client)
 from .math_skills import algebra9, practice_graph
+from .class_report import install_class_report_routes
 from .progress import install_progress_routes
 from .push import install_push_routes
 from .monitoring import ActionLog, RETURN_GAP, install_monitoring_routes
@@ -128,6 +132,12 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
                 "roles": (user or {}).get("roles", []),
                 "permissions": (user or {}).get("permissions", []),
                 "teacher": bool((user or {}).get("teacher")),
+                # the AI: this account sends to it itself (ai_direct), or asks its teacher (app/ai_queue.py);
+                # ai_review: it reviews students' requests
+                "ai_direct": may_send(user),
+                "ai_review": bool(user) and may_send(user) and (
+                    has_permission(user, "management.access")
+                    or any(email.lower() in (row.get("teachers") or []) for row in mine)),
                 "classes": [{"id": row["id"], "name": row["name"], "lessons": units_of(row),
                              "exams": row.get("exams") or [], "exam_note": row.get("exam_note") or "",
                              "exam_title": row.get("exam_title") or "",
@@ -157,9 +167,12 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
         raw = body.get("emails", "")
         parts = raw.replace(",", " ").split() if isinstance(raw, str) else raw
         emails = sorted({str(part).strip().lower() for part in parts if str(part).strip()})
+        # the class's teacher is one of its students (or none yet)
+        teachers = sorted({str(t).strip().lower() for t in body.get("teachers") or [] if str(t).strip()})
+        if len(teachers) > 1 or not set(teachers) <= set(emails):
+            raise HTTPException(400, "choose one of the class's students as its teacher")
         try:
-            app.state.auth.save_class(class_id, name, emails, {}, selected,
-                                      teachers=body.get("teachers") or [])
+            app.state.auth.save_class(class_id, name, emails, {}, selected, teachers=teachers)
         except ClassConflict as exc:
             raise HTTPException(409, "a class with that name already exists") from exc
         except AuthUnavailable as exc:
@@ -201,10 +214,51 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
             app.state.photo_key = key
         return app.state.photo
 
+    # the teacher's AI queue sends a student's photo with this (app/ai_queue.py)
+    def solve_for_queue(image: bytes, media_type: str) -> dict:
+        try:
+            service = solver()
+        except HTTPException as exc:
+            raise PhotoUnavailable("פתרון מתמונה לא זמין כרגע.", "missing_key", "ANTHROPIC_API_KEY is not set") from exc
+        return service.solve(image, media_type)
+    app.state.solve_photo = solve_for_queue
+
     @app.post("/api/math/photo")
     async def solve_photo(photo: UploadFile = File(...), user: dict | None = Depends(signed_in)):
+        if not may_send(user):
+            return await ask_teacher(photo, user)
         return await solve_upload(photo, user)
 
+    async def ask_teacher(photo: UploadFile, user: dict):
+        """A student's photo waits in their teacher's AI queue; the teacher sends it to the AI."""
+        queue = app.state.ai_queue
+        if not queue.configured:
+            raise HTTPException(503, "עזרה בצילום אינה זמינה כרגע.")
+        counter = (user["email"].lower(), datetime.now(LOCAL_TZ).date().isoformat())
+        if photo.content_type not in PHOTO_TYPES:
+            raise HTTPException(415, "send a JPEG, PNG, or WebP image")
+        raw = await photo.read(MAX_PHOTO + 1)
+        if not raw:
+            raise HTTPException(400, "the image is empty")
+        if len(raw) > MAX_PHOTO:
+            raise HTTPException(413, "the image is too large")
+        if photo_counts.get(counter, 0) >= DAILY_PHOTOS:
+            raise HTTPException(429, "daily photo limit reached")
+        try:
+            if await run_in_threadpool(queue.open_count, user["id"]) >= MAX_OPEN:
+                raise HTTPException(429, "כבר יש לכם כמה בקשות שמחכות למורה. חכו שהמורה יענה עליהן.")
+            image = await run_in_threadpool(clean_image, raw, photo.content_type)   # also drops the photo's metadata
+            row = await run_in_threadpool(queue.add, {
+                "user_id": user["id"], "email": user["email"].lower(), "kind": "photo",
+                "image": base64.standard_b64encode(image).decode("ascii")})
+        except ScanError as exc:
+            if exc.code.endswith("image"):
+                raise HTTPException(415, "לא הצלחנו לקרוא את התמונה. צלמו שוב.") from exc
+            raise HTTPException(503, "עזרה בצילום אינה זמינה כרגע.") from exc
+        photo_counts[counter] = photo_counts.get(counter, 0) + 1
+        app.state.actions.record(user, "ai_request", "תרגיל מצולם")
+        return {"queued": True, "request": for_student(row), "left": DAILY_PHOTOS - photo_counts[counter]}
+
     async def solve_upload(photo: UploadFile, user: dict | None):
         service = solver()
         email = (user or {}).get("email", "").lower()
@@ -239,8 +293,10 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
         return {**result, "left": DAILY_PHOTOS - photo_counts.get(counter, 0) if counter else None}
 
     install_progress_routes(app, signed_in)
+    install_class_report_routes(app, signed_in, units_of)
     install_push_routes(app, signed_in)
     install_answer_routes(app, signed_in)
+    install_ai_queue_routes(app, signed_in)
     install_resource_routes(app, signed_in)
     install_science_routes(app)
     install_monitoring_routes(app, manager)

app/math_photo.py

@@ -26,7 +26,43 @@ MEDIA_TYPES = ("image/jpeg", "image/png", "image/webp")
 
 
 class PhotoUnavailable(Exception):
-    """The photo could not be solved; the message is for the student (Hebrew)."""
+    """The photo could not be solved; the message is for the student (Hebrew). `reason` names the cause for the
+    teacher's error details (see failure_reason), and `detail` is the technical line behind it."""
+
+    def __init__(self, message: str = "", reason: str = "", detail: str = ""):
+        super().__init__(message)
+        self.reason, self.detail = reason, detail
+
+
+def failure_reason(exc) -> tuple[str, str]:
+    """Why an Anthropic API call failed, as (reason, technical detail). The detail is the error's type, HTTP status
+    and the API's own short message, never the request (which holds a student's work)."""
+    import anthropic
+    status = getattr(exc, "status_code", None)
+    body = getattr(exc, "body", None)
+    said = body.get("error", {}).get("message") if isinstance(body, dict) and isinstance(body.get("error"), dict) else ""
+    message = " ".join(str(said or getattr(exc, "message", "") or exc).split())
+    low = message.lower()
+    if isinstance(exc, anthropic.AuthenticationError):
+        reason = "api_key_invalid"
+    elif isinstance(exc, anthropic.PermissionDeniedError):
+        reason = "permission"
+    elif isinstance(exc, anthropic.NotFoundError):
+        reason = "model_not_found"
+    elif isinstance(exc, anthropic.RateLimitError):
+        reason = "rate_limited"
+    elif isinstance(exc, anthropic.APIConnectionError):
+        reason = "no_connection"
+    elif "credit balance" in low or "billing" in low:
+        reason = "no_credit"
+    elif status == 529 or "overloaded" in low:
+        reason = "overloaded"
+    elif isinstance(exc, anthropic.BadRequestError):
+        reason = "bad_request"
+    else:
+        reason = "provider_error"
+    detail = type(exc).__name__ + (f" {status}" if status else "") + (f": {message[:200]}" if message else "")
+    return reason, detail
 
 
 def photo_schema(skill_ids: list[str]) -> dict:
@@ -84,27 +120,28 @@ class PhotoSolver:
             )
         except anthropic.RateLimitError as e:
             log.warning("math photo rate limited: %s", e)
-            raise PhotoUnavailable("עמוס כרגע. נסו שוב בעוד דקה.") from e
+            raise PhotoUnavailable("עמוס כרגע. נסו שוב בעוד דקה.", *failure_reason(e)) from e
         except anthropic.AuthenticationError as e:
             log.error("math photo: the API key was refused: %s", e)
-            raise PhotoUnavailable("פתרון מתמונה לא זמין כרגע (מפתח ה-API לא תקין).") from e
+            raise PhotoUnavailable("פתרון מתמונה לא זמין כרגע (מפתח ה-API לא תקין).", *failure_reason(e)) from e
         except anthropic.APIStatusError as e:
             log.warning("math photo: the API answered %s: %s", e.status_code, e.message)
-            raise PhotoUnavailable("פתרון מתמונה לא זמין כרגע. נסו שוב.") from e
+            raise PhotoUnavailable("פתרון מתמונה לא זמין כרגע. נסו שוב.", *failure_reason(e)) from e
         except anthropic.APIConnectionError as e:
             log.warning("math photo: no connection: %s", e)
-            raise PhotoUnavailable("אין חיבור כרגע. נסו שוב.") from e
+            raise PhotoUnavailable("אין חיבור כרגע. נסו שוב.", *failure_reason(e)) from e
         if res.stop_reason == "refusal":
             log.warning("math photo: the model declined (%s)", res.stop_details)
-            raise PhotoUnavailable("לא הצלחנו לפתור את התמונה הזו. נסו לצלם תרגיל אחר.")
+            raise PhotoUnavailable("לא הצלחנו לפתור את התמונה הזו. נסו לצלם תרגיל אחר.", "refused",
+                                   f"stop_reason=refusal ({res.model})")
         if res.stop_reason == "max_tokens":
-            raise PhotoUnavailable("הפתרון נקטע. נסו שוב.")
+            raise PhotoUnavailable("הפתרון נקטע. נסו שוב.", "incomplete", f"stop_reason=max_tokens ({res.model})")
         text = next((b.text for b in res.content if b.type == "text"), "")
         try:
             out = json.loads(text)
         except ValueError as e:
             log.warning("math photo: an answer that is not JSON: %r", text[:300])
-            raise PhotoUnavailable("לא הצלחנו לפתור את התרגיל. נסו שוב.") from e
+            raise PhotoUnavailable("לא הצלחנו לפתור את התרגיל. נסו שוב.", "bad_output", "the answer was not JSON") from e
         log.info("math photo: %s, %d+%d tokens", res.model, res.usage.input_tokens, res.usage.output_tokens)
         return {**out, "usage": usage_of(res)}   # the route pops "usage" and records it (ai_usage.py)
 

app/monitoring.py

@@ -27,7 +27,8 @@ LOCAL_TZ = ZoneInfo("Asia/Jerusalem")
 PERIODS = {"day": (15, 96), "week": (60, 168), "month": (24 * 60, 30)}
 SEEN_KEEP = 24 * 3600
 RETURN_GAP = 30 * 60  # a sign-in after this long away counts as a new visit
-ACTION_KINDS = frozenset({"visit", "photo", "answer_upload", "answer_graded", "class_saved", "class_deleted"})
+ACTION_KINDS = frozenset({"visit", "photo", "answer_upload", "answer_graded", "class_saved", "class_deleted",
+                          "ai_request", "ai_sent", "ai_failed", "ai_declined"})
 
 
 class ActionLog:

static/answer-scans.js

@@ -5,15 +5,41 @@ const esc=s=>String(s??"").replace(/[&<>"']/g,c=>({"&":"&amp;","<":"&lt;",">":"&
 const fmt=s=>esc(s).replace(/\$([^$]+)\$/g,'<span class="m">$1</span>');
 const states={waiting:"ממתינים לטלפון",confirmed:"ממתינים לטלפון",uploading:"מעלים את התשובה…",received:"התשובה התקבלה",failed:"ההעלאה נכשלה",expired:"בקשת הצילום פגה",superseded:"הבקשה הוחלפה",declined:"הבקשה נדחתה בטלפון"};
 const errors={expired:"בקשת הצילום פגה. צרו בקשה חדשה ונסו שוב.",superseded:"הבקשה הוחלפה. בחרו את הבקשה העדכנית.",upload_in_progress:"העלאה כבר מתבצעת. ממתינים לעדכון…",confirmation_required:"יש לאשר את בקשת הצילום תחילה.",invalid_upload:"ההעלאה הופסקה. נסו שוב.",question_changed:"השאלה השתנתה. רעננו את העמוד ופתחו אותה מחדש.",invalid_image:"לא ניתן לקרוא את התמונה. צלמו שוב.",image_too_large:"התמונה גדולה מדי. צלמו שוב.",unsupported_image:"בחרו תמונת JPEG, PNG או WebP.",answer_storage_unavailable:"שמירת תשובות אינה זמינה כרגע. נסו שוב מאוחר יותר.",sign_in_required:"יש להיכנס לאותו חשבון בשני המכשירים."};
-Object.assign(errors,{grading_unavailable:"בדיקת תשובות אינה זמינה כרגע באתר.",grading_failed:"הבדיקה נכשלה. התמונה נשמרה; אפשר לנסות שוב.",grading_interrupted:"הבדיקה הופסקה. אפשר לנסות שוב.",grading_limit:"הגעתם למכסת 20 הבדיקות היומית. נסו שוב מחר.",grading_busy:"כבר מתבצעות בדיקות בחשבון. נסו שוב בעוד רגע.",answer_required:"יש לצלם ולשלוח תשובה לפני הבדיקה."});
+Object.assign(errors,{grading_unavailable:"בדיקת תשובות אינה זמינה כרגע באתר.",grading_failed:"הבדיקה נכשלה. התמונה נשמרה; אפשר לנסות שוב.",grading_interrupted:"הבדיקה הופסקה. אפשר לנסות שוב.",grading_limit:"הגעתם למכסת 20 הבדיקות היומית. נסו שוב מחר.",grading_busy:"כבר מתבצעות בדיקות בחשבון. נסו שוב בעוד רגע.",answer_required:"יש לצלם ולשלוח תשובה לפני הבדיקה.",queue_unavailable:"שליחת תשובות לבדיקת המורה אינה זמינה כרגע.",request_taken:"המורה כבר טיפל בבקשה. רעננו את העמוד."});
+/* Why an AI check failed (the server's `reason`, app/math_photo.py: failure_reason), for the people who can fix it:
+   a teacher sending from the AI queue, or checking their own answer. Each is what happened and what to do. */
+const reasons={
+  missing_key:["חסר מפתח API בשרת","משתנה הסביבה ANTHROPIC_API_KEY לא מוגדר בשרת. הוסיפו אותו להגדרות השרת (Secrets או קובץ .env) והפעילו את השרת מחדש."],
+  api_key_invalid:["מפתח ה-API לא תקין","Anthropic דחתה את המפתח (401). בדקו שהערך של ANTHROPIC_API_KEY הועתק במלואו, ושהמפתח לא בוטל ב-Anthropic Console."],
+  permission:["אין הרשאה","למפתח ה-API אין הרשאה למודל או לפעולה הזו (403). בדקו את הרשאות המפתח וה-Workspace ב-Anthropic Console."],
+  model_not_found:["המודל לא נמצא","המודל שמוגדר בשרת (MATH_MODEL) לא קיים או לא זמין למפתח הזה (404). בדקו את שם המודל, או מחקו את MATH_MODEL כדי לחזור לברירת המחדל."],
+  no_credit:["נגמר הקרדיט","אין מספיק קרדיט בחשבון Anthropic. הוסיפו קרדיט ב-Anthropic Console, בעמוד Billing."],
+  rate_limited:["יותר מדי בקשות","הגעתם למגבלת הקצב של ה-API (429). חכו דקה ונסו שוב."],
+  overloaded:["שירות ה-AI עמוס","השרתים של Anthropic עמוסים כרגע. נסו שוב בעוד כמה דקות."],
+  no_connection:["אין חיבור ל-AI","השרת לא הצליח להתחבר ל-API של Anthropic (רשת או זמן המתנה ארוך מדי). בדקו את החיבור של השרת ונסו שוב."],
+  bad_request:["ה-API דחה את הבקשה","Anthropic החזירה שגיאה 400. הפרטים הטכניים למטה מסבירים למה."],
+  refused:["ה-AI סירב לבדוק","המודל סירב לענות על הבקשה הזו. אפשר לנסות שוב או לבקש מהתלמיד לצלם מחדש."],
+  incomplete:["הבדיקה נקטעה","ה-AI הפסיק לפני שסיים את הבדיקה. נסו שוב."],
+  bad_output:["תשובה לא תקינה מה-AI","ה-AI החזיר תשובה שלא עברה את בדיקות השרת, ולכן לא ניתן ציון. נסו שוב."],
+  provider_error:["שגיאה בשירות ה-AI","Anthropic החזירה שגיאה לא צפויה. נסו שוב, ואם זה חוזר, ראו את הפרטים הטכניים."],
+  server_error:["שגיאה בשרת שלנו","משהו נכשל בשרת של Mathly. הפרטים הטכניים למטה, וגם ביומן השגיאות בלשונית ניטור."],
+  answer_storage_unavailable:["האחסון לא זמין","לא הצלחנו לקרוא את התמונה השמורה. בדקו את Supabase או את MATHLY_ANSWER_BUCKET ו-HF_TOKEN."],
+  open_ended_locked:["שאלות פתוחות נעולות","בשרת מוגדר MATHLY_OPEN_ENDED_LOCKED=1. שנו ל-0 והפעילו מחדש כדי לאפשר בדיקה."]};
+// a "פירוט השגיאה" button that opens what happened, what to do, and the technical line; "" without a reason
+function errorDetails(reason,detail){
+  if(!reason&&!detail)return "";
+  const [title,say]=reasons[reason]||["שגיאה לא מוכרת","לא זיהינו את סוג השגיאה. הפרטים הטכניים למטה."];
+  return `<details class="mx-error-details"><summary>פירוט השגיאה</summary><p><b>${esc(title)}</b></p><p>${esc(say)}</p>${detail?`<code dir="ltr">${esc(detail)}</code>`:""}</details>`;
+}
 const verdicts={correct:"נכון! הפתרון מלא",partial:"פתרון נכון בחלקו",incorrect:"יש לתקן את הפתרון",unreadable:"לא ניתן לקרוא את התשובה",needs_review:"נדרשת הבהרה לפני מתן ציון"};
+let queued=false;   // a student: an answer is checked only after their teacher sends it to the AI (app/ai_queue.py)
 let api=null,account=null,epoch=0,question=null,inbox=false,inboxTimer=null,inboxPoll=null,capture=null,visibleRoot=null,onGraded=null;
 const handled=new Set();   // requests this phone already answered (photographed or declined): not shown again
 const live=(e)=>e===epoch&&!!account;
 async function json(url,options={}){
   const r=await api(url,{cache:"no-store",...options});
   const d=await r.json().catch(()=>({}));
-  if(!r.ok){if(r.status===401)reset();const error=Error(errors[d.detail]||"החיבור נקטע. נסו שוב.");error.status=r.status;error.code=d.detail;throw error;}
+  if(!r.ok){if(r.status===401)reset();const error=Error(errors[d.detail]||"החיבור נקטע. נסו שוב.");error.status=r.status;error.code=d.detail;error.reason=d.reason||"";error.detail=d.error_detail||"";throw error;}
   return d;
 }
 const post=(url,body={})=>json(url,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(body)});
@@ -28,7 +54,7 @@ function reset(){
   inbox=false;account=null;onGraded=null;PUSH_MODE="hidden";paintPush();document.querySelector(".mx-push-ask")?.remove();
 }
 function configure(options){
-  reset();api=options.api;account=options.enabled?options.account:null;visibleRoot=options.root;onGraded=options.onGraded;
+  reset();api=options.api;account=options.enabled?options.account:null;visibleRoot=options.root;onGraded=options.onGraded;queued=!!options.queued;
   if(!account)return;
   // The phone (the responsive app/PWA) watches for requests from the computer and pops them up.
   if(matchMedia("(max-width: 700px)").matches||navigator.maxTouchPoints){inbox=true;pollInbox(epoch);pushSync(epoch);}
@@ -223,11 +249,12 @@ async function pollQuestion(q){
 async function renderQuestion(q){
   if(!current(q))return;
   const r=q.result,s=r.scan,state=s?.state,received=!!r.attachment,g=r.grading;
-  const checking=q.grading||g?.state==="grading";
+  const checking=q.grading||g?.state==="grading", req=r.ai_request;
+  const waiting=!checking&&g?.state!=="completed"&&waitingTeacher(req);
   // while the phone has the request, its code and progress are in the phone box itself (phoneLive)
-  const statusText=checking?"בודקים את התשובה…":g?.state==="completed"?verdicts[g.result.verdict]:g?.state==="failed"?errors[g.error]||errors.grading_failed:!received&&phonePending(state)?"":states[state]||"כתבו את הפתרון על דף וצלמו אותו בטלפון.";
+  const statusText=checking?(q.grading&&queued?"שולחים למורה…":"בודקים את התשובה…"):waiting?"התשובה מחכה למורה":g?.state==="completed"?verdicts[g.result.verdict]:g?.state==="failed"?errors[g.error]||errors.grading_failed:!received&&phonePending(state)?"":states[state]||"כתבו את הפתרון על דף וצלמו אותו בטלפון.";
   // Rebuilding controls on every poll would steal focus and race a button click.
-  const signature=[state,s?.id,r.attachment?.id,g?.id,g?.state,r.grading_available].join(":");
+  const signature=[state,s?.id,r.attachment?.id,g?.id,g?.state,r.grading_available,req?.id,req?.state].join(":");
   if(q.signature!==signature){
     q.signature=signature;
     q.node.innerHTML=`<small>ניסיון ${esc(r.attempt.id.slice(0,8))}</small><p role="status" aria-live="polite">${esc(statusText)}</p>
@@ -289,20 +316,33 @@ function gradingPanel(r,checking){
       <small>בדיקה אוטומטית באמצעות AI. בדקו שהתמלול תואם למה שכתבתם.</small></section>`;
   }
   if(!r.grading_available&&!checking)return '<p>התמונה נשמרה כתשובה. בדיקה אוטומטית אינה זמינה כרגע באתר.</p>';
+  if(queued&&!checking){
+    const req=r.ai_request;
+    if(waitingTeacher(req))return '<p>התשובה נשלחה למורה. אחרי שהמורה יאשר את הבדיקה, התוצאה תופיע כאן.</p>';
+    if(req?.state==="declined")return `<p>המורה לא אישר את הבדיקה.${req.note?` <b>הערת המורה:</b> ${esc(req.note)}`:""}</p>
+      <button class="mx-btn" data-grade>שליחה מחדש למורה</button>`;
+    return `<p>${g?.state==="failed"||req?.state==="failed"?"הבדיקה נכשלה. אפשר לשלוח שוב למורה.":"שלחו את התשובה למורה, והמורה יעביר אותה לבדיקה."}</p>
+      <button class="mx-btn solid" data-grade>שליחה לבדיקת המורה</button>`;
+  }
   return `<p>התשובה נשלחת לבדיקה אוטומטית באמצעות AI.</p>
     <button class="mx-btn solid" data-grade ${checking?"disabled":""}>${checking?"בודקים את התשובה…":g?.state==="failed"?"ניסיון בדיקה נוסף":"בדיקת התשובה"}</button>`;
 }
+// the answer's request is in the teacher's queue (a failed send stays there for the teacher to try again)
+const waitingTeacher=req=>!!req&&["pending","sending","failed"].includes(req.state);
 async function checkAnswer(q,automatic=false){
   if(!current(q)||q.grading)return;
   q.grading=true;q.signature=null;await renderQuestion(q);schedule(q);
   try{
     const r=await post(`/api/math/answer-attempts/${q.result.attempt.id}/grade`,{automatic});
     if(!current(q))return;q.result=r;
-  }catch(error){if(current(q))q.gradeError=error.message;}
+  }catch(error){if(current(q))q.gradeError=error;}
   finally{
     if(current(q)){
       q.grading=false;q.signature=null;await renderQuestion(q);
-      if(q.gradeError){q.node.querySelector("[role=status]").textContent=q.gradeError;q.gradeError=null;}
+      if(q.gradeError){
+        const status=q.node.querySelector("[role=status]");status.textContent=q.gradeError.message;
+        status.insertAdjacentHTML("afterend",errorDetails(q.gradeError.reason,q.gradeError.detail));q.gradeError=null;
+      }
       schedule(q);
     }
   }
@@ -450,5 +490,5 @@ document.addEventListener("visibilitychange",()=>{
   if(question?.result)pollQuestion(question);
 });
 window.addEventListener("online",()=>{if(account&&inbox)pollInbox(epoch);if(question?.result)pollQuestion(question);});
-window.MathlyAnswers={configure,mountQuestion,closeQuestion,reset,phoneLive,forgetPush,pushButton,paintPush,togglePush};
+window.MathlyAnswers={errorDetails,configure,mountQuestion,closeQuestion,reset,phoneLive,forgetPush,pushButton,paintPush,togglePush};
 })();

static/guide.js

@@ -0,0 +1,124 @@
+/* The user guide: how to use the app, for students and for teachers.
+   A "?" button on the start screen (before and after sign-in) opens it as a dialog with a tab for each.
+   It stands alone, with its own styles, so it also works on the sign-in screen before math.css is loaded.
+   Other screens add the same button with MathlyGuide.button(). */
+(()=>{
+const STUDENT=[
+  ["🚪","כניסה ובחירת מקצוע",`<p>נכנסים עם חשבון Google של בית הספר. כדאי להיכנס תמיד עם <b>אותו חשבון</b> בכל מכשיר: ההתקדמות נשמרת בחשבון ועוברת בין המחשב לטלפון.</p>
+    <p>במסך <b>המקצועות שלי</b> בוחרים מקצוע כדי לפתוח את המסלול שלו. לכל מקצוע מופיעים גם המבחנים הקרובים של הכיתה.</p>`],
+  ["⭐","המסלול",`<p>כל יחידה היא קבוצת כוכבים, וכל כוכב הוא מיומנות. כל השיעורים פתוחים, והינשוף מסמן איפה <b>ממשיכים</b>.</p>
+    <ul><li>לוחצים על כוכב כדי לפתוח את המיומנות ולענות על השאלות שלה.</li>
+    <li>הכוכב נדלק כשעונים נכון על כל השאלות, והופך ל<b>זהב</b> אחרי כמה תשובות נכונות ברצף בניסיון הראשון.</li>
+    <li>כוכב שלא תרגלו שבועיים <b>דועך</b>. תשובה נכונה אחת מחזירה לו את האור.</li>
+    <li>תשובה שגויה לא מגלה את התשובה הנכונה. השאלה תחזור אחרי האחרות, ואפשר לנסות שוב.</li></ul>`],
+  ["🔥","היעד היומי והרצף",`<p>היעד היומי הוא 5 תשובות נכונות. מי שמגיע אליו כל יום בונה <b>רצף</b>. לוחצים על הלהבה כדי לראות את לוח הרצף של החודש.</p>`],
+  ["🔁","חזרה מעורבת ודפוסים שחוזרים",`<p><b>חזרה מעורבת</b> מופיעה בבית כשמיומנויות שכבר סיימתם צריכות חזרה: כמה שאלות מנושאים שונים, כדי שמה שלמדתם יישאר.</p>
+    <p><b>דפוסים שחוזרים</b> מראה טעות שחוזרת אצלכם בכמה נושאים, ואיזו מיומנות כדאי לחזק כדי שהיא תיעלם.</p>`],
+  ["📝","מבחן תרגול",`<p>12 שאלות מעורבבות מכמה יחידות, כמו במבחן אמיתי: שם הנושא לא מופיע ואין משוב באמצע. בוחרים אילו יחידות ייכנסו, ובסוף מקבלים ציון ותוכנית: מה לחזק עד המבחן. השעון רק מראה את הזמן, בלי לחץ.</p>`],
+  ["🧾","בוחן מסכם ליחידה",`<p>בסוף כל יחידה יש בוחן עם שאלות פתוחות ושעון שסופר לאחור.</p>
+    <ul><li>כותבים את הפתרונות על דף, כל שאלה בנפרד, עם דרך פתרון מלאה.</li>
+    <li>מצלמים את התשובה לכל שאלה: מהטלפון, מהמחשב (<b>צילום בטלפון</b> נותן קוד, ופותחים את האפליקציה בטלפון עם אותו חשבון), או פותרים ב<b>לוח</b> ומגישים ממנו.</li>
+    <li>כשהזמן לכתיבה נגמר יש עוד 10 דקות לצלם ולהגיש.</li>
+    <li>הבדיקה האוטומטית, הציון והפתרונות מגיעים אחרי ההגשה. הבדיקה יכולה לטעות: בדקו את התמלול שמוצג.</li></ul>`],
+  ["✏️","לוח טיוטה",`<p>הכפתור <b>לוח</b> בכל שאלה פותח דף לכתיבה: עט, קו ישר, עיגול, נוסחה מוקלדת ומחק. בטלפון הלוח נפתח במסך מלא, ו<b>חזרה לשאלה</b> מחזיר. גוללים עם שתי אצבעות או עם כלי ההזזה (כף היד). כפתור הלוח עם הדף (<b>השאלה</b>) מעתיק את השאלה לראש הדף.</p>`],
+  ["🔔","התראות בטלפון",`<p>כשהמחשב מבקש צילום של תשובה, הטלפון יכול לקבל התראה גם כשהאפליקציה סגורה. מפעילים אותה בכפתור הפעמון. באייפון זה עובד רק מהאפליקציה שהוספה למסך הבית.</p>`],
+  ["☄️","האוסף ושביטים",`<p>בלשונית <b>האוסף</b> רואים את כל הכוכבים וקבוצות הכוכבים שאספתם. לפעמים חולף על המסך שביט בזמן תרגול: מי שלוחץ עליו בזמן תופס אותו.</p>`],
+  ["🚀","מדעים: חידות בהצבעה",`<p>המורה פותח הצבעה ומציג על הלוח <b>קוד בן 4 ספרות</b>. נכנסים לחידה, מקלידים את הקוד ב<b>הצטרפות להצבעה</b> ומצביעים. אפשר לשנות הצבעה עד שהמורה בודק.</p>`],
+];
+const TEACHER=[
+  ["👩‍🏫","להיות מורה הכיתה",`<p>לכל כיתה יש מורה אחד. מנהל בוחר אותו ב<b>ניהול ← כיתות ← עריכה ← מורה הכיתה</b>, מתוך החשבונות של הכיתה. אחרי הבחירה מופיע למורה הכפתור <b>הכיתה שלי</b>.</p>`],
+  ["📊","דוח הכיתה",`<p><b>הכיתה שלי</b> פותח דוח על כל תלמיד:</p>
+    <ul><li>המיומנויות שסיים ביחידות של הכיתה.</li>
+    <li>הטעויות שחוזרות אצלו.</li>
+    <li>הציון ב<b>בוחן המסכם</b> של כל יחידה, ותוצאות <b>מבחני התרגול</b>.</li></ul>
+    <p>בראש הדוח מופיעות הטעויות הנפוצות בכל הכיתה, כדי לדעת מה כדאי לחזור עליו בשיעור. הנתונים של תלמיד מופיעים אחרי שנכנס לחשבון ותרגל.</p>`],
+  ["📷","משאבי שיעור",`<p>במסלול המתמטיקה, לוחצים על שם יחידה (או על <b>📷 משאבים</b> מתחתיה) כדי לפתוח את המשאבים של השיעור.</p>
+    <ul><li><b>📷 צילום תמונה</b>: מצלמים תרגיל או הסבר מהלוח או מהספר.</li>
+    <li>מסמנים את הסוג: <b>תרגיל חדש</b>, <b>הסבר תיאורטי</b> או <b>אחר</b>, ואפשר לכתוב לאיזה נושא הוא שייך.</li>
+    <li>רק מי שהוסיף תמונה (או מנהל) יכול למחוק אותה.</li></ul>
+    <p>בשלב זה המשאבים גלויים למורים בלבד.</p>`],
+  ["🚀","הצבעה כיתתית במדעים",`<p>במקצוע <b>מדעים</b> בוחרים חידה ולוחצים <b>פתיחת הצבעה לכיתה</b>. על המסך מופיע קוד בן 4 ספרות: מציגים אותו על הלוח והתלמידים מצטרפים איתו מהמכשירים שלהם.</p>
+    <ul><li>ההצבעות מוסתרות עד שלוחצים <b>בדיקה</b>. הטיל משוגר עם התשובה שרוב הכיתה בחרה.</li>
+    <li>בתיקו הטיל לא משוגר: התלמידים יכולים לשנות הצבעה, ובודקים שוב.</li>
+    <li><b>לחידה הבאה</b> ממשיך באותה הצבעה.</li></ul>`],
+  ["🗓️","מבחנים ותרגול לקראתם",`<p>לוח המבחנים של הכיתה מופיע לתלמידים במסך המקצועות ובמסלול. כשמבחן מתקרב, <b>מבחן התרגול</b> מכוון אליו ומציע את היחידות שנלמדו עד אז. כדאי להזכיר לתלמידים לעשות אותו בשבוע שלפני המבחן.</p>`],
+  ["⚙️","ניהול (למנהלים)",`<p>הכפתור <b>ניהול</b> מופיע למי שיש לו הרשאה. שם יוצרים כיתות, מוסיפים תלמידים לפי כתובת דוא״ל (שורה לכל תלמיד), בוחרים יחידות ומקצועות, מגדירים לוח מבחנים ובוחרים את מורה הכיתה. כל כיתה פותחת לתלמידים שלה רק את היחידות שנבחרו לה. בלשונית המעקב רואים פעילות ושימוש.</p>`],
+];
+
+const css=`
+.mg-help{position:absolute;top:max(14px,env(safe-area-inset-top,0px));left:16px;width:44px;height:44px;border-radius:50%;
+  border:1px solid #7EE3C8;background:transparent;color:#7EE3C8;font:700 20px/1 system-ui,sans-serif;cursor:pointer;display:grid;place-items:center}
+.mg-help:hover,.mg-help:focus-visible{background:#163A36}
+.mg-help.inline{position:static;width:36px;height:36px;font-size:17px}
+.mg-scrim{position:fixed;inset:0;z-index:1100;background:rgb(3 5 14 / .78);display:flex;align-items:flex-end;justify-content:center}
+.mg-scrim[hidden]{display:none}
+.mg-box{direction:rtl;width:min(720px,100%);max-height:90vh;display:flex;flex-direction:column;background:#121B3B;color:#F2EFFF;
+  border:1px solid #27335F;border-radius:20px 20px 0 0;font:400 16px/1.6 "Rubik",system-ui,-apple-system,"Segoe UI",sans-serif;
+  padding-bottom:env(safe-area-inset-bottom,0px)}
+@media (min-width:760px){.mg-scrim{align-items:center}.mg-box{border-radius:20px;max-height:86vh}}
+.mg-head{display:flex;align-items:center;justify-content:space-between;gap:12px;padding:18px 20px 10px}
+.mg-head h2{margin:0;font:400 24px/1.2 "Secular One","Rubik",system-ui,sans-serif}
+.mg-x{border:1px solid #27335F;background:none;color:#9BA5CD;width:38px;height:38px;border-radius:50%;font-size:16px;cursor:pointer;flex:none}
+.mg-tabs{display:flex;gap:8px;padding:0 20px 12px;border-bottom:1px solid #27335F}
+.mg-tabs button{flex:1;border:1px solid #7EE3C8;background:transparent;color:#7EE3C8;font:700 15px/1 "Rubik",system-ui,sans-serif;padding:11px 12px;border-radius:999px;cursor:pointer}
+.mg-tabs button[aria-selected="true"]{background:#7EE3C8;color:#05231B}
+.mg-body{overflow:auto;padding:14px 20px 22px;overscroll-behavior:contain}
+.mg-body[hidden]{display:none}
+.mg-body details{border:1px solid #27335F;border-radius:14px;background:#18234A;margin-bottom:10px}
+.mg-body summary{display:flex;align-items:center;gap:10px;padding:13px 14px;cursor:pointer;font-weight:700;list-style:none}
+.mg-body summary::-webkit-details-marker{display:none}
+.mg-body summary::after{content:"‹";margin-inline-start:auto;color:#9BA5CD;transition:transform .15s}
+.mg-body details[open] summary::after{transform:rotate(-90deg)}
+.mg-body summary i{font-style:normal;font-size:20px;width:26px;text-align:center}
+.mg-body .mg-txt{padding:0 14px 12px 14px;color:#D9DDF2}
+.mg-body p{margin:0 0 8px}.mg-body ul{margin:0 0 8px;padding-inline-start:20px}.mg-body li{margin-bottom:4px}
+.mg-body b{color:#F2EFFF}
+.mg-intro{color:#9BA5CD;margin:0 0 12px}
+@media (max-width:420px){.mg-head,.mg-tabs,.mg-body{padding-inline:16px}}
+`;
+
+let scrim=null, back=null;
+const section=([icon,title,body],i)=>`<details${i===0?" open":""}><summary><i aria-hidden="true">${icon}</i><span>${title}</span></summary><div class="mg-txt">${body}</div></details>`;
+const style=document.createElement("style"); style.textContent=css; document.head.append(style);
+function build(){
+  scrim=document.createElement("div"); scrim.className="mg-scrim"; scrim.hidden=true;
+  scrim.innerHTML=`<div class="mg-box" role="dialog" aria-modal="true" aria-labelledby="mgTitle">
+    <div class="mg-head"><h2 id="mgTitle">איך משתמשים באפליקציה</h2><button class="mg-x" data-mg="close" aria-label="סגירת המדריך">✕</button></div>
+    <div class="mg-tabs" role="tablist">
+      <button role="tab" id="mgTabS" aria-controls="mgS" aria-selected="true" data-mg-tab="S">לתלמידים</button>
+      <button role="tab" id="mgTabT" aria-controls="mgT" aria-selected="false" data-mg-tab="T" tabindex="-1">למורים</button></div>
+    <div class="mg-body" id="mgS" role="tabpanel" aria-labelledby="mgTabS"><p class="mg-intro">מתרגלים במסלול, אוספים כוכבים ומתכוננים למבחנים. לחצו על נושא כדי לפתוח אותו.</p>${STUDENT.map(section).join("")}</div>
+    <div class="mg-body" id="mgT" role="tabpanel" aria-labelledby="mgTabT" hidden><p class="mg-intro">רואים איך הכיתה מתקדמת, שומרים חומרים לשיעור ומפעילים את הכיתה. לחצו על נושא כדי לפתוח אותו.</p>${TEACHER.map(section).join("")}</div></div>`;
+  document.body.append(scrim);
+  scrim.addEventListener("click",e=>{
+    if(e.target===scrim||e.target.closest("[data-mg=close]")) return close();
+    const tab=e.target.closest("[data-mg-tab]"); if(tab) pick(tab.dataset.mgTab);
+  });
+  scrim.addEventListener("keydown",e=>{
+    if(e.key==="Escape"){ e.stopPropagation(); return close(); }
+    if(e.target.matches("[data-mg-tab]")&&["ArrowLeft","ArrowRight"].includes(e.key)){
+      const to=e.target.dataset.mgTab==="S"?"T":"S"; pick(to); scrim.querySelector(`[data-mg-tab=${to}]`).focus();
+    }
+  });
+}
+function pick(which){
+  scrim.querySelectorAll("[data-mg-tab]").forEach(b=>{ const on=b.dataset.mgTab===which; b.setAttribute("aria-selected",on); b.tabIndex=on?0:-1; });
+  scrim.querySelector("#mgS").hidden=which!=="S"; scrim.querySelector("#mgT").hidden=which!=="T";
+}
+function open(which="S"){
+  if(!scrim) build();
+  back=document.activeElement; pick(which); scrim.hidden=false;
+  scrim.querySelector(".mg-x").focus({preventScroll:true});
+}
+function close(){ if(!scrim||scrim.hidden) return; scrim.hidden=true; back?.focus?.({preventScroll:true}); }
+
+const button=(cls="inline")=>`<button type="button" class="mg-help ${cls}" data-guide-open aria-label="מדריך שימוש" title="מדריך שימוש">?</button>`;
+// one listener for every "?" button, wherever a screen draws it (capture: before a screen's own handlers)
+document.addEventListener("click",e=>{ if(e.target.closest?.("[data-guide-open]")){ e.preventDefault(); open(); } },true);
+
+// the sign-in screen's button
+const boot=document.getElementById("boot");
+if(boot){ boot.style.position="relative"; boot.insertAdjacentHTML("afterbegin",button("")); }
+
+window.MathlyGuide={open,close,button};
+})();

static/index.html

@@ -24,6 +24,7 @@
   </main>
   <script>window.MATHLY={supabaseUrl:"__SUPABASE_URL__",supabaseKey:"__SUPABASE_KEY__",token:"",email:"",classes:[],permissions:[]};</script>
   <script src="https://cdn.jsdelivr.net/npm/@supabase/supabase-js@2"></script>
+  <script src="/static/guide.js"></script>
   <script src="/static/photo-image.js"></script>
   <script src="/static/answer-scans.js"></script>
   <script src="/static/math-tex.js"></script>

static/math-board.js

@@ -21,7 +21,27 @@ const setOn=on=>{ try{ localStorage.setItem(PREF,on?"on":"off"); }catch{} };
 
 const INKS=[["#1B2140","שחור"],["#2563D9","כחול"],["#D3455B","אדום"]];
 const ERASERS=[[16,"קטן"],[40,"בינוני"],[90,"גדול"]];
-const TOOLS=[["move","✋","הזזה"],["pen","✏️","עט"],["line","╱","קו ישר"],["circle","◯","עיגול"],["math","∑","נוסחה"],["eraser","🧽","מחק"]];
+const TOOLS=[["move","הזזה"],["pen","עט"],["line","קו ישר"],["circle","עיגול"],["math","נוסחה"],["eraser","מחק"]];
+/* one line-drawn icon set (24×24, the button's text colour), so every button looks alike on every device and
+   follows the button's hover and pressed colours; "flip" icons point the other way in a right-to-left page */
+const DOT='fill="currentColor" stroke="none"';
+const ICONS={
+  move:'<path d="M18 11V6.5a1.5 1.5 0 0 0-3 0V11M15 10V4.5a1.5 1.5 0 0 0-3 0V10M12 10V5.5a1.5 1.5 0 0 0-3 0V13M18 9.5a1.5 1.5 0 0 1 3 0V14a7 7 0 0 1-7 7h-1.5c-2.2 0-3.7-.8-5-2.1l-3.3-3.3a1.5 1.5 0 0 1 2.1-2.1L9 15.2"/>',
+  pen:'<path d="M4 20l1.2-4.2L16.5 4.5a2.1 2.1 0 0 1 3 3L8.2 18.8z"/><path d="M14.5 6.5l3 3"/>',
+  line:`<path d="M6 18L18 6"/><circle cx="6" cy="18" r="2" ${DOT}/><circle cx="18" cy="6" r="2" ${DOT}/>`,
+  circle:`<circle cx="12" cy="12" r="8"/><circle cx="12" cy="12" r="1.6" ${DOT}/>`,
+  math:'<path d="M17.5 5.5V4H6.5l6 8-6 8h11v-1.5"/>',
+  eraser:'<path d="M20 20H9.5M4.6 15.4l9.8-9.8a2 2 0 0 1 2.8 0l2.2 2.2a2 2 0 0 1 0 2.8L11 19H8.2l-3.6-3.6"/><path d="M9.5 10.5l5 5"/>',
+  question:'<rect x="5.5" y="5" width="13" height="16" rx="2"/><path d="M9 5V4a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1v1M9 11h6M9 15h4"/>',
+  undo:'<path d="M9 14L4 9l5-5"/><path d="M4 9h10.5a5.5 5.5 0 0 1 0 11H11"/>',
+  clear:'<path d="M4 7h16M10 11v6M14 11v6M6 7l1 12.2A2 2 0 0 0 9 21h6a2 2 0 0 0 2-1.8L18 7M9 7V4.5a1 1 0 0 1 1-1h4a1 1 0 0 1 1 1V7"/>',
+  close:'<path d="M6 6l12 12M18 6L6 18"/>',
+  send:'<path d="M12 15V4M7 9l5-5 5 5M5 15v4a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-4"/>',
+  done:'<path d="M5 12.5l4.5 4.5L19 7"/>',
+  back:'<path d="M19 12H5M11 6l-6 6 6 6"/>',
+  top:'<path d="M12 19V5M6 11l6-6 6 6"/>'};
+const FLIP=new Set(["undo","back"]);
+const ic=n=>`<svg class="mx-ic${FLIP.has(n)?" mx-ic-flip":""}" viewBox="0 0 24 24" aria-hidden="true">${ICONS[n]}</svg>`;
 const MATH_SIZE=26;
 const PEN=2.6, SHAPE=2.4, SNAP=12, GRAB=9, STEP=2, HISTORY=100;
 const PAPER_INK="#1B2140", PAPER_FAINT="#C5CBDF", SELECT="#2563D9";
@@ -49,21 +69,21 @@ const same=(a,b)=>dist(a,b)<.5;
 
 function build(){
   el=document.createElement("aside"); el.className="mx-board"; el.setAttribute("aria-label","לוח טיוטה");
-  el.innerHTML=`<div class="mx-board-head"><b data-title>לוח טיוטה</b><button type="button" data-do="hide" class="mx-board-back">↩ חזרה לשאלה</button></div>
+  el.innerHTML=`<div class="mx-board-head"><b data-title>לוח טיוטה</b><button type="button" data-do="hide" class="mx-board-back">${ic("back")}<span>חזרה לשאלה</span></button></div>
     <div class="mx-board-bar" role="toolbar" aria-label="כלי הלוח">
-      <span class="mx-board-group">${TOOLS.map(([t,icon,name])=>`<button type="button" data-tool="${t}" aria-pressed="${t===tool}" title="${name}"><i aria-hidden="true">${icon}</i><span>${name}</span></button>`).join("")}</span>
+      <span class="mx-board-group">${TOOLS.map(([t,name])=>`<button type="button" data-tool="${t}" aria-pressed="${t===tool}" title="${name}">${ic(t)}<span>${name}</span></button>`).join("")}</span>
       <span class="mx-board-group mx-board-inks">${INKS.map(([c,name])=>`<button type="button" data-ink="${c}" aria-pressed="${c===ink}" aria-label="${name}" title="${name}" style="--dot:${c}"></button>`).join("")}</span>
       <span class="mx-board-group mx-board-sizes">${ERASERS.map(([w,name])=>`<button type="button" data-eraser="${w}" aria-pressed="${w===eraser}" aria-label="מחק ${name}" title="מחק ${name}" style="--d:${Math.round(6+w/6)}px"></button>`).join("")}</span>
-      <span class="mx-board-gap"></span>
-      <button type="button" data-do="question" title="העתקת השאלה לראש הלוח"><i aria-hidden="true">📋</i><span>השאלה</span></button>
-      <button type="button" data-do="undo" title="ביטול (Ctrl+Z)"><i aria-hidden="true">↶</i></button>
-      <button type="button" data-do="clear" title="ניקוי הלוח"><i aria-hidden="true">🗑</i></button>
-      <button type="button" data-do="hide" aria-label="סגירת הלוח" title="סגירת הלוח">✕</button>
+      <span class="mx-board-group mx-board-acts">
+        <button type="button" data-do="question" title="העתקת השאלה לראש הלוח">${ic("question")}<span>השאלה</span></button>
+        <button type="button" data-do="undo" title="ביטול (Ctrl+Z)">${ic("undo")}<span>ביטול</span></button>
+        <button type="button" data-do="clear" title="ניקוי הלוח">${ic("clear")}<span>ניקוי</span></button></span>
+      <button type="button" data-do="hide" class="mx-board-close" aria-label="ס��ירת הלוח" title="סגירת הלוח">${ic("close")}</button>
     </div><div class="mx-board-row"><div class="mx-board-pages" role="tablist" aria-label="הדף של כל שאלה"></div>
       <button type="button" data-do="send" class="mx-board-send" hidden></button></div>
     <div class="mx-board-stage"><canvas></canvas>
-      <button type="button" data-do="delete" class="mx-board-del" title="מחיקת מה שנבחר (Delete)" hidden>✕ מחיקה</button>
-      <button type="button" data-do="top" class="mx-board-top" hidden>⇡ לראש הדף</button></div>`;
+      <button type="button" data-do="delete" class="mx-board-del" title="מחיקת מה שנבחר (Delete)" hidden>${ic("clear")}מחיקה</button>
+      <button type="button" data-do="top" class="mx-board-top" hidden>${ic("top")}לראש הדף</button></div>`;
   canvas=el.querySelector("canvas"); ctx=canvas.getContext("2d");
   el.addEventListener("click",e=>{
     const b=e.target.closest("button"); if(!b) return;
@@ -107,7 +127,7 @@ function select(list){ selection=list; }
 function turn(p){ if(editing) finishMath(true); page=p; key=`${base}:${page}`; reset(); drawPages(); drawSend(); paint(); }
 function drawSend(){
   const b=el.querySelector(".mx-board-send"); b.hidden=!hand; el.querySelector(".mx-board-row").hidden=pages<2&&!hand; if(!hand) return;
-  b.disabled=false; b.innerHTML=`<i aria-hidden="true">📤</i><span>${sendLabel||`הגשה לשאלה ${page+1}`}</span>`; b.title=sendLabel||`הגשת הלוח כתשובה לשאלה ${page+1}`;
+  b.disabled=false; b.innerHTML=`${ic("send")}<span>${sendLabel||`הגשה לשאלה ${page+1}`}</span>`; b.title=sendLabel||`הגשת הלוח כתשובה לשאלה ${page+1}`;
 }
 function drawPages(){
   const box=el.querySelector(".mx-board-pages"); el.querySelector(".mx-board-row").hidden=pages<2&&!hand;
@@ -427,7 +447,7 @@ async function send(){
   if(!blob){ say(`<span>הלוח ריק: אין מה להגיש</span>`); return setTimeout(()=>page===p&&drawSend(),2500); }
   b.disabled=true; say(`<span>מגישים…</span>`);
   let r; try{ r=await hand(p,blob); }catch(e){ r={error:e.message}; }
-  b.disabled=false; say(r?.error?`<span>⚠ ${r.error}</span>`:`<i aria-hidden="true">✓</i><span>${sendLabel?"נשלחה":`הוגשה לשאלה ${p+1}`}</span>`);
+  b.disabled=false; say(r?.error?`<span>⚠ ${r.error}</span>`:`${ic("done")}<span>${sendLabel?"נשלחה":`הוגשה לשאלה ${p+1}`}</span>`);
   if(r?.close&&full) return setTimeout(closeFull,900);   // done: back to the window that asked
   setTimeout(()=>page===p&&!b.disabled&&drawSend(),3000);
 }
@@ -481,7 +501,7 @@ function openFull({host,key:k,pages:n=1,page:p=0,question=null,submit=null,turne
   el.querySelector("[data-title]").textContent=title;
   el.classList.add("full"); el.setAttribute("role","dialog"); el.setAttribute("aria-modal","true");
   reset(); drawPages(); drawSend(); host.append(el); fit();
-  el.querySelector(".mx-board-back").focus({preventScroll:true});
+  el.querySelector(".mx-board-back").focus({preventScroll:true,focusVisible:false});   // reachable by keyboard, without a ring on a tap
 }
 function closeFull(){
   if(!full) return; if(editing) finishMath(true); const f=full; full=null;
@@ -490,7 +510,7 @@ function closeFull(){
   if(layer?.isConnected&&desk()) again();
 }
 // the header's switch: beside the exercise on a desktop screen, full screen on a phone
-const button=()=>`<button class="mx-board-btn" data-board-toggle aria-pressed="${isOn()&&desk()}" title="לוח טיוטה">✏️ לוח</button>`;
+const button=()=>`<button class="mx-board-btn" data-board-toggle aria-pressed="${isOn()&&desk()}" title="לוח טיוטה">${ic("pen")}<span>לוח</span></button>`;
 
 window.MathlyBoard={button,mount,toggle,show,openFull,closeFull,isOn};
 })();

static/math.css

@@ -50,6 +50,14 @@ html.math-on, html.math-on body{overflow:hidden}
 .mx-subject-icon{flex:none;width:46px;height:46px;border-radius:14px;display:grid;place-items:center;background:color-mix(in srgb,var(--exam) 22%,var(--bg));color:var(--exam);font:700 24px/1 var(--f-body)}
 .mx-subject-card>span:nth-child(2){display:flex;flex:1;flex-direction:column;gap:4px;min-width:0}.mx-subject-card b{font-size:18px}.mx-subject-card small{color:var(--muted);font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.mx-subject-card i{color:var(--exam);font-size:26px;font-style:normal}
 .mx-subject-empty{--exam:var(--mx-accent);display:flex;flex-direction:column;align-items:center;gap:10px;text-align:center;border:1px solid color-mix(in srgb,var(--exam) 45%,var(--line));border-radius:18px;background:var(--surface);padding:32px 20px}.mx-subject-empty>span{font-size:42px}.mx-subject-empty h2{color:var(--exam)}.mx-subject-empty p{max-width:480px;margin:0;color:var(--muted);line-height:1.5}
+.mx-subject-left{display:flex;align-items:center;gap:6px}
+.mx-subject-dots{display:inline-flex;gap:3px;flex:none}.mx-subject-dots>span{width:8px;height:8px;border-radius:50%;background:var(--exam)}.mx-subject-dots>span.past{background:transparent;box-shadow:inset 0 0 0 1.5px color-mix(in srgb,var(--exam) 55%,var(--line))}
+.mx-subject-bar{display:block;height:6px;border-radius:99px;background:color-mix(in srgb,var(--exam) 28%,var(--line));overflow:hidden;margin-top:2px}.mx-subject-bar>span{display:block;height:100%;border-radius:inherit;background:var(--exam)}
+.mx-subject-count{flex:none;display:flex;flex-direction:column;align-items:center;min-width:48px;padding:6px 8px;border-radius:12px;background:color-mix(in srgb,var(--exam) 14%,var(--bg));line-height:1.1}
+.mx-subject-card .mx-subject-count b{font:700 22px/1.1 var(--f-display)}.mx-subject-card .mx-subject-count small{font-size:11px}
+.mx-subject-count.soon{background:var(--amber-bg);color:var(--amber)}.mx-subject-count.urgent{background:var(--sumac-bg);color:var(--sumac)}
+.mx-subject-count.soon small,.mx-subject-count.urgent small{color:inherit}
+.mx-subject-card.is-over{opacity:.55;filter:saturate(.4)}.mx-subject-card.is-over:hover{opacity:.8}
 @media (max-width:520px){.mx-subject-grid{grid-template-columns:1fr}}
 
 /* a skill's sheet */
@@ -211,6 +219,7 @@ html.math-on, html.math-on body{overflow:hidden}
 .mx-class-form label>small,.mx-class-form legend small{display:block;color:var(--muted);font-size:12px;font-weight:500;margin-top:3px}
 .mx-class-form input[type="text"],.mx-class-form input[name="name"],.mx-class-form textarea{box-sizing:border-box;width:100%;border:1px solid var(--line);border-radius:10px;background:var(--bg);color:var(--ink);padding:11px 12px;font:inherit}
 .mx-class-form textarea{min-height:110px;resize:vertical;text-align:left}
+.mx-class-form select{box-sizing:border-box;width:100%;border:1px solid var(--line);border-radius:10px;background:var(--bg);color:var(--ink);padding:11px 12px;font:inherit;text-align:left}
 .mx-class-form fieldset{margin:0}
 .mx-subject-picks{--exam:var(--mx-accent);display:grid;grid-template-columns:repeat(auto-fill,minmax(170px,1fr));gap:8px}
 .mx-subject-picks label{display:flex;align-items:center;gap:10px;border:1px solid var(--line);border-radius:13px;padding:9px 10px;cursor:pointer}
@@ -661,7 +670,11 @@ button.sky-chip.flame{padding:6px 11px;color:var(--ink)}
 /* the sketch board beside a skill's exercise (static/math-board.js): a desktop screen with a mouse or a pen only */
 .mx-shacts{display:flex;align-items:center;gap:6px}
 .mx-board{display:none}   /* the buttons that open it show everywhere: beside the exercise on a desktop, full screen on a phone */
-.mx-board-btn{border:1px solid var(--line);background:none;color:var(--muted);font:700 14px/1 var(--f-body);padding:7px 12px;border-radius:999px;cursor:pointer}
+.mx-board-btn{display:inline-flex;align-items:center;gap:6px;border:1px solid var(--line);background:none;color:var(--muted);font:700 14px/1 var(--f-body);padding:7px 12px;border-radius:999px;cursor:pointer}
+.mx-board-btn .mx-ic{width:16px;height:16px}
+/* the board's icons: one line-drawn set in the button's own colour */
+.mx-ic{width:20px;height:20px;flex:none;fill:none;stroke:currentColor;stroke-width:1.8;stroke-linecap:round;stroke-linejoin:round}
+[dir="rtl"] .mx-ic-flip{transform:scaleX(-1)}   /* back and undo point to the start of a right-to-left line */
 .mx-board-btn[aria-pressed="true"]{border-color:var(--mx-accent);background:var(--mx-accent-soft);color:var(--ink)}
 @media (min-width:1000px) and (any-pointer:fine){
   .mx-sheet.with-board{inset:16px 16px 16px auto;width:min(600px,42vw);max-height:none;border-radius:20px}
@@ -669,20 +682,29 @@ button.sky-chip.flame{padding:6px 11px;color:var(--ink)}
     background:var(--surface);border:1px solid var(--line);border-radius:20px;overflow:hidden;box-shadow:0 6px 30px rgb(0 0 0/.25)}
 }
 .mx-board-bar{display:flex;align-items:center;gap:6px;padding:8px 10px;border-bottom:1px solid var(--line);flex-wrap:wrap}
-.mx-board-bar button{display:inline-flex;align-items:center;gap:5px;border:1px solid transparent;background:none;color:var(--muted);
-  font:500 14px/1 var(--f-body);padding:7px 10px;border-radius:10px;cursor:pointer;min-height:34px}
-.mx-board-bar button i{font-style:normal;font-size:16px;line-height:1}
+.mx-board-bar button{display:inline-flex;align-items:center;justify-content:center;gap:6px;border:1px solid transparent;background:none;color:var(--muted);
+  font:500 14px/1 var(--f-body);padding:0 7px;border-radius:10px;cursor:pointer;height:36px;min-width:36px}
 .mx-board-bar button:hover{color:var(--ink);background:var(--surface-2)}
 .mx-board-bar button[hidden]{display:none}
 .mx-board-bar button[aria-pressed="true"]{color:var(--ink);border-color:var(--mx-accent);background:var(--mx-accent-soft)}
 @media (max-width:1600px){.mx-board-bar button span{display:none}}   /* a narrower board: icons only, names stay as tooltips */
 .mx-board-group{display:inline-flex;align-items:center;gap:3px}
-.mx-board-inks,.mx-board-sizes{padding-inline:6px;border-inline-start:1px solid var(--line)}
-.mx-board-inks button,.mx-board-sizes button{width:34px;padding:0;justify-content:center}
-.mx-board-inks button::before{content:"";width:16px;height:16px;border-radius:50%;background:var(--dot);box-shadow:0 0 0 2px #fff}
-.mx-board-sizes button::before{content:"";width:var(--d);height:var(--d);border-radius:50%;border:1.5px solid currentColor}
-.mx-board:not([data-tool="eraser"]) .mx-board-sizes{display:none}   /* the sizes show with the eraser */
-.mx-board-gap{flex:1}
+/* the inks and the eraser's sizes sit on a strip of the paper's colour, so each ink shows as it will be drawn
+   (the black one too); the chosen one has a ring, not the tools' outline. The sizes take the inks' place with
+   the eraser, so the bar keeps its shape. */
+.mx-board-inks,.mx-board-sizes{background:#F8F7F2;border-radius:12px;padding:2px;gap:2px}
+.mx-board-bar .mx-board-inks button,.mx-board-bar .mx-board-sizes button{width:34px;min-width:0;height:32px;padding:0;border:0;border-radius:9px;background:none}
+.mx-board-bar .mx-board-inks button:hover,.mx-board-bar .mx-board-sizes button:hover{background:rgb(27 33 64/.08)}
+.mx-board-inks button::before,.mx-board-sizes button::before{content:"";border-radius:50%}
+.mx-board-inks button::before{width:18px;height:18px;background:var(--dot)}
+.mx-board-sizes button::before{width:var(--d);height:var(--d);background:#8A93B8}
+.mx-board-bar .mx-board-inks button[aria-pressed="true"],.mx-board-bar .mx-board-sizes button[aria-pressed="true"]{background:none}
+.mx-board-inks button[aria-pressed="true"]::before{box-shadow:0 0 0 2px #F8F7F2,0 0 0 4px #1B2140}
+.mx-board-sizes button[aria-pressed="true"]::before{background:#1B2140;box-shadow:0 0 0 2px #F8F7F2,0 0 0 4px #1B2140}
+.mx-board:not([data-tool="eraser"]) .mx-board-sizes,.mx-board[data-tool="eraser"] .mx-board-inks{display:none}
+.mx-board-acts{margin-inline-start:auto}   /* the page's actions at the far end, apart from the tools */
+.mx-board-bar .mx-board-close{position:relative;margin-inline-start:9px}   /* close, kept apart from clear by a line */
+.mx-board-close::before{content:"";position:absolute;inset-inline-start:-8px;top:8px;bottom:8px;width:1px;background:var(--line)}
 .mx-board-row{display:flex;align-items:center;gap:8px;padding:6px 10px;border-bottom:1px solid var(--line)}
 .mx-board-row[hidden]{display:none}
 .mx-board-pages{display:flex;align-items:center;gap:4px;flex:1;color:var(--muted);font-size:13px}
@@ -694,10 +716,13 @@ button.sky-chip.flame{padding:6px 11px;color:var(--ink)}
 .mx-board canvas{position:absolute;inset:0;width:100%;height:100%;display:block;touch-action:none;cursor:crosshair;
   background-color:#F8F7F2;background-image:linear-gradient(rgb(27 33 64/.07) 1px,transparent 1px),linear-gradient(90deg,rgb(27 33 64/.07) 1px,transparent 1px);
   background-size:28px 28px}
+.mx-board-del,.mx-board-top{display:inline-flex;align-items:center;gap:5px}
+.mx-board-del .mx-ic,.mx-board-top .mx-ic{width:16px;height:16px}
 .mx-board-del{position:absolute;z-index:1;border:1px solid #E7B3BB;background:#FFF1F3;color:#B4233A;font:700 13px/1 var(--f-body);
   padding:7px 11px;border-radius:999px;cursor:pointer;box-shadow:0 2px 8px rgb(27 33 64/.15)}
 .mx-board-del[hidden]{display:none}
 
+.mx-board-send .mx-ic{width:18px;height:18px}
 .mx-board-send{display:inline-flex;align-items:center;gap:6px;border:1px solid var(--mx-accent);background:var(--mx-accent);color:var(--mx-on-accent);
   font:700 14px/1 var(--f-body);padding:8px 14px;border-radius:999px;cursor:pointer}
 .mx-board-send[hidden]{display:none}
@@ -712,11 +737,11 @@ button.sky-chip.flame{padding:6px 11px;color:var(--ink)}
 .mx-board.full{display:flex;flex-direction:column;position:fixed;inset:0;z-index:1100;border:0;border-radius:0;box-shadow:none;background:var(--surface);
   padding:env(safe-area-inset-top,0px) env(safe-area-inset-right,0px) env(safe-area-inset-bottom,0px) env(safe-area-inset-left,0px)}
 .mx-board.full .mx-board-head{display:flex;align-items:center;justify-content:space-between;gap:10px;padding:8px 12px;border-bottom:1px solid var(--line);color:var(--ink)}
-.mx-board-back{border:1px solid var(--mx-accent);background:var(--mx-accent-soft);color:var(--ink);font:700 14px/1 var(--f-body);padding:9px 14px;border-radius:999px;cursor:pointer}
+.mx-board-back{display:inline-flex;align-items:center;gap:6px;border:1px solid var(--mx-accent);background:var(--mx-accent-soft);color:var(--ink);font:700 14px/1 var(--f-body);padding:9px 14px;border-radius:999px;cursor:pointer}
 .mx-board.full .mx-board-bar{flex-wrap:wrap;row-gap:4px}   /* every tool in sight: two rows on a phone rather than hidden off the edge */
-.mx-board.full .mx-board-gap{flex:0}
 .mx-board.full .mx-board-bar [data-do="hide"]{display:none}   /* the head's "back" does it */
-.mx-board.full .mx-board-bar button{min-height:40px;min-width:40px;justify-content:center}
+.mx-board.full .mx-board-bar button{height:40px;min-width:40px}
+.mx-board.full .mx-board-bar .mx-board-inks button,.mx-board.full .mx-board-bar .mx-board-sizes button{height:36px;width:40px}
 
 /* typing math on the board: a bar over the board's top; MathLive's keyboard sits above everything, the board too */
 body{--keyboard-zindex:3000}
@@ -727,3 +752,60 @@ body{--keyboard-zindex:3000}
 .mx-board-mathedit button{flex:none;width:40px;height:40px;border-radius:10px;border:1px solid #C5CBDF;background:#F4F6FC;color:#1B2140;font:700 18px/1 var(--f-body);cursor:pointer}
 .mx-board-mathedit button[data-math="ok"]{background:var(--mx-accent);border-color:var(--mx-accent);color:var(--mx-on-accent)}
 .mx-board-mathwait{flex:1;color:#5B6694;font:500 14px/1.3 var(--f-body);padding:8px}
+
+/* the class teacher's report (math.js: classReport) */
+.mx-report-tabs{display:flex;gap:6px;flex-wrap:wrap}
+.mx-report-tabs [aria-pressed="true"]{border-color:var(--mx-accent);color:var(--mx-accent)}
+.mx-report{display:flex;flex-direction:column;gap:10px}
+.mx-report h4{margin:10px 0 0;font-size:18px}
+.mx-report-common{border:1px solid var(--amber);border-radius:14px;background:var(--amber-bg);padding:14px 16px}
+.mx-report-common h4{margin:0 0 6px;color:var(--amber)}
+.mx-report-list{margin:0;padding-inline-start:18px;display:flex;flex-direction:column;gap:6px}
+.mx-report-list li small{display:block;color:var(--muted)}
+.mx-report-student{border:1px solid var(--line);border-radius:14px;background:var(--surface)}
+.mx-report-student>summary{display:flex;flex-wrap:wrap;align-items:center;gap:8px 12px;padding:12px 14px;cursor:pointer;list-style:none}
+.mx-report-student>summary::-webkit-details-marker{display:none}
+.mx-report-student>summary b{min-width:8ch}
+.mx-report-student[open]>summary{border-bottom:1px solid var(--line)}
+.mx-report-prog{display:flex;align-items:center;gap:8px;flex:1;min-width:150px}
+.mx-report-prog .mx-meter{flex:1;height:8px;background:var(--surface-2)}
+.mx-report-prog .mx-meter i{background:var(--aurora)}
+.mx-report-prog small{color:var(--muted);white-space:nowrap}
+.mx-report-chip{font:700 12px/1 var(--f-body);padding:5px 9px;border-radius:999px;background:var(--surface-2);color:var(--muted);white-space:nowrap}
+.mx-report-chip.good,.mx-report-grade.good{color:var(--ok)}.mx-report-chip.good{background:var(--ok-bg)}
+.mx-report-chip.mid,.mx-report-grade.mid{color:var(--amber)}.mx-report-chip.mid{background:var(--amber-bg)}
+.mx-report-chip.low,.mx-report-grade.low{color:var(--sumac)}.mx-report-chip.low{background:var(--sumac-bg)}
+.mx-report-body{display:flex;flex-direction:column;gap:16px;padding:14px}
+.mx-report-body h5{margin:0 0 8px;font-size:15px;color:var(--mx-accent)}
+.mx-report-body p{margin:0}
+.mx-report-table{width:100%;border-collapse:collapse;font-size:14px}
+.mx-report-table th{color:var(--muted);font-weight:400;text-align:start;padding:4px 6px;border-bottom:1px solid var(--line)}
+.mx-report-table td{padding:6px;border-bottom:1px solid var(--line)}
+.mx-report-grade{font-weight:700}
+@media (max-width:600px){.mx-report-prog{flex-basis:100%}.mx-report-table{font-size:13px}}
+
+/* the teacher's AI queue (math.js: aiQueue) */
+.mx-aq-badge{display:inline-block;min-width:1.6em;margin-inline-start:4px;padding:2px 6px;border-radius:999px;background:var(--sumac);color:#fff;font:700 12px/1.2 var(--f-body);text-align:center}
+.mx-aq{display:flex;flex-direction:column;gap:10px}
+.mx-aq-done{margin:10px 0 0;font-size:16px;color:var(--muted)}
+.mx-aq-card{display:flex;flex-direction:column;gap:8px;border:1px solid var(--line);border-radius:14px;background:var(--surface);padding:12px 14px}
+.mx-aq-card p{margin:0}
+.mx-aq-card.done,.mx-aq-card.declined,.mx-aq-card.cancelled{opacity:.8}
+.mx-aq-head{display:flex;flex-wrap:wrap;align-items:center;gap:6px 12px}
+.mx-aq-head small{color:var(--muted)}
+.mx-aq-state{margin-inline-start:auto;font:700 12px/1 var(--f-body);padding:5px 9px;border-radius:999px;background:var(--surface-2);color:var(--muted)}
+.mx-aq-card.pending .mx-aq-state{background:var(--amber-bg);color:var(--amber)}
+.mx-aq-card.done .mx-aq-state{background:var(--ok-bg);color:var(--ok)}
+.mx-aq-card.failed .mx-aq-state,.mx-aq-card.declined .mx-aq-state{background:var(--sumac-bg);color:var(--sumac)}
+.mx-aq-label{font-weight:700}
+.mx-aq-q{color:var(--muted);font-size:14px}
+.mx-aq-error{color:var(--sumac)}
+.mx-aq-img{max-width:100%;max-height:360px;object-fit:contain;border-radius:10px;border:1px solid var(--line);align-self:flex-start}
+/* "פירוט השגיאה": why an AI check failed (answer-scans.js: errorDetails) */
+.mx-error-details{align-self:flex-start;max-width:100%}
+.mx-error-details>summary{display:inline-flex;align-items:center;gap:6px;padding:6px 12px;border:1px solid var(--line);border-radius:999px;cursor:pointer;font:500 13px/1.2 var(--f-body);color:var(--sumac);list-style:none}
+.mx-error-details>summary::-webkit-details-marker{display:none}
+.mx-error-details>summary::before{content:"ⓘ"}
+.mx-error-details[open]>summary{border-color:var(--sumac)}
+.mx-error-details p{margin:8px 0 0}
+.mx-error-details code{display:block;margin-top:8px;padding:8px 10px;border-radius:8px;background:var(--surface-2);color:var(--muted);font-size:12px;white-space:pre-wrap;overflow-wrap:anywhere;text-align:left}

static/math.js

@@ -164,7 +164,8 @@ async function show(){
   if(remote){ try{ localStorage.setItem(key(),JSON.stringify(P)); }catch{} queuePush(); }   // this device's own work goes up too
   if(!P.set||typeof P.set!=="object") P.set={}; SHOWN=new Set(shownUnits().map(u=>u.id));
   hasExams()?drawSubjectPicker():selectSubject("מתמטיקה");   // no exams yet: straight to math, science is a tap away
-  window.MathlyAnswers?.configure({api,account:CFG.userId,enabled:CFG.answerScans,root,onGraded:({questionId,grading})=>{
+  if(CFG.aiReview) aqCount();
+  window.MathlyAnswers?.configure({api,account:CFG.userId,enabled:CFG.answerScans,root,queued:CFG.aiDirect===false,onGraded:({questionId,grading})=>{
     if(grading.result.verdict!=="correct"||P.done[questionId])return;
     const unitWas=unitDone(unitOf(questionId));
     P.done[questionId]=grading.finished_at||new Date().toISOString(); Sky.mastered(P,questionId);
@@ -185,16 +186,32 @@ function subjectOptions(){
     const item=bySubject.get(exam.subject)||{name:exam.subject,dates:[],classes:new Set()};
     item.dates.push(exam.date);item.classes.add(row.name);bySubject.set(exam.subject,item);
   }));
-  return [...bySubject.values()].map(item=>({...item,dates:item.dates.sort()})).sort((a,b)=>!a.dates.length-!b.dates.length||String(a.dates[0]||"").localeCompare(String(b.dates[0]||"")));
+  const today=new Date();today.setHours(0,0,0,0);
+  // first the subjects with an exam ahead (nearest first), then those with no exams yet, then those whose exams are over
+  return [...bySubject.values()].map(item=>{
+    const dates=item.dates.sort(), left=dates.filter(date=>examDate(date)>=today);
+    return {...item,dates,left,rank:left.length?0:dates.length?2:1};
+  }).sort((a,b)=>a.rank-b.rank||String(a.left[0]||"").localeCompare(String(b.left[0]||"")));
+}
+// the stars lit in a subject's units out of all its skills; null when the subject has no practice path here
+function subjectSkills(name){
+  const ids=mineUnits().filter(u=>u.subject===name).flatMap(u=>unitIds(u).filter(live));
+  return ids.length?{lit:ids.filter(id=>P.done[id]).length,total:ids.length}:null;
+}
+function subjectCard(item,today){
+  const [icon,tone]=examLooks[item.name]||["●","other"], count=item.dates.length, left=item.left.length, over=count>0&&!left;
+  const days=left?Math.round((examDate(item.left[0])-today)/86400000):null, skills=subjectSkills(item.name);
+  const dots=count&&count<=12?`<span class="mx-subject-dots" aria-hidden="true">${item.dates.map(date=>`<span${examDate(date)<today?' class="past"':""}></span>`).join("")}</span>`:"";
+  const exams=count?(over?"כל המבחנים הסתיימו":`נשארו ${left} מתוך ${count} מבחנים`):item.name==="מדעים"?"חידות בהצבעה כיתתית":"מסלול תרגול";
+  const bar=skills?`<span class="mx-subject-bar" role="progressbar" aria-label="מיומנויות שהושלמו" aria-valuemin="0" aria-valuemax="${skills.total}" aria-valuenow="${skills.lit}"><span style="width:${Math.round(100*skills.lit/skills.total)}%"></span></span><small>${skills.lit} מתוך ${skills.total} מיומנויות</small>`:"";
+  const when=days===null?"":`<span class="mx-subject-count${days<3?" urgent":days<7?" soon":""}" title="${esc(examFullDate(item.left[0]))}">${days===0?"<b>היום</b>":days===1?"<b>מחר</b>":`<small>בעוד</small><b>${days}</b><small>ימים</small>`}</span>`;
+  return `<button class="mx-subject-card exam-${tone}${over?" is-over":""}" data-subject="${esc(item.name)}"><span class="mx-subject-icon" aria-hidden="true">${icon}</span><span><b>${esc(item.name)}</b><small class="mx-subject-left">${dots}${exams}</small>${bar}</span>${when}<i aria-hidden="true">‹</i></button>`;
 }
 function drawSubjectPicker(){
   ACTIVE_SUBJECT=""; nav.hidden=true;
   const manage=can("management.access"), subjects=subjectOptions(), today=new Date();today.setHours(0,0,0,0);
-  path.innerHTML=`<header class="mx-top"><div><h1>המקצועות שלי</h1><p class="mx-sub">בחרו מקצוע כדי לפתוח את המסלול שלו</p></div><div class="mx-acts">${manage?'<button class="mx-btn" data-act="manage">ניהול</button>':""}${window.MathlyAnswers?.pushButton?.()||""}${AUTH_URL?'<button class="mx-btn" data-act="out">יציאה</button>':""}</div></header>
-    <section class="mx-subject-grid" aria-label="מקצועות הכיתה">${subjects.map(item=>{
-      const [icon,tone]=examLooks[item.name]||["●","other"],future=item.dates.find(date=>examDate(date)>=today),count=item.dates.length;
-      return `<button class="mx-subject-card exam-${tone}" data-subject="${esc(item.name)}"><span class="mx-subject-icon" aria-hidden="true">${icon}</span><span><b>${esc(item.name)}</b><small>${count?`${count} מבחנים${future?` · הבא ${examDay(future)}`:" · הסתיימו"}`:item.name==="מדעים"?"חידות בהצבעה כיתתית":"מסלול תרגול"}</small></span><i aria-hidden="true">‹</i></button>`;
-    }).join("")}</section>`;
+  path.innerHTML=`<header class="mx-top"><div><h1>המקצועות שלי</h1><p class="mx-sub">��חרו מקצוע כדי לפתוח את המסלול שלו</p></div><div class="mx-acts">${window.MathlyGuide?.button()||""}${teachButton()}${manage?'<button class="mx-btn" data-act="manage">ניהול</button>':""}${window.MathlyAnswers?.pushButton?.()||""}${AUTH_URL?'<button class="mx-btn" data-act="out">יציאה</button>':""}</div></header>
+    <section class="mx-subject-grid" aria-label="מקצועות הכיתה">${subjects.map(item=>subjectCard(item,today)).join("")}</section>`;
 }
 function selectSubject(subject){
   ACTIVE_SUBJECT=subject;
@@ -244,7 +261,7 @@ function nextExam(){
 function topBar(){
   const st=skyStats(), hot=Sky.today(P)>=Sky.GOAL, manage=can("management.access"), on=Sky.soundOn(), streak=Sky.streak(P);
   return `<header class="mx-top"><div class="mx-brand">${Sky.spark()}<span>מתמטיקה</span></div>
-    <div class="mx-acts"><button class="mx-btn" data-act="subjects">מקצועות</button>${manage?'<button class="mx-btn" data-act="manage">ניהול</button>':""}${window.MathlyAnswers?.pushButton?.()||""}${AUTH_URL?'<button class="mx-btn" data-act="out">יציאה</button>':""}</div></header>
+    <div class="mx-acts"><button class="mx-btn" data-act="subjects">מקצועות</button>${window.MathlyGuide?.button()||""}${teachButton()}${manage?'<button class="mx-btn" data-act="manage">ניהול</button>':""}${window.MathlyAnswers?.pushButton?.()||""}${AUTH_URL?'<button class="mx-btn" data-act="out">יציאה</button>':""}</div></header>
     <div class="mx-hud"><div class="mx-stats">
       <button class="sky-chip flame${hot?"":" cold"}" data-act="streak" title="${streak} ימים ברצף">${Sky.FLAME}<b>${streak}</b><span class="mx-sr">ימים ברצף</span></button>
       <span class="sky-chip stars" title="${st.lit} כוכבים">${Sky.spark()}<b>${st.lit}</b><span class="mx-sr">כוכבים</span></span>
@@ -448,7 +465,7 @@ function open(id){
   sheet.querySelector(".mx-x").focus({preventScroll:true});
   if(openEnded&&st!=="off")window.MathlyAnswers?.mountQuestion(sheet.querySelector(".mx-answer"),id,s.question_version);
 }
-function closeSheet(){ stopPhone(); dropResources(); cancelAdvance(); REV=null; stopQuizClock(); QZ=null; stopUnitQuiz(); if(sheet)sheet.hidden=true; cur=null; back?.focus?.({preventScroll:true}); back=null; }
+function closeSheet(){ stopPhone(); dropResources(); dropQueue(); cancelAdvance(); REV=null; stopQuizClock(); QZ=null; stopUnitQuiz(); if(sheet)sheet.hidden=true; cur=null; back?.focus?.({preventScroll:true}); back=null; }
 
 // counts down, then opens `target` (a skill id); stops if the student moved on in the meantime
 function autoAdvance(id,target){
@@ -969,7 +986,7 @@ async function uqResult(uid,h,check=false){
   sheet.innerHTML=`<div class="mx-scrim" data-act="close"></div>
     <div class="mx-sheet mx-uq-sheet u-${uid}" role="dialog" aria-modal="true" aria-labelledby="mxTitle">
       <div class="mx-shtop"><div><span class="mx-uchip">${esc(u.name)}</span><h3 id="mxTitle">בוחן מסכם: בודקים…</h3>
-        <small class="mx-src" aria-live="polite">בודקים את התשובות, זה לוקח כחצי דקה לשאלה</small></div>
+        <small class="mx-src" aria-live="polite">${CFG.aiDirect===false?"שולחים את התשובות לבדיקת המורה":"בודקים את התשובות, זה לוקח כחצי דקה לשאלה"}</small></div>
         <button class="mx-x" data-act="close" aria-label="סגירה">✕</button></div><div class="mx-uq-report"></div></div>`;
   sheet.hidden=false; sheet.querySelector(".mx-x").focus({preventScroll:true});
   const results=[];
@@ -979,7 +996,7 @@ async function uqResult(uid,h,check=false){
       r=await uqJson(`${UQ_BASE}/${entry.attempts[i]}`);
       if(r.attachment&&r.grading_available&&(!r.grading||(check&&r.grading.state==="failed"))){
         if(UQ?.uid!==uid) return;
-        sheet.querySelector(".mx-src").textContent=`בודקים את שאלה ${i+1} מתוך ${n}…`;
+        sheet.querySelector(".mx-src").textContent=CFG.aiDirect===false?`שולחים את שאלה ${i+1} מתוך ${n} למורה…`:`בודקים את שאלה ${i+1} מתוך ${n}…`;
         try{ r=await uqPost(`${UQ_BASE}/${entry.attempts[i]}/grade`,{automatic:!check}); }catch(e){ r.error=e.message; }
       }
       if(r.attachment){ const b=await api(`${UQ_BASE}/${entry.attempts[i]}/image`,{cache:"no-store"}); if(b.ok&&UQ?.uid===uid) UQ.images[i]=URL.createObjectURL(await b.blob()); }
@@ -994,7 +1011,8 @@ async function uqResult(uid,h,check=false){
     let pts=null, say="";
     if(!r?.attachment) { pts=0; say="לא צולמה תשובה"; }
     else if(a&&a.score!=null){ pts=Math.round(q.points*a.score/100); say={correct:"נכון ומלא",partial:"נכון בחלקו",incorrect:"לא נכון"}[a.verdict]||""; }
-    else { open++; say=a?.verdict==="unreadable"?"לא הצלחנו לקרוא את התמונה":a?.verdict==="needs_review"?"נדרשת בדיקה של מורה":r.error||(!r.grading_available?"הבדיקה האוטומטית אינה זמינה כרגע":"עוד לא נ��דקה"); }
+    else { open++; const req=a?null:r.ai_request;
+      say=req&&["pending","sending","failed"].includes(req.state)?"מחכה למורה שיאשר את הבדיקה":req?.state==="declined"?`המורה לא אישר את הבדיקה${req.note?`: ${req.note}`:""}`:a?.verdict==="unreadable"?"לא הצלחנו לקרוא את התמונה":a?.verdict==="needs_review"?"נדרשת בדיקה של מורה":r.error||(!r.grading_available?"הבדיקה האוטומטית אינה זמינה כרגע":"עוד לא נבדקה"); }
     if(pts!=null) earned+=pts;
     return `<li class="mx-uq-q"><div class="mx-uq-qhead"><b>שאלה ${i+1}</b><span>${pts==null?"–":pts}/${q.points} נק׳</span></div>
       <p class="mx-uq-text">${fmt(q.question).replace(/\n/g,"<br>")}</p>
@@ -1002,7 +1020,7 @@ async function uqResult(uid,h,check=false){
       <p class="mx-uq-verdict ${a?.verdict||"none"}">${esc(say)}</p>
       ${a?.feedback?`<p>${fmtLoose(a.feedback)}</p>`:""}${a?.next_step?`<p><b>הצעד הבא: </b>${fmtLoose(a.next_step)}</p>`:""}
       ${a?.solution?`<details><summary>הפתרון המלא</summary><p class="mx-grade-solution">${fmtLoose(a.solution)}</p></details>`:""}
-      ${r?.attachment&&!a&&r.grading_available?`<button class="mx-btn" data-uq-result="${uid}:${h}:check">בדיקה נוספת</button>`:""}</li>`;
+      ${r?.attachment&&!a&&r.grading_available&&!["pending","sending","failed"].includes(r.ai_request?.state)?`<button class="mx-btn" data-uq-result="${uid}:${h}:check">${CFG.aiDirect===false?"שליחה מחדש למורה":"בדיקה נוספת"}</button>`:""}</li>`;
   });
   entry.score=open?null:earned; save(); draw();
   const total=open?`${earned} נקודות עד עכשיו · ${open===1?"שאלה אחת לא נבדקה":`${open} שאלות לא נבדקו`}`:`${earned}/100`;
@@ -1033,8 +1051,15 @@ function onClick(e){
   if(t.dataset.id) return open(t.dataset.id);
   if(t.dataset.manageMode) return showManageMode(t.dataset.manageMode);
   if(t.dataset.classAction) return manageClassAction(t.dataset.classAction,t.dataset.classId);
+  if(t.dataset.reportClass!=null) return classReport(t.dataset.reportClass);
+  if(t.dataset.aqSend) return aqSend(t.dataset.aqSend);
+  if(t.dataset.aqDecline) return aqDecline(t.dataset.aqDecline);
   switch(t.dataset.act){
     case "manage": return manageClasses();
+    case "class-report": return classReport();
+    case "ai-queue": return aiQueue();
+    case "aq-all": return aqAll();
+    case "photo-cancel": return photoCancel();
     case "manage-refresh": return loadManagedClasses(true);
     case "manage-lab": return showManageMode("lab");
     case "manage-practice": return closeSheet();
@@ -1166,7 +1191,8 @@ function showManageMode(mode){
 /* Monitoring (ניטור): a snapshot of the system, open-answer activity, and the server's latest warnings.
    Each source loads and fails on its own, so a slow Supabase does not hold up the rest. */
 const MON_RANGES={day:["יום","24 השעות האחרונות","15 דקות"],week:["שבוע","7 הימים האחרונים","שעה"],month:["חודש","30 הימים האחרונים","יום"]};
-const MON_ACTIONS={visit:["👋","נכנס/ה לאפליקציה"],photo:["📷","צילם/ה תרגיל לעזרה"],answer_upload:["📝","שלח/ה תשובה פתוחה"],answer_graded:["✔️","תשובה נבדקה"],class_saved:["🏫","שמר/ה כיתה"],class_deleted:["🗑️","מחק/ה כיתה"],resource_added:["🖼️","הוסיף/ה תמונה למשאבי שיעור"]};
+const MON_ACTIONS={visit:["👋","נכנס/ה לאפליקציה"],photo:["📷","צילם/ה תרגיל לעזרה"],answer_upload:["📝","שלח/ה תשובה פתוחה"],answer_graded:["✔️","תשובה נבדקה"],class_saved:["🏫","שמר/ה כיתה"],class_deleted:["🗑️","מחק/ה כיתה"],resource_added:["🖼️","הוסיף/ה תמונה למשאבי שיעור"],
+  ai_request:["🙋","ביקש/ה בדיקת AI מהמורה"],ai_sent:["🤖","שלח/ה בקשה של תלמיד ל-AI"],ai_failed:["⚠️","שליחה ל-AI נכשלה"],ai_declined:["✋","דחה/תה בקשת AI"]};
 const VERDICTS={correct:"נכונות",partial:"נכונות חלקית",incorrect:"שגויות",unreadable:"לא קריאות",needs_review:"דורשות בדיקה",grading:"בבדיקה",failed:"הבדיקה נכשלה"};
 let MON={}, MON_RANGE=(()=>{try{return localStorage.getItem("mathly.monRange")}catch{return null}})();
 if(!MON_RANGES[MON_RANGE]) MON_RANGE="week";
@@ -1306,8 +1332,8 @@ function drawManagedClasses(box){
       const subjects=classSubjects(row);
       const unitLine=units.length===G.units.length?`כל היחידות (${G.units.length})`:units.map(unit=>unit.name).join(" · ")||"לא נבחרו";
       const students=row.emails||[], teachers=row.teachers||[];
-      return `<article class="mx-class-card"><div class="mx-class-card-head"><h5>${esc(row.name)}</h5><div class="mx-class-actions"><button class="mx-btn" data-class-action="edit" data-class-id="${esc(row.id)}">עריכה</button><button class="mx-btn danger" data-class-action="delete" data-class-id="${esc(row.id)}">מחיקה</button></div></div>
-        <dl><dt>יחידות</dt><dd>${esc(unitLine)}</dd><dt>מקצועות היחידות</dt><dd>${esc(subjects.join(" · ")||"לא הוגדרו")}</dd><dt>תלמידים</dt><dd>${students.length?`${students.length}: ${esc(students.join(" · "))}`:"עוד אין"}</dd><dt>מורים</dt><dd>${teachers.length?esc(teachers.join(" · ")):"עוד לא נבחרו"}</dd></dl>${examBoard(row)}</article>`;
+      return `<article class="mx-class-card"><div class="mx-class-card-head"><h5>${esc(row.name)}</h5><div class="mx-class-actions"><button class="mx-btn" data-class-action="report" data-class-id="${esc(row.id)}">מעקב</button><button class="mx-btn" data-class-action="edit" data-class-id="${esc(row.id)}">עריכה</button><button class="mx-btn danger" data-class-action="delete" data-class-id="${esc(row.id)}">מחיקה</button></div></div>
+        <dl><dt>יחידות</dt><dd>${esc(unitLine)}</dd><dt>מקצועות היחידות</dt><dd>${esc(subjects.join(" · ")||"לא הוגדרו")}</dd><dt>תלמידים</dt><dd>${students.length?`${students.length}: ${esc(students.join(" · "))}`:"עוד אין"}</dd><dt>מורה הכיתה</dt><dd dir="auto">${teachers.length?esc(teachers.join(" · ")):"עוד לא נבחר"}</dd></dl>${examBoard(row)}</article>`;
     }).join("")}</div>`:'<div class="mx-empty-class"><h5>עוד אין כיתות</h5><p>פתחו כיתה ראשונה, בחרו את יחידות הלימוד והוסיפו את כתובות התלמידים.</p></div>'}`;
 }
 
@@ -1318,6 +1344,7 @@ function manageClassAction(action,id){
   if(!row) return;
   if(action==="edit") return openClassEditor(row);
   if(action==="delete") return deleteManagedClass(row);
+  if(action==="report") return classReport(row.id);
 }
 
 function openClassEditor(row){
@@ -1333,7 +1360,7 @@ function openClassEditor(row){
         <p class="mx-note mx-no-subject">בחרו מקצוע כדי לראות את יחידות הלימוד שלו.</p>
         ${subjects.map(subject=>`<section class="mx-subject-units" data-subject-units="${esc(subject)}"><h6 class="mx-pick-subject">${esc(subject)}</h6><div class="mx-unit-picks">${subjectUnits(subject).map(unit=>{const skills=unitSkills(unit.id);return `<label class="u-${unit.id}"><input type="checkbox" name="unit" value="${esc(unit.id)}" data-subject="${esc(subject)}"${selected.has(unit.id)?" checked":""}><span>${esc(unit.name)}<small>${skills.length} תת־נושאים · ${questionCount(skills)} שאלות</small></span></label>`}).join("")}</div></section>`).join("")}</fieldset>
       <label>התלמידים<small>כתובת דוא״ל אחת בכל שורה. תלמיד יכול להשתייך ליותר מכיתה אחת.</small><textarea name="emails" dir="ltr" spellcheck="false" placeholder="student@example.com">${esc((row?.emails||[]).join("\n"))}</textarea></label>
-      <label>מורי הכיתה<small>כתובת דוא״ל אחת בכל שורה. למורים תהיה גישה לכיתה הזו.</small><textarea name="teachers" dir="ltr" spellcheck="false" placeholder="teacher@example.com">${esc((row?.teachers||[]).join("\n"))}</textarea></label>
+      <label>מורה הכיתה<small>אחד מתלמידי הכיתה. המורה רואה את ההתקדמות, הקשיים והציונים של כל התלמידים בכיתה.</small><select name="teacher" dir="ltr"></select></label>
       <div class="mx-class-form-actions"><button class="mx-btn solid" type="submit">${creating?"פתיחת הכיתה":"שמירת השינויים"}</button><button class="mx-btn" type="button" data-class-action="cancel">ביטול</button><span role="status" aria-live="polite"></span></div></form>`;
   const form=box.querySelector("form"), message=form.querySelector('[role="status"]');
   const unitBoxes=subject=>[...form.querySelectorAll('input[name="unit"]')].filter(input=>input.dataset.subject===subject);
@@ -1356,19 +1383,26 @@ function openClassEditor(row){
     if(input.name==="subject"||input.name==="unit") syncSubjects();
   });
   syncSubjects();
+  // the teacher is picked from the students: the list follows the students box as it is edited
+  const lines=name=>form.elements[name].value.split(/[\n,;]+/).map(value=>value.trim().toLowerCase()).filter(Boolean);
+  const pickTeacher=form.elements.teacher;
+  const syncTeacher=()=>{
+    const chosen=pickTeacher.options.length?pickTeacher.value:(row?.teachers||[])[0]||"", students=[...new Set(lines("emails"))];
+    pickTeacher.innerHTML=`<option value="">ללא מורה</option>${students.map(email=>`<option value="${esc(email)}"${email===chosen?" selected":""}>${esc(email)}</option>`).join("")}`;
+  };
+  form.elements.emails.addEventListener("input",syncTeacher); syncTeacher();
   form.querySelector('input[name="name"]').focus();
   form.onsubmit=async event=>{
     event.preventDefault();
     const lessons=[...form.querySelectorAll('input[name="unit"]:checked')].map(input=>input.value);
     if(!lessons.length){message.textContent="בחרו לפחות מקצוע אחד.";return;}
-    const lines=name=>form.elements[name].value.split(/[\n,;]+/).map(value=>value.trim().toLowerCase()).filter(Boolean);
-    const body={name:form.elements.name.value.trim(),emails:lines("emails"),teachers:lines("teachers"),lessons};
+    const body={name:form.elements.name.value.trim(),emails:lines("emails"),teachers:pickTeacher.value?[pickTeacher.value]:[],lessons};
     const buttons=form.querySelectorAll("button"); buttons.forEach(button=>button.disabled=true); message.textContent=creating?"פותחים את הכיתה…":"שומרים…";
     try{
       const response=await api(creating?"/api/classes":`/api/classes/${encodeURIComponent(row.id)}`,{method:creating?"POST":"PUT",headers:{"Content-Type":"application/json"},body:JSON.stringify(body)});
       if(!response.ok){const detail=(await response.json().catch(()=>({}))).detail;throw new Error(detail||"לא הצלחנו לשמור את הכיתה. נסו שוב.");}
       if(!creating){
-        Object.assign(row,body); MY_CLASSES.forEach(item=>{if(String(item.id)===String(row.id))Object.assign(item,body);});
+        Object.assign(row,body); MY_CLASSES.forEach(item=>{if(String(item.id)===String(row.id))Object.assign(item,body,{teacher:body.teachers.includes(ME_EMAIL.toLowerCase())});});
         if(String(MY_CLASS?.id)===String(row.id))Object.assign(MY_CLASS,body);
         SHOWN=new Set(shownUnits().map(unit=>unit.id)); draw();
       }
@@ -1390,6 +1424,190 @@ async function deleteManagedClass(row){
   }catch(error){state.textContent=error.message;}
 }
 
+/* ---------- the class teacher's report ----------
+   A class's teacher is one of its students, chosen in the class editor. That account (and a manager, from the class's
+   card) opens the class's report (/api/classes/{id}/report, app/class_report.py): each student's saved progress, read
+   the same way the student's own page reads it. It shows, per student, the skills finished in the class's units,
+   the mistakes that keep coming back (Sky.patterns), the summarizing quizzes' grades and the practice exams' results,
+   and above them the mistakes most common in the class. */
+const teachClasses=()=>MY_CLASSES.filter(row=>row.teacher);
+const teachButton=()=>(teachClasses().length?'<button class="mx-btn" data-act="class-report">הכיתה שלי</button>':"")
+  +(CFG.aiReview?`<button class="mx-btn" data-act="ai-queue">${aqLabel()}</button>`:"");
+let REPORT=null;
+const shortDate=at=>{ const d=new Date(at); return isNaN(d)?"":d.toLocaleDateString("he-IL",{day:"numeric",month:"numeric"}); };
+const pct=(a,b)=>b?Math.round(100*a/b):0;
+// one student's numbers, from their saved progress (null: nothing saved yet)
+function reportOf(student,units){
+  const p=student.progress; if(!p) return null;
+  const perUnit=units.map(u=>{ const ids=unitIds(u).filter(live); return {u,n:ids.length,done:ids.filter(id=>p.done?.[id]).length,
+    gold:ids.filter(id=>p.gold?.[id]).length,stuck:ids.filter(id=>!p.done?.[id]&&(p.missed?.[id]||[]).length).map(id=>BY[id])}; });
+  const n=perUnit.reduce((s,x)=>s+x.n,0), done=perUnit.reduce((s,x)=>s+x.done,0);
+  const {recurring}=Sky.patterns(p,G.mistakes);
+  const quizzes=units.filter(u=>u.quiz).map(u=>({u,st:p.uq?.[u.id]||{history:[]}}));
+  const scores=quizzes.map(x=>x.st.history.filter(h=>h.score!=null).at(-1)?.score).filter(s=>s!=null);
+  const exams=(p.quizzes||[]).slice().reverse();
+  const days=Object.keys(p.days||{}).sort(), last=[p.updated?new Date(+p.updated):null,days.length?new Date(days.at(-1)):null].filter(d=>d&&!isNaN(d)).sort((a,b)=>b-a)[0];
+  return {perUnit,n,done,recurring:recurring.filter(x=>G.mistakes[x.m]),quizzes,quizAvg:scores.length?Math.round(scores.reduce((a,b)=>a+b,0)/scores.length):null,exams,last};
+}
+async function classReport(id){
+  const mine=teachClasses(), classId=id??REPORT?.id??mine[0]?.id; if(classId==null) return;
+  if(!cur) back=document.activeElement;
+  closeSheetQuietly(); cur="report"; REPORT={id:classId,data:null};
+  const tabs=mine.length>1?`<div class="mx-report-tabs">${mine.map(row=>`<button class="mx-btn" data-report-class="${esc(row.id)}" aria-pressed="${String(row.id)===String(classId)}">${esc(row.name)}</button>`).join("")}</div>`:"";
+  sheet.innerHTML=`<div class="mx-scrim"></div>
+    <div class="mx-sheet mx-manage-sheet mx-report-sheet" role="dialog" aria-modal="true" aria-labelledby="mxTitle">
+      <div class="mx-manage-head"><h3 id="mxTitle">הכיתה שלי</h3><span class="mx-manage-spacer"></span>
+        <button class="mx-btn" data-report-class="${esc(classId)}">רענון</button><button class="mx-x" data-act="close" aria-label="סגירה">✕</button></div>
+      ${tabs}<p class="mx-manage-state" aria-live="polite">טוענים את נתוני הכיתה…</p><div class="mx-report"></div></div>`;
+  sheet.hidden=false; sheet.querySelector(".mx-x").focus({preventScroll:true});
+  try{
+    const r=await api(`/api/classes/${encodeURIComponent(classId)}/report`,{cache:"no-store"});
+    if(!r.ok) throw Error(r.status===403?"רק מורה הכיתה יכול לראות את הנתונים שלה.":"לא הצלחנו לטעון את נתוני הכיתה. נסו שוב.");
+    const data=await r.json(); if(cur!=="report"||REPORT?.id!==classId) return;
+    REPORT.data=data; drawReport();
+  }catch(e){ if(cur==="report") sheet.querySelector(".mx-manage-state").textContent=e.message; }
+}
+function closeSheetQuietly(){ const b=back; closeSheet(); back=b; }
+function drawReport(){
+  const {class:row,students}=REPORT.data, ids=new Set(row.lessons||[]);
+  const units=G.units.filter(u=>ids.has(u.id)&&unitIds(u).some(live));
+  const all=students.map(s=>({s,r:reportOf(s,units)}));
+  sheet.querySelector("#mxTitle").textContent=`הכיתה שלי: ${row.name}`;
+  sheet.querySelector(".mx-manage-state").textContent=`${students.length} תלמידים · ${all.filter(x=>x.r).length} התחילו לתרגל`;
+  // the mistakes that keep coming back for the most students
+  const common={}; all.forEach(({s,r})=>r?.recurring.forEach(x=>(common[x.m]||=[]).push(s.email)));
+  const top=Object.entries(common).sort((a,b)=>b[1].length-a[1].length).slice(0,5);
+  const name=email=>email.split("@")[0];
+  const quizUnits=units.filter(u=>u.quiz);
+  const grade=score=>score==null?"–":`${score}`;
+  const tone=score=>score==null?"":score>=80?" good":score>=55?" mid":" low";
+  const card=({s,r})=>{
+    if(!r) return `<details class="mx-report-student"><summary><b dir="ltr">${esc(name(s.email))}</b><span class="mx-small">${s.signed_in?"עוד לא התחיל לתרגל":"עוד לא נכנס לחשבון"}</span></summary><p class="mx-small" dir="ltr">${esc(s.email)}</p></details>`;
+    const exam=r.exams[0];
+    return `<details class="mx-report-student"><summary><b dir="ltr">${esc(name(s.email))}</b>
+        <span class="mx-report-prog"><span class="mx-meter" aria-hidden="true"><i style="width:${pct(r.done,r.n)}%"></i></span><small>${r.done}/${r.n} מיומנויות</small></span>
+        <span class="mx-report-chip${tone(r.quizAvg)}" title="ממוצע בחנים מסכמים">בוחן ${grade(r.quizAvg)}</span>
+        <span class="mx-report-chip${tone(exam?pct(exam.right,exam.n):null)}" title="מבחן התרגול האחרון">תרגול ${exam?`${exam.right}/${exam.n}`:"–"}</span>
+        ${r.recurring.length?`<span class="mx-report-chip low">${r.recurring.length} קשיים</span>`:""}</summary>
+      <div class="mx-report-body">
+        <p class="mx-small"><span dir="ltr">${esc(s.email)}</span>${r.last?` · פעילות אחרונה ${r.last.toLocaleDateString("he-IL")}`:""}</p>
+        <section><h5>התקדמות ביחידות</h5><div class="mx-quiz-units-score">${r.perUnit.map(x=>`<div><span>${esc(x.u.name)}${x.gold?` <small>· ${x.gold} זהב</small>`:""}</span><b>${x.done}/${x.n}</b><span class="mx-meter" aria-hidden="true"><i style="width:${pct(x.done,x.n)}%"></i></span></div>`).join("")}</div></section>
+        <section><h5>קשיים</h5>${r.recurring.length?`<ul class="mx-report-list">${r.recurring.map(x=>`<li><b>${fmt(G.mistakes[x.m].name)}</b> <small>${x.n} פעמים ב־${x.skills.length} מיומנויות, לאחרונה ${shortDate(x.last)}</small>${BY[x.practise]?`<small>לחזק: ${fmt(BY[x.practise].name)}</small>`:""}</li>`).join("")}</ul>`:'<p class="mx-small">אין טעויות שחוזרות לאחרונה.</p>'}
+          ${r.perUnit.some(x=>x.stuck.length)?`<p class="mx-small">מיומנויות עם שאלות שעוד לא נפתרו: ${r.perUnit.flatMap(x=>x.stuck).slice(0,8).map(sk=>fmt(sk.name)).join(" · ")}</p>`:""}</section>
+        <section><h5>בוחן מסכם</h5>${quizUnits.length?`<table class="mx-report-table"><thead><tr><th>יחידה</th><th>ציון אחרון</th><th>הגשות</th><th>תאריך</th></tr></thead><tbody>${r.quizzes.map(({u,st})=>{ const h=st.history.at(-1);
+            return `<tr><td>${esc(u.name)}</td><td class="mx-report-grade${tone(h?.score)}">${st.going?"בתהליך":h?(h.score==null?"ממתין לבדיקה":`${h.score}/100`):"–"}</td><td>${st.history.length||"–"}</td><td>${h?shortDate(h.at):"–"}</td></tr>`; }).join("")}</tbody></table>`:'<p class="mx-small">ליחידות של הכיתה אין בוחן מסכם.</p>'}</section>
+        <section><h5>מבחני תרגול</h5>${r.exams.length?`<table class="mx-report-table"><thead><tr><th>תאריך</th><th>ציון</th><th>תשובות נכונות</th><th>זמן</th></tr></thead><tbody>${r.exams.slice(0,10).map(q=>`<tr><td>${shortDate(q.at)}</td><td class="mx-report-grade${tone(pct(q.right,q.n))}">${pct(q.right,q.n)}</td><td>${q.right}/${q.n}</td><td>${q.ms?`${Math.round(q.ms/60000)} דק׳`:"–"}</td></tr>`).join("")}</tbody></table>`:'<p class="mx-small">עוד לא נעשו מבחני תרגול.</p>'}</section>
+      </div></details>`;
+  };
+  sheet.querySelector(".mx-report").innerHTML=`
+    ${top.length?`<section class="mx-report-common"><h4>קשיים נפוצים בכיתה</h4><ul class="mx-report-list">${top.map(([m,who])=>`<li><b>${fmt(G.mistakes[m].name)}</b> <small>${who.length} תלמידים: ${who.map(e=>esc(name(e))).join(", ")}</small></li>`).join("")}</ul></section>`:""}
+    <h4>תלמידים</h4>${students.length?all.map(card).join(""):'<p class="mx-note">אין עדיין תלמידים בכיתה.</p>'}`;
+}
+
+/* ---------- the teacher's AI queue (app/ai_queue.py) ----------
+   A student does not call the AI. Their answer to check (or a photographed problem) waits here for their class's
+   teacher, who looks at the photo and sends it to the AI or declines it with a note. The student's page shows the
+   result. A manager sees every class's requests. */
+let AQ=null, AQ_OPEN=null;   // AQ: the queue on the sheet; AQ_OPEN: how many requests wait (for the header button)
+const AQ_KIND={photo:"📷 תרגיל לעזרה",grading:"📝 בדיקת תשובה"};
+const AQ_STATE={pending:"ממתינה",sending:"נשלחת…",done:"נשלחה ל-AI",failed:"השליחה נכשלה",declined:"נדחתה",cancelled:"בוטלה"};
+const AQ_ERR={grading_failed:"הבדיקה נכשלה. אפשר לנסות שוב.",grading_unavailable:"בדיקה אוטומטית אינה זמינה כרגע באתר.",open_ended_locked:"שאלות פתוחות נעולות כרגע.",
+  grading_limit:"התלמיד הגיע למכסת הבדיקות היומית.",grading_busy:"כבר מתבצעות בדיקות לתלמיד הזה. נסו שוב בעוד רגע.",grading_interrupted:"הבדיקה הופסקה. אפשר לנסות שוב.",
+  request_taken:"הבקשה כבר טופלה (אולי ממכשיר אחר). רעננו את התור.",queue_unavailable:"התור אינו זמין כרגע.",
+  answer_storage_unavailable:"לא הצלחנו לקרוא את התמונה השמורה.",photo_failed:"פתרון התמונה נכשל. אפשר לנסות שוב."};
+// a failed send's error is "code|reason|technical detail" (app/ai_queue.py)
+function aqError(error){
+  const [code,reason="",...rest]=String(error||"").split("|"), detail=rest.join("|");
+  return `<p class="mx-aq-error">${esc(AQ_ERR[code]||code||"השליחה נכשלה.")}</p>${window.MathlyAnswers?.errorDetails?.(reason,detail)||""}`;
+}
+const AQ_VERDICT={correct:"נכונה",partial:"נכונה חלקית",incorrect:"שגויה",unreadable:"לא קריאה",needs_review:"דורשת בדיקה שלכם"};
+const aqWaiting=r=>["pending","sending","failed"].includes(r.state);
+const aqLabel=()=>`תור AI${AQ_OPEN?` <span class="mx-aq-badge">${AQ_OPEN}</span>`:""}`;
+function aqBadge(rows){
+  AQ_OPEN=rows.filter(r=>r.state==="pending").length;
+  document.querySelectorAll('[data-act="ai-queue"]').forEach(b=>{ if(!b.closest(".mx-sheet")) b.innerHTML=aqLabel(); });
+}
+async function aqCount(){
+  try{ const r=await api("/api/ai-queue",{cache:"no-store"}); if(r.ok) aqBadge((await r.json()).requests||[]); }catch{}
+}
+function dropQueue(){ if(AQ) Object.values(AQ.urls).forEach(u=>u&&URL.revokeObjectURL(u)); AQ=null; }
+async function aiQueue(){
+  if(cur!=="aiqueue"){ if(!cur) back=document.activeElement; closeSheetQuietly(); cur="aiqueue"; AQ={rows:null,urls:{},busy:new Set()}; }
+  const mine=AQ;
+  sheet.innerHTML=`<div class="mx-scrim"></div>
+    <div class="mx-sheet mx-manage-sheet mx-aq-sheet" role="dialog" aria-modal="true" aria-labelledby="mxTitle">
+      <div class="mx-manage-head"><h3 id="mxTitle">תור AI</h3><span class="mx-manage-spacer"></span>
+        <button class="mx-btn" data-act="aq-all" hidden>שליחת כל הממתינות</button><button class="mx-btn" data-act="ai-queue">רענון</button><button class="mx-x" data-act="close" aria-label="סגירה">✕</button></div>
+      <p class="mx-small">בקשות התלמידים מחכות כאן. הסתכלו בתמונה, ואז שלחו אותה ל-AI או דחו אותה. התלמיד רואה את התוצאה בעמוד שלו.</p>
+      <p class="mx-manage-state" aria-live="polite">טוענים את הבקשות…</p><div class="mx-aq"></div></div>`;
+  sheet.hidden=false; sheet.querySelector(".mx-x").focus({preventScroll:true});
+  try{
+    const r=await api("/api/ai-queue",{cache:"no-store"});
+    if(!r.ok) throw Error(r.status===403?"רק מורה של כיתה יכול לראות את התור.":"לא הצלחנו לטעון את התור. נסו שוב.");
+    const d=await r.json(); if(AQ!==mine) return;
+    mine.rows=d.requests||[]; drawQueue();
+  }catch(e){ if(AQ===mine) sheet.querySelector(".mx-manage-state").textContent=e.message; }
+}
+function aqResult(r){
+  const x=r.result||{};
+  if(r.kind==="photo") return x.readable===false?"ה-AI לא הצליח לקרוא את התרגיל.":`התשובה שה-AI מצא: ${fmtLoose(x.answer||"")}`;
+  return `תוצאה: ${esc(AQ_VERDICT[x.verdict]||"")}${x.score==null?"":` · ${esc(x.score)}/100`}`;
+}
+function drawQueue(){
+  const box=sheet.querySelector(".mx-aq"); if(!box||!AQ?.rows) return;
+  const open=AQ.rows.filter(aqWaiting), rest=AQ.rows.filter(r=>!aqWaiting(r));
+  aqBadge(AQ.rows);
+  sheet.querySelector(".mx-manage-state").textContent=open.length?(open.length===1?"בקשה אחת ממתינה":`${open.length} בקשות ממ��ינות`):"אין בקשות ממתינות.";
+  sheet.querySelector('[data-act="aq-all"]').hidden=open.filter(r=>r.state==="pending").length<2;
+  const when=at=>new Date(at).toLocaleString("he-IL",{dateStyle:"short",timeStyle:"short"});
+  const card=r=>{
+    const busy=AQ.busy.has(r.id), act=r.state==="pending"||r.state==="failed";
+    return `<article class="mx-aq-card ${esc(r.state)}"><div class="mx-aq-head"><b dir="ltr">${esc(String(r.email).split("@")[0])}</b><span>${AQ_KIND[r.kind]||""}</span>
+        <small>${when(r.created_at)}</small><span class="mx-aq-state">${busy?"שולחים ל-AI…":AQ_STATE[r.state]||esc(r.state)}</span></div>
+      ${r.label?`<p class="mx-aq-label">${fmt(r.label)}</p>`:""}${r.question?`<p class="mx-aq-q">${fmtLoose(r.question).replace(/\n/g,"<br>")}</p>`:""}
+      ${aqWaiting(r)?`<img class="mx-aq-img" alt="התמונה ששלח התלמיד" data-aq-img="${esc(r.id)}" hidden>`:""}
+      ${r.state==="failed"&&r.error?aqError(r.error):""}
+      ${r.state==="declined"&&r.note?`<p class="mx-small">ההערה שלכם: ${esc(r.note)}</p>`:""}
+      ${r.state==="done"?`<p class="mx-small">${aqResult(r)}</p>`:""}
+      ${act?`<div class="mx-row"><button class="mx-btn solid" data-aq-send="${esc(r.id)}"${busy?" disabled":""}>${r.state==="failed"?"שליחה חוזרת ל-AI":"שליחה ל-AI"}</button>
+        <button class="mx-btn" data-aq-decline="${esc(r.id)}"${busy?" disabled":""}>דחייה</button></div>`:""}</article>`;
+  };
+  box.innerHTML=`${open.map(card).join("")}${rest.length?`<h4 class="mx-aq-done">טופלו ביממה האחרונה</h4>${rest.map(card).join("")}`:""}`;
+  open.forEach(r=>aqImage(r.id));
+}
+async function aqImage(id){
+  const mine=AQ, show=url=>{ const img=sheet.querySelector(`[data-aq-img="${CSS.escape(id)}"]`); if(img){ img.src=url; img.hidden=false; } };
+  if(mine.urls[id]) return show(mine.urls[id]);
+  if(id in mine.urls) return;   // loading
+  mine.urls[id]=null;
+  try{
+    const r=await api(`/api/ai-queue/${encodeURIComponent(id)}/image`,{cache:"no-store"}); if(!r.ok) throw Error();
+    const url=URL.createObjectURL(await r.blob());
+    if(AQ!==mine) return URL.revokeObjectURL(url);
+    mine.urls[id]=url; show(url);
+  }catch{ if(AQ===mine) delete mine.urls[id]; }
+}
+async function aqPost(id,what,body){
+  const mine=AQ; if(!mine||mine.busy.has(id)) return;
+  mine.busy.add(id); drawQueue();
+  let row=null, err="";
+  try{
+    const r=await api(`/api/ai-queue/${encodeURIComponent(id)}/${what}`,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(body||{})});
+    const d=await r.json().catch(()=>({}));
+    if(!r.ok) throw Error(AQ_ERR[d.detail]||"הפעולה נכשלה. נסו שוב.");
+    row=d;
+  }catch(e){ err=e.message; }
+  mine.busy.delete(id); if(AQ!==mine) return;
+  if(row){ const i=mine.rows.findIndex(x=>x.id===id); if(i>=0) mine.rows[i]=row; }
+  drawQueue(); if(err) sheet.querySelector(".mx-manage-state").textContent=err;
+}
+const aqSend=id=>aqPost(id,"send");
+function aqDecline(id){
+  const note=prompt("הערה לתלמיד (לא חובה), למשל: צלמו שוב, התמונה לא ברורה");
+  if(note!==null) return aqPost(id,"decline",{note});
+}
+async function aqAll(){ for(const r of (AQ?.rows||[]).filter(x=>x.state==="pending")){ if(!AQ) return; await aqSend(r.id); } }
+
 /* A photographed problem (/api/math/photo, app/math_photo.py): hints first. The sheet shows the problem as it was
    read (a wrong reading is the student's cue to photograph again), then one hint; each further hint, each step and
    the whole solution with its answer come only when the student asks for them. */
@@ -1406,16 +1624,38 @@ async function photo(file){
     const form=new FormData(); form.append("photo",blob,"problem.jpg");
     const res=await api("/api/math/photo",{method:"POST",body:form}), data=await res.json().catch(()=>({}));
     if(!res.ok) throw new Error(typeof data.detail==="string"?data.detail:`השרת ענה ${res.status}`);
-    mine.data=data;
+    if(data.queued){ mine.req=data.request; mine.left=data.left; } else mine.data=data;
   }catch(e){ mine.error=e.message; }
   mine.busy=false;
   if(PH===mine&&cur==="photo") drawPhoto();   // a newer photo, or a closed sheet, keeps its own
+  if(mine.req) photoWait(mine);
+}
+// a student's photo waits for their teacher (app/ai_queue.py): the sheet looks for the answer while it is open
+const photoWaiting=req=>!!req&&["pending","sending","failed"].includes(req.state);
+async function photoWait(mine){
+  while(PH===mine&&cur==="photo"&&photoWaiting(mine.req)){
+    await new Promise(done=>setTimeout(done,8000));
+    if(PH!==mine||cur!=="photo") return;
+    try{
+      const r=await api("/api/math/ai-requests",{cache:"no-store"}); if(!r.ok) continue;
+      const row=((await r.json()).requests||[]).find(x=>x.id===mine.req.id); if(!row) continue;
+      mine.req=row; if(row.state==="done"&&row.result) mine.data={...row.result,left:mine.left};
+    }catch{ continue; }
+    if(!photoWaiting(mine.req)&&PH===mine&&cur==="photo") drawPhoto();
+  }
+}
+async function photoCancel(){
+  const mine=PH; if(!mine?.req) return;
+  try{ const r=await api(`/api/math/ai-requests/${encodeURIComponent(mine.req.id)}/cancel`,{method:"POST"}); if(r.ok) mine.req=await r.json(); }catch{}
+  if(PH===mine&&cur==="photo") drawPhoto();
 }
 function drawPhoto(){
   const d=PH.data;
   let body;
   if(PH.busy) body='<div class="mx-wait"><span class="mx-spin" aria-hidden="true"></span><b>קוראים את התרגיל ופותרים…</b><small>זה לוקח כמה שניות.</small></div>';
   else if(PH.error) body=`<div class="mx-bad"><b>לא הצלחנו</b><span>${esc(PH.error)}</span><button class="mx-btn" data-act="retake">צילום מחדש</button></div>`;
+  else if(!d&&photoWaiting(PH.req)) body=`<div class="mx-wait"><b>התמונה נשלחה למורה</b><small>אחרי שהמורה יאשר, הרמזים והפתרון יופיעו כאן.</small><button class="mx-btn" data-act="photo-cancel">ביטול הבקשה</button></div>`;
+  else if(!d) body=`<div class="mx-bad"><b>${PH.req?.state==="cancelled"?"הבקשה בוטלה":"המורה לא אישר את הבקשה"}</b>${PH.req?.note?`<span>הערת המורה: ${esc(PH.req.note)}</span>`:""}<button class="mx-btn" data-act="retake">צילום חדש</button></div>`;
   else if(!d.readable) body=`<div class="mx-bad"><b>לא הצלחנו לקרוא את התרגיל</b><span>${fmtLoose(d.note||"צלמו שוב, קרוב יותר ובאור טוב.")}</span><button class="mx-btn" data-act="retake">צילום מחדש</button></div>`;
   else{
     const n=d.steps.length, shown=PH.all?n:Math.min(PH.shown,n);
@@ -1698,7 +1938,7 @@ async function boot(){
     const response=await api("/api/me");
     if(!response.ok){ state.className="error"; state.textContent=response.status===403?"החשבון אינו משויך לכיתת מתמטיקה.":"לא ניתן להשלים את הכניסה."; return; }
     const me=await response.json();CFG.userId=me.user_id;CFG.answerScans=me.answer_scans; ME_EMAIL=me.email||""; MY_CLASSES=me.classes||[]; MY_CLASS=MY_CLASSES.length===1?MY_CLASSES[0]:null;
-    CFG.permissions=me.permissions||[]; CFG.roles=me.roles||[];
+    CFG.permissions=me.permissions||[]; CFG.roles=me.roles||[]; CFG.aiDirect=me.ai_direct!==false; CFG.aiReview=!!me.ai_review;
   }
   document.getElementById("boot").hidden=true;
   show();

supabase/migrations/20261104090000_math_ai_requests.sql

@@ -0,0 +1,33 @@
+-- The teacher's AI queue (app/ai_queue.py): a student does not call Claude. Their photographed problem, or the answer
+-- they want checked, waits here until their class's teacher (or a manager) looks at it and sends it to the AI or
+-- declines it. Additive: one new table; nothing existing changes. Only the server's secret key reads or writes it.
+begin;
+create table public.math_ai_requests (
+  id uuid primary key default gen_random_uuid(),
+  created_at timestamptz not null default now(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  email text not null check (length(email) <= 320),
+  kind text not null check (kind in ('photo', 'grading')),
+  state text not null default 'pending'
+    check (state in ('pending', 'sending', 'done', 'failed', 'declined', 'cancelled')),
+  attempt_id uuid,                              -- grading: the saved answer (math_question_attempts) to check
+  label text not null default '' check (length(label) <= 300),        -- grading: the question's name
+  question text not null default '' check (length(question) <= 4000), -- grading: the question, for the teacher
+  image text check (length(image) <= 8000000),  -- photo: base64 JPEG; cleared once the request is handled
+  result jsonb,                                 -- photo: the solution the student sees
+  note text not null default '' check (length(note) <= 500),         -- the teacher's word when declining
+  error text not null default '' check (length(error) <= 300),
+  reviewed_by text not null default '' check (length(reviewed_by) <= 320),
+  sent_at timestamptz,
+  finished_at timestamptz,
+  check ((kind = 'grading') = (attempt_id is not null))
+);
+create index math_ai_requests_queue on public.math_ai_requests(state, created_at);
+create index math_ai_requests_mine on public.math_ai_requests(user_id, created_at desc);
+-- one open request per answer: a second click finds the first
+create unique index math_ai_requests_one_open on public.math_ai_requests(attempt_id)
+  where state in ('pending', 'sending');
+alter table public.math_ai_requests enable row level security;
+revoke all on public.math_ai_requests from public, anon, authenticated;
+grant select, insert, update, delete on public.math_ai_requests to service_role;
+commit;

tests/scan_support.py

@@ -32,9 +32,14 @@ class ScanAuth:
     url = 'https://test.invalid'
     key = 'public-test'
     secret = 'server-test'
-    teachers = frozenset()
+    # OWNER is a teacher, so these tests check answers straight with the AI; the students' queue is in test_ai_queue
+    teachers = frozenset({OWNER + '@test.invalid'})
     developers = frozenset()
 
+    def _admin(self, path, *args, **kwargs):
+        from app.auth import AuthUnavailable
+        raise AuthUnavailable('supabase answered 404: no tables here but the answer RPCs')
+
     def user(self, token):
         if token not in (OWNER, OTHER):
             return None

tests/test_ai_queue.py

@@ -0,0 +1,351 @@
+"""The teacher's AI queue: a student's request waits for the class teacher, who sends it to the AI or declines it."""
+import asyncio
+import base64
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+import httpx
+import pytest
+
+from app.ai_queue import AiQueue, may_send
+from app.answer_grading import validate_assessment
+from app.answer_scans import ScanError
+from app.main import create_app
+from scan_support import OWNER, OTHER, ScanAuth, answer_store, postgres_server
+from test_answer_grading import assessment
+from test_answer_scans import begin, finish, png, request
+
+STRANGER = '33333333-3333-4333-8333-333333333333'
+mail = lambda uid: uid + '@test.invalid'
+
+
+@pytest.fixture(autouse=True)
+def grading_on(monkeypatch):
+    monkeypatch.setenv('MATHLY_OPEN_ENDED_LOCKED', '0')
+    monkeypatch.setenv('ANTHROPIC_API_KEY', 'test-key')
+
+
+class ClassAuth(ScanAuth):
+    """OWNER is a student whose class teacher is OTHER; STRANGER teaches another class."""
+    teachers = frozenset()
+
+    def user(self, token):
+        return {'id': token, 'email': mail(token)} if token in (OWNER, OTHER, STRANGER) else None
+
+    def classes(self, fresh=False):
+        return [{'id': 1, 'name': 'ט1', 'emails': [mail(OWNER), mail(OTHER)], 'teachers': [mail(OTHER)]},
+                {'id': 2, 'name': 'ט2', 'emails': [mail(STRANGER), 'x@test.invalid'], 'teachers': [mail(STRANGER)]}]
+
+
+class MemoryQueue(AiQueue):
+    """AiQueue's behaviour over a list, in place of the Supabase table."""
+    configured = True
+
+    def __init__(self):
+        self.rows = []
+
+    def _new(self, row):
+        out = {'id': str(uuid.uuid4()), 'created_at': datetime.now(timezone.utc).isoformat(), 'state': 'pending',
+               'attempt_id': None, 'label': '', 'question': '', 'image': None, 'result': None, 'note': '',
+               'error': '', 'reviewed_by': '', 'sent_at': None, 'finished_at': None, **row}
+        self.rows.append(out)
+        return out
+
+    def _public(self, row, image=False):
+        return {k: v for k, v in row.items() if image or k != 'image'} if row else None
+
+    def _find(self, rid):
+        return next((r for r in self.rows if r['id'] == rid), None)
+
+    def add(self, row):
+        if row.get('attempt_id') and any(r['attempt_id'] == row['attempt_id'] and r['state'] in ('pending', 'sending')
+                                         for r in self.rows):
+            return self.for_attempt(row['user_id'], row['attempt_id'])
+        return self._public(self._new(row))
+
+    def for_attempt(self, user_id, attempt_id):
+        rows = [r for r in self.rows if r['user_id'] == user_id and r['attempt_id'] == attempt_id]
+        return self._public(rows[-1]) if rows else None
+
+    def open_count(self, user_id):
+        return sum(r['user_id'] == user_id and r['state'] in ('pending', 'sending') for r in self.rows)
+
+    def mine(self, user_id, limit=20):
+        return [self._public(r) for r in reversed(self.rows) if r['user_id'] == user_id and r['kind'] == 'photo']
+
+    def cancel(self, user_id, rid):
+        r = self._find(rid)
+        if not r or r['user_id'] != user_id or r['state'] != 'pending':
+            return None
+        r.update(state='cancelled', image=None)
+        return self._public(r)
+
+    def reopen(self, rid):
+        r = self._find(rid)
+        if not r or r['state'] not in ('failed', 'declined'):
+            raise ScanError(409, 'request_taken')
+        r.update(state='pending', error='', note='')
+        return self._public(r)
+
+    def listing(self, emails, limit=100):
+        return [self._public(r) for r in reversed(self.rows) if emails is None or r['email'] in emails]
+
+    def get(self, rid, image=False):
+        return self._public(self._find(rid), image)
+
+    def claim(self, rid, reviewer):
+        r = self._find(rid)
+        if not r or r['state'] not in ('pending', 'failed'):
+            raise ScanError(409, 'request_taken')
+        r.update(state='sending', reviewed_by=reviewer, error='')
+        return self._public(r, image=True)
+
+    def finish(self, rid, state, **fields):
+        r = self._find(rid)
+        r.update(state=state, **fields)
+        return self._public(r)
+
+    def decline(self, rid, reviewer, note):
+        r = self._find(rid)
+        if not r or r['state'] not in ('pending', 'failed'):
+            raise ScanError(409, 'request_taken')
+        r.update(state='declined', image=None, note=note, reviewed_by=reviewer)
+        return self._public(r)
+
+
+class Grader:
+    def __init__(self):
+        self.calls = []
+
+    def grade(self, image, snapshot):
+        self.calls.append((image, snapshot))
+        return validate_assessment(assessment())
+
+
+class Solver:
+    def __init__(self):
+        self.calls = []
+
+    def solve(self, image, media_type):
+        self.calls.append((image, media_type))
+        return {"readable": True, "problem": "$x² = 9$", "steps": [{"hint": "h", "work": "w"}],
+                "answer": "$x = ±3$", "skill": "", "note": "", "usage": None}
+
+
+def make_app(store=None):
+    app = create_app(auth=ClassAuth())
+    if store is not None:
+        app.state.answers = store
+    app.state.ai_queue, app.state.answer_grader = MemoryQueue(), Grader()
+    app.state.photo, app.state.photo_key = Solver(), 'test-key'
+    return app
+
+
+def as_user(app, uid):
+    return httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url='http://test',
+                             headers={'Authorization': f'Bearer {uid}'})
+
+
+def test_who_sends_to_the_ai_itself():
+    assert may_send(None)   # sign-in off
+    assert not may_send({'roles': ['student'], 'permissions': ['path.use'], 'email': 's@x', 'classes': []})
+    assert may_send({'roles': ['teacher'], 'permissions': [], 'email': 't@x', 'classes': []})
+    assert may_send({'roles': ['developer'], 'permissions': ['*'], 'email': 'd@x', 'classes': []})
+    assert may_send({'roles': ['student'], 'permissions': [], 'email': 't@x',
+                     'classes': [{'teachers': ['t@x'], 'emails': ['t@x']}]})
+
+
+def test_a_students_answer_waits_for_the_teacher_who_sends_it(answer_store):
+    store = answer_store
+    upload = begin(store, request(store))
+    sid, lid, aid = upload['scan']['id'], upload['scan']['lease_id'], upload['attempt']['id']
+    app = make_app(store)
+    grader, queue = app.state.answer_grader, app.state.ai_queue
+
+    async def check():
+        async with as_user(app, OWNER) as student, as_user(app, OTHER) as teacher, as_user(app, STRANGER) as other:
+            me = (await student.get('/api/me')).json()
+            assert me['ai_direct'] is False and me['ai_review'] is False
+            assert (await teacher.get('/api/me')).json()['ai_review'] is True
+            # the upload asks the teacher, never the AI
+            up = await student.post(f'/api/math/answer-scans/{sid}/uploads/{lid}',
+                                    files={'photo': ('a.png', png(), 'image/png')})
+            assert up.status_code == 200 and not grader.calls
+            got = (await student.get(f'/api/math/answer-attempts/{aid}')).json()
+            assert got['grading'] is None and got['ai_request']['state'] == 'pending'
+            assert 'email' not in got['ai_request']
+            # asking again does not make a second request, and does not call the AI
+            again = (await student.post(f'/api/math/answer-attempts/{aid}/grade')).json()
+            assert again['ai_request']['id'] == got['ai_request']['id'] and len(queue.rows) == 1 and not grader.calls
+            # only the class's teacher reviews it
+            assert (await student.get('/api/ai-queue')).status_code == 403
+            assert (await other.get('/api/ai-queue')).json()['requests'] == []
+            rid = got['ai_request']['id']
+            assert (await other.post(f'/api/ai-queue/{rid}/send')).status_code == 404
+            listed = (await teacher.get('/api/ai-queue')).json()['requests']
+            assert [r['id'] for r in listed] == [rid] and listed[0]['email'] == mail(OWNER)
+            image = await teacher.get(f'/api/ai-queue/{rid}/image')
+            assert image.status_code == 200 and image.headers['content-type'] == 'image/jpeg'
+            sent = (await teacher.post(f'/api/ai-queue/{rid}/send')).json()
+            assert sent['state'] == 'done' and sent['result']['verdict'] == 'correct' and len(grader.calls) == 1
+            assert (await teacher.post(f'/api/ai-queue/{rid}/send')).status_code == 409   # sent once
+            done = (await student.get(f'/api/math/answer-attempts/{aid}')).json()
+            assert done['grading']['state'] == 'completed' and done['grading']['result']['score'] == 100
+    asyncio.run(check())
+
+
+def test_a_declined_answer_can_be_asked_again(answer_store):
+    store = answer_store
+    aid = finish(store, begin(store, request(store)))['attempt']['id']
+    app = make_app(store)
+
+    async def check():
+        async with as_user(app, OWNER) as student, as_user(app, OTHER) as teacher:
+            rid = (await student.post(f'/api/math/answer-attempts/{aid}/grade',
+                                      json={'automatic': True})).json()['ai_request']['id']
+            declined = (await teacher.post(f'/api/ai-queue/{rid}/decline', json={'note': 'צלמו  שוב'})).json()
+            assert declined['state'] == 'declined' and declined['note'] == 'צלמו שוב'
+            seen = (await student.get(f'/api/math/answer-attempts/{aid}')).json()['ai_request']
+            assert seen['state'] == 'declined' and seen['note'] == 'צלמו שוב'
+            # the automatic check does not ask again; the student's click does
+            auto = (await student.post(f'/api/math/answer-attempts/{aid}/grade', json={'automatic': True})).json()
+            assert auto['ai_request']['state'] == 'declined'
+            asked = (await student.post(f'/api/math/answer-attempts/{aid}/grade')).json()
+            assert asked['ai_request']['id'] == rid and asked['ai_request']['state'] == 'pending'
+            assert not app.state.answer_grader.calls
+    asyncio.run(check())
+
+
+def test_a_teachers_own_answer_goes_straight_to_the_ai(answer_store):
+    store = answer_store
+    aid = finish(store, begin(store, request(store)))['attempt']['id']
+    app = make_app(store)
+    app.state.auth.teachers = frozenset({mail(OWNER)})   # OWNER has the teacher role now
+
+    async def check():
+        async with as_user(app, OWNER) as me:
+            result = (await me.post(f'/api/math/answer-attempts/{aid}/grade')).json()
+            assert result['grading']['state'] == 'completed' and not app.state.ai_queue.rows
+    asyncio.run(check())
+
+
+def test_a_students_photo_waits_for_the_teacher():
+    app = make_app()
+    solver, queue = app.state.photo, app.state.ai_queue
+
+    async def check():
+        async with as_user(app, OWNER) as student, as_user(app, OTHER) as teacher:
+            sent = await student.post('/api/math/photo', files={'photo': ('p.png', png(), 'image/png')})
+            assert sent.status_code == 200 and sent.json()['queued'] is True and not solver.calls
+            rid = sent.json()['request']['id']
+            assert base64.b64decode(queue.rows[0]['image'])[:2] == b'\xff\xd8'   # kept as a clean JPEG
+            assert (await student.post('/api/math/photo', files={'photo': ('p.jpg', b'nope', 'image/jpeg')})).status_code == 415
+            mine = (await student.get('/api/math/ai-requests')).json()
+            assert mine['direct'] is False and mine['requests'][0]['state'] == 'pending'
+            assert (await teacher.get(f'/api/ai-queue/{rid}/image')).status_code == 200
+            done = (await teacher.post(f'/api/ai-queue/{rid}/send')).json()
+            assert done['state'] == 'done' and len(solver.calls) == 1 and solver.calls[0][1] == 'image/jpeg'
+            assert queue.rows[0]['image'] is None   # the photo is not kept once it is answered
+            mine = (await student.get('/api/math/ai-requests')).json()['requests'][0]
+            assert mine['state'] == 'done' and mine['result']['answer'] == '$x = ±3$' and 'usage' not in mine['result']
+            # the teacher's own photo is solved at once
+            own = (await teacher.post('/api/math/photo', files={'photo': ('p.png', png(), 'image/png')})).json()
+            assert own['answer'] == '$x = ±3$' and len(queue.rows) == 1
+    asyncio.run(check())
+
+
+def test_a_student_can_cancel_and_has_a_limit_of_open_requests():
+    app = make_app()
+
+    async def check():
+        async with as_user(app, OWNER) as student:
+            ids = []
+            for _ in range(5):
+                ids.append((await student.post('/api/math/photo', files={'photo': ('p.png', png(), 'image/png')})).json()['request']['id'])
+            assert (await student.post('/api/math/photo', files={'photo': ('p.png', png(), 'image/png')})).status_code == 429
+            assert (await student.post(f'/api/math/ai-requests/{ids[0]}/cancel')).json()['state'] == 'cancelled'
+            assert (await student.post(f'/api/math/ai-requests/{ids[0]}/cancel')).status_code == 409
+            assert (await student.post('/api/math/photo', files={'photo': ('p.png', png(), 'image/png')})).status_code == 200
+    asyncio.run(check())
+
+
+def test_the_migration_keeps_one_open_request_per_answer(postgres_server):
+    import psycopg
+    database = 'queue_' + uuid.uuid4().hex
+    with psycopg.connect(postgres_server.get_uri(), autocommit=True) as c:
+        c.execute('create database ' + database)
+    try:
+        with psycopg.connect(postgres_server.get_uri(database=database), autocommit=True) as c:
+            c.execute('create schema auth; create table auth.users(id uuid primary key);')
+            c.execute(Path('supabase/migrations/20261104090000_math_ai_requests.sql').read_text())
+            c.execute('insert into auth.users values(%s)', (OWNER,))
+            attempt = str(uuid.uuid4())
+            add = "insert into public.math_ai_requests(user_id,email,kind,attempt_id) values(%s,'s@x','grading',%s)"
+            c.execute(add, (OWNER, attempt))
+            with pytest.raises(psycopg.errors.UniqueViolation):
+                c.execute(add, (OWNER, attempt))
+            c.execute("update public.math_ai_requests set state='done'")
+            c.execute(add, (OWNER, attempt))   # a new request once the first is handled
+            with pytest.raises(psycopg.errors.CheckViolation):   # a photo has no answer; an answer check needs one
+                c.execute("insert into public.math_ai_requests(user_id,email,kind,attempt_id) values(%s,'s@x','photo',%s)",
+                          (OWNER, attempt))
+            c.execute("set role anon")
+            with pytest.raises(psycopg.errors.InsufficientPrivilege):
+                c.execute('select * from public.math_ai_requests')
+    finally:
+        with psycopg.connect(postgres_server.get_uri(), autocommit=True) as c:
+            c.execute('drop database ' + database + ' with (force)')
+
+
+def test_a_failed_send_keeps_why_it_failed(answer_store):
+    from app.math_photo import PhotoUnavailable
+    store = answer_store
+    aid = finish(store, begin(store, request(store)))['attempt']['id']
+    app = make_app(store)
+
+    class Refused:
+        def grade(self, image, snapshot):
+            raise PhotoUnavailable('הבדיקה אינה זמינה כרגע.', 'api_key_invalid', 'AuthenticationError 401: invalid x-api-key')
+    app.state.answer_grader = Refused()
+
+    async def check():
+        async with as_user(app, OWNER) as student, as_user(app, OTHER) as teacher:
+            rid = (await student.post(f'/api/math/answer-attempts/{aid}/grade')).json()['ai_request']['id']
+            failed = (await teacher.post(f'/api/ai-queue/{rid}/send')).json()
+            assert failed['state'] == 'failed'
+            assert failed['error'] == 'grading_failed|api_key_invalid|AuthenticationError 401: invalid x-api-key'
+            assert 'error' not in (await student.get(f'/api/math/answer-attempts/{aid}')).json()['ai_request']
+    asyncio.run(check())
+
+
+def test_a_teachers_own_failed_check_says_why(answer_store, monkeypatch):
+    store = answer_store
+    aid = finish(store, begin(store, request(store)))['attempt']['id']
+    app = make_app(store)
+    app.state.auth.teachers = frozenset({mail(OWNER)})
+    monkeypatch.delenv('ANTHROPIC_API_KEY')
+
+    async def check():
+        async with as_user(app, OWNER) as me:
+            body = (await me.post(f'/api/math/answer-attempts/{aid}/grade')).json()
+            assert body == {'detail': 'grading_unavailable', 'reason': 'missing_key',
+                            'error_detail': 'ANTHROPIC_API_KEY is not set'}
+    asyncio.run(check())
+
+
+@pytest.mark.parametrize('status,message,reason', [
+    (401, 'invalid x-api-key', 'api_key_invalid'), (403, 'no access', 'permission'),
+    (404, 'model: claude-x', 'model_not_found'), (429, 'slow down', 'rate_limited'),
+    (400, 'Your credit balance is too low to access the Anthropic API.', 'no_credit'),
+    (529, 'Overloaded', 'overloaded'), (400, 'bad image', 'bad_request')])
+def test_api_errors_are_named(status, message, reason):
+    import anthropic
+    from app.math_photo import failure_reason
+    response = httpx.Response(status, request=httpx.Request('POST', 'https://api.anthropic.com/v1/messages'))
+    cls = {401: anthropic.AuthenticationError, 403: anthropic.PermissionDeniedError, 404: anthropic.NotFoundError,
+           429: anthropic.RateLimitError, 400: anthropic.BadRequestError}.get(status, anthropic.InternalServerError)
+    exc = cls(message, response=response, body=None)
+    got, detail = failure_reason(exc)
+    assert got == reason and str(status) in detail and message[:20] in detail
+    assert failure_reason(anthropic.APIConnectionError(request=response.request))[0] == 'no_connection'

tests/test_ai_queue_browser.py

@@ -0,0 +1,128 @@
+"""In the browser: a student's quiz answers wait in the teacher's AI queue; the teacher sends them; the grade shows."""
+import socket
+import threading
+import time
+
+import pytest
+import uvicorn
+
+from app.answer_grading import validate_assessment
+from app.main import create_app
+from scan_support import OWNER, OTHER, answer_store, postgres_server
+from test_ai_queue import ClassAuth, MemoryQueue
+from test_answer_grading import assessment
+from test_unit_quiz import photograph
+
+playwright = pytest.importorskip("playwright.sync_api")
+
+
+@pytest.fixture(autouse=True)
+def grading_on(monkeypatch):
+    monkeypatch.setenv("MATHLY_OPEN_ENDED_LOCKED", "0")
+    monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key")
+
+
+@pytest.fixture
+def queue_server(answer_store):
+    app = create_app(auth=ClassAuth()); app.state.answers = answer_store
+    app.state.ai_queue = MemoryQueue()
+    calls = []
+
+    class Grader:
+        def grade(self, image, snapshot):
+            if "fail" in calls:
+                from app.math_photo import PhotoUnavailable
+                raise PhotoUnavailable("x", "api_key_invalid", "AuthenticationError 401: invalid x-api-key")
+            calls.append(snapshot["name"])
+            return validate_assessment(assessment(score=100))
+    app.state.answer_grader = Grader()
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        server = uvicorn.Server(uvicorn.Config(app, log_level="error"))
+        thread = threading.Thread(target=server.run, kwargs={"sockets": [sock]}, daemon=True)
+        thread.start()
+        try:
+            while not server.started:
+                time.sleep(.01)
+            yield f"http://127.0.0.1:{sock.getsockname()[1]}", calls
+        finally:
+            server.should_exit = True; thread.join(timeout=5)
+
+
+def page_of(browser, url, owner, errors):
+    from test_answer_browser import session
+    page = session(browser, owner=owner).new_page()
+    page.on("pageerror", lambda e: errors.append(str(e)))
+    page.goto(url)
+    page.locator('.mx-nav [data-view="path"]').click()
+    return page
+
+
+def test_the_teacher_sends_a_students_quiz_answer_to_the_ai(queue_server, tmp_path):
+    url, calls = queue_server
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        errors = []
+        try:
+            student = page_of(browser, url, OWNER, errors)
+            playwright.expect(student.locator('[data-act="ai-queue"]')).to_have_count(0)   # a student has no queue
+            student.locator('.mx-uquiz[data-uquiz="t"]').click()
+            student.locator("[data-act=uq-start]").click()
+            photograph(student, 0, tmp_path)
+            paper = student.locator(".mx-uq-paper")
+            paper.locator("[data-act=uq-submit]").click()
+            paper.locator("[data-act=uq-submit]").click()   # past the warning about unanswered questions
+            sheet = student.locator(".mx-uq-sheet")
+            playwright.expect(sheet.locator(".mx-uq-verdict").first).to_have_text("מחכה למורה שיאשר את הבדיקה", timeout=15000)
+            assert not calls
+
+            teacher = page_of(browser, url, OTHER, errors)
+            button = teacher.locator('.mx-acts [data-act="ai-queue"]').first
+            playwright.expect(button).to_contain_text("1")
+            button.click()
+            card = teacher.locator(".mx-aq-card.pending")
+            playwright.expect(card).to_have_count(1)
+            playwright.expect(card.locator(".mx-aq-img")).to_be_visible()
+            card.locator("[data-aq-send]").click()
+            playwright.expect(teacher.locator(".mx-aq-card.done")).to_contain_text("נכונה · 100/100")
+            assert len(calls) == 1
+
+            sheet.locator('[data-act="close"]').last.click()
+            student.locator('.mx-uquiz[data-uquiz="t"]').click()
+            student.locator("[data-uq-result]").first.click()
+            playwright.expect(student.locator(".mx-uq-verdict").first).to_have_text("נכון ומלא", timeout=10000)
+            assert len(calls) == 1 and not errors, errors
+        finally:
+            browser.close()
+
+
+def test_a_failed_send_has_an_error_details_button(queue_server, tmp_path):
+    from app.math_photo import PhotoUnavailable
+    url, calls = queue_server
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        errors = []
+        try:
+            student = page_of(browser, url, OWNER, errors)
+            student.locator('.mx-uquiz[data-uquiz="t"]').click()
+            student.locator("[data-act=uq-start]").click()
+            photograph(student, 0, tmp_path)
+            paper = student.locator(".mx-uq-paper")
+            paper.locator("[data-act=uq-submit]").click()
+            paper.locator("[data-act=uq-submit]").click()
+            playwright.expect(student.locator(".mx-uq-verdict").first).to_have_text("מחכה למורה שיאשר את הבדיקה", timeout=15000)
+            calls.append("fail")   # the grader below fails while this is in the list
+
+            teacher = page_of(browser, url, OTHER, errors)
+            teacher.locator('.mx-acts [data-act="ai-queue"]').first.click()
+            teacher.locator(".mx-aq-card.pending [data-aq-send]").click()
+            card = teacher.locator(".mx-aq-card.failed")
+            playwright.expect(card.locator(".mx-aq-error")).to_have_text("הבדיקה נכשלה. אפשר לנסות שוב.")
+            details = card.locator(".mx-error-details")
+            playwright.expect(details.locator("code")).to_be_hidden()
+            details.locator("summary").click()
+            playwright.expect(details).to_contain_text("מפתח ה-API לא תקין")
+            playwright.expect(details.locator("code")).to_have_text("AuthenticationError 401: invalid x-api-key")
+            assert not errors, errors
+        finally:
+            browser.close()

tests/test_class_report.py

@@ -0,0 +1,105 @@
+"""The class teacher's report: one of the students is the class's teacher and sees the others' progress and grades."""
+import asyncio
+import urllib.parse
+
+import httpx
+
+from app.main import create_app
+
+TEACHER, STUDENT, NEWBIE, OUTSIDER = "t-id", "s-id", "n-id", "o-id"
+EMAILS = {TEACHER: "teacher@x.test", STUDENT: "student@x.test", NEWBIE: "newbie@x.test", OUTSIDER: "out@x.test"}
+
+
+class ReportAuth:
+    url, key, secret = "https://test.invalid", "public-test", "server-test"
+    teachers = developers = frozenset()
+
+    def __init__(self):
+        self.row = {"id": 3, "name": "ט׳1", "lessons": [], "teachers": ["teacher@x.test"],
+                    "emails": ["newbie@x.test", "student@x.test", "teacher@x.test", "ghost@x.test"]}
+        self.saved = []
+        self.progress = {STUDENT: {"done": {"t1": "2026-11-01"}, "updated": 5, "comets": ["c1"],
+                                   "slips": [{"at": "2026-11-01T10:00:00Z", "id": "t1", "q": 0, "m": "sign"}],
+                                   "quizzes": [{"at": "2026-11-02", "n": 12, "right": 9, "ms": 600000, "units": ["t"],
+                                                "weak": ["t1"]}],
+                                   "uq": {"t": {"sitting": {"started": 1, "attempts": ["a"], "submitted": 2},
+                                                "history": [{"at": "2026-11-03", "attempts": ["a"], "score": 85}]}}},
+                         TEACHER: {"done": {"secret": 1}}}
+
+    def user(self, token):
+        return {"id": token, "email": EMAILS[token]} if token in EMAILS else None
+
+    def classes(self, fresh=False):
+        return [self.row]
+
+    def access_for(self, _id, **kwargs):
+        return None
+
+    def user_ids(self, emails):
+        return {e: i for i, e in EMAILS.items() if e in emails and i != NEWBIE} | (
+            {"newbie@x.test": NEWBIE} if "newbie@x.test" in emails else {})
+
+    def save_class(self, class_id, name, emails, nicknames, lessons, *, teachers=None):
+        self.saved.append({"emails": emails, "teachers": teachers})
+
+    def _admin(self, path, method="GET", body=None, prefer=""):
+        table, _, query = path.partition("?")
+        assert table == "/rest/v1/math_progress"
+        ids = dict(urllib.parse.parse_qsl(query))["user_id"].removeprefix("in.(").removesuffix(")").split(",")
+        return [{"user_id": i, "data": self.progress[i], "updated_at": "2026-11-03T00:00:00Z"}
+                for i in ids if i in self.progress]
+
+
+def client(app, user):
+    return httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test",
+                             headers={"Authorization": f"Bearer {user}"})
+
+
+def test_teacher_sees_the_other_students():
+    app = create_app(auth=ReportAuth())
+
+    async def check():
+        async with client(app, TEACHER) as c:
+            r = await c.get("/api/classes/3/report")
+            assert r.status_code == 200
+            data = r.json()
+            assert data["class"]["name"] == "ט׳1" and data["class"]["lessons"]
+            students = {s["email"]: s for s in data["students"]}
+            assert "teacher@x.test" not in students   # the teacher is not in their own report
+            assert students["ghost@x.test"] == {"email": "ghost@x.test", "signed_in": False, "progress": None,
+                                                "saved_at": None}
+            assert students["newbie@x.test"]["signed_in"] and students["newbie@x.test"]["progress"] is None
+            p = students["student@x.test"]["progress"]
+            assert p["done"] == {"t1": "2026-11-01"} and p["slips"][0]["m"] == "sign"
+            assert p["quizzes"] == [{"at": "2026-11-02", "n": 12, "right": 9, "ms": 600000, "units": ["t"]}]
+            assert p["uq"] == {"t": {"history": [{"at": "2026-11-03", "score": 85, "timeUp": None}], "going": False}}
+            assert "comets" not in p
+            assert (await c.get("/api/classes/99/report")).status_code == 404
+            me = (await c.get("/api/me")).json()
+            assert me["classes"][0]["teacher"] is True
+        for other in (STUDENT, OUTSIDER):
+            async with client(app, other) as c:
+                assert (await c.get("/api/classes/3/report")).status_code == 403
+
+    asyncio.run(check())
+
+
+def test_the_teacher_is_one_of_the_students():
+    auth = ReportAuth()
+    app = create_app(auth=auth)
+
+    async def check():
+        # a manager (TEACHER_EMAILS) saves the class
+        auth.teachers = frozenset({"out@x.test"})
+        async with client(app, OUTSIDER) as c:
+            body = {"name": "ט׳1", "emails": ["a@x.test", "b@x.test"], "lessons": ["t"]}
+            assert (await c.put("/api/classes/3", json={**body, "teachers": ["c@x.test"]})).status_code == 400
+            assert (await c.put("/api/classes/3", json={**body, "teachers": ["a@x.test", "b@x.test"]})).status_code == 400
+            assert (await c.put("/api/classes/3", json={**body, "teachers": ["B@x.test"]})).status_code == 200
+            assert (await c.put("/api/classes/3", json=body)).status_code == 200
+            assert auth.saved == [{"emails": ["a@x.test", "b@x.test"], "teachers": ["b@x.test"]},
+                                  {"emails": ["a@x.test", "b@x.test"], "teachers": []}]
+            # a manager can open any class's report
+            assert (await c.get("/api/classes/3/report")).status_code == 200
+
+    asyncio.run(check())

tests/test_guide_browser.py

@@ -0,0 +1,58 @@
+"""Browser checks of the user guide (static/guide.js): the "?" button opens it, with a tab for students and one for teachers.
+Optional, like the other browser tests: pip install playwright && playwright install chromium."""
+import socket
+import threading
+import time
+
+import pytest
+import uvicorn
+
+from app.main import create_app
+
+playwright = pytest.importorskip("playwright.sync_api")
+
+
+@pytest.fixture(scope="module")
+def server():
+    app = create_app()
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        srv = uvicorn.Server(uvicorn.Config(app, log_level="error"))
+        thread = threading.Thread(target=srv.run, kwargs={"sockets": [sock]}, daemon=True)
+        thread.start()
+        try:
+            deadline = time.monotonic() + 5
+            while not srv.started:
+                assert thread.is_alive() and time.monotonic() < deadline
+                time.sleep(.01)
+            yield f"http://127.0.0.1:{sock.getsockname()[1]}"
+        finally:
+            srv.should_exit = True
+            thread.join(timeout=5)
+
+
+def test_guide_opens_with_student_and_teacher_tabs(server):
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            ctx = browser.new_context(viewport={"width": 390, "height": 844})
+            ctx.route("https://cdn.jsdelivr.net/**", lambda route: route.abort())
+            ctx.route("https://fonts.googleapis.com/**", lambda route: route.abort())
+            page = ctx.new_page()
+            errors = []
+            page.on("pageerror", lambda e: errors.append(str(e)))
+            page.goto(server)
+            assert page.locator("#boot [data-guide-open]").count() == 1   # on the sign-in screen
+            page.locator("#mathView [data-guide-open]").first.click()   # and in the app's header
+            guide = page.get_by_role("dialog", name="איך משתמשים באפליקציה")
+            playwright.expect(guide).to_be_visible()
+            playwright.expect(page.locator("#mgS")).to_contain_text("בוחן מסכם")
+            playwright.expect(page.locator("#mgT")).to_be_hidden()
+            page.get_by_role("tab", name="למורים").click()
+            playwright.expect(page.locator("#mgT")).to_contain_text("הכיתה שלי")
+            playwright.expect(page.locator("#mgS")).to_be_hidden()
+            page.keyboard.press("Escape")
+            playwright.expect(guide).to_be_hidden()
+            assert errors == []
+        finally:
+            browser.close()

tests/test_phone_browser.py

@@ -44,7 +44,7 @@ def test_class_management_geometry_and_permissions(phone_server, manager):
     import json
 
     row = {"id": 7, "name": "כיתת תרגול", "lessons": ["t"],
-           "emails": ["student@example.com"], "teachers": ["teacher@example.com"],
+           "emails": ["student@example.com", "teacher@example.com"], "teachers": ["teacher@example.com"],
            "exam_title": "לוח מבחנים – כיתה ט׳11, תשפ״ז",
            "exam_note": "ייתכנו שינויים.",
            "exams": [{"date": "2026-11-16", "subject": "מתמטיקה"}]}
@@ -126,3 +126,106 @@ def test_class_management_geometry_and_permissions(phone_server, manager):
             playwright.expect(page.locator('[data-id="a_30_side"]')).to_be_visible()
         finally:
             browser.close()
+
+
+def test_class_teacher_report(phone_server):
+    """A student chosen as the class's teacher opens the class report: progress, difficulties and both kinds of grades."""
+    from datetime import datetime, timedelta, timezone
+
+    now = datetime.now(timezone.utc)
+    slips = [{"at": (now - timedelta(days=d)).isoformat(), "id": "t_ext", "q": 0, "m": "ext_partial"} for d in (1, 3)]
+    row = {"id": 4, "name": "ט׳2", "lessons": ["t"], "teacher": True, "exams": []}
+    report = {"class": {"id": 4, "name": "ט׳2", "lessons": ["t"]}, "students": [
+        {"email": "dana@example.com", "signed_in": True, "saved_at": None, "progress": {
+            "done": {"t_ext": "2026-11-01"}, "gold": {}, "days": {}, "missed": {}, "slips": slips, "updated": 1,
+            "quizzes": [{"at": "2026-11-02T10:00:00Z", "n": 12, "right": 9, "ms": 600000, "units": ["t"]}],
+            "uq": {"t": {"history": [{"at": "2026-11-03T10:00:00Z", "score": 85}], "going": False}}}},
+        {"email": "omer@example.com", "signed_in": False, "saved_at": None, "progress": None}]}
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            page = browser.new_page()
+            page.route("https://cdn.jsdelivr.net/**", lambda route: route.abort())
+            page.add_init_script('''window.supabase={createClient:()=>({auth:{
+                getSession:async()=>({data:{session:{access_token:"test",user:{id:"test"}}}}),
+                onAuthStateChange:()=>{},signOut:async()=>{}
+            }})};''')
+
+            def index(route):
+                response = route.fetch()
+                route.fulfill(response=response, body=response.text().replace(
+                    'supabaseUrl:""', 'supabaseUrl:"https://auth.invalid"'))
+
+            page.route(phone_server + "/", index)
+            page.route("**/api/me", lambda route: route.fulfill(json={
+                "email": "teacher@example.com", "user_id": "test", "answer_scans": False,
+                "permissions": ["path.use"], "classes": [row]}))
+            page.route("**/api/math/progress", lambda route: route.fulfill(json={"progress": {}}))
+            page.route("**/api/classes/4/report", lambda route: route.fulfill(json=report))
+            page.goto(phone_server)
+            page.locator('[data-act="class-report"]').click()
+            sheet = page.locator(".mx-report-sheet")
+            playwright.expect(sheet.locator("#mxTitle")).to_have_text("הכיתה שלי: ט׳2")
+            playwright.expect(sheet.locator(".mx-report-common")).to_contain_text("1 תלמידים: dana")
+            dana, omer = sheet.locator(".mx-report-student").nth(0), sheet.locator(".mx-report-student").nth(1)
+            playwright.expect(dana.locator("summary")).to_contain_text("בוחן 85")
+            playwright.expect(dana.locator("summary")).to_contain_text("תרגול 9/12")
+            playwright.expect(omer).to_contain_text("עוד לא נכנס לחשבון")
+            dana.locator("summary").click()
+            playwright.expect(dana.locator(".mx-report-table").first).to_contain_text("85/100")
+            playwright.expect(dana.locator(".mx-report-table").nth(1)).to_contain_text("75")
+            page.locator(".mx-report-sheet .mx-x").click()
+            playwright.expect(sheet).to_be_hidden()
+        finally:
+            browser.close()
+
+
+def test_class_editor_picks_the_teacher_from_the_students(phone_server):
+    import json
+
+    row = {"id": 7, "name": "ט׳3", "lessons": ["t"], "emails": ["a@example.com", "b@example.com"],
+           "teachers": ["b@example.com"], "exams": []}
+    writes = []
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            page = browser.new_page()
+            page.route("https://cdn.jsdelivr.net/**", lambda route: route.abort())
+            page.add_init_script('''window.supabase={createClient:()=>({auth:{
+                getSession:async()=>({data:{session:{access_token:"test",user:{id:"test"}}}}),
+                onAuthStateChange:()=>{},signOut:async()=>{}
+            }})};''')
+
+            def index(route):
+                response = route.fetch()
+                route.fulfill(response=response, body=response.text().replace(
+                    'supabaseUrl:""', 'supabaseUrl:"https://auth.invalid"'))
+
+            def save(route):
+                writes.append(json.loads(route.request.post_data))
+                route.fulfill(json={"ok": True})
+
+            page.route(phone_server + "/", index)
+            page.route("**/api/me", lambda route: route.fulfill(json={
+                "email": "boss@example.com", "user_id": "test", "answer_scans": False,
+                "permissions": ["management.access", "classes.manage"], "classes": []}))
+            page.route("**/api/math/progress", lambda route: route.fulfill(json={"progress": {}}))
+            page.route("**/api/classes", lambda route: route.fulfill(json={"classes": [row]}))
+            page.route("**/api/classes/7", save)
+            page.goto(phone_server)
+            page.locator('[data-act="manage"]').click()
+            playwright.expect(page.locator(".mx-class-card")).to_contain_text("b@example.com")
+            page.get_by_role("button", name="עריכה").click()
+            teacher = page.locator('select[name="teacher"]')
+            playwright.expect(teacher).to_have_value("b@example.com")
+            assert teacher.locator("option").all_inner_texts() == ["ללא מורה", "a@example.com", "b@example.com"]
+            page.locator('textarea[name="emails"]').fill("a@example.com\nb@example.com\nc@example.com")
+            playwright.expect(teacher.locator("option")).to_have_count(4)
+            playwright.expect(teacher).to_have_value("b@example.com")   # the choice stays while the list grows
+            teacher.select_option("c@example.com")
+            page.get_by_role("button", name="שמירת השינויים").click()
+            playwright.expect(page.locator(".mx-manage-state")).not_to_have_text("שומרים…")
+            assert writes[-1]["teachers"] == ["c@example.com"]
+            assert writes[-1]["emails"] == ["a@example.com", "b@example.com", "c@example.com"]
+        finally:
+            browser.close()

tests/test_unit_quiz.py

@@ -256,7 +256,7 @@ def test_a_unit_quiz_answer_is_handed_in_from_the_board(quiz_server):
             playwright.expect(page.locator(".mx-board")).to_be_visible()
             playwright.expect(page.locator('.mx-board-pages [data-page="2"]')).to_have_attribute("aria-selected", "true")
             send = page.locator(".mx-board-send")
-            playwright.expect(send).to_have_text("📤הגשה לשאלה 3")
+            playwright.expect(send).to_have_text("הגשה לשאלה 3")
             send.click()   # an empty page is not handed in
             playwright.expect(send).to_contain_text("הלוח ריק")
             draw_line(page)