Implement push notifications for photo requests from computer to phone

- Added push notification functionality in app/push.py to notify phones when a photo of an answer is requested from the computer.
- Created a new service worker (static/service-worker.js) to handle push notifications.
- Introduced a new database table (supabase/migrations/20261103180000_math_push_subs.sql) to store push subscriptions.
- Updated the frontend (static/math.js, static/math.css) to remove phone pairing functionality and adjust UI accordingly.
- Removed related tests (tests/test_phone_browser.py) and added new tests for push notifications (tests/test_push.py).
- Ensured proper handling of push subscription lifecycle and error cases.

.env.example

@@ -4,12 +4,30 @@ 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=
 
 # Enables photographed-problem help and checks of saved handwritten answers.
-# Apply the answer-grading migration before enabling checks in a deployment.
 ANTHROPIC_API_KEY=
 # MATH_MODEL=claude-opus-5-5
+
+# ---- Open-ended questions and unit quizzes (answers written on paper and photographed) ----
+# All of these are needed, plus sign-in (SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY above)
+# and ANTHROPIC_API_KEY for the automatic check.
+# Before turning them on, apply these Supabase migrations in order:
+#   supabase/migrations/20261031133254_math_answer_scans.sql         (answer photos and the private bucket)
+#   supabase/migrations/20261031193200_math_answer_grading.sql       (automatic checks)
+#   supabase/migrations/20261103120000_math_answer_scan_decline.sql  (declining a phone photo request)
+# 1 stores photographed answers (computer and phone on the same account). 0 = off.
+MATHLY_ANSWER_SCANS_ENABLED=0
+# 0 opens open-ended questions and unit quizzes to students and lets the server check them with AI
+# (this spends API tokens). Anything else, or unset, keeps them locked.
+MATHLY_OPEN_ENDED_LOCKED=1
+
+# ---- Phone notifications for photo requests (app/push.py) ----
+# When the computer asks for a photo of an answer, the student's phone gets a notification, even with the app closed.
+# Apply supabase/migrations/20261103180000_math_push_subs.sql first. Make a key with:  python -m app.push
+# Changing the key drops every subscription: each phone has to turn notifications on again.
+VAPID_PRIVATE_KEY=
+# A contact for the push services, "mailto:...". Default: the first developer's email.
+# VAPID_SUBJECT=

README.md

@@ -12,9 +12,11 @@ pinned: false
 
 Mathly is a Hebrew ninth-grade algebra and geometry practice path. It contains 140 skills across 14 units that follow the Ministry of Education's 9th-grade teaching schedule (see `docs/prisa_9A.md`), ten per unit, immediate feedback for known mistakes, and optional photographed-problem help.
 
-Choose **צילום בטלפון, פתרון במחשב** on the computer, scan the QR code with your phone, take a photo, and confirm sending it. The answer and worked solution appear automatically on the computer. Links last 15 minutes and accept one exercise; the phone does not need a separate login. Geometry practice includes diagrams for rectangle area, triangle area, and Pythagoras.
+Geometry practice includes diagrams for rectangle area, triangle area, and Pythagoras.
 
-Both devices must be able to reach the same app URL. For local use, open the computer's LAN address (for example `http://192.168.1.10:7860`) on both devices instead of `localhost`. Phone links and results are temporary in server memory: use a single server worker; restarting it clears active links. Images are sent to the configured AI provider for solving and are not stored by Mathly.
+Photographed problems are sent to the configured AI provider for solving and are not stored by Mathly.
+
+When the computer asks for a photo of a handwritten answer, the student's phone can get a notification, even with the app closed. The phone offers it after its first photo is sent. It needs `VAPID_PRIVATE_KEY` (make one with `python -m app.push`) and the migration `supabase/migrations/20261103180000_math_push_subs.sql`. On an iPhone it works only from the app added to the home screen.
 
 ## Run locally
 

app/answer_routes.py

@@ -155,11 +155,16 @@ def install_answer_routes(app, signed_in):
             log.info("automatic answer grading stopped: %s", exc.code)
 
     @app.post("/api/math/answer-attempts/{attempt_id}/scans")
-    def create_scan(attempt_id: str, body: dict, user=Depends(student)):
+    def create_scan(attempt_id: str, body: dict, background_tasks: BackgroundTasks, 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))
+        result = call(user, "create_scan", **fields)
+        push = getattr(app.state, "push", None)
+        if push is not None and push.on:
+            # the phone may be in a pocket with the app closed: a notification brings the student to the request
+            background_tasks.add_task(push.scan_requested, user, result)
+        return reply(result)
 
     @app.get("/api/math/answer-scans")
     def pending(user=Depends(student)):

app/main.py

@@ -3,8 +3,6 @@ from __future__ import annotations
 
 import logging
 import os
-import io
-import secrets
 import time
 from datetime import datetime
 from pathlib import Path
@@ -22,6 +20,7 @@ from .auth import AuthUnavailable, ClassConflict, SupabaseAuth, load_auth
 from .math_photo import (DAILY_PHOTOS, MAX_PHOTO, MEDIA_TYPES as PHOTO_TYPES,
                          PhotoSolver, PhotoUnavailable, math_model, photo_client)
 from .math_skills import algebra9, practice_graph
+from .push import install_push_routes
 from .monitoring import ActionLog, RETURN_GAP, install_monitoring_routes
 from .unit_resources import install_resource_routes
 
@@ -101,25 +100,12 @@ def create_app(auth: SupabaseAuth | None = None) -> FastAPI:
     async def index():
         return page()
 
-    @app.get("/phone", response_class=HTMLResponse, include_in_schema=False)
-    async def phone():
-        return HTMLResponse((STATIC / "phone.html").read_text(encoding="utf-8"),
-                            headers={"Cache-Control": "no-store", "Referrer-Policy": "no-referrer"})
-
     @app.get("/service-worker.js", include_in_schema=False)
-    async def retired_service_worker():
-        # An older version installed a service worker that served /static/ from its own cache forever.
-        # Browsers that still have it fetch this file to update it: the new one clears that cache,
-        # removes itself and reloads the open pages, so they get the current app.
-        script = """
-self.addEventListener("install", () => self.skipWaiting());
-self.addEventListener("activate", event => event.waitUntil((async () => {
-  await Promise.all((await caches.keys()).map(key => caches.delete(key)));
-  await self.registration.unregister();
-  for (const client of await self.clients.matchAll({type: "window"})) client.navigate(client.url);
-})()));
-"""
-        return Response(script, media_type="text/javascript", headers={"Cache-Control": "no-store"})
+    async def service_worker():
+        # Push notifications only (see app/push.py). It serves nothing from a cache: an older version kept /static/
+        # in its own cache forever, so on activation this one also deletes every cache that version left.
+        return Response((STATIC / "service-worker.js").read_text(encoding="utf-8"), media_type="text/javascript",
+                        headers={"Cache-Control": "no-store"})
 
     @app.get("/manifest.webmanifest", include_in_schema=False)
     async def manifest():
@@ -202,47 +188,6 @@ self.addEventListener("activate", event => event.waitUntil((async () => {
         return {"ok": True}
 
     photo_counts: dict[tuple[str, str], int] = app.state.photo_counts
-    photo_sessions: dict[str, dict] = {}
-
-    def session_for(token: str) -> dict:
-        session = photo_sessions.get(token)
-        if not session or session["expires"] <= time.monotonic():
-            photo_sessions.pop(token, None)
-            raise HTTPException(410, "הקישור פג. פתחו קישור חדש במחשב.")
-        return session
-
-    @app.post("/api/math/photo-sessions")
-    async def pair_phone(user: dict | None = Depends(signed_in)):
-        solver()  # Report missing configuration before asking the student to scan.
-        for token in list(photo_sessions):
-            if photo_sessions[token]["expires"] <= time.monotonic():
-                del photo_sessions[token]
-        if len(photo_sessions) >= 1000:
-            raise HTTPException(429, "נסו שוב מאוחר יותר.")
-        token = secrets.token_urlsafe(32)
-        photo_sessions[token] = {"expires": time.monotonic() + 900, "user": user,
-                                 "state": "waiting", "result": None, "error": ""}
-        return {"token": token, "expires_in": 900}
-
-    @app.get("/api/math/photo-sessions/{token}")
-    async def paired_result(token: str, user: dict | None = Depends(signed_in)):
-        session = session_for(token)
-        if (session["user"] or {}).get("email") != (user or {}).get("email"):
-            raise HTTPException(404, "session not found")
-        return JSONResponse({key: session[key] for key in ("state", "result", "error")},
-                            headers={"Cache-Control": "no-store"})
-
-    @app.post("/api/math/photo-qr")
-    async def photo_qr(request: Request, _user: dict | None = Depends(signed_in)):
-        import qrcode
-        import qrcode.image.svg
-        body = await request.json()
-        url = body.get("url", "")
-        if not isinstance(url, str) or len(url) > 2048 or not url.startswith(("https://", "http://")):
-            raise HTTPException(400, "invalid phone URL")
-        output = io.BytesIO()
-        qrcode.make(url, image_factory=qrcode.image.svg.SvgPathImage, border=4).save(output)
-        return Response(output.getvalue(), media_type="image/svg+xml", headers={"Cache-Control": "no-store"})
 
     def solver() -> PhotoSolver:
         key = os.environ.get("ANTHROPIC_API_KEY", "").strip() or os.environ.get("CLAUDE_API_KEY", "").strip()
@@ -289,23 +234,7 @@ self.addEventListener("activate", event => event.waitUntil((async () => {
         app.state.actions.record(user, "photo", skill if result.get("readable") else "התמונה לא נקראה")
         return {**result, "left": DAILY_PHOTOS - photo_counts.get(counter, 0) if counter else None}
 
-    @app.post("/api/math/phone-photo")
-    async def phone_photo(request: Request, photo: UploadFile = File(...)):
-        session = session_for(request.headers.get("x-photo-token", ""))
-        if session["state"] in ("solving", "done"):
-            raise HTTPException(409, "התמונה כבר נשלחה. פתחו קישור חדש במחשב לתרגיל נוסף.")
-        session.update(state="solving", error="")
-        try:
-            result = await solve_upload(photo, session["user"])
-        except HTTPException as exc:
-            session.update(state="error", error=str(exc.detail))
-            raise
-        except Exception:
-            session.update(state="error", error="לא הצלחנו לפתור. נסו שוב.")
-            raise
-        session.update(state="done", result=result)
-        return {"ok": True, "readable": result.get("readable", False)}
-
+    install_push_routes(app, signed_in)
     install_answer_routes(app, signed_in)
     install_resource_routes(app, signed_in)
     install_monitoring_routes(app, manager)

app/push.py

@@ -0,0 +1,228 @@
+"""Push notifications: the phone is told when the computer asks for a photo of an answer.
+
+The computer creates a photo request (POST /api/math/answer-attempts/{id}/scans). The phone already looks for requests
+while the app is open on it; this notification brings the student to the app when it is closed. A tap opens the app,
+and its usual look for requests shows the request's window with the 4-digit code.
+
+Only phones subscribe (the page offers it on the same devices that look for requests), so the computer that made the
+request does not get it. The browser's subscription (its push service address and two keys) is kept in the Supabase
+table `math_push_subs` with the account's user ID; only the server's secret key reads it. A subscription the push
+service no longer knows (404/410) is deleted.
+
+On an iPhone the browser sends them only from the app added to the home screen (iOS 16.4 and later).
+
+Env:  VAPID_PRIVATE_KEY  (the server's push key; make one with  python -m app.push  and keep it as a secret.
+                          Changing it drops every subscription: each phone has to turn notifications on again.)
+      VAPID_SUBJECT      (a contact the push services may write to, "mailto:..."; default: the first developer's email)
+"""
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import urllib.parse
+from datetime import datetime, timezone
+
+from .answer_scans import scan_code
+from .auth import AuthUnavailable
+
+log = logging.getLogger("mathly.push")
+MAX_ENDPOINT = 1000
+MIGRATION = "supabase/migrations/20261103180000_math_push_subs.sql"
+
+
+def _b64(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def new_private_key() -> str:
+    """A new VAPID private key, as VAPID_PRIVATE_KEY keeps it: the raw 32 bytes, base64url."""
+    from cryptography.hazmat.primitives.asymmetric import ec
+    return _b64(ec.generate_private_key(ec.SECP256R1()).private_numbers().private_value.to_bytes(32, "big"))
+
+
+def public_key(private: str) -> str:
+    """The browser's applicationServerKey for this private key: the uncompressed point, base64url."""
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric import ec
+    raw = base64.urlsafe_b64decode(private + "=" * (-len(private) % 4))
+    if len(raw) != 32 or base64.urlsafe_b64encode(raw).rstrip(b"=").decode() != private:
+        raise ValueError("not a 32-byte base64url key")
+    key = ec.derive_private_key(int.from_bytes(raw, "big"), ec.SECP256R1())
+    return _b64(key.public_key().public_bytes(serialization.Encoding.X962, serialization.PublicFormat.UncompressedPoint))
+
+
+def scan_payload(result: dict) -> dict:
+    """What the service worker shows for a photo request. No question text or name: it may show on a locked screen.
+    The tag is the attempt's, so a new request for the same question replaces the old notification."""
+    code = scan_code((result.get("scan") or {}).get("id"))
+    return {"title": "📷 בקשת צילום מהמחשב",
+            "body": (f"קוד {code} · " if code else "") + "צלמו את התשובה ושלחו למחשב.",
+            "url": "/?from=push-scan", "tag": f"scan-{result['attempt']['id']}"}
+
+
+def seconds_left(result: dict, now: datetime | None = None) -> int:
+    """How long the push service should keep trying: until the request expires (a dead request is not worth a ring)."""
+    expires = (result.get("scan") or {}).get("expires_at")
+    try:
+        end = datetime.fromisoformat(str(expires).replace("Z", "+00:00"))
+    except ValueError:
+        return 900
+    return max(0, min(900, int((end - (now or datetime.now(timezone.utc))).total_seconds())))
+
+
+class Push:
+    def __init__(self, auth, private: str = "", subject: str = ""):
+        self.auth, self.private, self.subject = auth, private.strip(), subject
+        self.public, self.why = "", ""   # why: what keeps notifications off, in words for logs and the API
+        self.notified: set[str] = set()   # scan IDs already announced (a repeated create_scan returns the same scan)
+        if not self.private:
+            self.why = "VAPID_PRIVATE_KEY is not set"
+        elif not getattr(auth, "secret", ""):
+            self.why = "SUPABASE_SECRET_KEY is not set"
+        else:
+            try:
+                self.public = public_key(self.private)
+            except ValueError as e:
+                log.error("VAPID_PRIVATE_KEY is not a valid key: push notifications are off (%s)", e)
+                self.why = "VAPID_PRIVATE_KEY is not a valid key"
+
+    @property
+    def on(self) -> bool:
+        return not self.why
+
+    # the table
+    def _admin(self, path: str, method: str = "GET", body=None, prefer: str = "return=representation"):
+        try:
+            return self.auth._admin(path, method, body, prefer=prefer)
+        except AuthUnavailable as e:
+            if "answered 404" in str(e) or "math_push_subs" in str(e):
+                raise AuthUnavailable(f"the table math_push_subs is missing; apply {MIGRATION}") from e
+            raise
+
+    def save(self, user_id: str, sub: dict) -> None:
+        """Keeps a browser's subscription for this account, raising ValueError when it is not one.
+        A subscription that belonged to another account on this phone moves to this one."""
+        endpoint, keys = str(sub.get("endpoint") or ""), sub.get("keys") or {}
+        if not endpoint.startswith("https://") or len(endpoint) > MAX_ENDPOINT or not isinstance(keys, dict):
+            raise ValueError("not a push subscription")
+        p256dh, auth = str(keys.get("p256dh") or ""), str(keys.get("auth") or "")
+        if not (0 < len(p256dh) <= 200 and 0 < len(auth) <= 100):
+            raise ValueError("not a push subscription")
+        self._admin("/rest/v1/math_push_subs?on_conflict=endpoint", "POST",
+                    {"endpoint": endpoint, "user_id": user_id, "p256dh": p256dh, "auth": auth},
+                    prefer="resolution=merge-duplicates,return=minimal")
+
+    def delete(self, endpoint: str, user_id: str | None = None) -> None:
+        q = {"endpoint": f"eq.{endpoint}", **({"user_id": f"eq.{user_id}"} if user_id else {})}
+        self._admin("/rest/v1/math_push_subs?" + urllib.parse.urlencode(q), "DELETE", prefer="return=minimal")
+
+    def mine(self, user_id: str) -> list[dict]:
+        return self._admin("/rest/v1/math_push_subs?select=*&" + urllib.parse.urlencode({"user_id": f"eq.{user_id}"})) or []
+
+    # sending
+    def send(self, row: dict, payload: dict, ttl: int) -> bool:
+        """One notification; False when it did not go (a subscription that is gone is deleted)."""
+        from pywebpush import WebPushException, webpush
+        try:
+            webpush({"endpoint": row["endpoint"], "keys": {"p256dh": row["p256dh"], "auth": row["auth"]}},
+                    json.dumps(payload, ensure_ascii=False), vapid_private_key=self.private,
+                    vapid_claims={"sub": self.subject}, ttl=ttl, timeout=10,
+                    headers={"Urgency": "high"})   # the student is waiting at the computer
+            return True
+        except WebPushException as e:
+            status = getattr(e.response, "status_code", None)
+            if status in (404, 410):
+                log.info("push subscription is gone: deleted")
+                try:
+                    self.delete(row["endpoint"])
+                except AuthUnavailable as e2:
+                    log.warning("push subscription not deleted: %s", e2)
+            else:
+                log.warning("push failed: %s", e)
+        except Exception as e:   # a network failure: the phone still finds the request when the app opens
+            log.warning("push failed: %s", e)
+        return False
+
+    def scan_requested(self, user_id: str, result: dict) -> int:
+        """Tells the account's phones about a new photo request; how many went. Called in the background."""
+        scan = result.get("scan") or {}
+        if not self.on or scan.get("state") != "waiting" or not scan.get("id") or scan["id"] in self.notified:
+            return 0
+        ttl = seconds_left(result)
+        if not ttl:
+            return 0
+        self.notified.add(scan["id"])
+        if len(self.notified) > 10_000:
+            self.notified.clear()
+        try:
+            rows = self.mine(user_id)
+        except AuthUnavailable as e:
+            log.warning("photo request not pushed: %s", e)
+            return 0
+        message = scan_payload(result)
+        return sum(self.send(row, message, ttl) for row in rows)
+
+
+def load_push(auth) -> Push | None:
+    if auth is None:
+        return None
+    subject = os.environ.get("VAPID_SUBJECT", "").strip()
+    if not subject:
+        dev = sorted(getattr(auth, "developers", ()) or getattr(auth, "teachers", ()) or ())
+        subject = f"mailto:{dev[0]}" if dev else "mailto:admin@example.com"
+    push = Push(auth, os.environ.get("VAPID_PRIVATE_KEY", ""), subject)
+    log.info("photo request notifications: %s", "on" if push.on else f"off ({push.why})")
+    return push
+
+
+def install_push_routes(app, signed_in):
+    """GET /api/push (the public key), POST /api/push/subscribe and /api/push/unsubscribe."""
+    from fastapi import Body, Depends, HTTPException
+    from fastapi.responses import JSONResponse
+
+    if not hasattr(app.state, "push"):
+        app.state.push = load_push(app.state.auth)
+
+    def account(user=Depends(signed_in)) -> str:
+        if not user or not user.get("id"):
+            raise HTTPException(401, "sign_in_required")
+        return user["id"]
+
+    def push_on() -> Push:
+        p = app.state.push
+        if not p or not p.on:
+            raise HTTPException(503, f"push notifications are off: {p.why if p else 'no sign-in'}")
+        return p
+
+    @app.get("/api/push")
+    def push_info(_user: str = Depends(account)):
+        """The server's push key, for the page to subscribe with; empty when notifications are off."""
+        p = app.state.push
+        return JSONResponse({"key": p.public if p and p.on else ""}, headers={"Cache-Control": "no-store"})
+
+    @app.post("/api/push/subscribe")
+    def push_subscribe(body: dict = Body(...), user: str = Depends(account)):
+        p = push_on()
+        try:
+            p.save(user, body)
+        except ValueError as e:
+            raise HTTPException(400, str(e)) from e
+        except AuthUnavailable as e:
+            raise HTTPException(503, str(e)) from e
+        return {"ok": True}
+
+    @app.post("/api/push/unsubscribe")
+    def push_unsubscribe(body: dict = Body(...), user: str = Depends(account)):
+        p = push_on()
+        try:
+            p.delete(str(body.get("endpoint") or ""), user)
+        except AuthUnavailable as e:
+            raise HTTPException(503, str(e)) from e
+        return {"ok": True}
+
+
+if __name__ == "__main__":
+    key = new_private_key()
+    print(f"VAPID_PRIVATE_KEY={key}\n# its public key (the page reads it from the server): {public_key(key)}")

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

@@ -28,6 +28,6 @@ None. This repository has no main capability specifications yet.
 
 - 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`.
+- Existing account integration in `app/auth.py`, mobile/PWA entry in `static/index.html`, and reusable photo preparation from `static/photo-image.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.

requirements.txt

@@ -3,7 +3,7 @@ uvicorn[standard]>=0.29
 anyio>=4.10,<4.11  # Python 3.10: newer releases can hang Starlette's worker-thread bridge
 python-multipart>=0.0.9
 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
+pywebpush>=2.0,<3  # phone notifications for photo requests (app/push.py)

static/answer-scans.js

@@ -31,8 +31,87 @@ function configure(options){
   reset();api=options.api;account=options.enabled?options.account:null;visibleRoot=options.root;onGraded=options.onGraded;
   if(!account)return;
   // The phone (the responsive app/PWA) watches for requests from the computer and pops them up.
-  if(matchMedia("(max-width: 700px)").matches||navigator.maxTouchPoints){inbox=true;pollInbox(epoch);}
+  if(matchMedia("(max-width: 700px)").matches||navigator.maxTouchPoints){inbox=true;pollInbox(epoch);pushSync(epoch);}
 }
+/* ---------- the phone: a notification when the computer asks for a photo (app/push.py) ----------
+   Only the phone subscribes, so the computer that made the request is not notified. The notification just brings the
+   student here; the look for requests above shows the request itself. On an iPhone only the app added to the home
+   screen may get notifications. A tap while the app is open comes as a message from the service worker. */
+const PUSH_IOS=/iPhone|iPad|iPod/.test(navigator.userAgent)||(navigator.platform==="MacIntel"&&navigator.maxTouchPoints>1);
+const PUSH_STANDALONE=matchMedia("(display-mode: standalone)").matches||navigator.standalone===true;
+const PUSH_CAN="serviceWorker" in navigator&&"PushManager" in window&&"Notification" in window;
+const PUSH_OFF="mathly.pushOff";   // turned off here: not turned on again by itself
+const pushOptOut=v=>{try{if(v===undefined)return localStorage.getItem(PUSH_OFF)==="1";v?localStorage.setItem(PUSH_OFF,"1"):localStorage.removeItem(PUSH_OFF);}catch{return false;}};
+let pushKey=null,pushReg=null;
+function pushWorker(){
+  if(!("serviceWorker" in navigator))return Promise.resolve(null);
+  return pushReg||=navigator.serviceWorker.register("/service-worker.js").then(()=>navigator.serviceWorker.ready).catch(()=>null);
+}
+async function pushState(){   // {key, sub}: key is empty when the server sends no notifications
+  if(!PUSH_CAN||!account)return {key:"",sub:null};
+  if(pushKey===null)pushKey=await json("/api/push").then(d=>d.key||"").catch(()=>"");
+  const reg=await pushWorker();
+  const sub=reg?await reg.pushManager.getSubscription().catch(()=>null):null;
+  return {key:pushKey,sub};
+}
+const subscribeBody=sub=>({method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(sub.toJSON())});
+async function pushOn(key){   // asks the permission (call it from a tap) and subscribes; the subscription, or null
+  if(await Notification.requestPermission()!=="granted")return null;
+  const reg=await pushWorker();if(!reg)throw Error("no worker");
+  const raw=atob(key.replace(/-/g,"+").replace(/_/g,"/")+"=".repeat((4-key.length%4)%4));
+  const sub=await reg.pushManager.subscribe({userVisibleOnly:true,applicationServerKey:Uint8Array.from(raw,c=>c.charCodeAt(0))});
+  const r=await api("/api/push/subscribe",subscribeBody(sub));
+  if(!r.ok){await sub.unsubscribe().catch(()=>{});throw Error("not kept");}
+  pushOptOut(false);return sub;
+}
+async function pushOff(sub){
+  await api("/api/push/unsubscribe",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({endpoint:sub.endpoint})}).catch(()=>{});
+  await sub.unsubscribe().catch(()=>{});
+}
+/* A phone's subscription belongs to the account signed in on it: on sign-in it moves to that account (or, notifications
+   being allowed already, is made again after a sign-out), unless it was turned off here. */
+async function pushSync(e){
+  try{
+    const st=await pushState();if(!live(e)||!st.key)return;
+    if(st.sub)await api("/api/push/subscribe",subscribeBody(st.sub));
+    else if(Notification.permission==="granted"&&!pushOptOut())await pushOn(st.key);
+  }catch{}
+}
+async function forgetPush(){   // signing out: the next account on this phone does not get this one's requests
+  try{const st=await pushState();if(st.sub)await pushOff(st.sub);}catch{}
+}
+async function clearScanNotices(){   // the app is open and shows requests itself: the tray's ones are old news
+  try{const reg=await navigator.serviceWorker?.getRegistration();for(const n of await reg?.getNotifications()||[])if(String(n.tag).startsWith("scan-"))n.close();}catch{}
+}
+/* The offer, at the end of a request on the phone: "next time, tell me". Nothing is shown when notifications cannot
+   work here or are blocked; an iPhone's browser gets the home-screen hint instead. */
+function pushOffer(node,e){
+  const box=document.createElement("div");box.className="mx-push-offer";box.hidden=true;node.append(box);
+  const draw=(text,button,act)=>{
+    box.replaceChildren();const p=document.createElement("small");p.textContent=text;box.append(p);
+    if(button){const b=document.createElement("button");b.className="mx-btn";b.type="button";b.textContent=button;b.onclick=async()=>{
+      b.disabled=true;try{await act();}catch{p.textContent="לא הצלחנו להפעיל התראות. נסו שוב מאוחר יותר.";}finally{b.disabled=false;}};box.append(b);}
+    box.hidden=false;
+  };
+  if(!PUSH_CAN){
+    if(PUSH_IOS&&!PUSH_STANDALONE)draw("📱 רוצים שהטלפון יצלצל כשהמחשב מבקש צילום? באייפון זה עובד רק מהאפליקציה שעל מסך הבית: שיתוף ← „הוספה למסך הבית”.");
+    return;
+  }
+  pushState().then(st=>{
+    if(!live(e)||!st.key||Notification.permission==="denied")return;
+    const show=sub=>sub
+      ?draw("🔔 התראה תגיע לטלפון כשהמחשב מבקש צילום.","כיבוי ההתראות",async()=>{await pushOff(sub);pushOptOut(true);show(null);})
+      :draw("רוצים שהטלפון יודיע לכם בפעם הבאה שהמחשב מבקש צילום, גם כשהאפליקציה סגורה?","🔔 כן, להודיע לי",async()=>{const s=await pushOn(st.key);if(live(e))show(s);});
+    show(st.sub);
+  });
+}
+if("serviceWorker" in navigator){
+  navigator.serviceWorker.addEventListener("message",ev=>{
+    if(ev.data?.type!=="notified"||!account||!inbox)return;
+    clearScanNotices();pollInbox(epoch);
+  });
+}
+if(new URLSearchParams(location.search).get("from")==="push-scan")history.replaceState(null,"",location.pathname);
 /* The phone looks for requests every few seconds while the app is open. A new request pops up as a window with its
    4-digit code (the same code the computer shows); the student photographs the answer or declines. */
 async function pollInbox(e){
@@ -48,7 +127,7 @@ async function pollInbox(e){
       if(!mine||mine.scan.id!==capture.result.scan.id&&!capture.busy)capture.withdrawn?.(mine);
     }
     const ask=list.find(r=>["waiting","confirmed","failed"].includes(r.scan.state)&&!handled.has(r.scan.id));
-    if(ask&&!capture)openCapture(ask);
+    if(ask&&!capture){openCapture(ask);clearScanNotices();}
   }catch(error){
     if(!live(e))return;
     if(error.status===401){reset();return;}
@@ -194,7 +273,7 @@ function openCapture(result){
   const valid=()=>capture===c&&live(e),say=message=>{if(valid())status.textContent=message;};
   const controls=busy=>{c.busy=busy;take.disabled=send.disabled=renew.disabled=decline.disabled=busy;};
   // the request is over: only closing is left
-  const finish=message=>{c.ended=true;handled.add(c.result.scan.id);take.hidden=send.hidden=renew.hidden=decline.hidden=true;close.hidden=false;say(message);close.focus();};
+  const finish=(message,offer=false)=>{c.ended=true;handled.add(c.result.scan.id);take.hidden=send.hidden=renew.hidden=decline.hidden=true;close.hidden=false;say(message);if(offer)pushOffer($(".mx-scan-actions"),e);close.focus();};
   const expired=()=>{take.hidden=send.hidden=true;renew.hidden=false;say(errors.expired);};
   c.withdrawn=mine=>{ if(c.photo&&mine&&waitingState(mine.scan.state)){c.result=mine;return;} finish("הבקשה בוטלה במחשב."); };
   close.onclick=()=>{closeCapture();if(valid())pollInbox(e);};
@@ -223,7 +302,7 @@ function openCapture(result){
     }catch(error){say("לא ניתן להכין את התמונה. נסו לצלם שוב.");}
     finally{if(valid())controls(false);}
   };
-  const success=()=>{c.photo=null;finish("✓ התשובה נשלחה למחשב.");};
+  const success=()=>{c.photo=null;finish("✓ התשובה נשלחה למחשב.",true);};
   send.onclick=async()=>{
     if(!c.photo||c.busy)return;
     controls(true);say(states.uploading);
@@ -322,9 +401,9 @@ function waitForPhone(result,scanTo={}){
 }
 document.addEventListener("visibilitychange",()=>{
   if(document.hidden)return;
-  if(account&&inbox)pollInbox(epoch);
+  if(account&&inbox){clearScanNotices();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,waitForPhone};
+window.MathlyAnswers={configure,mountQuestion,closeQuestion,reset,waitForPhone,forgetPush};
 })();

static/math.css

@@ -129,9 +129,6 @@ html.math-on, html.math-on body{overflow:hidden}
 .mx-geometry path{stroke:var(--uc);stroke-width:2;fill:none}
 .mx-geometry text{fill:var(--ink);font:16px var(--f-body)}
 .mx-geometry small{font-size:12px;color:var(--muted)}
-.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}
@@ -148,6 +145,8 @@ html.math-on, html.math-on body{overflow:hidden}
 .mx-scan-actions{display:flex;flex-direction:column;gap:10px}
 .mx-scan-actions .mx-btn{min-height:50px;font-size:17px}
 .mx-btn-quiet{border-color:#485050;color:#d7dcd8}
+.mx-push-offer{display:flex;flex-direction:column;gap:8px;padding-top:12px;border-top:1px solid #485050}
+.mx-push-offer[hidden]{display:none}
 .mx-scan-live{display:flex;align-items:center;justify-content:center;gap:10px;font-weight:700}
 .mx-scan-dot{width:10px;height:10px;border-radius:50%;background:var(--mx-accent);animation:sky-pulse 1.4s ease-out infinite}
 .mx-scan-wait.is-over .mx-scan-dot{display:none}

static/math.js

@@ -33,10 +33,8 @@ let G=null, BY={}, POST={}, ORDER=[], P={done:{},tries:{},solved:{},at:{}}, root
 let nav=null, FIRST=true, COMBO=0, REV=null, QZ=null, UQ=null;   // UQ: the unit quiz on the sheet (see unit quiz below)   // QZ: the practice exam in progress (see quiz below)   // the tab bar; whether the shown question is still at its first try; first-try answers in a row
 let picker=null, PH=null, resPicker=null, RES=null;   // RES: the open lesson-resources sheet (see openResources())   // the photo file picker, and the photographed problem on the sheet (see photo())
 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; }
 
@@ -988,18 +986,16 @@ function onClick(e){
     case "cal-prev": return showStreak(-1);
     case "cal-next": return showStreak(1);
     case "sound": Sky.setSound(!Sky.soundOn()); Sky.sound.tap(); return draw();
-    case "phone": return pairPhone();
     case "resources": return openResources(t.dataset.unit);
     case "res-take": case "res-retake": return resPicker.click();
     case "res-cancel": RES.photo=null; RES.msg=""; return drawResources();
     case "res-delete": return deleteResource(t.dataset.res);
-    case "copy-phone": return copyPhone(t);
     case "photo": case "retake": return picker.click();
     case "hint": PH.shown++; return drawPhoto();
     case "work": PH.works.add(+t.dataset.i); return drawPhoto();
     case "all": PH.all=true; return drawPhoto();
     case "close": return closeSheet();
-    case "out": window.MathlyAnswers?.reset();closeSheet();hide();return client?.auth.signOut().then(()=>location.reload());
+    case "out": return Promise.resolve(window.MathlyAnswers?.forgetPush?.()).finally(()=>{window.MathlyAnswers?.reset();closeSheet();hide();return client?.auth.signOut().then(()=>location.reload());});
   }
 }
 
@@ -1366,74 +1362,6 @@ function drawPhoto(){
   if(PH.fresh){ PH.fresh=false; sheet.querySelector(".mx-x").focus({preventScroll:true}); }
 }
 
-async function copyPhone(button){
-  try{
-    await navigator.clipboard.writeText(phonePair?.url||"");
-    button.textContent="הקישור הועתק";
-  }catch{
-    const input=sheet.querySelector(".mx-phone-url");
-    input?.focus();input?.select();
-    button.textContent="בחרו והעתיקו את הקישור";
-  }
-}
-
-async function pairPhone(){
-  cancelAdvance();stopPhone();
-  if(!cur)back=document.activeElement;
-  cur="phone";
-  const pair=phonePair={timer:null,qr:null,url:""};
-  sheet.innerHTML=`<div class="mx-scrim" data-act="close"></div><div class="mx-sheet" role="dialog" aria-modal="true" aria-labelledby="mxTitle">
-    <div class="mx-shtop"><h3 id="mxTitle">צילום בטלפון, פתרון במחשב</h3><button class="mx-x" data-act="close" aria-label="סגירה">✕</button></div>
-    <div class="mx-pair-content"></div><p class="mx-pair-status" role="status" aria-live="polite">מכינים קישור לטלפון…</p></div>`;
-  sheet.hidden=false;sheet.querySelector(".mx-x").focus({preventScroll:true});
-  const content=sheet.querySelector(".mx-pair-content"),message=sheet.querySelector(".mx-pair-status");
-  try{
-    const response=await api("/api/math/photo-sessions",{method:"POST"}),data=await response.json();
-    if(!response.ok)throw Error(data.detail||"לא הצלחנו ליצור קישור.");
-    if(phonePair!==pair)return;
-    pair.url=`${location.origin}/phone#${data.token}`;
-    content.innerHTML=`<p>סרקו בטלפון וצלמו את התרגיל. התשובה והפתרון יופיעו כאן. הקישור תקף ל־15 דקות ולתרגיל אחד.</p>
-      <div class="mx-qr-slot"></div><label>אפשר גם לפתוח בטלפון את הקישור:<input class="mx-phone-url" readonly dir="ltr" value="${esc(pair.url)}" aria-label="קישור לצילום בטלפון"></label>
-      <button class="mx-btn" data-act="copy-phone">העתקת קישור</button>
-      ${["localhost","127.0.0.1","[::1]"].includes(location.hostname)?'<p class="mx-bad">כדי שהטלפון יתחבר, פתחו במחשב את האתר בכתובת רשת שנגישה גם מהטלפון, ואז צרו קישור חדש.</p>':""}`;
-    message.textContent="ממתינים לתמונה מהטלפון…";
-    // Start polling independently so a QR failure still leaves a working link.
-    const poll=async()=>{
-      if(phonePair!==pair)return;
-      try{
-        const res=await api(`/api/math/photo-sessions/${data.token}`,{cache:"no-store"}),result=await res.json();
-        if(phonePair!==pair)return;
-        if(!res.ok){
-          if(res.status>=400&&res.status<500){
-            message.textContent=result.detail||"החיבור הופסק. פתחו קישור חדש.";
-            stopPhone();return;
-          }
-          throw Error(result.detail||"החיבור נקטע לרגע. מנסים שוב…");
-        }
-        if(result.state==="done"){
-          stopPhone();cur="photo";
-          if(PH?.url)URL.revokeObjectURL(PH.url);
-          PH={url:null,data:result.result,error:"",busy:false,shown:1,works:new Set(),all:true,fresh:true};
-          drawPhoto();return;
-        }
-        message.textContent=result.state==="solving"?"התמונה התקבלה! קוראים ופותרים…":result.state==="error"?result.error+" אפשר לנסות שוב בטלפון.":"ממתינים לתמונה מהטלפון…";
-      }catch(error){
-        if(phonePair!==pair)return;
-        message.textContent="החיבור נקטע לרגע. מנסים שוב…";
-      }
-      pair.timer=setTimeout(poll,2000);
-    };
-    poll();
-    try{
-      const qr=await api("/api/math/photo-qr",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({url:pair.url})});
-      if(!qr.ok)throw Error("qr");
-      const blob=await qr.blob();if(phonePair!==pair)return;
-      pair.qr=URL.createObjectURL(blob);
-      content.querySelector(".mx-qr-slot").innerHTML=`<img class="mx-phone-qr" src="${pair.qr}" alt="סרקו בטלפון כדי לצלם תרגיל">`;
-    }catch{if(phonePair===pair)content.querySelector(".mx-qr-slot").textContent="הקוד לא נטען. אפשר להעתיק את הקישור לטלפון.";}
-  }catch(error){if(phonePair===pair)message.textContent=error.message;}
-}
-
 /* Lesson resources (app/unit_resources.py). A teacher taps a unit's title on the path, photographs an exercise or an
    explanation, says what it shows (a new exercise, a theory explanation, or other words) and, if they like, which of
    the unit's topics it belongs to. Images come through the API with the teacher's sign-in, so each is a blob URL. */

static/service-worker.js

@@ -0,0 +1,30 @@
+/* Mathly's service worker: push notifications only (app/push.py). It has no fetch handler and keeps no cache.
+   An older version served /static/ from its own cache forever; activating this one deletes those caches. */
+self.addEventListener("install", () => self.skipWaiting());
+self.addEventListener("activate", event => event.waitUntil((async () => {
+  await Promise.all((await caches.keys()).map(key => caches.delete(key)));
+  await self.clients.claim();
+})()));
+
+// a photo request from the computer (or any later message): shown even when the app is closed
+self.addEventListener("push", event => {
+  let msg = {};
+  try { msg = event.data ? event.data.json() : {}; } catch { msg = { body: event.data && event.data.text() }; }
+  event.waitUntil(self.registration.showNotification(msg.title || "לומדים בכיף", {
+    body: msg.body || "", tag: msg.tag || "mathly", renotify: true, requireInteraction: false,
+    lang: "he", dir: "rtl",
+    icon: "/static/icons/icon-192.png", badge: "/static/icons/icon-192.png",
+    data: { url: msg.url || "/" }
+  }));
+});
+
+// a tap: the app already open is brought forward and told to look for requests now; otherwise it is opened
+self.addEventListener("notificationclick", event => {
+  event.notification.close();
+  const url = new URL((event.notification.data && event.notification.data.url) || "/", self.location.origin).href;
+  event.waitUntil(self.clients.matchAll({ type: "window", includeUncontrolled: true }).then(wins => {
+    const app = wins.find(w => new URL(w.url).origin === self.location.origin && !new URL(w.url).pathname.startsWith("/static/"));
+    if (app) { app.postMessage({ type: "notified", url }); return app.focus(); }
+    return self.clients.openWindow(url);
+  }));
+});

supabase/migrations/20261103180000_math_push_subs.sql

@@ -0,0 +1,15 @@
+-- Push subscriptions of phones (app/push.py): a phone is notified when the computer asks for a photo of an answer.
+-- Additive: one new table; nothing existing changes. Only the server's secret key reads or writes it.
+begin;
+create table public.math_push_subs (
+  endpoint text primary key check (endpoint like 'https://%' and length(endpoint) <= 1000),
+  user_id uuid not null references auth.users(id) on delete cascade,
+  p256dh text not null check (length(p256dh) between 1 and 200),
+  auth text not null check (length(auth) between 1 and 100),
+  created_at timestamptz not null default now()
+);
+create index math_push_subs_user on public.math_push_subs(user_id);
+alter table public.math_push_subs enable row level security;
+revoke all on public.math_push_subs from public, anon, authenticated;
+grant select, insert, update, delete on public.math_push_subs to service_role;
+commit;

tests/test_phone_browser.py

@@ -1,5 +1,4 @@
 """Optional browser regression checks: pip install playwright && playwright install chromium."""
-import base64
 import socket
 import threading
 import time
@@ -40,64 +39,6 @@ def phone_server(monkeypatch):
             thread.join(timeout=5)
 
 
-def test_phone_refresh_upload_and_desktop_network_recovery(phone_server):
-    with playwright.sync_playwright() as p:
-        browser = p.chromium.launch()
-        try:
-            computer = browser.new_page()
-            computer.route("https://cdn.jsdelivr.net/**", lambda route: route.abort())
-            polls = []
-
-            def flaky_network(route):
-                polls.append(route.request.url)
-                if len(polls) == 1:
-                    route.abort()
-                else:
-                    route.continue_()
-
-            computer.route("**/api/math/photo-sessions/*", flaky_network)
-            computer.goto(phone_server)
-            computer.locator('[data-act="phone"]').click()
-            qr = computer.locator(".mx-phone-qr")
-            playwright.expect(qr).to_be_visible()
-            assert qr.evaluate("img => img.complete && img.naturalWidth > 0")
-            url = computer.locator(".mx-phone-url").input_value()
-
-            # LAN HTTP pages have no Clipboard API. The link must still be selectable.
-            computer.evaluate('Object.defineProperty(navigator, "clipboard", {value: undefined})')
-            computer.locator('[data-act="copy-phone"]').click()
-            playwright.expect(computer.locator(".mx-phone-url")).to_be_focused()
-
-            phone = browser.new_context(is_mobile=True, viewport={"width": 390, "height": 844}).new_page()
-            phone.goto(url)
-            assert "#" not in phone.url
-            phone.reload()
-            playwright.expect(phone.locator("#take")).to_be_enabled()
-            phone.locator("#camera").set_input_files({"name": "bad.heic", "mimeType": "image/heic", "buffer": b"undecodable"})
-            playwright.expect(phone.locator("#status")).to_contain_text("JPEG, PNG")
-            playwright.expect(phone.locator("#send")).to_be_hidden()
-            # Exercise the fallback used when camera photos cannot use createImageBitmap.
-            phone.evaluate("window.createImageBitmap = undefined")
-            encoded = computer.evaluate("""() => {
-                const canvas = document.createElement('canvas');
-                canvas.width = canvas.height = 10;
-                return canvas.toDataURL('image/png').split(',')[1];
-            }""")
-            png = base64.b64decode(encoded)
-            phone.locator("#camera").set_input_files({"name": "exercise.png", "mimeType": "image/png", "buffer": png})
-            # A proxy can return HTML on failure. Keep the photo ready for another attempt.
-            phone.route("**/api/math/phone-photo", lambda route: route.fulfill(status=503, content_type="text/html", body="Unavailable"), times=1)
-            phone.locator("#send").click()
-            playwright.expect(phone.locator("#status")).to_have_text("לא הצלחנו לשלוח. נסו שוב.")
-            playwright.expect(phone.locator("#send")).to_be_enabled()
-            phone.locator("#send").click()
-            playwright.expect(phone.locator("#status")).to_have_text("הפתרון מוכן במחשב!")
-            playwright.expect(computer.locator(".mx-ok")).to_contain_text("10 cm", timeout=10000)
-            assert len(polls) >= 2
-        finally:
-            browser.close()
-
-
 @pytest.mark.parametrize("manager", [True, False])
 def test_class_management_geometry_and_permissions(phone_server, manager):
     import json

tests/test_push.py

@@ -0,0 +1,200 @@
+import asyncio
+import json
+import urllib.parse
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import httpx
+import pytest
+
+from app import push as pushes
+from app.answer_scans import scan_code
+from app.auth import AuthUnavailable
+from app.main import create_app
+from scan_support import OTHER, OWNER, ScanAuth, answer_store, postgres_server  # noqa: F401
+
+KEY = pushes.new_private_key()
+SUB = {"endpoint": "https://push.example/abc", "keys": {"p256dh": "p" * 87, "auth": "a" * 22}}
+
+
+class PushAuth(ScanAuth):
+    """ScanAuth with an in-memory math_push_subs behind the PostgREST calls Push makes."""
+
+    def __init__(self):
+        self.rows: dict[str, dict] = {}
+
+    def _admin(self, path, method="GET", body=None, prefer=""):
+        table, _, query = path.partition("?")
+        assert table == "/rest/v1/math_push_subs"
+        q = dict(urllib.parse.parse_qsl(query))
+        match = lambda r: all(r[k] == v.removeprefix("eq.") for k, v in q.items() if k in ("endpoint", "user_id"))
+        if method == "POST":
+            self.rows[body["endpoint"]] = dict(body)
+            return None
+        if method == "DELETE":
+            for e in [e for e, r in self.rows.items() if match(r)]:
+                del self.rows[e]
+            return None
+        return [r for r in self.rows.values() if match(r)]
+
+
+def scan(state="waiting", minutes=10, sid="7d9c2f0e-3c1a-4c55-9a1e-2b3c4d5e6f70"):
+    end = datetime.now(timezone.utc) + timedelta(minutes=minutes)
+    return {"attempt": {"id": "11111111-1111-1111-1111-111111111111"},
+            "scan": {"id": sid, "state": state, "expires_at": end.isoformat()}}
+
+
+@pytest.fixture
+def sent(monkeypatch):
+    calls = []
+
+    def webpush(sub, data, **kwargs):
+        calls.append({"endpoint": sub["endpoint"], "data": json.loads(data), **kwargs})
+
+    import pywebpush
+    monkeypatch.setattr(pywebpush, "webpush", webpush)
+    return calls
+
+
+def test_payload_has_code_and_no_question_and_replaces_by_attempt():
+    result = scan()
+    msg = pushes.scan_payload(result)
+    assert scan_code(result["scan"]["id"]) in msg["body"]
+    assert msg["tag"] == "scan-11111111-1111-1111-1111-111111111111"
+    assert msg["url"] == "/?from=push-scan"
+    assert 590 <= pushes.seconds_left(result) <= 600
+    assert pushes.seconds_left(scan(minutes=-1)) == 0
+    assert pushes.seconds_left({"scan": {"expires_at": None}}) == 900
+
+
+def test_keys_round_trip_and_off_reasons():
+    assert len(pushes.public_key(KEY)) == 87   # 65 bytes, base64url
+    assert pushes.Push(PushAuth(), "").why == "VAPID_PRIVATE_KEY is not set"
+    assert pushes.Push(PushAuth(), "not a key!").why == "VAPID_PRIVATE_KEY is not a valid key"
+    p = pushes.Push(PushAuth(), KEY, "mailto:a@test.invalid")
+    assert p.on and p.public == pushes.public_key(KEY)
+
+
+def test_request_goes_once_to_the_accounts_phones_and_gone_ones_are_deleted(sent, monkeypatch):
+    auth = PushAuth()
+    p = pushes.Push(auth, KEY, "mailto:a@test.invalid")
+    p.save(OWNER, SUB)
+    p.save(OWNER, {**SUB, "endpoint": "https://push.example/gone"})
+    p.save(OTHER, {**SUB, "endpoint": "https://push.example/other"})
+    with pytest.raises(ValueError):
+        p.save(OWNER, {"endpoint": "http://insecure", "keys": SUB["keys"]})
+
+    import pywebpush
+    real = pywebpush.webpush
+
+    def webpush(sub, data, **kwargs):
+        if sub["endpoint"].endswith("/gone"):
+            raise pywebpush.WebPushException("gone", response=type("R", (), {"status_code": 410})())
+        return real(sub, data, **kwargs)
+
+    monkeypatch.setattr(pywebpush, "webpush", webpush)
+    assert p.scan_requested(OWNER, scan()) == 1
+    assert [c["endpoint"] for c in sent] == [SUB["endpoint"]]
+    assert sent[0]["headers"] == {"Urgency": "high"} and 0 < sent[0]["ttl"] <= 600
+    assert "https://push.example/gone" not in auth.rows and "https://push.example/other" in auth.rows
+    assert p.scan_requested(OWNER, scan()) == 0   # the same request again: no second ring
+    assert p.scan_requested(OWNER, scan("received", sid="22222222-2222-2222-2222-222222222222")) == 0
+    assert p.scan_requested(OWNER, scan(minutes=-1, sid="33333333-3333-3333-3333-333333333333")) == 0
+    assert len(sent) == 1
+
+
+def test_missing_table_does_not_break_the_request(sent):
+    class NoTable(PushAuth):
+        def _admin(self, *a, **k):
+            raise AuthUnavailable("supabase answered 404: relation math_push_subs does not exist")
+
+    assert pushes.Push(NoTable(), KEY, "mailto:a@test.invalid").scan_requested(OWNER, scan()) == 0
+
+
+def test_subscribe_api_moves_a_phone_between_accounts(monkeypatch):
+    monkeypatch.setenv("VAPID_PRIVATE_KEY", KEY)
+    auth = PushAuth()
+    app = create_app(auth=auth)
+
+    async def check():
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as c:
+            assert (await c.get("/api/push")).status_code == 401
+            owner, other = ({"Authorization": f"Bearer {u}"} for u in (OWNER, OTHER))
+            assert (await c.get("/api/push", headers=owner)).json()["key"] == pushes.public_key(KEY)
+            assert (await c.post("/api/push/subscribe", json={"endpoint": "x"}, headers=owner)).status_code == 400
+            assert (await c.post("/api/push/subscribe", json=SUB, headers=owner)).json() == {"ok": True}
+            assert auth.rows[SUB["endpoint"]]["user_id"] == OWNER
+            assert (await c.post("/api/push/subscribe", json=SUB, headers=other)).status_code == 200
+            assert auth.rows[SUB["endpoint"]]["user_id"] == OTHER   # one row per phone: the account signed in now
+            await c.post("/api/push/unsubscribe", json={"endpoint": SUB["endpoint"]}, headers=owner)
+            assert SUB["endpoint"] in auth.rows   # another account cannot remove it
+            await c.post("/api/push/unsubscribe", json={"endpoint": SUB["endpoint"]}, headers=other)
+            assert not auth.rows
+            sw = await c.get("/service-worker.js")
+            assert "showNotification" in sw.text and 'addEventListener("fetch"' not in sw.text and sw.headers["cache-control"] == "no-store"
+
+    asyncio.run(check())
+
+
+def test_push_off_without_key(monkeypatch):
+    monkeypatch.delenv("VAPID_PRIVATE_KEY", raising=False)
+    app = create_app(auth=PushAuth())
+
+    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/push")).json() == {"key": ""}
+            assert (await c.post("/api/push/subscribe", json=SUB)).status_code == 503
+
+    asyncio.run(check())
+
+
+def test_computer_request_pushes_to_the_phone(answer_store, sent, monkeypatch):
+    monkeypatch.setenv("VAPID_PRIVATE_KEY", KEY)
+    auth = PushAuth()
+    app = create_app(auth=auth)
+    app.state.answers = answer_store
+    app.state.push.save(OWNER, SUB)
+    aid = answer_store.action(OWNER, "resume", question_id="q", question_version="v1",
+                              snapshot={"question": "Prove it", "type": "open-ended"})["attempt"]["id"]
+
+    async def check():
+        async with httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test",
+                                     headers={"Authorization": f"Bearer {OWNER}"}) as c:
+            first = (await c.post(f"/api/math/answer-attempts/{aid}/scans", json={})).json()
+            again = (await c.post(f"/api/math/answer-attempts/{aid}/scans", json={})).json()
+            assert again["scan"]["id"] == first["scan"]["id"]
+            renewed = (await c.post(f"/api/math/answer-attempts/{aid}/scans", json={"renew": True})).json()
+            return first, renewed
+
+    first, renewed = asyncio.run(check())
+    assert len(sent) == 2   # the repeated request did not ring again; the renewed one did
+    assert first["scan"]["code"] in sent[0]["data"]["body"] and renewed["scan"]["code"] in sent[1]["data"]["body"]
+    assert sent[0]["data"]["tag"] == sent[1]["data"]["tag"] == f"scan-{aid}"
+    assert "Prove it" not in json.dumps(sent)
+
+
+def test_migration_keeps_subscriptions_from_browsers(postgres_server):
+    import uuid
+
+    import psycopg
+    database = "push_" + uuid.uuid4().hex
+    with psycopg.connect(postgres_server.get_uri(), autocommit=True) as c:
+        c.execute("create database " + database)
+    try:
+        with psycopg.connect(postgres_server.get_uri(database=database), autocommit=True) as c:
+            c.execute("create schema auth; create table auth.users(id uuid primary key);"
+                      "grant usage on schema public to anon, authenticated, service_role;")
+            c.execute(Path("supabase/migrations/20261103180000_math_push_subs.sql").read_text())
+            c.execute("insert into auth.users values(%s)", (OWNER,))
+            c.execute("set role service_role")
+            c.execute("insert into math_push_subs(endpoint,user_id,p256dh,auth) values(%s,%s,'p','a')", (SUB["endpoint"], OWNER))
+            c.execute("reset role; set role authenticated")
+            with pytest.raises(psycopg.errors.InsufficientPrivilege):
+                c.execute("select * from math_push_subs")
+            c.execute("reset role")
+            with pytest.raises(psycopg.errors.CheckViolation):
+                c.execute("insert into math_push_subs(endpoint,user_id,p256dh,auth) values('http://x',%s,'p','a')", (OWNER,))
+    finally:
+        with psycopg.connect(postgres_server.get_uri(), autocommit=True) as c:
+            c.execute("drop database " + database + " with (force)")