feat: add additive answer-scanning schema and related functionality

- Introduced new JavaScript file for shared camera preparation for answer scans.
- Created new tables in the Supabase database for managing math question attempts, answer scans, and attachments.
- Implemented row-level security and policies for data access control.
- Added a new RPC function for handling answer scans, including actions for creating, confirming, and finalizing scans.
- Developed tests for the new functionality, ensuring proper handling of answer scans, including retries and error management.
- Established a local testing environment with PostgreSQL and integrated Playwright for end-to-end testing of the answer scanning process.

.env.example

@@ -4,6 +4,8 @@ SUPABASE_PUBLISHABLE_KEY=
 
 # Required for class roster management.
 SUPABASE_SECRET_KEY=
+# Enable only after applying the additive answer-scan migration and creating its private bucket.
+MATHLY_ANSWER_SCANS_ENABLED=0
 TEACHER_EMAILS=
 DEVELOPER_EMAILS=
 

README.md

@@ -37,3 +37,32 @@ For an existing deployment, back up Supabase and then run [docs/mathly-supabase.
 ```bash
 venv/bin/python -m pytest
 ```
+
+## Handwritten answers from a phone
+
+Open-ended questions support handwritten calculations and drawings. On the computer, open the question and select **סריקת התשובה שלי בטלפון** (“Scan my answer with my phone”). Open the same site or installed Mathly PWA on your phone and sign in to the **same account**. Pending requests appear with the question and attempt identifier; choose one and confirm. Select **צילום התשובה**, allow the camera if asked, review the photograph, and use **צילום מחדש** to retake it before selecting **שליחת התשובה למחשב**. No image is uploaded before submission.
+
+The computer shows waiting, uploading, answer received, upload failed, or request expired. After receipt, it displays the saved image on the original attempt, including after refresh. Receipt means the answer was saved; it does **not** award correctness or mark the skill mastered. Existing multiple-choice practice and photographed-problem AI help remain separate.
+
+Requests last **15 minutes**. A failed upload can be retried on the phone without taking another photo while that page remains open. An expired request offers **יצירת בקשת צילום חדשה** on either device; this keeps the attempt and invalidates the old request. A lost success response can safely be retried. Closing or refreshing the phone page discards an unsubmitted preview. If camera access is denied or capture is cancelled, retry the camera button and allow camera access in the site's browser settings. Camera behavior varies by platform; deploy over **HTTPS** and test on the phones you support.
+
+### Enable private answer storage
+
+1. Configure `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY`, and the **server-only** `SUPABASE_SECRET_KEY` for the same project. Guest practice cannot initiate or access answer scans.
+2. Apply [the additive answer-scan migration](supabase/migrations/20261031133254_math_answer_scans.sql) in that project's SQL editor or your normal migration pipeline. It adds three tables, ownership policies, a service-only transactional RPC, and the private `mathly-answers` bucket. **Do not rerun `docs/mathly-supabase.sql`**, which is the older destructive migration. Back up the target database before applying migrations.
+3. Set `MATHLY_ANSWER_SCANS_ENABLED=1` and restart the app after the migration succeeds. The scan feature needs no AI key. With the flag off or credentials absent, scan APIs fail closed; guest practice and AI problem help still work.
+4. Run `python -m app.answer_cleanup` hourly with the same server environment. It removes unreferenced private objects older than **24 hours** using the Storage API, including images orphaned by failed commits or account/attempt deletion. Referenced answers remain with their attempts; deleting an account/attempt cascades its records and cleanup removes the bytes after the grace period. The maintenance command continues to work when the student-facing feature flag is off. Monitor nonzero cleanup exit codes.
+
+Upload leases last at most **3 minutes**, bounded by request expiry. Interrupted leases become retryable failures on the next status/discovery check. Images are limited to 5 MB JPEG/PNG/WebP, decoded and re-encoded as JPEG to remove metadata, and accessed through owner-checked authenticated endpoints. Images and private storage URLs are never sent to the AI solver. The new flow works across workers and server restarts.
+
+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.
+
+Integration tests use bundled disposable PostgreSQL and local private test blobs, without project credentials or Docker:
+
+```bash
+.venv/bin/python -m pip install -r requirements.txt -r requirements-dev.txt
+.venv/bin/python -m playwright install chromium
+.venv/bin/python -m pytest tests/test_answer_scans.py tests/test_answer_browser.py
+```
+
+See [scan verification](docs/answer-scan-verification.md) for coverage and device checks.

app/answer_cleanup.py

@@ -0,0 +1,21 @@
+"""Run hourly: python -m app.answer_cleanup (same server-only configuration)."""
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from .answer_scans import AnswerScans, ScanError
+from .auth import load_auth
+
+
+def main():
+    load_dotenv(Path(__file__).resolve().parent.parent / '.env')
+    try:
+        # Rollback disables student access, not deletion of orphaned private data.
+        removed = AnswerScans(load_auth(), enabled=True).cleanup()
+    except ScanError as exc:
+        raise SystemExit('Answer cleanup failed: ' + exc.code) from None
+    print(f'Removed {removed} unreferenced answer images.')
+
+
+if __name__ == '__main__':
+    main()

app/answer_routes.py

@@ -0,0 +1,125 @@
+"""Authenticated student-facing API for photographed answers."""
+from __future__ import annotations
+
+import uuid
+
+from fastapi import Depends, File, UploadFile
+from fastapi.responses import JSONResponse, Response
+from starlette.concurrency import run_in_threadpool
+
+from .answer_scans import AnswerScans, MAX_IMAGE, ScanError, clean_image, public_result, uuid_text
+from .math_skills import algebra9, question_version
+
+
+def install_answer_routes(app, signed_in):
+    if not hasattr(app.state, "answers"):
+        app.state.answers = AnswerScans(app.state.auth)
+
+    @app.exception_handler(ScanError)
+    async def scan_error(_request, exc):
+        return JSONResponse({"detail": exc.code}, status_code=exc.status,
+                            headers={"Cache-Control": "no-store"})
+
+    def student(user=Depends(signed_in)):
+        if not user or not user.get("id"):
+            raise ScanError(401, "sign_in_required")
+        if not app.state.answers.configured:
+            raise ScanError(503, "answer_storage_unavailable")
+        return user["id"]
+
+    def call(user, action, **data):
+        return app.state.answers.action(user, action, **data)
+
+    def reply(result):
+        return JSONResponse(public_result(result), headers={"Cache-Control": "no-store"})
+
+    def usable(result):
+        if not result.get("scan"):
+            raise ScanError(404, "not_found")
+        if result["scan"]["state"] == "expired":
+            raise ScanError(410, "expired")
+        return result
+
+    @app.post("/api/math/answer-attempts")
+    def resume_attempt(body: dict, user=Depends(student)):
+        question = next((s for s in algebra9()["skills"] if s["id"] == body.get("question_id")), None)
+        if not question or question["sample"].get("type") != "open-ended":
+            raise ScanError(404, "not_found")
+        sample = question["sample"]
+        version = question_version(sample)
+        if body.get("question_version") != version:
+            raise ScanError(409, "question_changed")
+        return reply(call(user, "resume", question_id=question["id"], question_version=version,
+                          snapshot={"name": question["name"], **sample}, new=body.get("new") is True))
+
+    @app.get("/api/math/answer-attempts/{attempt_id}")
+    def get_attempt(attempt_id: str, user=Depends(student)):
+        return reply(call(user, "get", attempt_id=uuid_text(attempt_id)))
+
+    @app.post("/api/math/answer-attempts/{attempt_id}/scans")
+    def create_scan(attempt_id: str, body: dict, user=Depends(student)):
+        fields = {"attempt_id": uuid_text(attempt_id), "renew": body.get("renew") is True}
+        if "question_id" in body:
+            fields["question_id"] = str(body["question_id"])
+        return reply(call(user, "create_scan", **fields))
+
+    @app.get("/api/math/answer-scans")
+    def pending(user=Depends(student)):
+        return reply(call(user, "pending"))
+
+    @app.get("/api/math/answer-scans/{scan_id}")
+    def get_scan(scan_id: str, user=Depends(student)):
+        return reply(call(user, "get", scan_id=uuid_text(scan_id)))
+
+    @app.post("/api/math/answer-scans/{scan_id}/confirm")
+    def confirm(scan_id: str, user=Depends(student)):
+        return reply(usable(call(user, "confirm", scan_id=uuid_text(scan_id))))
+
+    @app.post("/api/math/answer-scans/{scan_id}/uploads")
+    def begin(scan_id: str, body: dict, user=Depends(student)):
+        result = usable(call(user, "begin", scan_id=uuid_text(scan_id), key=uuid_text(body.get("key"))))
+        response = public_result(result)
+        # Only this authenticated upload operation returns the bounded lease.
+        response["lease_id"] = result["scan"].get("lease_id")
+        return JSONResponse(response, headers={"Cache-Control": "no-store"})
+
+    @app.post("/api/math/answer-scans/{scan_id}/uploads/{lease_id}")
+    async def upload(scan_id: str, lease_id: str, photo: UploadFile = File(...), user=Depends(student)):
+        sid, lease = uuid_text(scan_id), uuid_text(lease_id)
+        data = await photo.read(MAX_IMAGE + 1)
+        return await run_in_threadpool(submit, user, sid, lease, data, photo.content_type)
+
+    def submit(user, sid, lease, data, content_type):
+        result = usable(call(user, "get", scan_id=sid))
+        if result.get("attachment"):
+            return reply(result)  # an earlier response may have been lost
+        scan = result["scan"]
+        if scan["state"] != "uploading" or scan.get("lease_id") != lease:
+            raise ScanError(409, "invalid_upload")
+        try:
+            image = clean_image(data, content_type)
+            object_key = f"{user}/{sid}/{lease}/{uuid.uuid4()}.jpg"
+            app.state.answers.put(object_key, image)
+            result = usable(call(user, "finalize", scan_id=sid, lease_id=lease,
+                                 object_key=object_key, byte_size=len(image)))
+            # Another transfer with the same lease may have finalized first.
+            if result["attachment"]["object_key"] != object_key:
+                try:
+                    app.state.answers.delete(object_key)
+                except ScanError:
+                    pass  # orphan cleanup is safe even after an uncertain response
+            return reply(result)
+        except ScanError:
+            try:
+                call(user, "fail", scan_id=sid, lease_id=lease)
+            except ScanError:
+                pass
+            raise
+
+    @app.get("/api/math/answer-attempts/{attempt_id}/image")
+    def image(attempt_id: str, user=Depends(student)):
+        result = call(user, "get", attempt_id=uuid_text(attempt_id))
+        if not result.get("attachment"):
+            raise ScanError(404, "not_found")
+        return Response(app.state.answers.read(result["attachment"]["object_key"]), media_type="image/jpeg",
+                        headers={"Cache-Control": "no-store", "X-Content-Type-Options": "nosniff"})

app/answer_scans.py

@@ -0,0 +1,132 @@
+"""Durable answer scans. RPC transactions own state; the server owns image access.
+
+No fallback to process memory is allowed. The adapter uses the same Supabase
+project as sign-in; a verified user ID is passed on every student operation.
+"""
+from __future__ import annotations
+
+import io
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+import warnings
+from dataclasses import dataclass
+
+from PIL import Image, ImageOps, UnidentifiedImageError
+
+MAX_IMAGE = 5_000_000
+Image.MAX_IMAGE_PIXELS = 20_000_000
+BUCKET = "mathly-answers"
+
+
+@dataclass
+class ScanError(Exception):
+    status: int
+    code: str
+
+
+def clean_image(data: bytes, content_type: str) -> bytes:
+    if not data:
+        raise ScanError(400, "empty_image")
+    if len(data) > MAX_IMAGE:
+        raise ScanError(413, "image_too_large")
+    if content_type not in ("image/jpeg", "image/png", "image/webp"):
+        raise ScanError(415, "unsupported_image")
+    try:
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", Image.DecompressionBombWarning)
+            with Image.open(io.BytesIO(data)) as source:
+                if source.format not in ("JPEG", "PNG", "WEBP") or source.width * source.height > 20_000_000:
+                    raise ValueError("image dimensions or format")
+                image = ImageOps.exif_transpose(source).convert("RGB")
+                image.thumbnail((2400, 2400))
+                output = io.BytesIO()
+                image.save(output, "JPEG", quality=88)  # drops EXIF, GPS, and embedded metadata
+                result = output.getvalue()
+                if len(result) > MAX_IMAGE:
+                    raise ScanError(413, "image_too_large")
+                return result
+    except (UnidentifiedImageError, OSError, ValueError, Image.DecompressionBombError,
+            Image.DecompressionBombWarning) as exc:
+        raise ScanError(415, "invalid_image") from exc
+
+
+class AnswerScans:
+    def __init__(self, auth, *, enabled=None):
+        self.auth = auth
+        self.enabled = (os.environ.get("MATHLY_ANSWER_SCANS_ENABLED") == "1") if enabled is None else enabled
+
+    @property
+    def configured(self):
+        return bool(self.enabled and self.auth and self.auth.secret)
+
+    def action(self, user_id: str | None, action: str, **data):
+        if not self.configured:
+            raise ScanError(503, "answer_storage_unavailable")
+        body = {"p_user": user_id, "p_action": action, "p_data": data}
+        raw = self._request("/rest/v1/rpc/math_answer_action", "POST", json.dumps(body).encode(), "application/json")
+        return json.loads(raw)
+
+    def _request(self, path, method="GET", data=None, content_type=None):
+        headers = {"Authorization": "Bearer " + self.auth.secret, "apikey": self.auth.secret,
+                   "User-Agent": "mathly/1.0"}
+        if content_type:
+            headers["Content-Type"] = content_type
+        req = urllib.request.Request(self.auth.url + path, data=data, method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=30) as response:
+                return response.read()
+        except urllib.error.HTTPError as exc:
+            # Only recognized database errors become public errors. Never expose SQL or keys.
+            try:
+                error = json.loads(exc.read())
+            except (ValueError, OSError):
+                error = {}
+            code, message = error.get("code"), error.get("message", "")
+            if code == "P0002":
+                raise ScanError(404, "not_found") from exc
+            if code == "P0001" and message in {"superseded", "invalid_upload", "upload_in_progress", "confirmation_required"}:
+                raise ScanError(409, message) from exc
+            raise ScanError(503, "answer_storage_unavailable") from exc
+        except (urllib.error.URLError, TimeoutError, OSError) as exc:
+            raise ScanError(503, "answer_storage_unavailable") from exc
+
+    def put(self, object_key, data):
+        self._request(f"/storage/v1/object/{BUCKET}/{urllib.parse.quote(object_key, safe='/')}",
+                      "POST", data, "image/jpeg")
+
+    def read(self, object_key):
+        return self._request(f"/storage/v1/object/authenticated/{BUCKET}/{urllib.parse.quote(object_key, safe='/')}")
+
+    def delete(self, object_key):
+        self._request(f"/storage/v1/object/{BUCKET}", "DELETE",
+                      json.dumps({"prefixes": [object_key]}).encode(), "application/json")
+
+    def cleanup(self):
+        candidates = self.action(None, "cleanup_candidates")
+        for key in candidates:
+            self.delete(key)
+        return len(candidates)
+
+
+def public_result(result):
+    """Keep storage paths and upload coordination secrets out of public responses."""
+    if isinstance(result, list):
+        return [public_result(item) for item in result]
+    result = {k: dict(v) if isinstance(v, dict) else v for k, v in result.items()}
+    if result.get("scan"):
+        for key in ("idempotency_key", "lease_id", "lease_until"):
+            result["scan"].pop(key, None)
+    if result.get("attachment"):
+        result["attachment"].pop("object_key", None)
+    return result
+
+
+def uuid_text(value):
+    try:
+        return str(uuid.UUID(str(value)))
+    except (ValueError, TypeError, AttributeError) as exc:
+        raise ScanError(404, "not_found") from exc

app/main.py

@@ -17,10 +17,11 @@ from fastapi.staticfiles import StaticFiles
 from starlette.concurrency import run_in_threadpool
 
 from .access import has_permission, resolve_access
+from .answer_routes import install_answer_routes
 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
+from .math_skills import algebra9, practice_graph
 
 logging.basicConfig(level=logging.INFO)
 log = logging.getLogger("mathly")
@@ -97,7 +98,9 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
     async def me(user: dict | None = Depends(signed_in)):
         mine = (user or {}).get("classes", [])
         email = (user or {}).get("email", "")
-        return {"email": email, "roles": (user or {}).get("roles", []),
+        return {"email": email, "user_id": (user or {}).get("id"),
+                "answer_scans": app.state.answers.configured,
+                "roles": (user or {}).get("roles", []),
                 "permissions": (user or {}).get("permissions", []),
                 "teacher": bool((user or {}).get("teacher")),
                 "classes": [{"id": row["id"], "name": row["name"], "lessons": units_of(row),
@@ -105,7 +108,7 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
 
     @app.get("/api/math/skills")
     async def math_skills():
-        return algebra9()
+        return JSONResponse(practice_graph(app.state.answers.configured), headers={"Cache-Control": "no-store"})
 
     @app.get("/api/classes")
     async def classes(_user: dict = Depends(manager)):
@@ -256,6 +259,7 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
         session.update(state="done", result=result)
         return {"ok": True, "readable": result.get("readable", False)}
 
+    install_answer_routes(app, signed_in)
     return app
 
 

app/math_algebra9.json

@@ -1942,6 +1942,19 @@
    ],
    "description": "שטח משולש הוא מחצית מכפלת הבסיס בגובה המאונך לו.",
    "sample": {
+    "question": "במשולש ישר זווית, אורכי הניצבים הם $6$ ס״מ ו־$8$ ס״מ. שרטטו את המשולש, חשבו את שטחו וכתבו את דרך הפתרון על דף.",
+    "diagram": {
+     "type": "triangle",
+     "base": "8 cm",
+     "height": "6 cm",
+     "side": "",
+     "alt": "משולש ישר זווית עם ניצבים באורך 6 ו־8 סנטימטרים"
+    },
+    "type": "open-ended",
+    "version": 1
+   },
+   "core": false,
+   "fallback_sample": {
     "question": "במשולש ישר זווית, אורכי הניצבים הם $6$ ס״מ ו־$8$ ס״מ. מה שטחו?",
     "choices": [
      {
@@ -1964,8 +1977,7 @@
      "side": "",
      "alt": "משולש ישר זווית עם ניצבים באורך 6 ו־8 סנטימטרים"
     }
-   },
-   "core": false
+   }
   },
   {
    "id": "g_pythagoras",

app/math_skills.py

@@ -1,6 +1,7 @@
 """The 9th-grade algebra skill graph for the math path (`math_algebra9.json`).
 
-Each skill names the skills it needs first, a sample question, and for each wrong choice the mistake it shows.
+Each skill names its prerequisites and a sample question. Choice samples identify mistakes;
+open-ended samples name their type and revision and accept a photographed answer.
 A mistake sends the student back to the skill it comes from (`back`), or keeps them on the same skill (`null`).
 The graph follows the Ministry of Education's 9th-grade teaching schedule (2026/27) and the summer review for
 students placed in 5 units; `core` marks what that review stresses. The questions are written for the app, and
@@ -11,12 +12,20 @@ every skill, link and mistake still needs a 5-unit teacher's review.
 from __future__ import annotations
 
 import json
+import hashlib
+import copy
 from functools import cache
 from pathlib import Path
 
 GRAPH = Path(__file__).with_name("math_algebra9.json")
 
 
+def question_version(sample: dict) -> str:
+    """Bind attempts to the complete prompt, including its diagram and revision."""
+    return hashlib.sha256(json.dumps(sample, ensure_ascii=False, sort_keys=True,
+                                    separators=(",", ":")).encode()).hexdigest()
+
+
 def problems(graph: dict) -> list[str]:
     """What is wrong with a graph: unknown units, skills or mistakes, a cycle, a link implied by another,
     a question without exactly one right answer, or a mistake that sends the student to a skill that is not before it."""
@@ -43,7 +52,20 @@ def problems(graph: dict) -> list[str]:
         return [f"cycle: {cycle}"]
     for s in skills.values():
         out += [f"{s['id']}: {p} is implied by {q}" for p in s["prereqs"] for q in s["prereqs"] if p != q and p in below[q]]
-        choices = s["sample"]["choices"]
+        sample = s["sample"]
+        kind = sample.get("type", "multiple-choice")
+        if kind not in ("open-ended", "multiple-choice"):
+            out.append(f"{s['id']}: unknown question type {kind}")
+            continue
+        if kind == "open-ended":
+            if "choices" in sample:
+                out.append(f"{s['id']}: open-ended questions cannot have choices")
+            if not isinstance(sample.get("question"), str) or not sample["question"].strip():
+                out.append(f"{s['id']}: question text is required")
+            if type(sample.get("version")) is not int or sample["version"] < 1:
+                out.append(f"{s['id']}: positive question version is required")
+            continue
+        choices = sample.get("choices", [])
         if sum(bool(c.get("correct")) for c in choices) != 1:
             out.append(f"{s['id']}: needs exactly one correct choice")
         if len({c["text"] for c in choices}) != len(choices):
@@ -66,3 +88,18 @@ def algebra9() -> dict:
     if found := problems(graph):
         raise ValueError(f"{GRAPH.name}: " + "; ".join(found))
     return graph
+
+
+def practice_graph(answer_scans_enabled: bool) -> dict:
+    """Keep practice usable during a scan rollout or rollback.
+
+    Public responses never expose fallback choices for an open-ended question.
+    The original choice sample is served when authenticated storage is disabled.
+    """
+    graph = copy.deepcopy(algebra9())
+    for skill in graph["skills"]:
+        fallback = skill.pop("fallback_sample", None)
+        if not answer_scans_enabled and fallback is not None:
+            skill["sample"] = fallback
+        skill["question_version"] = question_version(skill["sample"])
+    return graph

docs/answer-scan-verification.md

@@ -0,0 +1,42 @@
+# Answer scan verification
+
+The automated database tests run the actual additive migration in disposable PostgreSQL. Auth and Storage metadata schemas are minimal local fixtures; private test image bytes are stored on disk. No hosted Supabase project is modified. Storage HTTP requests have separate adapter contract tests; live deployment must still verify the hosted bucket and API configuration.
+
+| Contract | Automated verification |
+| --- | --- |
+| Open-ended rendering; existing choices | Graph validation and desktop browser checks |
+| Stable owned attempt; content changes | API and real database tests |
+| Same-account discovery; several requests | Two independent browser contexts and database tests |
+| Confirm before camera; review and retake | Mobile browser capture simulation |
+| Private requests and images | API, RLS, service-only RPC, and restrictive Storage policies, including a pre-existing permissive policy |
+| Waiting/uploading/received/failure/expiry | API state checks and desktop/mobile browser checks |
+| Lost response; concurrent finalization | Idempotency and real PostgreSQL concurrent connection tests |
+| Expiry, stale lease, renewal | Server-clock database and API tests |
+| Restart persistence; deletion cleanup | New application instance against the same database and private files |
+| No grading or mastery from upload | Browser progress assertion |
+| AI solver remains independent | Existing photo API and phone browser regressions |
+
+## Local verification record — 2026-10-31
+
+- Full suite: `.venv/bin/python -m pytest -q` — **28 passed**, including three new desktop/mobile browser tests and the existing phone-solver browser regression.
+- The actual migration was applied through the Supabase CLI to a disposable PostgreSQL database with local Auth/Storage metadata fixtures. The pre-existing class row was preserved. Local `supabase db advisors` returned no issues; migration listing recognized the generated file.
+- Verified rollback by disabling scan access: APIs fail closed and the skills endpoint serves the original choice question. Re-enabling restores the open question and access to the same saved image; class and answer records remain intact.
+- Browser tests use separate account contexts with an SDK sign-in stub; app APIs, ownership checks, PostgreSQL transactions, and private file reads run normally. They cover several pending requests, confirmation/cancellation, review/retake, upload failure, lost success response, reconnect, expiry/renewal, question switching, reload, and account change. The question version from the displayed graph is sent with attempt creation.
+- Image orientation and metadata stripping are checked using actual JPEG EXIF data. Concurrent finalization and renewal run on independent PostgreSQL connections. Storage request methods, paths, headers, and error redaction have adapter contract coverage.
+- JavaScript syntax, Python compilation, `git diff --check`, and strict OpenSpec validation pass.
+- No hosted migration, live Supabase OAuth/Storage test, or physical iOS/Android camera/PWA test was performed. Tasks 4.2 and 4.4 retain open checkboxes for the real-device checks below, despite their capture UI and documentation being implemented.
+
+## Real-phone smoke check
+
+This is a manual checklist, not a claim that physical devices have been tested. Serve the migrated app over HTTPS with answer scanning enabled, and record device/browser versions and the result.
+
+1. On a computer sign in, open the triangle-area open question, and request a scan.
+2. On an actual phone/PWA sign in as the same student. Verify automatic pending-request discovery and correct question/attempt context.
+3. Decline confirmation: no camera or permission prompt should appear. Reopen and confirm; then select the camera button.
+4. Deny camera permission or cancel capture. Verify guidance and that the request remains available. Enable camera access and retry. Some mobile browsers use an OS capture picker rather than exposing a web camera permission prompt.
+5. Photograph a page in portrait and landscape; verify orientation and legibility. Retake and check that only the new preview is submitted.
+6. Interrupt network access during upload; restore access and retry. Check that the computer displays one attached answer on the original attempt and that the phone confirms success.
+7. Sign out and use a different student account: the old request and image must not appear. Repeat on a second computer tab with a different question to check association.
+8. Let a request expire or shorten its expiry in an isolated test project; renew and complete the same attempt.
+
+Physical camera permissions, OS picker behavior, and installed-PWA resume must be checked on supported iOS/Safari and Android/Chrome releases. Browser automation supplies image files and simulates cancellation; it cannot certify those OS interactions.

openspec/changes/add-open-question-phone-scan/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-10-31

openspec/changes/add-open-question-phone-scan/design.md

@@ -0,0 +1,63 @@
+# Design
+
+## Context
+
+See proposal.md for motivation. `app/math_skills.py` requires sample choices; `static/math.js` rotates them unconditionally and keeps progress and try counts in localStorage. There is no persistent question-attempt model. `app/main.py` stores existing photo sessions in memory for 15 minutes; phone uploads authenticate through a bearer link, invoke the AI solver, and retain no image. That flow cannot provide account-only discovery or durable answer attachments.
+
+The repository contains a responsive web app with a PWA manifest, not a native mobile project. This design treats the signed-in mobile web/PWA as the Mathly phone app. Existing Supabase authentication exposes a stable user ID. The current database script is destructive and must not be reused for this addition.
+
+## Goals / Non-Goals
+
+**Goals:** Durable cross-device association; ownership enforced at every boundary; correct behavior under refresh, retry, concurrency, and lost responses; no AI dependency for capture.
+
+**Non-Goals:** Native iOS/Android clients, background push notifications, OCR, automatic grading, teacher review, multiple-page answers, and changing existing multiple-choice mastery behavior. One photograph is accepted per scan request.
+
+## Decisions
+
+### Explicit question type and stable attempts
+
+Add `sample.type: open-ended`; missing type continues to mean multiple-choice. Validate each variant separately. Open-ended samples have no choices and may retain a diagram. Use skill ID plus sample content version as question identity; persist a prompt snapshot/version on an attempt so later content edits cannot silently change what was answered. Add an original geometry sample exercising this variant.
+
+Create `math_question_attempts` with UUID ID, user ID, question ID/version, snapshot, submission status, and timestamps. Resume the owner's active attempt; an explicit new attempt produces a separate ID. Do not treat upload receipt as a correct answer or update mastery. Keeping only local try counts was rejected because another device cannot reliably associate them.
+
+### Additive Supabase persistence and private storage
+
+Add `math_answer_scans` (ID, immutable owner/attempt references, state, expiry, generation, upload lease, timestamps, safe error code) and `math_answer_attachments` (ID, owner, attempt, unique scan ID, private object key, validated media type/size, timestamps). Use composite ownership constraints or equivalent transactional checks to prevent owner/attempt mismatches. Enforce one active scan per attempt and one committed answer per attempt in this first version. Other attempts can have independent pending scans.
+
+Use a private answer-image bucket with server-generated object paths. Enable RLS on new exposed tables, owner-scoped SELECT policies using `auth.uid()`, and deny direct client writes to scan state and attachments. FastAPI validates user ownership and executes narrowly scoped server-side mutations; privileged credentials stay on the server. No user-editable metadata or email-based ownership checks. Serve image bytes through an authenticated owner-checking endpoint with `Cache-Control: no-store`; avoid public or reusable signed image links. Restrict Storage access to the trusted server path and explicit owner reads only if needed.
+
+This follows current [Supabase private bucket guidance](https://supabase.com/docs/guides/storage/buckets/fundamentals) and [Storage access controls](https://supabase.com/docs/guides/storage/security/access-control). In-memory state was rejected because restarts and multiple workers would lose or disagree about attachments. Reusing the existing bearer-link upload was rejected because possession of its token authorizes another phone.
+
+### Authenticated request API and state machine
+
+Add APIs for creating/resuming attempts; creating a scan under an owned attempt; listing the signed-in student's pending scans; reading and confirming a selected scan; beginning and submitting an upload; renewing an expired scan; and reading the attempt attachment. All routes require real authenticated identity even when the deployment otherwise permits guest practice. Unknown and foreign IDs return the same not-found response; unauthenticated access returns sign-in-required. Disabled storage returns a configuration error, never a local-memory substitute.
+
+Persist states `waiting`, `confirmed`, `uploading`, `received`, `failed`, `expired`, and `superseded`. Map waiting/confirmed to Waiting for phone. Requests expire 15 minutes after creation by server time. Discover pending requests on mobile app entry and foreground resume, with bounded polling while open. Show question text and attempt context in a chooser when several requests exist. Desktop polls the selected attempt every two seconds while visible, backs off on errors, and refreshes immediately on resume. Responses are private and uncached. Polling fits the current stack; Realtime and push add infrastructure without being necessary for foreground discovery.
+
+Confirmation is an authenticated transition. Camera access is invoked only from the subsequent student gesture using the phone's capture picker, requesting permission only as the browser requires. Reuse the existing image orientation, compression, and preview techniques without changing the solver endpoints. Retakes stay local until explicit submission. Permission denial or picker cancellation leaves the request resumable. Use HTTPS in deployment for camera support.
+
+### Observable upload, idempotency, and races
+
+Before transferring bytes, the phone begins an upload with an idempotency key; this persists `uploading` so the computer sees transfer status. A conditional database update grants a bounded upload lease to one submission. Use existing 5 MB JPEG/PNG/WebP limits, validate actual decoded image content and dimensions server-side, and strip metadata through re-encoding. Never trust a client-supplied object path, owner, question, or attempt during upload.
+
+Store the image privately, then atomically insert the attachment and transition the matching scan generation to `received` after rechecking ownership, lease, expiry, and active attempt. A database transaction/function must enforce these conditions across workers; Python check-then-write is insufficient. Where a privileged database function is necessary, keep it unexposed, revoke PUBLIC execution, pin its search path, and restrict execution to the backend role. It is not a public authorization bypass.
+
+Return success only after commit. Lost-response retries query the existing result and return the same attachment; another in-flight submission gets a conflict and refreshes status. A failed commit deletes the staged object when possible; periodic cleanup removes unreferenced objects. An abandoned upload lease becomes failed and retryable while its request is valid. Requests past expiry become expired, including stale uploads; finalization cannot accept them.
+
+Retry of an unexpired failed request uses the same attempt and a new lease. Renewal supersedes the prior request and creates a new 15-minute generation for that attempt. Reject late commits from older generations; serialize renewal and completion on the attempt so only one wins. Never replace a received answer through scan retry. The preview stays available in the phone page after transient failure; no offline image persistence is introduced.
+
+## Risks / Trade-offs
+
+- Storage and database commits are separate → stage objects, finalize transactionally, and clean orphans; report success only after finalization.
+- Browser camera behavior varies → preserve capture picker fallback, test denial/cancellation on target devices, and document HTTPS requirements.
+- Polling adds requests → pause when hidden and back off; status resumes on foreground entry.
+- Guest mode lacks account ownership → keep guest practice available but require sign-in for answer scans.
+- New persistent handwritten images change data retention → retain committed images with their attempts, cascade user/attempt deletion through a cleanup process, and purge unreferenced staging images after 24 hours. No images enter the AI solver or diagnostic logs.
+
+## Migration Plan
+
+1. Generate a separate additive migration for the new tables, constraints, indexes, functions, grants, RLS, and private bucket. Do not rerun `docs/mathly-supabase.sql`.
+2. Verify ownership policies with two test accounts and unauthenticated callers, including direct table/storage access. Verify conditional finalization and renewal with concurrent requests.
+3. Deploy backend and mobile/desktop UI together; expose capture only when authenticated answer storage is configured. Add one open-ended geometry sample after compatible rendering is deployed.
+4. Run the API and browser acceptance suite plus existing choice and photo-solver regressions. Document setup, TTLs, cleanup, and retention in README.
+5. Roll back by disabling `MATHLY_ANSWER_SCANS_ENABLED`; the skills endpoint then serves the retained original choice sample for compatibility with guest practice and older frontends. Preserve new tables and private objects for recovery. No existing tables or solver sessions need migration. Cleanup remains available with server credentials while student scanning is disabled.

openspec/changes/add-open-question-phone-scan/proposal.md

@@ -0,0 +1,33 @@
+# Proposal
+
+## Why
+
+Students need to submit handwritten reasoning and drawings for open-ended questions. Mathly currently offers multiple-choice practice and phone-based AI problem solving, but cannot securely attach a student's photographed answer to the correct question attempt.
+
+## What Changes
+
+- Support open-ended question samples without predefined answer options.
+- Add persistent, student-owned question attempts and answer attachments.
+- Let a student request a phone scan from an open question and discover pending requests in the mobile app after signing in to the same account.
+- Require confirmation before camera access, offer preview and retake, and confirm successful submission on both devices.
+- Show waiting, uploading, received, failure, and expiry states; allow safe retries without duplicate attachments or association with a different attempt.
+- Keep the existing photographed-problem solver available as a separate flow.
+
+## Capabilities
+
+### New Capabilities
+
+- `open-question-answers`: Open-ended question rendering, owned attempts, and persistent photographed answer attachments.
+- `phone-answer-scans`: Same-account request discovery, confirmation, capture, submission, status synchronization, expiry, and retries.
+
+### Modified Capabilities
+
+None. This repository has no main capability specifications yet.
+
+## Impact
+
+- Question validation in `app/math_skills.py`, sample content, and question rendering in `static/math.js`.
+- Authenticated attempt and scan APIs in `app/main.py` with a dedicated persistence module.
+- Existing account integration in `app/auth.py`, mobile/PWA entry in `static/index.html`, and reusable photo preparation from `static/phone.js`.
+- Additive Supabase tables and private image storage; use a separate migration rather than rerunning the destructive `docs/mathly-supabase.sql` script.
+- API, ownership, concurrency, and desktop/mobile browser coverage alongside current phone-solver tests.

openspec/changes/add-open-question-phone-scan/specs/open-question-answers/spec.md

@@ -0,0 +1,57 @@
+# Spec Delta
+
+## Purpose
+
+Allow students to answer questions requiring handwritten reasoning or drawings and retain a private photographed answer on the correct question attempt.
+
+## ADDED Requirements
+
+### Requirement: Open-ended question presentation
+The system SHALL support open-ended questions without predefined answer options and SHALL offer “Scan my answer with my phone” on those questions, using localized text where appropriate.
+
+#### Scenario: Open a geometry question
+- **WHEN** a student opens an open-ended geometry question
+- **THEN** the question and any diagram appear without answer-choice controls
+- **AND** the student can initiate a phone scan
+
+#### Scenario: Existing choice question
+- **WHEN** a student opens an existing multiple-choice question
+- **THEN** its answer choices and feedback continue to work
+
+### Requirement: Stable student question attempts
+The system SHALL give each open-ended attempt a stable identity owned by the authenticated student and bound to the question and its content version. The system SHALL verify ownership before creating a scan or attaching an answer.
+
+#### Scenario: Resume the same attempt
+- **WHEN** the student reloads an open-ended question with an active attempt
+- **THEN** the system restores that attempt and its scan or attached answer
+
+#### Scenario: Reject a foreign or mismatched attempt
+- **WHEN** a student requests a scan using another student's attempt or a different question identifier
+- **THEN** the system rejects the request without revealing the other student's data
+
+### Requirement: Private durable answer attachment
+The system SHALL retain a submitted photograph as an answer attachment to its original student, question, and attempt. Only that student SHALL be able to retrieve the photograph through the student-facing flow. Upload confirmation SHALL occur only after both image storage and attachment persistence succeed.
+
+#### Scenario: Submission succeeds
+- **WHEN** a confirmed scan submission completes successfully
+- **THEN** the photograph appears on its original question attempt on the computer
+- **AND** both devices confirm successful upload
+
+#### Scenario: Navigate to another question
+- **WHEN** the student changes questions before an upload completes
+- **THEN** the received answer remains attached exclusively to the original attempt
+
+#### Scenario: Restart after submission
+- **WHEN** the server restarts and the student reopens a submitted attempt
+- **THEN** the saved answer remains accessible to its owner
+
+#### Scenario: Photograph access by another account
+- **WHEN** another account requests an attachment or its image
+- **THEN** access is denied without revealing the attachment contents
+
+### Requirement: Submission does not imply correctness
+The system SHALL distinguish answer receipt from grading and SHALL NOT mark an open-ended answer correct or a skill mastered solely because a photograph was uploaded.
+
+#### Scenario: Answer received without grading
+- **WHEN** a photograph is attached successfully
+- **THEN** the attempt displays an answer-received state without automatically awarding correctness or mastery

openspec/changes/add-open-question-phone-scan/specs/phone-answer-scans/spec.md

@@ -0,0 +1,90 @@
+# Spec Delta
+
+## Purpose
+
+Coordinate a private phone capture with a computer question attempt so students can safely submit handwritten answers across devices using the same account.
+
+## ADDED Requirements
+
+### Requirement: Owned scan request and mobile discovery
+The system SHALL create a scan request only for the signed-in student's open-ended attempt and SHALL allow only that student to discover, inspect, confirm, upload to, or retry it. Opening the mobile app signed in to the same account SHALL discover pending requests without requiring a pairing link.
+
+#### Scenario: Same account opens the phone app
+- **WHEN** a student initiates a scan on the computer and opens the mobile app with the same account
+- **THEN** the phone offers the pending request with enough question context to identify its attempt
+
+#### Scenario: Several pending questions
+- **WHEN** the student has pending requests for multiple question attempts
+- **THEN** the mobile app lets the student select a request by its question and attempt context
+- **AND** confirmation and upload apply only to that selected request
+
+#### Scenario: Different or missing account
+- **WHEN** another student or an unauthenticated caller attempts to discover or access the request
+- **THEN** the system exposes no request or answer data
+- **AND** knowing a request identifier does not grant access
+
+### Requirement: Confirm before camera access
+The mobile app SHALL ask the student to confirm the selected scan before invoking camera capture or requesting camera permission. Denial or cancellation SHALL leave the answer unsubmitted and provide a way to try again.
+
+#### Scenario: Confirmation accepted
+- **WHEN** the student confirms the selected request
+- **THEN** the app opens camera capture and requests permission if the platform requires it
+
+#### Scenario: Confirmation declined
+- **WHEN** the student declines confirmation
+- **THEN** the app does not open the camera or request camera permission
+- **AND** no answer is uploaded
+
+#### Scenario: Camera permission denied
+- **WHEN** camera access is denied or capture is cancelled
+- **THEN** the app explains how to retry and leaves the attempt without a submitted photograph
+
+### Requirement: Review and retake before submission
+The mobile app SHALL display a captured photograph for review, SHALL allow retaking it, and SHALL upload only after an explicit submit action.
+
+#### Scenario: Retake the photograph
+- **WHEN** the student retakes a photograph on the review screen
+- **THEN** the new capture replaces the local preview
+- **AND** neither capture is submitted until the student selects submit
+
+### Requirement: Shared status and upload feedback
+The computer SHALL display Waiting for phone, Uploading, Answer received, Upload failed, or Request expired as appropriate. Status SHALL be associated with the original attempt and restored after reconnection. Both devices SHALL confirm success only when the answer is durably attached.
+
+#### Scenario: Upload begins and finishes
+- **WHEN** the student submits the reviewed photograph
+- **THEN** the computer displays Uploading while the transfer is active
+- **AND** displays Answer received with the attachment after successful completion
+
+#### Scenario: Network interruption
+- **WHEN** upload or persistence fails
+- **THEN** the system displays Upload failed once the failure is detected
+- **AND** the phone retains the preview for retry while its page remains open
+- **AND** the computer resumes authoritative status checks after reconnection
+
+### Requirement: Expiry and safe retries
+The system SHALL expire unused scan requests after 15 minutes and reject new submissions to expired or superseded requests. The student SHALL be able to retry a failed upload or replace an expired request for the same attempt. Repeated or concurrent submissions SHALL create at most one answer attachment for a request.
+
+#### Scenario: Expired request
+- **WHEN** the student submits to a request after its expiry
+- **THEN** the system rejects the upload and offers a fresh request for the same attempt
+- **AND** the replacement invalidates the expired request
+
+#### Scenario: Upload retry after failure
+- **WHEN** the student retries a failed upload on an unexpired request
+- **THEN** the system retries attachment to the original attempt without creating a new attempt
+
+#### Scenario: Success response was lost
+- **WHEN** the phone repeats a submission that already completed
+- **THEN** the system reports the existing successful attachment without duplicating it
+
+#### Scenario: Concurrent or superseded upload
+- **WHEN** two phones submit to one request or an older request finishes after replacement
+- **THEN** at most one valid attachment is committed
+- **AND** the obsolete submission cannot overwrite the accepted answer
+
+### Requirement: Answer capture is independent of the solver
+The system SHALL support answer scanning without an AI solver key. The existing photographed-problem solving flow SHALL remain usable with its established configuration and behavior.
+
+#### Scenario: AI is not configured
+- **WHEN** a signed-in student requests an answer scan without an AI solver key configured
+- **THEN** scan capture and attachment remain available when answer storage is configured

openspec/changes/add-open-question-phone-scan/tasks.md

@@ -0,0 +1,36 @@
+# Tasks
+
+## 1. Question model and owned attempts
+
+- [x] 1.1 Add open-ended sample typing and version identity in `app/math_skills.py`; extend `tests/test_math_skills.py` to accept open-ended samples without choices and reject malformed variants while retaining existing choice validation.
+- [x] 1.2 Generate a separate additive Supabase migration for attempts, scans, attachments, ownership constraints, indexes, RLS, grants, and private storage; verify clean application in a disposable database and confirm existing class data remains intact.
+- [x] 1.3 Add a persistence adapter and authenticated create/resume/read attempt endpoints using stable user IDs; verify same-account resume, version changes, forged question IDs, foreign ownership, and guest rejection with API tests.
+- [x] 1.4 Document storage/auth setup and the additive migration in README; verify setup steps against the disposable environment without rerunning the destructive legacy script.
+
+## 2. Request lifecycle and durable attachment
+
+- [x] 2.1 Implement create/discover/read/confirm/renew scan APIs with server-clock expiry and generation checks; verify two-account isolation, missing authentication, several pending attempts, expiry, and supersession through API tests.
+- [x] 2.2 Implement begin-upload leases, idempotency, image validation/re-encoding, private object storage, and transactional finalization; verify valid image attachment, invalid/oversized data, storage failure, and commit failure without false success.
+- [x] 2.3 Enforce serialization of renewal and finalization plus unique attachments across workers; verify concurrent submissions, stale leases, late old-generation commits, and lost-response retries using database integration tests.
+- [x] 2.4 Add authenticated image retrieval and staging/deletion cleanup; verify foreign and unauthenticated reads fail through API and direct table/storage access, accepted attachments survive a restart, and orphan images are purged without deleting referenced images.
+- [x] 2.5 Document states, 15-minute expiry, lease timeout, errors, cleanup operation, and image retention; verify examples against endpoint responses and ensure no AI key is required for scans.
+
+## 3. Desktop open-ended question flow
+
+- [x] 3.1 Render open-ended questions and diagrams without rotating or displaying choices in `static/math.js`; add a versioned geometry sample and verify browser rendering plus existing multiple-choice feedback and mastery behavior.
+- [x] 3.2 Add the localized scan action, attempt restoration, polling, status messages, attachment preview, and failure/expiry retry controls; verify waiting/uploading/received/failed/expired states and question switching in browser tests without attaching an answer to the currently displayed wrong question.
+- [x] 3.3 Handle desktop refresh, hidden tabs, reconnect, and sign-out safely; verify polling resumes with server state and no previous-account request or photograph remains visible after account changes.
+- [x] 3.4 Document the desktop flow and answer-received versus correctness distinction in README; verify displayed copy and screenshots or browser assertions match the instructions.
+
+## 4. Mobile discovery and camera flow
+
+- [x] 4.1 Add authenticated pending-request discovery on mobile/PWA entry and foreground resume, with question/attempt selection and explicit confirmation; verify same-account discovery, multiple requests, wrong-account isolation, and no camera invocation before confirmation.
+- [ ] 4.2 Reuse photo preparation for camera capture, review, retake, and explicit submit with localized accessible controls; verify cancellation, denied permission, rotated images, replacement previews, and no upload before submit in browser tests and a documented phone smoke check.
+- [x] 4.3 Connect begin/upload/retry/renew actions, retain the local preview after transient failure, and display durable success; verify upload failures, expired requests, duplicate taps, lost responses, and page resume with two independent browser contexts.
+- [ ] 4.4 Document mobile sign-in, confirmation, permission recovery, HTTPS, and retry behavior; verify the documented happy path on the mobile web/PWA and record browser-specific camera limitations.
+
+## 5. Integrated acceptance
+
+- [x] 5.1 Run a complete two-device same-account scan to the original geometry attempt and a second-account rejection case; verify every scenario in both capability specs with API, database, browser, or recorded manual evidence.
+- [x] 5.2 Run the existing pytest suite and phone browser regressions alongside new checks; verify existing photographed-problem solving remains independent and functional and that answer upload never awards correctness or mastery.
+- [x] 5.3 Rehearse additive deployment and rollback in a disposable environment; verify private answers remain recoverable, rollback hides unsupported open-ended content, and no production data or legacy tables are deleted.

openspec/config.yaml

@@ -0,0 +1 @@
+schema: spec-driven

requirements-dev.txt

@@ -2,3 +2,7 @@ fastapi>=0.110
 python-multipart>=0.0.9
 httpx>=0.27
 pytest>=8
+# Optional local PostgreSQL integration checks (bundled server; no Docker or project credentials).
+pgserver==0.1.4; sys_platform == 'linux'
+psycopg[binary]==3.3.6
+playwright==1.64.1

requirements.txt

@@ -6,3 +6,4 @@ python-dotenv>=1.0
 qrcode>=7.4,<9
 anthropic>=1.0  # photographed-problem hints and solutions
 tzdata>=2024.1
+Pillow==12.3.0  # validate and strip metadata; compatible with Python 3.10 and 3.11

static/answer-scans.js

@@ -0,0 +1,190 @@
+/* Same-account handwritten answers. Every async continuation checks its account
+   and view before changing the UI. The server is authoritative for all states. */
+(()=>{
+const esc=s=>String(s??"").replace(/[&<>"']/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[c]));
+const fmt=s=>esc(s).replace(/\$([^$]+)\$/g,'<span class="m">$1</span>');
+const states={waiting:"ממתינים לטלפון",confirmed:"ממתינים לטלפון",uploading:"מעלים את התשובה…",received:"התשובה התקבלה",failed:"ההעלאה נכשלה",expired:"בקשת הצילום פגה",superseded:"הבקשה הוחלפה"};
+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:"יש להיכנס לאותו חשבון בשני המכשירים."};
+let api=null,account=null,epoch=0,question=null,inbox=null,inboxTimer=null,inboxPoll=null,capture=null,visibleRoot=null;
+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;}
+  return d;
+}
+const post=(url,body={})=>json(url,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(body)});
+function closeQuestion(){
+  if(question){clearTimeout(question.timer);if(question.image)URL.revokeObjectURL(question.image);question=null;}
+}
+function closeCapture(){
+  if(capture){if(capture.url)URL.revokeObjectURL(capture.url);capture.node.remove();capture.returnFocus?.focus?.();capture=null;}
+}
+function reset(){
+  epoch++;if(question)question.node.replaceChildren();closeQuestion();closeCapture();clearTimeout(inboxTimer);inboxTimer=null;
+  inbox?.remove();inbox=null;account=null;
+}
+function configure(options){
+  reset();api=options.api;account=options.enabled?options.account:null;visibleRoot=options.root;
+  if(!account)return;
+  // Foreground discovery is available in the responsive phone app/PWA.
+  if(matchMedia("(max-width: 700px)").matches||navigator.maxTouchPoints){
+    inbox=document.createElement("section");inbox.className="mx-scan-inbox mx-wrap";
+    inbox.setAttribute("aria-label","בקשות לצילום תשובה");visibleRoot.prepend(inbox);pollInbox(epoch);
+  }
+}
+async function pollInbox(e){
+  clearTimeout(inboxTimer);if(!live(e)||!inbox||inboxPoll===e)return;
+  if(document.hidden){inboxTimer=setTimeout(()=>pollInbox(e),5000);return;}
+  inboxPoll=e;
+  let delay=5000;
+  try{
+    const list=await json("/api/math/answer-scans");if(!live(e)||!inbox)return;
+    const signature=JSON.stringify(list.map(r=>[r.scan.id,r.scan.state]));
+    if(inbox.dataset.signature!==signature){
+      inbox.dataset.signature=signature;
+      inbox.innerHTML=list.length?`<h2>בקשות לצילום תשובה</h2>${list.map((r,i)=>`<button class="mx-btn" data-scan-index="${i}"><b>${fmt(r.attempt.snapshot.question)}</b><small>ניסיון ${esc(r.attempt.id.slice(0,8))} · ${esc(states[r.scan.state])}</small></button>`).join("")}`:"";
+      inbox.querySelectorAll("[data-scan-index]").forEach(button=>button.onclick=()=>openCapture(list[Number(button.dataset.scanIndex)]));
+    }
+  }catch(error){
+    if(!live(e))return;
+    if(error.status===401){reset();return;}
+    if(inbox){inbox.textContent="לא ניתן לבדוק בקשות צילום כרגע. מנסים שוב…";delete inbox.dataset.signature;}delay=15000;
+  }finally{if(inboxPoll===e)inboxPoll=null;}
+  if(live(e))inboxTimer=setTimeout(()=>pollInbox(e),delay);
+}
+async function mountQuestion(node,id,version){
+  closeQuestion();const e=epoch;
+  if(!account){node.innerHTML='<p>כדי לסרוק תשובה בטלפון, היכנסו לאותו חשבון בשני המכשירים. שמירת תשובות צריכה להיות זמינה באתר.</p>';return;}
+  const q=question={node,id,e,timer:null,image:null,busy:false,result:null};
+  node.innerHTML='<p role="status">טוענים את ניסיון התשובה…</p>';
+  try{const r=await post("/api/math/answer-attempts",{question_id:id,question_version:version});if(!current(q))return;q.result=r;await renderQuestion(q);schedule(q);}
+  catch(error){if(current(q)){node.innerHTML=`<p role="status">${esc(error.message)}</p><button class="mx-btn" data-reload>ניסיון נוסף</button>`;node.querySelector("button").onclick=()=>error.code==="question_changed"?location.reload():mountQuestion(node,id,version);}}
+}
+const current=q=>question===q&&live(q.e)&&q.node.isConnected;
+function schedule(q,delay=2000){clearTimeout(q.timer);if(current(q))q.timer=setTimeout(()=>pollQuestion(q),delay);}
+async function pollQuestion(q){
+  if(!current(q)||q.polling)return;
+  if(document.hidden){schedule(q,5000);return;}
+  q.polling=true;
+  try{
+    const r=await json(`/api/math/answer-attempts/${q.result.attempt.id}`);if(!current(q))return;
+    q.result=r;await renderQuestion(q);schedule(q);
+  }catch(error){if(current(q)){q.node.querySelector("[role=status]").textContent=error.message;schedule(q,8000);}}
+  finally{q.polling=false;}
+}
+async function renderQuestion(q){
+  if(!current(q))return;
+  const r=q.result,s=r.scan,state=s?.state,received=!!r.attachment;
+  // Rebuilding controls on every poll would steal focus and race a button click.
+  const signature=[state,r.attachment?.id].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(states[state]||"כתבו את הפתרון על דף וצלמו אותו בטלפון.")}</p>
+      ${received?'<p>התמונה נשמרה כתשובה. היא עדיין לא נבדקה.</p><img class="mx-answer-image" alt="התשובה המצולמת שלכם" hidden>':`<button class="mx-btn solid" data-request>${s?["expired","superseded"].includes(state)?"יצירת בקשת צילום חדשה":state==="failed"?"ניסיון נוסף":"פתחו את Mathly בטלפון באותו חשבון":"סריקת התשובה שלי בטלפון"}</button>`}`;
+    if(!received){
+      const b=q.node.querySelector("[data-request]");b.disabled=["uploading","waiting","confirmed"].includes(state);
+      b.onclick=async()=>{
+        b.disabled=true;
+        try{const result=await post(`/api/math/answer-attempts/${r.attempt.id}/scans`,{question_id:q.id,renew:["expired","superseded","failed"].includes(state)});
+          if(!current(q))return;q.result=result;q.signature=null;await renderQuestion(q);schedule(q);}
+        catch(error){if(current(q)){q.node.querySelector("[role=status]").textContent=error.message;b.disabled=false;}}
+      };
+    }
+  }else q.node.querySelector("[role=status]").textContent=states[state]||"כתבו את הפתרון על דף וצלמו אותו בטלפון.";
+  if(received&&!q.image&&!q.loadingImage){
+    q.loadingImage=true;
+    try{
+      const response=await api(`/api/math/answer-attempts/${r.attempt.id}/image`,{cache:"no-store"});
+      if(!response.ok)throw Error("לא ניתן לטעון את התמונה. מנסים שוב…");
+      const blob=await response.blob();if(!current(q))return;
+      q.image=URL.createObjectURL(blob);const img=q.node.querySelector("img");
+      img.onload=()=>{if(current(q))img.hidden=false;};img.src=q.image;
+    }catch(error){if(current(q))q.node.querySelector("[role=status]").textContent=error.message;}
+    finally{q.loadingImage=false;}
+  }else if(q.image&&q.node.querySelector("img"))q.node.querySelector("img").src=q.image;
+}
+function openCapture(result){
+  closeCapture();const e=epoch;
+  if(!live(e))return;
+  const node=document.createElement("div");node.className="mx-scan-overlay";node.setAttribute("role","dialog");node.setAttribute("aria-modal","true");node.setAttribute("aria-labelledby","scanTitle");
+  node.innerHTML=`<div class="mx-scan-card"><button class="mx-btn" data-close>סגירה</button><h2 id="scanTitle">צילום תשובה</h2>
+    <p>${fmt(result.attempt.snapshot.question)}</p><small>ניסיון ${esc(result.attempt.id.slice(0,8))}</small>
+    <p data-status role="status" aria-live="polite">האם לצלם תשובה לשאלה הזו?</p>
+    <button class="mx-btn solid" data-confirm>כן, אני רוצה לצלם תשובה</button>
+    <button class="mx-btn" data-renew hidden>יצירת בקשת צילום חדשה</button>
+    <input data-camera type="file" accept="image/*" capture="environment" hidden>
+    <button class="mx-btn" data-take hidden>צילום התשובה</button>
+    <img class="mx-answer-image" data-preview alt="תצוגה מקדימה של התשובה" hidden>
+    <button class="mx-btn solid" data-submit hidden>שליחת התשובה למחשב</button></div>`;
+  const c=capture={node,e,result,photo:null,url:null,key:null,busy:false,returnFocus:document.activeElement};visibleRoot.append(node);
+  const status=node.querySelector("[data-status]"),camera=node.querySelector("[data-camera]"),take=node.querySelector("[data-take]"),send=node.querySelector("[data-submit]"),preview=node.querySelector("[data-preview]"),confirm=node.querySelector("[data-confirm]"),renew=node.querySelector("[data-renew]");
+  const valid=()=>capture===c&&live(e),say=message=>{if(valid())status.textContent=message;};
+  const controls=busy=>{c.busy=busy;take.disabled=send.disabled=confirm.disabled=renew.disabled=busy;};
+  const expired=()=>{confirm.hidden=true;take.hidden=true;send.hidden=true;renew.hidden=false;say(errors.expired);};
+  node.querySelector("[data-close]").onclick=closeCapture;
+  node.onkeydown=event=>{
+    if(event.key==="Escape"&&!c.busy){event.preventDefault();event.stopPropagation();closeCapture();}
+    if(event.key==="Tab"){
+      const buttons=[...node.querySelectorAll("button")].filter(b=>!b.hidden&&!b.disabled);
+      if(event.shiftKey&&document.activeElement===buttons[0]){event.preventDefault();buttons.at(-1)?.focus();}
+      else if(!event.shiftKey&&document.activeElement===buttons.at(-1)){event.preventDefault();buttons[0]?.focus();}
+    }
+  };
+  confirm.onclick=async()=>{
+    controls(true);
+    try{const r=await post(`/api/math/answer-scans/${c.result.scan.id}/confirm`);if(!valid())return;c.result=r;
+      if(r.attachment){success();return;}
+      confirm.hidden=true;take.hidden=false;say("בחרו צילום. אם תתבקשו, אפשרו גישה למצלמה.");take.focus();}
+    catch(error){if(valid()){say(error.message);if(error.status===410)expired();}}
+    finally{if(valid())controls(false);}
+  };
+  take.onclick=()=>{say("צלמו את הפתרון. אם המצלמה חסומה, אפשרו אותה בהגדרות האתר ונסו שוב.");camera.click();};
+  camera.addEventListener("cancel",()=>say("הצילום בוטל או שלא ניתנה הרשאה. אפשר לנסות שוב בכפתור הצילום."));
+  camera.onchange=async()=>{
+    const file=camera.files[0];camera.value="";if(!file||!valid())return;
+    controls(true);say("מכינים את התמונה…");
+    try{
+      const photo=await window.MathlyPhoto.prepare(file);if(!valid())return;
+      if(photo.size>5000000)throw Error(errors.image_too_large);
+      if(c.url)URL.revokeObjectURL(c.url);
+      c.photo=photo;c.key=null;preview.src=c.url=URL.createObjectURL(photo);preview.hidden=false;
+      take.textContent="צילום מחדש";send.hidden=false;say("בדקו שכל הפתרון ברור, ואז שלחו את התשובה.");
+    }catch(error){say("לא ניתן להכין את התמונה. נסו לצלם שוב.");}
+    finally{if(valid())controls(false);}
+  };
+  const success=()=>{say("התשובה הועלתה בהצלחה ומצורפת לשאלה במחשב.");take.hidden=send.hidden=confirm.hidden=renew.hidden=true;c.photo=null;if(valid())pollInbox(e);};
+  send.onclick=async()=>{
+    if(!c.photo||c.busy)return;
+    controls(true);say(states.uploading);
+    try{
+      c.key=c.key||crypto.randomUUID();
+      let b=await post(`/api/math/answer-scans/${c.result.scan.id}/uploads`,{key:c.key});if(!valid())return;
+      if(b.attachment){success();return;}
+      const form=new FormData();form.append("photo",c.photo,"answer.jpg");
+      b=await json(`/api/math/answer-scans/${c.result.scan.id}/uploads/${b.lease_id}`,{method:"POST",body:form});
+      if(!valid())return;c.result=b;success();
+    }catch(error){
+      if(!valid())return;say(error.message+" התמונה נשמרה לתצוגה מקדימה. אפשר לנסות שוב.");
+      if(error.status===410||error.code==="superseded")expired();
+      // Reuse the key after an uncertain response; the server returns prior success.
+    }finally{if(valid())controls(false);}
+  };
+  renew.onclick=async()=>{
+    controls(true);
+    try{const r=await post(`/api/math/answer-attempts/${c.result.attempt.id}/scans`,{renew:true});if(!valid())return;
+      c.result=r;c.key=null;renew.hidden=true;confirm.hidden=false;say("נוצרה בקשה חדשה. האם לצלם תשובה לשאלה הזו?");}
+    catch(error){say(error.message);}
+    finally{if(valid())controls(false);}
+  };
+  if(result.scan.state==="expired")expired();
+  node.querySelector("[data-close]").focus();
+}
+document.addEventListener("visibilitychange",()=>{
+  if(document.hidden)return;
+  if(account&&inbox)pollInbox(epoch);
+  if(question?.result)pollQuestion(question);
+});
+window.addEventListener("online",()=>{if(account&&inbox)pollInbox(epoch);if(question?.result)pollQuestion(question);});
+window.MathlyAnswers={configure,mountQuestion,closeQuestion,reset};
+})();

static/index.html

@@ -24,6 +24,8 @@
   </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/photo-image.js"></script>
+  <script src="/static/answer-scans.js"></script>
   <script src="/static/math.js"></script>
 </body>
 </html>

static/math.css

@@ -143,3 +143,12 @@ html.math-on, html.math-on body{overflow:hidden}
 .mx-pair-content{display:flex;flex-direction:column;gap:14px;align-items:stretch}
 .mx-phone-qr{display:block;width:230px;max-width:100%;height:auto;background:white;margin:auto;border-radius:8px}
 .mx-phone-url{display:block;box-sizing:border-box;width:100%;background:var(--bg);color:var(--ink);border:1px solid var(--line);border-radius:8px;padding:10px;font:14px monospace}
+/* Handwritten answer scanning */
+.mx-answer{display:flex;flex-direction:column;gap:12px}
+.mx-answer [hidden]{display:none}
+.mx-answer-image{display:block;max-width:100%;max-height:420px;object-fit:contain;border-radius:12px;background:#fff}
+.mx-scan-inbox:empty{display:none}.mx-scan-inbox{display:flex;flex-direction:column;gap:12px;padding-top:24px}
+.mx-scan-inbox .mx-btn{display:flex;flex-direction:column;align-items:flex-start;text-align:start;white-space:normal;gap:8px}
+.mx-scan-overlay{position:fixed;inset:0;z-index:1000;background:#000c;overflow:auto;padding:20px;display:flex;align-items:flex-start;justify-content:center}
+.mx-scan-card{background:#141719;color:#f4f2ec;border:1px solid #485050;border-radius:18px;padding:24px;width:min(520px,100%);display:flex;flex-direction:column;gap:14px;line-height:1.6}
+.mx-scan-card p{margin:0}.mx-scan-card [hidden]{display:none}.mx-scan-card small{color:#adb7b1}

static/math.js

@@ -28,6 +28,7 @@ let picker=null, PH=null;   // the photo file picker, and the photographed probl
 let advanceTimer=null;
 let phonePair=null;
 function stopPhone(){
+  window.MathlyAnswers?.closeQuestion();
   if(phonePair){clearTimeout(phonePair.timer);if(phonePair.qr)URL.revokeObjectURL(phonePair.qr);phonePair=null;}
 }
 function cancelAdvance(){ clearTimeout(advanceTimer); advanceTimer=null; }
@@ -70,6 +71,7 @@ async function show(){
     catch(e){ path.innerHTML=`<p class="mx-note">לא הצלחנו לטעון את המסלול: ${esc(e.message)}. רעננו את העמוד ונסו שוב.</p>`; return; }
   }
   P=Object.assign({done:{},tries:{}},load()); SHOWN=new Set(shownUnits().map(u=>u.id)); draw();
+  window.MathlyAnswers?.configure({api,account:CFG.userId,enabled:CFG.answerScans,root});
 }
 function hide(){ cancelAdvance(); if(root) root.hidden=true; document.documentElement.classList.remove("math-on"); }
 
@@ -110,8 +112,9 @@ function chips(ids){
 function open(id){
   stopPhone();
   cancelAdvance();
-  const s=BY[id], st=status(id), unit=G.units.find(u=>u.id===s.unit), rot=ORDER.indexOf(id)%s.sample.choices.length;
-  const choices=s.sample.choices.slice(rot).concat(s.sample.choices.slice(0,rot)), missing=s.prereqs.filter(p=>!P.done[p]&&SHOWN.has(BY[p].unit));
+  const s=BY[id], st=status(id), unit=G.units.find(u=>u.id===s.unit), openEnded=s.sample.type==="open-ended";
+  const options=s.sample.choices||[],rot=options.length?ORDER.indexOf(id)%options.length:0;
+  const choices=options.slice(rot).concat(options.slice(0,rot)), missing=s.prereqs.filter(p=>!P.done[p]&&SHOWN.has(BY[p].unit));
   if(!cur) back=document.activeElement;
   cur=id;
   sheet.innerHTML=`<div class="mx-scrim" data-act="close"></div>
@@ -122,15 +125,16 @@ function open(id){
       <p>${fmt(s.description)}</p>
       ${st==="locked"?`<div class="mx-hint">מומלץ לעבור קודם על: <span class="mx-chips">${chips(missing)}</span></div>`:""}
       <div class="mx-q"><p>${fmt(s.sample.question)}</p>${s.sample.graph?plot(s.sample.graph):""}${s.sample.diagram?geometryDiagram(s.sample.diagram):""}
-        <div class="mx-choices">${choices.map((c,i)=>`<button data-choice="${i}" data-m="${c.correct?"":esc(c.mistake)}">${fmt(c.text)}</button>`).join("")}</div>
+        ${openEnded?'<div class="mx-answer"></div>':`<div class="mx-choices">${choices.map((c,i)=>`<button data-choice="${i}" data-m="${c.correct?"":esc(c.mistake)}">${fmt(c.text)}</button>`).join("")}</div>`}
         <div class="mx-fb" aria-live="polite"></div></div>
       <div class="mx-sec"><h4>דורשת</h4><div class="mx-chips">${chips(s.prereqs)}</div></div>
       <div class="mx-sec"><h4>פותחת</h4><div class="mx-chips">${chips(POST[id])}</div></div>
     </div>`;
   sheet.hidden=false; sheet.querySelector(".mx-sheet").scrollTop=0;
   sheet.querySelector(".mx-x").focus({preventScroll:true});
+  if(openEnded)window.MathlyAnswers?.mountQuestion(sheet.querySelector(".mx-answer"),id,s.question_version);
 }
-function closeSheet(){ stopPhone(); cancelAdvance(); sheet.hidden=true; cur=null; back?.focus?.({preventScroll:true}); back=null; }
+function closeSheet(){ stopPhone(); cancelAdvance(); if(sheet)sheet.hidden=true; cur=null; back?.focus?.({preventScroll:true}); back=null; }
 
 function answer(btn){
   if(btn.disabled) return;
@@ -176,19 +180,14 @@ function onClick(e){
     case "work": PH.works.add(+t.dataset.i); return drawPhoto();
     case "all": PH.all=true; return drawPhoto();
     case "close": return closeSheet();
-    case "out": return client?.auth.signOut().then(()=>location.reload());
+    case "out": window.MathlyAnswers?.reset();closeSheet();hide();return client?.auth.signOut().then(()=>location.reload());
   }
 }
 
 /* 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. */
-async function shrink(file){   // a phone photo is several MB: about 1600 px on its long side is enough to read it
-  const bmp=await createImageBitmap(file,{imageOrientation:"from-image"}), k=Math.min(1,1600/Math.max(bmp.width,bmp.height));
-  const c=document.createElement("canvas"); c.width=Math.round(bmp.width*k); c.height=Math.round(bmp.height*k);
-  c.getContext("2d").drawImage(bmp,0,0,c.width,c.height); bmp.close?.();
-  return new Promise((ok,no)=>c.toBlob(b=>b?ok(b):no(new Error("toBlob")),"image/jpeg",.85));
-}
+async function shrink(file){ return window.MathlyPhoto.prepare(file); }
 async function photo(file){
   stopPhone();
   cancelAdvance();
@@ -342,6 +341,12 @@ async function boot(){
   if(AUTH_URL){
     if(!window.supabase){ state.className="error"; state.textContent="לא ניתן לטעון את שירות הכניסה."; return; }
     client=window.supabase.createClient(AUTH_URL,CFG.supabaseKey);
+    client.auth.onAuthStateChange((event,session)=>{
+      CFG.token=session?.access_token||"";
+      if(event==="SIGNED_OUT"||(CFG.userId&&session?.user?.id&&session.user.id!==CFG.userId)){
+        window.MathlyAnswers?.reset();closeSheet();hide();location.reload();
+      }
+    });
     const {data}=await client.auth.getSession(), session=data.session;
     if(!session){
       state.textContent="יש להיכנס כדי לפתוח את מסלול המתמטיקה."; login.hidden=false;
@@ -351,7 +356,7 @@ async function boot(){
     CFG.token=session.access_token;
     const response=await api("/api/me");
     if(!response.ok){ state.className="error"; state.textContent=response.status===403?"החשבון אינו משויך לכיתת מתמטיקה.":"לא ניתן להשלים את הכניסה."; return; }
-    const me=await response.json(); ME_EMAIL=me.email||""; MY_CLASSES=me.classes||[]; MY_CLASS=MY_CLASSES.length===1?MY_CLASSES[0]:null;
+    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||[];
   }
   document.getElementById("boot").hidden=true;

static/phone.html

@@ -20,5 +20,5 @@
   <img id="preview" alt="התרגיל שצילמתם" hidden>
   <button id="send" type="button" hidden>שליחה למחשב</button>
   <p id="status" role="status" aria-live="polite"></p>
-</main><script src="/static/phone.js"></script></body>
+</main><script src="/static/photo-image.js"></script><script src="/static/phone.js"></script></body>
 </html>

static/phone.js

@@ -10,28 +10,13 @@ try{
 const camera=document.getElementById("camera"),take=document.getElementById("take"),send=document.getElementById("send"),
   preview=document.getElementById("preview"),status=document.getElementById("status");
 let photo=null,previewURL=null;
-async function loadPhoto(file){
-  try{return await createImageBitmap(file,{imageOrientation:"from-image"});}
-  catch{
-    // Safari can display some camera formats that createImageBitmap cannot decode.
-    const url=URL.createObjectURL(file),img=new Image();
-    try{
-      await new Promise((resolve,reject)=>{img.onload=resolve;img.onerror=reject;img.src=url;});
-      return img;
-    }finally{URL.revokeObjectURL(url);}
-  }
-}
 if(!token){status.textContent="סרקו שוב את הקוד שמופיע במחשב כדי להתחבר.";take.disabled=true;return;}
 take.onclick=()=>camera.click();
 camera.onchange=async()=>{
   const file=camera.files[0];camera.value=""; if(!file)return;
   photo=null;take.disabled=true;send.hidden=true;status.textContent="מכינים את התמונה…";
   try{
-    const bitmap=await loadPhoto(file);
-    const scale=Math.min(1,1600/Math.max(bitmap.width,bitmap.height)),canvas=document.createElement("canvas");
-    canvas.width=Math.round(bitmap.width*scale);canvas.height=Math.round(bitmap.height*scale);
-    canvas.getContext("2d").drawImage(bitmap,0,0,canvas.width,canvas.height);bitmap.close?.();
-    photo=await new Promise(resolve=>canvas.toBlob(resolve,"image/jpeg",.85));
+    photo=await window.MathlyPhoto.prepare(file);
     if(!photo)throw Error("image");
   }catch{
     if(["image/jpeg","image/png","image/webp"].includes(file.type))photo=file;

static/photo-image.js

@@ -0,0 +1,17 @@
+/* Shared camera preparation for answer scans and photographed-problem help. */
+window.MathlyPhoto={async prepare(file){
+  let bitmap,temporary;
+  try{bitmap=await createImageBitmap(file,{imageOrientation:"from-image"});}
+  catch{
+    temporary=URL.createObjectURL(file);
+    bitmap=new Image();
+    try{await new Promise((ok,no)=>{bitmap.onload=ok;bitmap.onerror=no;bitmap.src=temporary;});}
+    finally{URL.revokeObjectURL(temporary);}
+  }
+  try{
+    const scale=Math.min(1,1600/Math.max(bitmap.width,bitmap.height)),canvas=document.createElement("canvas");
+    canvas.width=Math.round(bitmap.width*scale);canvas.height=Math.round(bitmap.height*scale);
+    canvas.getContext("2d").drawImage(bitmap,0,0,canvas.width,canvas.height);
+    return await new Promise((ok,no)=>canvas.toBlob(blob=>blob?ok(blob):no(Error("image")),"image/jpeg",.85));
+  }finally{bitmap.close?.();}
+}};

supabase/.gitignore

@@ -0,0 +1,2 @@
+.temp/
+.branches/

supabase/migrations/20261031133254_math_answer_scans.sql

@@ -0,0 +1,174 @@
+-- Additive answer-scanning schema. Existing classes and solver sessions are untouched.
+begin;
+create table public.math_question_attempts (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  question_id text not null,
+  question_version text not null,
+  snapshot jsonb not null,
+  status text not null default 'draft' check (status in ('draft','received')),
+  created_at timestamptz not null default now(),
+  unique (id,user_id)
+);
+create index math_attempt_owner_question on public.math_question_attempts(user_id,question_id,question_version,created_at desc);
+create table public.math_answer_scans (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  attempt_id uuid not null,
+  generation integer not null,
+  state text not null default 'waiting' check (state in ('waiting','confirmed','uploading','received','failed','expired','superseded')),
+  expires_at timestamptz not null default (now()+interval '15 minutes'),
+  lease_id uuid,
+  lease_until timestamptz,
+  idempotency_key uuid,
+  error text not null default '',
+  created_at timestamptz not null default now(),
+  foreign key (attempt_id,user_id) references public.math_question_attempts(id,user_id) on delete cascade,
+  unique (attempt_id,generation),
+  unique (id,attempt_id,user_id)
+);
+create index math_scan_owner on public.math_answer_scans(user_id,created_at desc);
+create unique index math_scan_one_active on public.math_answer_scans(attempt_id)
+  where state in ('waiting','confirmed','uploading','failed');
+create table public.math_answer_attachments (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  attempt_id uuid not null unique,
+  scan_id uuid not null unique,
+  object_key text not null unique,
+  media_type text not null check (media_type = 'image/jpeg'),
+  byte_size integer not null check (byte_size > 0 and byte_size <= 5000000),
+  created_at timestamptz not null default now(),
+  foreign key (scan_id,attempt_id,user_id) references public.math_answer_scans(id,attempt_id,user_id) on delete cascade
+);
+create index math_attachment_owner on public.math_answer_attachments(user_id);
+alter table public.math_question_attempts enable row level security;
+alter table public.math_answer_scans enable row level security;
+alter table public.math_answer_attachments enable row level security;
+revoke all on public.math_question_attempts,public.math_answer_scans,public.math_answer_attachments from anon,authenticated;
+grant select on public.math_question_attempts,public.math_answer_scans,public.math_answer_attachments to authenticated;
+grant all on public.math_question_attempts,public.math_answer_scans,public.math_answer_attachments to service_role;
+create policy math_attempt_owner_read on public.math_question_attempts for select to authenticated using ((select auth.uid())=user_id);
+create policy math_scan_owner_read on public.math_answer_scans for select to authenticated using ((select auth.uid())=user_id);
+create policy math_attachment_owner_read on public.math_answer_attachments for select to authenticated using ((select auth.uid())=user_id);
+
+-- Invoker, service-role-only RPC. FastAPI supplies a verified user ID.
+-- All scan writers lock the attempt first, serializing renewal and completion.
+create function public.math_answer_action(p_user uuid, p_action text, p_data jsonb default '{}')
+returns jsonb language plpgsql security invoker set search_path = '' as $$
+declare
+  a public.math_question_attempts;
+  s public.math_answer_scans;
+  att public.math_answer_attachments;
+  t timestamptz := clock_timestamp();
+  sid uuid;
+  aid uuid;
+  listing jsonb;
+begin
+  if p_action='cleanup_candidates' then
+    return coalesce((select jsonb_agg(o.name) from storage.objects o
+      where o.bucket_id='mathly-answers' and o.created_at < t-interval '24 hours'
+      and not exists(select 1 from public.math_answer_attachments x where x.object_key=o.name)), '[]'::jsonb);
+  end if;
+  if p_user is null then raise exception 'not_found' using errcode='P0002'; end if;
+  if p_action='pending' then
+    -- Expiry and stale lease recovery are also persisted on discovery.
+    update public.math_answer_scans set state='expired',error='expired'
+      where user_id=p_user and expires_at<=t and state in ('waiting','confirmed','uploading','failed');
+    update public.math_answer_scans set state='failed',error='upload_interrupted'
+      where user_id=p_user and state='uploading' and lease_until<=t;
+    select jsonb_agg(jsonb_build_object('scan',to_jsonb(x),'attempt',to_jsonb(q)) order by x.created_at desc)
+      into listing from public.math_answer_scans x join public.math_question_attempts q on q.id=x.attempt_id
+      where x.user_id=p_user and x.state in ('waiting','confirmed','uploading','failed','expired')
+      and not exists(select 1 from public.math_answer_scans newer where newer.attempt_id=x.attempt_id and newer.generation>x.generation);
+    return coalesce(listing,'[]'::jsonb);
+  end if;
+  if p_action='resume' then
+    perform pg_catalog.pg_advisory_xact_lock(pg_catalog.hashtextextended(p_user::text||(p_data->>'question_id')||(p_data->>'question_version'),0));
+    if not coalesce((p_data->>'new')::boolean,false) then
+      select * into a from public.math_question_attempts where user_id=p_user
+        and question_id=p_data->>'question_id' and question_version=p_data->>'question_version'
+        order by created_at desc,id desc limit 1 for update;
+    end if;
+    if a.id is null then
+      insert into public.math_question_attempts(user_id,question_id,question_version,snapshot)
+        values(p_user,p_data->>'question_id',p_data->>'question_version',p_data->'snapshot') returning * into a;
+    end if;
+  else
+    if p_data ? 'scan_id' then
+      select attempt_id into aid from public.math_answer_scans where id=(p_data->>'scan_id')::uuid and user_id=p_user;
+    else aid := (p_data->>'attempt_id')::uuid;
+    end if;
+    select * into a from public.math_question_attempts where id=aid and user_id=p_user for update;
+    if a.id is null then raise exception 'not_found' using errcode='P0002'; end if;
+    if p_data ? 'question_id' and a.question_id<>p_data->>'question_id' then
+      raise exception 'not_found' using errcode='P0002';
+    end if;
+  end if;
+  select * into s from public.math_answer_scans where attempt_id=a.id order by generation desc limit 1 for update;
+  select * into att from public.math_answer_attachments where attempt_id=a.id;
+  t := clock_timestamp();
+  if p_data ? 'scan_id' and s.id is distinct from (p_data->>'scan_id')::uuid then
+    raise exception 'superseded' using errcode='P0001';
+  end if;
+  if s.id is not null then
+    if s.state in ('waiting','confirmed','uploading','failed') and s.expires_at<=t then
+      update public.math_answer_scans set state='expired',error='expired' where id=s.id returning * into s;
+    elsif s.state='uploading' and s.lease_until<=t then
+      update public.math_answer_scans set state='failed',error='upload_interrupted' where id=s.id returning * into s;
+    end if;
+  end if;
+  if p_action='create_scan' then
+    if att.id is not null then null;
+    elsif s.id is null or coalesce((p_data->>'renew')::boolean,false) then
+      if s.state='uploading' then raise exception 'upload_in_progress' using errcode='P0001'; end if;
+      if s.id is not null then update public.math_answer_scans set state='superseded' where id=s.id; end if;
+      insert into public.math_answer_scans(user_id,attempt_id,generation,expires_at,created_at)
+        values(p_user,a.id,coalesce(s.generation,0)+1,t+interval '15 minutes',t) returning * into s;
+    end if;
+  elsif p_action='confirm' then
+    if s.state='waiting' then
+      update public.math_answer_scans set state='confirmed' where id=s.id returning * into s;
+    end if;
+  elsif p_action='begin' then
+    if s.state in ('confirmed','failed') then
+      update public.math_answer_scans set state='uploading',lease_id=gen_random_uuid(),
+        lease_until=least(t+interval '3 minutes',expires_at),idempotency_key=(p_data->>'key')::uuid,error=''
+        where id=s.id returning * into s;
+    elsif s.state='uploading' and s.idempotency_key is distinct from (p_data->>'key')::uuid then
+      raise exception 'upload_in_progress' using errcode='P0001';
+    elsif s.state='waiting' then raise exception 'confirmation_required' using errcode='P0001';
+    end if;
+  elsif p_action='finalize' then
+    if att.id is null then
+      if s.state<>'uploading' or s.lease_id is distinct from (p_data->>'lease_id')::uuid then
+        raise exception 'invalid_upload' using errcode='P0001';
+      end if;
+      if (p_data->>'object_key') not like p_user::text||'/'||s.id::text||'/'||s.lease_id::text||'/%' then
+        raise exception 'invalid_upload' using errcode='P0001';
+      end if;
+      insert into public.math_answer_attachments(user_id,attempt_id,scan_id,object_key,media_type,byte_size)
+        values(p_user,a.id,s.id,p_data->>'object_key','image/jpeg',(p_data->>'byte_size')::integer) returning * into att;
+      update public.math_answer_scans set state='received',error='' where id=s.id returning * into s;
+      update public.math_question_attempts set status='received' where id=a.id returning * into a;
+    end if;
+  elsif p_action='fail' then
+    if s.state='uploading' and s.lease_id=(p_data->>'lease_id')::uuid then
+      update public.math_answer_scans set state='failed',error='upload_failed' where id=s.id returning * into s;
+    end if;
+  elsif p_action not in ('resume','get') then
+    raise exception 'invalid_action';
+  end if;
+  return jsonb_build_object('attempt',to_jsonb(a),'scan',case when s.id is null then null else to_jsonb(s) end,
+    'attachment',case when att.id is null then null else to_jsonb(att) end);
+end $$;
+revoke all on function public.math_answer_action(uuid,text,jsonb) from public,anon,authenticated;
+grant execute on function public.math_answer_action(uuid,text,jsonb) to service_role;
+
+-- Image bytes are accessed only by the backend after verifying attempt ownership.
+insert into storage.buckets(id,name,public,file_size_limit,allowed_mime_types)
+  values('mathly-answers','mathly-answers',false,5000000,array['image/jpeg']);
+-- Restrictive policies also block any pre-existing permissive "all buckets" policy.
+create policy math_answer_private on storage.objects as restrictive for all to anon,authenticated
+  using (bucket_id <> 'mathly-answers') with check (bucket_id <> 'mathly-answers');
+commit;

tests/scan_support.py

@@ -0,0 +1,116 @@
+"""Real PostgreSQL transactions and a local private-blob stand-in for tests."""
+import json
+import uuid
+from pathlib import Path
+
+import pytest
+
+from app.answer_scans import AnswerScans, ScanError
+
+OWNER = '11111111-1111-4111-8111-111111111111'
+OTHER = '22222222-2222-4222-8222-222222222222'
+
+BOOTSTRAP = '''
+create schema auth;
+create table auth.users(id uuid primary key);
+create function auth.uid() returns uuid language sql stable as
+ $$select nullif(current_setting('request.jwt.claim.sub',true),'')::uuid$$;
+grant usage on schema public,auth to anon,authenticated,service_role;
+create schema storage;
+create table storage.buckets(id text primary key,name text,public boolean,file_size_limit bigint,allowed_mime_types text[]);
+create table storage.objects(id uuid primary key default gen_random_uuid(),bucket_id text,name text unique,created_at timestamptz default now());
+alter table storage.objects enable row level security;
+grant usage on schema storage to anon,authenticated,service_role;
+grant all on storage.objects to anon,authenticated,service_role;
+create policy preexisting_permissive on storage.objects for all using(true) with check(true);
+create table public.classes(id int primary key,name text);
+insert into classes values(1,'existing math class');
+'''
+
+
+class ScanAuth:
+    url = 'https://test.invalid'
+    key = 'public-test'
+    secret = 'server-test'
+    teachers = frozenset()
+    developers = frozenset()
+
+    def user(self, token):
+        if token not in (OWNER, OTHER):
+            return None
+        return {'id': token, 'email': token + '@test.invalid'}
+
+    def classes(self):
+        return []
+
+    def access_for(self, _id, **kwargs):
+        return None
+
+
+class DatabaseAnswers(AnswerScans):
+    def __init__(self, uri, files):
+        super().__init__(ScanAuth(), enabled=True)
+        self.uri, self.files = uri, files
+        self.fail_put = self.fail_finalize = False
+
+    def connect(self):
+        import psycopg
+        return psycopg.connect(self.uri, autocommit=True)
+
+    def action(self, user_id, action, **data):
+        import psycopg
+        if self.fail_finalize and action == 'finalize':
+            raise ScanError(503, 'answer_storage_unavailable')
+        with self.connect() as c:
+            c.execute('set role service_role')
+            try:
+                return c.execute('select public.math_answer_action(%s,%s,%s::jsonb)',
+                                 (user_id, action, json.dumps(data))).fetchone()[0]
+            except psycopg.errors.NoDataFound as exc:
+                raise ScanError(404, 'not_found') from exc
+            except psycopg.errors.RaiseException as exc:
+                raise ScanError(409, str(exc).splitlines()[0]) from exc
+
+    def put(self, key, data):
+        if self.fail_put:
+            raise ScanError(503, 'answer_storage_unavailable')
+        p = self.files / key
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_bytes(data)
+        with self.connect() as c:
+            c.execute("insert into storage.objects(bucket_id,name) values('mathly-answers',%s)", (key,))
+
+    def read(self, key):
+        return (self.files / key).read_bytes()
+
+    def delete(self, key):
+        (self.files / key).unlink(missing_ok=True)
+        with self.connect() as c:
+            c.execute('delete from storage.objects where name=%s', (key,))
+
+
+@pytest.fixture(scope='session')
+def postgres_server(tmp_path_factory):
+    pgserver = pytest.importorskip('pgserver')
+    psycopg = pytest.importorskip('psycopg')
+    server = pgserver.get_server(tmp_path_factory.mktemp('postgres') / 'data', cleanup_mode='delete')
+    with psycopg.connect(server.get_uri(), autocommit=True) as c:
+        c.execute('create role anon; create role authenticated; create role service_role bypassrls;')
+    yield server
+
+
+@pytest.fixture
+def answer_store(postgres_server, tmp_path):
+    import psycopg
+    database = 'scan_' + uuid.uuid4().hex
+    with psycopg.connect(postgres_server.get_uri(), autocommit=True) as c:
+        c.execute('create database ' + database)
+    uri = postgres_server.get_uri(database=database)
+    store = DatabaseAnswers(uri, tmp_path / 'images')
+    with store.connect() as c:
+        c.execute(BOOTSTRAP)
+        c.execute(Path('supabase/migrations/20261031133254_math_answer_scans.sql').read_text())
+        c.execute('insert into auth.users values(%s),(%s)', (OWNER, OTHER))
+    yield store
+    with psycopg.connect(postgres_server.get_uri(), autocommit=True) as c:
+        c.execute('drop database ' + database + ' with (force)')

tests/test_answer_browser.py

@@ -0,0 +1,191 @@
+"""Desktop/mobile integration against real PostgreSQL and the production API."""
+import socket
+import threading
+import time
+
+import pytest
+import uvicorn
+
+from app.main import create_app
+from scan_support import OWNER, OTHER, ScanAuth, answer_store, postgres_server
+from test_answer_scans import png, request
+
+playwright = pytest.importorskip('playwright.sync_api')
+
+
+@pytest.fixture
+def scan_server(answer_store):
+    app = create_app(auth=ScanAuth()); app.state.answers = answer_store
+    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:
+            deadline = time.monotonic() + 5
+            while not server.started:
+                assert thread.is_alive() and time.monotonic() < deadline
+                time.sleep(.01)
+            yield f'http://127.0.0.1:{sock.getsockname()[1]}', answer_store
+        finally:
+            server.should_exit = True; thread.join(timeout=5)
+
+
+def session(browser, owner=OWNER, mobile=False):
+    ctx = browser.new_context(viewport={'width': 390 if mobile else 1280, 'height': 844},
+                              is_mobile=mobile, has_touch=mobile)
+    ctx.route('https://cdn.jsdelivr.net/**', lambda route: route.abort())
+    # Stub only the external sign-in SDK; all app APIs and ownership checks run.
+    ctx.add_init_script('''window.supabase={createClient:()=>({auth:{
+      getSession:async()=>{const id=localStorage.getItem('test.account')||'%s';return {data:{session:{access_token:id,user:{id}}}};},
+      onAuthStateChange:cb=>{window.testAuthEvent=cb;return {data:{subscription:{unsubscribe(){}}}};},
+      signOut:async()=>window.testAuthEvent('SIGNED_OUT',null)
+    }})};''' % owner)
+    return ctx
+
+
+def open_question(page):
+    page.locator('.mx-node[data-id="g_triangle_area"]').click()
+    playwright.expect(page.locator('.mx-answer')).to_be_visible()
+    playwright.expect(page.locator('.mx-choices')).to_have_count(0)
+
+
+def test_two_device_capture_retake_failure_retry_and_original_attempt(scan_server):
+    url, store = scan_server
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            computer = session(browser).new_page(); errors=[]
+            computer.on('pageerror', lambda error: errors.append(str(error)))
+            computer.goto(url)
+            with computer.expect_request('**/api/math/answer-attempts') as resume:
+                open_question(computer)
+            assert len(resume.value.post_data_json['question_version'])==64
+            computer.locator('[data-request]').click()
+            playwright.expect(computer.locator('.mx-answer [role=status]')).to_have_text('ממתינים לטלפון')
+            with store.connect() as c:
+                attempt_id = str(c.execute('select id from math_question_attempts').fetchone()[0])
+            phone = session(browser, mobile=True).new_page()
+            phone.on('pageerror', lambda error: errors.append(str(error)))
+            request(store, question='another-question')
+            phone.goto(url)
+            playwright.expect(phone.locator('[data-scan-index]')).to_have_count(2)
+            phone.locator('[data-scan-index]').filter(has_text='משולש ישר').click()
+            # Confirmation and cancellation do not invoke capture or upload.
+            assert phone.locator('[data-camera]').input_value() == ''
+            assert phone.locator('[data-take]').is_hidden()
+            phone.locator('[data-close]').click()
+            phone.locator('[data-scan-index]').filter(has_text='משולש ישר').click()
+            phone.evaluate("window.cameraClicks=0;document.addEventListener('click',e=>{if(e.target.matches('[data-camera]'))window.cameraClicks++},true)")
+            phone.locator('[data-confirm]').click()
+            playwright.expect(phone.locator('[data-take]')).to_be_visible()
+            phone.locator('[data-camera]').dispatch_event('cancel')
+            playwright.expect(phone.locator('[data-status]')).to_contain_text('לא ניתנה הרשאה')
+            image = {'name': 'answer.png', 'mimeType': 'image/png', 'buffer': png()}
+            assert phone.evaluate('window.cameraClicks')==0
+            with phone.expect_file_chooser() as chooser:
+                phone.locator('[data-take]').click()
+            chooser.value.set_files(image)
+            playwright.expect(phone.locator('[data-submit]')).to_be_visible()
+            phone.screenshot(path='/tmp/mathly-answer-phone.png', full_page=True, animations='disabled')
+            first = phone.locator('[data-preview]').get_attribute('src')
+            phone.locator('[data-camera]').set_input_files(image)
+            playwright.expect(phone.locator('[data-preview]')).not_to_have_attribute('src', first)
+            assert store.action(OWNER, 'get', attempt_id=attempt_id)['attachment'] is None
+            store.fail_put = True
+            phone.locator('[data-submit]').click()
+            playwright.expect(phone.locator('[data-status]')).to_contain_text('אפשר לנסות שוב')
+            playwright.expect(computer.locator('.mx-answer [role=status]')).to_have_text('ההעלאה נכשלה', timeout=10000)
+            assert phone.locator('[data-preview]').is_visible()
+            store.fail_put = False
+            started, release = threading.Event(), threading.Event()
+            original_put = store.put
+            def slow_put(key, data):
+                started.set(); assert release.wait(timeout=15); original_put(key, data)
+            store.put = slow_put
+            phone.locator('[data-submit]').click()
+            playwright.expect(computer.locator('.mx-answer [role=status]')).to_have_text('מעלים את התשובה…', timeout=10000)
+            assert started.is_set()
+            computer.locator('.mx-x').click();computer.locator('.mx-node[data-id="g_rectangle"]').click()
+            release.set()
+            playwright.expect(phone.locator('[data-status]')).to_contain_text('הועלתה בהצלחה', timeout=10000)
+            assert computer.locator('.mx-answer-image').count() == 0
+            assert computer.locator('.mx-choices button').count() > 0
+            computer.locator('.mx-x').click();open_question(computer)
+            playwright.expect(computer.locator('.mx-answer-image')).to_be_visible()
+            assert computer.locator('.mx-answer-image').evaluate('img=>img.complete&&img.naturalWidth>0')
+            computer.screenshot(path='/tmp/mathly-answer-computer.png', full_page=True, animations='disabled')
+            assert computer.evaluate("!JSON.parse(localStorage.getItem('mathly.progress.v1:'+'%s@test.invalid')||'{}').done?.g_triangle_area" % OWNER)
+            computer.reload();open_question(computer)
+            playwright.expect(computer.locator('.mx-answer-image')).to_be_visible()
+            foreign = session(browser, OTHER, mobile=True).new_page();foreign.goto(url)
+            playwright.expect(foreign.locator('.mx-scan-inbox')).to_be_empty()
+            assert store.action(OWNER, 'get', attempt_id=attempt_id)['attachment']
+            assert not errors
+        finally:
+            browser.close()
+
+
+def test_expiry_renewal_reconnect_and_account_change(scan_server):
+    url, store = scan_server
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            computer = session(browser).new_page();computer.goto(url);open_question(computer)
+            computer.locator('[data-request]').click()
+            playwright.expect(computer.locator('.mx-answer [role=status]')).to_have_text('ממתינים לטלפון')
+            with store.connect() as c:
+                old = str(c.execute('select id from math_answer_scans').fetchone()[0])
+                c.execute("update math_answer_scans set expires_at=now()-interval '1 second'")
+            computer.route('**/api/math/answer-attempts/*', lambda r:r.abort(), times=1)
+            playwright.expect(computer.locator('.mx-answer [role=status]')).to_have_text('בקשת הצילום פגה', timeout=15000)
+            phone = session(browser, mobile=True).new_page();phone.goto(url)
+            phone.locator('[data-scan-index]').click()
+            playwright.expect(phone.locator('[data-renew]')).to_be_visible()
+            phone.locator('[data-renew]').click()
+            playwright.expect(phone.locator('[data-confirm]')).to_be_visible()
+            assert store.action(OWNER, 'pending')[0]['scan']['generation'] == 2
+            phone.locator('[data-confirm]').click()
+            phone.locator('[data-camera]').set_input_files({'name':'answer.png','mimeType':'image/png','buffer':png()})
+            phone.locator('[data-submit]').click()
+            playwright.expect(phone.locator('[data-status]')).to_contain_text('הועלתה בהצלחה')
+            playwright.expect(computer.locator('.mx-answer-image')).to_be_visible(timeout=10000)
+            # Account change removes the photograph and all old-account continuations.
+            computer.evaluate("localStorage.setItem('test.account','%s');window.testAuthEvent('SIGNED_IN',{access_token:'%s',user:{id:'%s'}})" % (OTHER, OTHER, OTHER))
+            playwright.expect(computer.locator('.mx-node[data-id="g_triangle_area"]')).to_be_visible()
+            assert computer.locator('.mx-answer-image').count() == 0
+            open_question(computer)
+            playwright.expect(computer.locator('[data-request]')).to_be_enabled()
+            assert computer.locator('.mx-answer-image').count() == 0
+        finally:
+            browser.close()
+
+
+def test_success_response_loss_is_safe_to_retry(scan_server):
+    url, store = scan_server
+    with playwright.sync_playwright() as p:
+        browser = p.chromium.launch()
+        try:
+            computer=session(browser).new_page();computer.goto(url);open_question(computer)
+            computer.locator('[data-request]').click()
+            playwright.expect(computer.locator('.mx-answer [role=status]')).to_have_text('ממתינים לטלפון')
+            phone=session(browser,mobile=True).new_page();phone.goto(url)
+            phone.locator('[data-scan-index]').click();phone.locator('[data-confirm]').click()
+            phone.locator('[data-camera]').set_input_files({'name':'answer.png','mimeType':'image/png','buffer':png()})
+            def lost_response(route):
+                response=route.fetch()
+                assert response.ok
+                route.abort()
+            phone.route('**/api/math/answer-scans/*/uploads/*',lost_response,times=1)
+            phone.locator('[data-submit]').click()
+            playwright.expect(phone.locator('[data-status]')).to_contain_text('אפשר לנסות שוב')
+            playwright.expect(computer.locator('.mx-answer-image')).to_be_visible(timeout=10000)
+            phone.locator('[data-submit]').click()
+            playwright.expect(phone.locator('[data-status]')).to_contain_text('הועלתה בהצלחה')
+            with store.connect() as c:
+                assert c.execute('select count(*) from math_answer_attachments').fetchone()[0]==1
+            computer.locator('.mx-x').click();computer.locator('.mx-node[data-id="g_rectangle"]').click()
+            computer.locator('.mx-choices button[data-m=""]').click()
+            assert computer.evaluate("!!JSON.parse(localStorage.getItem('mathly.progress.v1:'+'%s@test.invalid')).done.g_rectangle" % OWNER)
+        finally:
+            browser.close()

tests/test_answer_scans.py

@@ -0,0 +1,299 @@
+import asyncio
+import io
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+
+import httpx
+import pytest
+from PIL import Image, ImageDraw
+
+from app.answer_scans import ScanError, clean_image
+from app.main import create_app
+from scan_support import OWNER, OTHER, ScanAuth, answer_store, postgres_server
+
+
+def png():
+    out = io.BytesIO()
+    image = Image.new('RGB', (320, 240), 'white')
+    pen = ImageDraw.Draw(image)
+    pen.line([(35, 30), (35, 150), (250, 150), (35, 30)], fill='navy', width=3)
+    pen.text((12, 80), '6', fill='navy'); pen.text((135, 160), '8', fill='navy')
+    pen.text((35, 195), '6 x 8 / 2 = 24 cm2', fill='navy')
+    image.save(out, 'PNG')
+    return out.getvalue()
+
+
+def attempt(store, owner=OWNER, version='v1', question='geometry'):
+    return store.action(owner, 'resume', question_id=question, question_version=version,
+                        snapshot={'question': 'Draw your proof', 'type': 'open-ended'})
+
+
+def request(store, owner=OWNER, **kwargs):
+    a = attempt(store, owner, **kwargs)
+    return store.action(owner, 'create_scan', attempt_id=a['attempt']['id'])
+
+
+def begin(store, result, key=None):
+    sid = result['scan']['id']
+    store.action(OWNER, 'confirm', scan_id=sid)
+    return store.action(OWNER, 'begin', scan_id=sid, key=key or str(uuid.uuid4()))
+
+
+def finish(store, result):
+    s = result['scan']
+    key = f"{OWNER}/{s['id']}/{s['lease_id']}/{uuid.uuid4()}.jpg"
+    store.put(key, clean_image(png(), 'image/png'))
+    return store.action(OWNER, 'finalize', scan_id=s['id'], lease_id=s['lease_id'], object_key=key, byte_size=500)
+
+
+def test_additive_migration_rls_and_service_only_rpc(answer_store):
+    import psycopg
+    store = answer_store
+    mine = request(store)
+    finish(store, begin(store, mine))
+    request(store, OTHER)
+    with store.connect() as c:
+        assert c.execute('select name from classes').fetchone()[0] == 'existing math class'
+        assert c.execute("select public from storage.buckets where id='mathly-answers'").fetchone()[0] is False
+        c.execute('set role authenticated')
+        c.execute("select set_config('request.jwt.claim.sub',%s,false)", (OWNER,))
+        rows = c.execute('select user_id from math_question_attempts').fetchall()
+        assert [str(row[0]) for row in rows] == [OWNER]
+        assert len(c.execute('select id from math_answer_scans').fetchall()) == 1
+        assert len(c.execute('select id from math_answer_attachments').fetchall()) == 1
+        c.execute("select set_config('request.jwt.claim.sub',%s,false)", (OTHER,))
+        assert c.execute('select id from math_answer_attachments').fetchall() == []
+        c.execute("select set_config('request.jwt.claim.sub',%s,false)", (OWNER,))
+        with pytest.raises(psycopg.errors.InsufficientPrivilege):
+            c.execute("select public.math_answer_action(%s,'get',%s::jsonb)", (OTHER, '{}'))
+        with pytest.raises(psycopg.errors.InsufficientPrivilege):
+            c.execute("update math_answer_scans set state='received'")
+        with pytest.raises(psycopg.errors.InsufficientPrivilege):
+            c.execute("insert into storage.objects(bucket_id,name) values('mathly-answers','foreign')")
+        assert c.execute("select * from storage.objects where bucket_id='mathly-answers'").fetchall() == []
+        c.execute('set role anon')
+        with pytest.raises(psycopg.errors.InsufficientPrivilege):
+            c.execute('select * from math_answer_scans')
+    with pytest.raises(ScanError) as e:
+        store.action(OTHER, 'get', attempt_id=mine['attempt']['id'])
+    assert e.value.status == 404
+
+
+def test_attempt_resume_version_and_generation(answer_store):
+    store = answer_store
+    a = attempt(store)
+    assert attempt(store)['attempt']['id'] == a['attempt']['id']
+    assert attempt(store, version='v2')['attempt']['id'] != a['attempt']['id']
+    r = store.action(OWNER, 'create_scan', attempt_id=a['attempt']['id'])
+    assert store.action(OWNER, 'create_scan', attempt_id=a['attempt']['id'])['scan']['id'] == r['scan']['id']
+    with pytest.raises(ScanError):
+        store.action(OWNER, 'create_scan', attempt_id=a['attempt']['id'], question_id='forged')
+    with store.connect() as c:
+        c.execute("update math_answer_scans set expires_at=now()-interval '1 second' where id=%s", (r['scan']['id'],))
+    assert store.action(OWNER, 'get', scan_id=r['scan']['id'])['scan']['state'] == 'expired'
+    new = store.action(OWNER, 'create_scan', attempt_id=a['attempt']['id'], renew=True)
+    assert new['scan']['generation'] == 2
+    with pytest.raises(ScanError, match='superseded'):
+        store.action(OWNER, 'confirm', scan_id=r['scan']['id'])
+
+
+def test_concurrent_uploads_and_lost_response(answer_store):
+    store = answer_store
+    r = request(store)
+    with pytest.raises(ScanError, match='confirmation_required'):
+        store.action(OWNER, 'begin', scan_id=r['scan']['id'], key=str(uuid.uuid4()))
+    b = begin(store, r)
+    assert store.action(OWNER, 'begin', scan_id=r['scan']['id'], key=b['scan']['idempotency_key'])['scan']['lease_id'] == b['scan']['lease_id']
+    with pytest.raises(ScanError, match='upload_in_progress'):
+        store.action(OWNER, 'begin', scan_id=r['scan']['id'], key=str(uuid.uuid4()))
+    with ThreadPoolExecutor(2) as pool:
+        results = list(pool.map(lambda _: finish(store, b), range(2)))
+    assert results[0]['attachment']['id'] == results[1]['attachment']['id']
+    assert results[0]['attempt']['status'] == 'received'
+    with store.connect() as c:
+        assert c.execute('select count(*) from math_answer_attachments').fetchone()[0] == 1
+    assert store.action(OWNER, 'create_scan', attempt_id=r['attempt']['id'], renew=True)['scan']['id'] == r['scan']['id']
+
+
+def test_stale_lease_and_renewal_reject_late_completion(answer_store):
+    store = answer_store
+    b = begin(store, request(store))
+    with store.connect() as c:
+        c.execute("update math_answer_scans set lease_until=now()-interval '1 second' where id=%s", (b['scan']['id'],))
+    assert store.action(OWNER, 'pending')[0]['scan']['state'] == 'failed'
+    store.action(OWNER, 'create_scan', attempt_id=b['attempt']['id'], renew=True)
+    with pytest.raises(ScanError, match='superseded'):
+        finish(store, b)
+    assert store.action(OWNER, 'get', attempt_id=b['attempt']['id'])['attachment'] is None
+
+
+def test_cleanup_retains_committed_images_and_removes_deleted_attempts(answer_store):
+    store = answer_store
+    done = finish(store, begin(store, request(store)))
+    store.put('orphan.jpg', b'orphan')
+    with store.connect() as c:
+        c.execute("update storage.objects set created_at=now()-interval '25 hours'")
+    assert store.cleanup() == 1
+    assert store.read(done['attachment']['object_key'])
+    with store.connect() as c:
+        c.execute('delete from math_question_attempts where id=%s', (done['attempt']['id'],))
+    assert store.cleanup() == 1
+
+
+def test_image_validation_and_exif_removal():
+    assert Image.open(io.BytesIO(clean_image(png(), 'image/png'))).format == 'JPEG'
+    for data, mime, status in [(b'fake', 'image/jpeg', 415), (b'', 'image/png', 400),
+                               (b'x' * 5_000_001, 'image/jpeg', 413), (png(), 'image/heic', 415)]:
+        with pytest.raises(ScanError) as e:
+            clean_image(data, mime)
+        assert e.value.status == status
+    image = Image.new('RGB', (30, 60))
+    exif = Image.Exif(); exif[274] = 6; exif[270] = 'private'
+    raw = io.BytesIO(); image.save(raw, 'JPEG', exif=exif)
+    result = Image.open(io.BytesIO(clean_image(raw.getvalue(), 'image/jpeg')))
+    assert result.size == (60, 30) and not result.getexif()
+
+
+def test_scan_api_end_to_end_failure_retry_and_restart(answer_store, monkeypatch):
+    import copy
+    from app.math_skills import algebra9, question_version
+    graph = copy.deepcopy(algebra9())
+    graph['skills'][0]['sample'] = {'type': 'open-ended', 'question': 'Draw a proof', 'version': 1}
+    monkeypatch.setattr('app.answer_routes.algebra9', lambda: graph)
+    monkeypatch.delenv('ANTHROPIC_API_KEY', raising=False)
+    store = answer_store
+    app = create_app(auth=ScanAuth()); app.state.answers = store
+    owner = {'Authorization': f'Bearer {OWNER}'}
+    other = {'Authorization': f'Bearer {OTHER}'}
+    async def check():
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url='http://test', headers=owner) as c:
+            assert (await c.get('/api/me')).json()['answer_scans'] is True
+            assert (await c.post('/api/math/answer-attempts', json={'question_id': 'forged'})).status_code == 404
+            assert (await c.post('/api/math/answer-attempts', json={'question_id': graph['skills'][0]['id'], 'question_version': 'bad'})).status_code == 409
+            assert (await c.post('/api/math/answer-attempts', json={'question_id': graph['skills'][0]['id']})).status_code == 409
+            result = (await c.post('/api/math/answer-attempts', json={'question_id': graph['skills'][0]['id'],
+                         'question_version': question_version(graph['skills'][0]['sample'])})).json()
+            aid = result['attempt']['id']
+            result = (await c.post(f'/api/math/answer-attempts/{aid}/scans', json={})).json()
+            sid = result['scan']['id']
+            assert 'lease_id' not in result['scan']
+            assert (await c.get(f'/api/math/answer-scans/{sid}', headers=other)).status_code == 404
+            assert (await c.get('/api/math/answer-scans', headers=other)).json() == []
+            assert (await c.get(f'/api/math/answer-attempts/{aid}/image', headers=other)).status_code == 404
+            assert (await c.post(f'/api/math/answer-scans/{sid}/confirm')).status_code == 200
+            async def lease():
+                return (await c.post(f'/api/math/answer-scans/{sid}/uploads', json={'key': str(uuid.uuid4())})).json()['lease_id']
+            lid = await lease()
+            url = f'/api/math/answer-scans/{sid}/uploads/{lid}'
+            assert (await c.post(url, files={'photo': ('fake.jpg', b'fake', 'image/jpeg')})).status_code == 415
+            assert (await c.get(f'/api/math/answer-scans/{sid}')).json()['scan']['state'] == 'failed'
+            for failure in ('fail_put', 'fail_finalize'):
+                lid = await lease(); url = f'/api/math/answer-scans/{sid}/uploads/{lid}'
+                setattr(store, failure, True)
+                assert (await c.post(url, files={'photo': ('answer.png', png(), 'image/png')})).status_code == 503
+                setattr(store, failure, False)
+                assert (await c.get(f'/api/math/answer-scans/{sid}')).json()['attachment'] is None
+            lid = await lease(); url = f'/api/math/answer-scans/{sid}/uploads/{lid}'
+            result = (await c.post(url, files={'photo': ('answer.png', png(), 'image/png')})).json()
+            assert result['scan']['state'] == 'received' and 'object_key' not in result['attachment']
+            assert (await c.post(url, files={'photo': ('answer.png', png(), 'image/png')})).json()['attachment']['id'] == result['attachment']['id']
+            image = await c.get(f'/api/math/answer-attempts/{aid}/image')
+            assert image.status_code == 200 and image.headers['cache-control'] == 'no-store'
+            restarted = create_app(auth=ScanAuth()); restarted.state.answers = store
+            async with httpx.AsyncClient(transport=httpx.ASGITransport(app=restarted), base_url='http://test', headers=owner) as new:
+                assert (await new.get(f'/api/math/answer-attempts/{aid}/image')).content == image.content
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=create_app()), base_url='http://test') as guest:
+            assert (await guest.get('/api/math/answer-scans')).status_code == 401
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url='http://test') as guest:
+            assert (await guest.get('/api/math/answer-scans')).status_code == 401
+    asyncio.run(check())
+
+
+def test_expired_scan_rejects_begin_and_submission_and_can_renew(answer_store):
+    store = answer_store
+    r = request(store)
+    b = begin(store, r)
+    with store.connect() as c:
+        c.execute("update math_answer_scans set expires_at=now()-interval '1 second' where id=%s", (r['scan']['id'],))
+    app = create_app(auth=ScanAuth());app.state.answers=store
+    async def check():
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url='http://test', headers={'Authorization':f'Bearer {OWNER}'}) as c:
+            sid, lid = b['scan']['id'], b['scan']['lease_id']
+            assert (await c.post(f'/api/math/answer-scans/{sid}/confirm')).status_code == 410
+            assert (await c.post(f'/api/math/answer-scans/{sid}/uploads', json={'key':str(uuid.uuid4())})).status_code == 410
+            assert (await c.post(f'/api/math/answer-scans/{sid}/uploads/{lid}', files={'photo':('a.png',png(),'image/png')})).status_code == 410
+            renewed = (await c.post(f"/api/math/answer-attempts/{r['attempt']['id']}/scans",json={'renew':True})).json()
+            assert renewed['attempt']['id'] == r['attempt']['id'] and renewed['scan']['generation']==2
+            assert (await c.post(f'/api/math/answer-scans/{sid}/confirm')).status_code == 409
+    asyncio.run(check())
+
+
+def test_enable_rollback_preserves_received_answers(answer_store):
+    store = answer_store
+    done = finish(store, begin(store, request(store)))
+    store.enabled = False
+    app = create_app(auth=ScanAuth());app.state.answers=store
+    async def check():
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app),base_url='http://test',headers={'Authorization':f'Bearer {OWNER}'}) as c:
+            assert (await c.get('/api/me')).json()['answer_scans'] is False
+            skills=(await c.get('/api/math/skills')).json()['skills']
+            assert len(next(s for s in skills if s['id']=='g_triangle_area')['sample']['choices'])==3
+            assert (await c.get('/api/math/answer-scans')).status_code==503
+            store.enabled=True
+            skills=(await c.get('/api/math/skills')).json()['skills']
+            assert next(s for s in skills if s['id']=='g_triangle_area')['sample']['type']=='open-ended'
+            assert (await c.get(f"/api/math/answer-attempts/{done['attempt']['id']}/image")).status_code==200
+        with store.connect() as c:
+            assert c.execute('select count(*) from classes').fetchone()[0]==1
+            assert c.execute('select count(*) from math_answer_attachments').fetchone()[0]==1
+    asyncio.run(check())
+
+
+def test_supabase_storage_http_contract(monkeypatch):
+    import json
+    from urllib.error import HTTPError
+    from app.answer_scans import AnswerScans
+    store = AnswerScans(ScanAuth(), enabled=True)
+    requests=[]
+    class Response:
+        def __enter__(self): return self
+        def __exit__(self,*args): pass
+        def read(self): return b'{}'
+    def urlopen(req, timeout):
+        requests.append(req)
+        return Response()
+    monkeypatch.setattr('urllib.request.urlopen',urlopen)
+    store.action(OWNER,'get',attempt_id=str(uuid.uuid4()))
+    assert requests[-1].full_url.endswith('/rest/v1/rpc/math_answer_action')
+    assert json.loads(requests[-1].data)['p_user']==OWNER
+    key=f'{OWNER}/scan/lease/image.jpg'
+    store.put(key,b'image');assert requests[-1].method=='POST' and requests[-1].full_url.endswith('/storage/v1/object/mathly-answers/'+key)
+    assert requests[-1].get_header('Content-type')=='image/jpeg'
+    store.read(key);assert requests[-1].full_url.endswith('/storage/v1/object/authenticated/mathly-answers/'+key)
+    store.delete(key);assert requests[-1].method=='DELETE' and json.loads(requests[-1].data)=={'prefixes':[key]}
+    assert all(r.get_header('Authorization')=='Bearer server-test' for r in requests)
+    def denied(req, timeout):
+        raise HTTPError(req.full_url,400,'bad',{},io.BytesIO(b'{"code":"P0002","message":"private detail"}'))
+    monkeypatch.setattr('urllib.request.urlopen',denied)
+    with pytest.raises(ScanError) as e:
+        store.action(OTHER,'get',attempt_id=str(uuid.uuid4()))
+    assert (e.value.status,e.value.code)==(404,'not_found')
+
+
+def test_renewal_and_finalization_are_serialized(answer_store):
+    store = answer_store
+    b = begin(store, request(store))
+    def renew():
+        try:
+            return store.action(OWNER,'create_scan',attempt_id=b['attempt']['id'],renew=True)
+        except ScanError as exc:
+            assert exc.code=='upload_in_progress'
+    with ThreadPoolExecutor(2) as pool:
+        finalizing=pool.submit(finish,store,b)
+        renewing=pool.submit(renew)
+        result=finalizing.result();renewing.result()
+    assert result['scan']['state']=='received'
+    assert store.action(OWNER,'get',attempt_id=b['attempt']['id'])['attachment']['id']==result['attachment']['id']
+    with store.connect() as c:
+        assert c.execute('select count(*) from math_answer_attachments').fetchone()[0]==1
+        assert c.execute('select count(*) from math_answer_scans').fetchone()[0]==1

tests/test_math_skills.py

@@ -4,7 +4,30 @@ import asyncio
 import httpx
 
 from app.main import create_app
-from app.math_skills import algebra9, problems
+from app.math_skills import algebra9, practice_graph, problems, question_version
+
+
+def test_open_ended_samples_and_content_identity():
+    graph = copy.deepcopy(algebra9())
+    sample = graph["skills"][0]["sample"] = {"type": "open-ended", "version": 1,
+                                           "question": "Draw a triangle."}
+    assert problems(graph) == []
+    original = question_version(sample)
+    sample["question"] = "Draw a rectangle."
+    assert question_version(sample) != original
+    sample["choices"] = []
+    assert any("cannot have choices" in item for item in problems(graph))
+    sample.pop("choices")
+    sample["version"] = True
+    assert any("version" in item for item in problems(graph))
+    sample["type"] = "unknown"
+    assert any("unknown question type" in item for item in problems(graph))
+
+
+def test_choice_samples_still_require_one_correct_choice():
+    graph = copy.deepcopy(algebra9())
+    graph["skills"][0]["sample"]["choices"] = []
+    assert any("exactly one correct choice" in item for item in problems(graph))
 
 
 def test_the_algebra_graph_is_whole():
@@ -26,7 +49,7 @@ def test_math_is_the_only_page_and_api():
         async with httpx.AsyncClient(transport=httpx.ASGITransport(app=create_app()), base_url="http://test") as client:
             assert "מתמטיקה בכיף" in (await client.get("/")).text
             assert "מתמטיקה בכיף" in (await client.get("/math")).text
-            assert (await client.get("/api/math/skills")).json() == algebra9()
+            assert (await client.get("/api/math/skills")).json() == practice_graph(False)
             assert (await client.get("/api/health")).json() == {"ok": True, "app": "mathly"}
     asyncio.run(check())
 
@@ -48,3 +71,14 @@ def test_a_photographed_problem_is_solved(monkeypatch):
             assert response.json()["answer"] == "$x = ±3$"
             assert response.json()["left"] is None
     asyncio.run(check())
+
+
+def test_rollout_and_rollback_question_variants():
+    enabled, disabled = practice_graph(True), practice_graph(False)
+    assert problems(enabled) == problems(disabled) == []
+    opened = next(s for s in enabled['skills'] if s['id']=='g_triangle_area')
+    fallback = next(s for s in disabled['skills'] if s['id']=='g_triangle_area')
+    assert opened['sample']['type']=='open-ended' and 'choices' not in opened['sample']
+    assert opened['question_version']==question_version(opened['sample'])
+    assert len(fallback['sample']['choices']) == 3
+    assert all('fallback_sample' not in s for s in enabled['skills'])