Harden demo runtime and add browser Pygame runner

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/security-audit.yml

@@ -0,0 +1,32 @@
+name: Dependency security audit
+
+on:
+  pull_request:
+  push:
+    paths:
+      - "requirements.txt"
+      - "requirements-ml.txt"
+      - ".github/workflows/security-audit.yml"
+  schedule:
+    - cron: "23 3 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  pip-audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+      - name: Install vulnerability scanner
+        run: python -m pip install pip-audit==2.10.1
+      - name: Audit runtime dependencies
+        run: pip-audit --strict -r requirements.txt
+      - name: Audit optional ML dependencies
+        if: ${{ hashFiles('requirements-ml.txt') != '' }}
+        run: pip-audit --strict -r requirements-ml.txt

Dockerfile

@@ -1,3 +1,19 @@
+FROM node:22-alpine AS pyodide-assets
+ARG PYODIDE_VERSION=0.27.7
+WORKDIR /build
+COPY scripts/vendor_pyodide_packages.mjs ./vendor_pyodide_packages.mjs
+RUN npm install --global --ignore-scripts --omit=dev pyodide@${PYODIDE_VERSION} codemirror@5.65.16 jszip@3.10.1 \
+    && node ./vendor_pyodide_packages.mjs /usr/local/lib/node_modules/pyodide https://cdn.jsdelivr.net/pyodide/v${PYODIDE_VERSION}/full/
+
+FROM python:3.11-slim AS python-dependencies
+ARG PIP_TOOLS_VERSION=7.6.1
+ARG PIP_AUDIT_VERSION=2.10.1
+WORKDIR /build
+COPY requirements.txt .
+RUN python -m pip install --no-cache-dir pip-tools==${PIP_TOOLS_VERSION} pip-audit==${PIP_AUDIT_VERSION} \
+    && pip-compile --resolver=backtracking --generate-hashes --output-file=requirements.lock requirements.txt \
+    && pip-audit --strict -r requirements.lock
+
 FROM python:3.11-slim
 
 # System deps for OpenCV headless, Pygame, MediaPipe + CJK fonts
@@ -7,6 +23,8 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libgomp1 \
     libgles2 \
     libegl1 \
+    bubblewrap \
+    util-linux \
     fonts-wqy-zenhei \
     fonts-wqy-microhei \
     fonts-noto-cjk \
@@ -18,23 +36,51 @@ ENV PYTHONUNBUFFERED=1 \
     SDL_AUDIODRIVER=dummy \
     PORT=7860 \
     MAX_CONCURRENT_RUNNERS=3 \
+    RUNNER_STARTS_PER_IP_PER_HOUR=120 \
+    RUNNER_START_COOLDOWN_SEC=0.75 \
     SESSION_TIMEOUT_SEC=900 \
-    PROJECT_CACHE_TTL_SEC=10
+    PROJECT_CACHE_TTL_SEC=10 \
+    ENABLE_HSTS=1 \
+    CLASSROOM_COURSE_QUOTA_MB=1024 \
+    CLASSROOM_MAX_VERSIONS_PER_KIND=100 \
+    CLASSROOM_CHECKPOINTS_PER_HOUR=60 \
+    CLASSROOM_SUBMISSIONS_PER_HOUR=20 \
+    CLASSROOM_VERSION_COOLDOWN_MS=1500 \
+    CLASSROOM_WS_CONNECTIONS_PER_MINUTE=300 \
+    CLASSROOM_WS_MESSAGES_PER_MINUTE=300 \
+    RUNNER_MEMORY_LIMIT_MB=3072 \
+    RUNNER_CPU_LIMIT_SEC=900 \
+    RUNNER_TMP_LIMIT_MB=256 \
+    RUNNER_PROJECT_LIMIT_MB=128 \
+    RUNNER_PROJECT_FILE_LIMIT=2000
 
 WORKDIR /app
+COPY --from=python-dependencies /build/requirements.lock /tmp/requirements.lock
 COPY requirements.txt .
 
 # Base image without TensorFlow (smaller / faster cold start).
 # To include Keras demos: COPY requirements-ml.txt . && pip install -r requirements-ml.txt
-RUN pip install --no-cache-dir -r requirements.txt
+RUN python -m pip install --no-cache-dir --require-hashes -r /tmp/requirements.lock
 
 COPY . .
+COPY --from=python-dependencies /build/requirements.lock /app/requirements.lock
+COPY --from=pyodide-assets /usr/local/lib/node_modules/pyodide /app/classroom_static/vendor/pyodide
+COPY --from=pyodide-assets /usr/local/lib/node_modules/codemirror/lib/codemirror.js /app/classroom_static/vendor/codemirror/codemirror.js
+COPY --from=pyodide-assets /usr/local/lib/node_modules/codemirror/lib/codemirror.css /app/classroom_static/vendor/codemirror/codemirror.css
+COPY --from=pyodide-assets /usr/local/lib/node_modules/codemirror/theme/material-darker.css /app/classroom_static/vendor/codemirror/material-darker.css
+COPY --from=pyodide-assets /usr/local/lib/node_modules/codemirror/mode/python/python.js /app/classroom_static/vendor/codemirror/python.js
+COPY --from=pyodide-assets /usr/local/lib/node_modules/jszip/dist/jszip.min.js /app/classroom_static/vendor/jszip/jszip.min.js
 
-RUN mkdir -p /app/projects /app/models /app/static \
-    && chmod -R 777 /app
+RUN groupadd --gid 10001 telearn \
+    && useradd --uid 10001 --gid 10001 --create-home --shell /usr/sbin/nologin telearn \
+    && mkdir -p /app/projects /app/models /app/static /app/classroom_data /tmp/telearn_runner /tmp/telearn_classroom \
+    && chown -R telearn:telearn /app/projects /app/classroom_data /tmp/telearn_runner /tmp/telearn_classroom \
+    && chmod 700 /tmp/telearn_runner /tmp/telearn_classroom
 
 # Healthcheck for orchestrators
 HEALTHCHECK --interval=30s --timeout=5s --start-period=40s --retries=3 \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/health' % __import__('os').environ.get('PORT','7860'))" || exit 1
 
-CMD uvicorn server:app --host 0.0.0.0 --port $PORT
+USER telearn
+
+CMD uvicorn server:app --host 0.0.0.0 --port $PORT --ws-max-size 1048576 --ws-max-queue 8

SECURITY.md

@@ -0,0 +1,24 @@
+# Security and deployment notes
+
+## Student Python execution
+
+- Docker installs Bubblewrap and `prlimit`; the app runs as the unprivileged `telearn` account.
+- Each public Python run gets a copied, size-limited project workspace, Linux user/PID/network namespaces, read-only system mounts, and CPU/address-space/file/process limits. Runner environments are cleared and no network is exposed.
+- The runner fails closed when the host does not support the required Linux sandbox. Confirm namespace creation in the Hugging Face Space after deployment; do not restore a direct, unsandboxed runner as a workaround.
+- Uvicorn caps WebSocket frames at 1 MiB. Classroom sockets also have per-IP handshake and per-student message budgets; saved checkpoints/submissions have per-hour limits, cooldowns, a per-course quota, and a rolling retention cap.
+
+## Classroom storage
+
+Defaults are configured in `Dockerfile` and may be changed with `CLASSROOM_*` environment variables. The database retains up to 100 checkpoints and 100 submissions per student per Lesson, with a 1 GiB active-data quota per course. Older versions are removed from the active SQLite history and Hugging Face repository tree.
+
+Deleting a file from a Hugging Face repository's current tree does not rewrite earlier Git commits. Therefore these limits bound the active version set and current tree, but cannot strictly cap the repository's historical Git object storage. A hard lifetime storage cap requires moving classroom versions to bounded object storage or periodically archiving/recreating the repository; neither is performed automatically.
+
+## Browser security
+
+The app sends CSP, COOP/COEP, `X-Content-Type-Options`, Referrer Policy, Permissions Policy, and HSTS (enabled in the Docker image). CodeMirror, JSZip, and Pyodide are served same-origin from exact package versions included during image build. The pinned `pygame-ce` wheel and its lockfile dependency closure are also vendored same-origin, with each wheel SHA-256 checked against Pyodide's lockfile during the image build. Google Fonts, the QR service, Appetize, and MakeCode remain explicit external sources. Student HTML remains inside an opaque-origin sandbox iframe.
+
+After deployment, inspect the final public HTTPS response headers: Hugging Face's edge proxy must preserve or add HSTS and must not replace the application CSP with a weaker policy. Local source changes cannot prove what the edge returns.
+
+## Dependency scanning and lock files
+
+Every Docker build resolves `requirements.txt` in a Python 3.11 build stage, generates a complete transitive lock with hashes, audits that resolved lock using `pip-audit`, then installs the runtime dependencies with `--require-hashes`. The generated lock is included in the image as `/app/requirements.lock`; it is build-specific rather than checked into source, so rebuilding later may select newer versions allowed by `requirements.txt`. GitHub Actions also runs `pip-audit` on pull requests and weekly when this repo is mirrored to GitHub; the canonical remote for this project is Hugging Face, which does not execute that GitHub workflow by itself.

classroom_data/classes.json

@@ -1,9 +1,4 @@
 [
-  {
-    "code": "L6A",
-    "name": "2026 Fall 進階專題",
-    "students": []
-  },
   {
     "code": "L6Sat",
     "name": "2026Fall進階專題六午",
@@ -71,15 +66,5 @@
         "display_name": "陳英赫"
       }
     ]
-  },
-  {
-    "code": "dsad",
-    "name": "dasdasda",
-    "students": [
-      {
-        "student_id": "burger",
-        "display_name": "burger"
-      }
-    ]
   }
 ]

classroom_service.py

@@ -1,6 +1,7 @@
 """Browser-side multi-file Python classroom for the Telearn demo Space."""
 from __future__ import annotations
 import asyncio, hmac, io, json, logging, os, re, sqlite3, threading, time, zipfile
+from collections import deque
 from pathlib import Path, PurePosixPath
 from typing import Any
 from fastapi import APIRouter, HTTPException, WebSocket, WebSocketDisconnect
@@ -10,16 +11,57 @@ from pydantic import BaseModel
 ROOT=Path(__file__).resolve().parent; STATIC=ROOT/"classroom_static"; DATA=ROOT/"classroom_data"; TEMPLATES=DATA/"templates"; REPAIRS=DATA/"repairs"; CHECKPOINTS=DATA/"checkpoints"; VERSIONS=DATA/"versions"; PUBLISHED=ROOT/"projects"
 RUNTIME=Path(os.getenv("CLASSROOM_DATA_DIR","/tmp/telearn_classroom")); DB=RUNTIME/"classroom.sqlite3"
 PASSWORD=os.getenv("CLASSROOM_TEACHER_PASSWORD",""); REPO=os.getenv("CLASSROOM_DEMO_REPO",os.getenv("SPACE_ID","Telearn/Project_Demo")).strip(); DEMO_CLASS=os.getenv("CLASSROOM_DEMO_CLASS","2026Fall進階專題"); TOKEN=os.getenv("HF_TOKEN","").strip()
+COURSE_STORAGE_QUOTA_BYTES=max(16, int(os.getenv("CLASSROOM_COURSE_QUOTA_MB", "1024"))) * 1024 * 1024
+MAX_VERSIONS_PER_KIND=max(2, int(os.getenv("CLASSROOM_MAX_VERSIONS_PER_KIND", "100")))
+CHECKPOINTS_PER_HOUR=max(1, int(os.getenv("CLASSROOM_CHECKPOINTS_PER_HOUR", "60")))
+SUBMISSIONS_PER_HOUR=max(1, int(os.getenv("CLASSROOM_SUBMISSIONS_PER_HOUR", "20")))
+VERSION_WRITE_COOLDOWN_MS=max(0, int(os.getenv("CLASSROOM_VERSION_COOLDOWN_MS", "1500")))
+STUDENT_WS_CONNECTIONS_PER_MINUTE=max(10, int(os.getenv("CLASSROOM_WS_CONNECTIONS_PER_MINUTE", "300")))
+STUDENT_WS_MESSAGES_PER_MINUTE=max(60, int(os.getenv("CLASSROOM_WS_MESSAGES_PER_MINUTE", "300")))
 ALLOWED={".py",".json",".txt",".csv",".md",".toml",".yaml",".yml"}; ID_RE=re.compile(r"[^0-9A-Za-z_\-一-鿿]")
 router=APIRouter(); lock=threading.Lock(); persist_lock=threading.Lock(); students={}; teachers={}; live={}; logger=logging.getLogger(__name__)
+_student_connection_windows={}
+_student_message_windows={}
+
+def allow_student_connection(remote_ip):
+    """Bound repeated WebSocket handshakes per client IP without persisting IPs."""
+    current=time.monotonic(); window=_student_connection_windows.get(remote_ip)
+    if window is None:
+        window=deque(); _student_connection_windows[remote_ip]=window
+    while window and current-window[0]>=60:window.popleft()
+    if len(window)>=STUDENT_WS_CONNECTIONS_PER_MINUTE:return False
+    window.append(current)
+    if len(_student_connection_windows)>4096:
+        for key,old_window in list(_student_connection_windows.items()):
+            while old_window and current-old_window[0]>=60:old_window.popleft()
+            if not old_window:_student_connection_windows.pop(key,None)
+            if len(_student_connection_windows)<=3072:break
+    return True
+
+def allow_student_message(student_key):
+    """Apply a rolling message budget across reconnects for the same student/workspace."""
+    current=time.monotonic(); window=_student_message_windows.get(student_key)
+    if window is None:
+        window=deque(); _student_message_windows[student_key]=window
+    while window and current-window[0]>=60:window.popleft()
+    if len(window)>=STUDENT_WS_MESSAGES_PER_MINUTE:return False
+    window.append(current)
+    if len(_student_message_windows)>4096:
+        for key,old_window in list(_student_message_windows.items()):
+            while old_window and current-old_window[0]>=60:old_window.popleft()
+            if not old_window:_student_message_windows.pop(key,None)
+            if len(_student_message_windows)<=3072:break
+    return True
 
 class TeacherRequest(BaseModel): class_code:str; week_id:str; password:str
 class CourseCreate(BaseModel): class_code:str; course_name:str=""; password:str
 class CourseUpdate(BaseModel): class_code:str; course_name:str; password:str
 class CourseDelete(BaseModel): class_code:str; password:str
 class StudentCreate(BaseModel): class_code:str; display_names:list[str]; password:str
+class StudentUpdate(BaseModel): class_code:str; student_id:str; display_name:str; password:str
 class StudentLogin(BaseModel): class_code:str; display_name:str
 class StudentDelete(BaseModel): class_code:str; student_id:str; password:str
+class VersionLimitError(Exception): pass
 def clean(v,fallback="item",limit=48): return ID_RE.sub("",str(v).strip())[:limit] or fallback
 def clean_label(v,fallback="",limit=80): return re.sub(r"[\x00-\x1f\x7f]", "", str(v).strip())[:limit] or fallback
 def safe_path(v):
@@ -35,6 +77,7 @@ def norm_files(value):
 def now(): return int(time.time()*1000)
 def init_db():
     RUNTIME.mkdir(parents=True,exist_ok=True)
+    os.chmod(RUNTIME,0o700)
     with lock,sqlite3.connect(DB) as c:
         c.execute("""CREATE TABLE IF NOT EXISTS classroom_projects(class_code TEXT,student_id TEXT,display_name TEXT,week_id TEXT,project_name TEXT,draft_files TEXT,final_files TEXT,active_file TEXT,output TEXT,status TEXT,needs_help INTEGER,updated_at INTEGER,submitted_at INTEGER,checkpoint_files TEXT,checkpoint_at INTEGER,PRIMARY KEY(class_code,student_id,week_id))""")
         columns={row[1] for row in c.execute("PRAGMA table_info(classroom_projects)")}
@@ -44,6 +87,7 @@ def init_db():
         c.execute("""CREATE TABLE IF NOT EXISTS classroom_members(class_code TEXT,student_id TEXT,display_name TEXT,created_at INTEGER,PRIMARY KEY(class_code,student_id))""")
         c.execute("""CREATE TABLE IF NOT EXISTS classroom_versions(class_code TEXT,student_id TEXT,display_name TEXT,week_id TEXT,version_id TEXT,kind TEXT,project_name TEXT,files TEXT,created_at INTEGER,PRIMARY KEY(class_code,student_id,week_id,version_id))""")
         c.execute("""CREATE TABLE IF NOT EXISTS classroom_migrations(migration_id TEXT PRIMARY KEY,applied_at INTEGER)""")
+        c.execute("""CREATE TABLE IF NOT EXISTS classroom_write_windows(class_code TEXT,student_id TEXT,week_id TEXT,kind TEXT,window_started INTEGER,write_count INTEGER,last_write INTEGER,PRIMARY KEY(class_code,student_id,week_id,kind))""")
         for item in json.loads((DATA/"classes.json").read_text(encoding="utf-8")):
             code=clean(item.get("code"),"L6A")
             c.execute("""INSERT INTO classroom_courses VALUES(?,?,?) ON CONFLICT(class_code) DO UPDATE SET course_name=excluded.course_name""",(code,clean_label(item.get("name"),code),now()))
@@ -108,6 +152,24 @@ def init_db():
                 if final is not None:final["main.py"]=fixed
                 c.execute("UPDATE classroom_projects SET draft_files=?,final_files=?,updated_at=? WHERE class_code=? AND student_id=? AND week_id=?",(json.dumps(draft,ensure_ascii=False),json.dumps(final,ensure_ascii=False) if final is not None else None,now(),class_code,student_id,week_id))
             c.execute("INSERT INTO classroom_migrations VALUES(?,?)",(migration_id,now()))
+        c.execute("""UPDATE classroom_projects SET display_name=(
+            SELECT display_name FROM classroom_members
+            WHERE classroom_members.class_code=classroom_projects.class_code
+            AND classroom_members.student_id=classroom_projects.student_id
+        ) WHERE EXISTS (
+            SELECT 1 FROM classroom_members
+            WHERE classroom_members.class_code=classroom_projects.class_code
+            AND classroom_members.student_id=classroom_projects.student_id
+        )""")
+        c.execute("""UPDATE classroom_versions SET display_name=(
+            SELECT display_name FROM classroom_members
+            WHERE classroom_members.class_code=classroom_versions.class_code
+            AND classroom_members.student_id=classroom_versions.student_id
+        ) WHERE EXISTS (
+            SELECT 1 FROM classroom_members
+            WHERE classroom_members.class_code=classroom_versions.class_code
+            AND classroom_members.student_id=classroom_versions.student_id
+        )""")
 def empty(c,s,n,w): return {"class_code":c,"student_id":s,"display_name":n,"week_id":w,"project_name":"","files":{"main.py":"# 在這裡寫 Python\n"},"final_files":None,"checkpoint_files":None,"active_file":"main.py","output":"","status":"idle","needs_help":False,"updated_at":now(),"submitted_at":None,"checkpoint_at":None,"connected":True}
 def from_row(r,connected=False): return {"class_code":r[0],"student_id":r[1],"display_name":r[2],"week_id":r[3],"project_name":r[4],"files":json.loads(r[5]),"final_files":json.loads(r[6]) if r[6] else None,"active_file":r[7],"output":r[8],"status":r[9],"needs_help":bool(r[10]),"updated_at":r[11],"submitted_at":r[12],"checkpoint_files":json.loads(r[13]) if r[13] else None,"checkpoint_at":r[14],"connected":connected}
 SELECT="SELECT class_code,student_id,display_name,week_id,project_name,draft_files,final_files,active_file,output,status,needs_help,updated_at,submitted_at,checkpoint_files,checkpoint_at FROM classroom_projects"
@@ -145,12 +207,49 @@ def get_submission(class_code,student_id,week_id):
     with lock,sqlite3.connect(DB) as db:row=db.execute(SELECT+" WHERE class_code=? AND student_id=? AND week_id=? AND final_files IS NOT NULL",(clean(class_code,""),clean(student_id,""),clean(week_id,""))).fetchone()
     if not row:raise HTTPException(404,"找不到這份提交")
     return from_row(row)
+def consume_version_write(class_code,student_id,week_id,kind):
+    """Persist a per-student/workspace hourly write budget in SQLite."""
+    current=now(); window_ms=60*60*1000
+    limit=CHECKPOINTS_PER_HOUR if kind=="checkpoint" else SUBMISSIONS_PER_HOUR
+    with lock,sqlite3.connect(DB) as db:
+        row=db.execute("SELECT window_started,write_count,last_write FROM classroom_write_windows WHERE class_code=? AND student_id=? AND week_id=? AND kind=?",(class_code,student_id,week_id,kind)).fetchone()
+        if row is None or current-row[0]>=window_ms:
+            window_started=current; count=0; last_write=0
+        else:
+            window_started,count,last_write=row
+        if last_write and current-last_write<VERSION_WRITE_COOLDOWN_MS:
+            raise VersionLimitError("儲存太頻繁，請稍候再試。")
+        if count>=limit:
+            raise VersionLimitError(f"已達本 Lesson 每小時{limit}次上限，稍後再試。")
+        db.execute("INSERT INTO classroom_write_windows VALUES(?,?,?,?,?,?,?) ON CONFLICT(class_code,student_id,week_id,kind) DO UPDATE SET window_started=excluded.window_started,write_count=excluded.write_count,last_write=excluded.last_write",(class_code,student_id,week_id,kind,window_started,count+1,current))
+
 def record_version(state,kind):
     created_at=state["checkpoint_at"] if kind=="checkpoint" else state["submitted_at"]
     files=state["checkpoint_files"] if kind=="checkpoint" else state["final_files"]
     version_id=f"{created_at}-{kind}-{time.time_ns()%1000000:06d}"
     record={"class_code":state["class_code"],"student_id":state["student_id"],"display_name":state["display_name"],"week_id":state["week_id"],"version_id":version_id,"kind":kind,"project_name":state["project_name"],"created_at":created_at,"files":dict(files)}
-    with lock,sqlite3.connect(DB) as db:db.execute("INSERT INTO classroom_versions VALUES(?,?,?,?,?,?,?,?,?)",(record["class_code"],record["student_id"],record["display_name"],record["week_id"],version_id,kind,record["project_name"],json.dumps(record["files"],ensure_ascii=False),created_at))
+    encoded_files=json.dumps(record["files"],ensure_ascii=False)
+    draft_json=json.dumps(state["files"],ensure_ascii=False)
+    final_json=json.dumps(state["final_files"],ensure_ascii=False) if state["final_files"] else None
+    checkpoint_json=json.dumps(state["checkpoint_files"],ensure_ascii=False) if state["checkpoint_files"] else None
+    with lock,sqlite3.connect(DB) as db:
+        db.execute("BEGIN IMMEDIATE")
+        existing=db.execute("SELECT version_id,created_at,length(CAST(files AS BLOB)),kind FROM classroom_versions WHERE class_code=? AND student_id=? AND week_id=? AND kind=? ORDER BY created_at DESC,version_id DESC",(record["class_code"],record["student_id"],record["week_id"],kind)).fetchall()
+        pruned=existing[MAX_VERSIONS_PER_KIND-1:] if len(existing)>=MAX_VERSIONS_PER_KIND else []
+        pruned_bytes=sum(row[2] or 0 for row in pruned)
+        version_bytes=db.execute("SELECT COALESCE(SUM(length(CAST(files AS BLOB))),0) FROM classroom_versions WHERE class_code=?",(record["class_code"],)).fetchone()[0]
+        current_bytes=db.execute("SELECT COALESCE(SUM(length(CAST(draft_files AS BLOB))+COALESCE(length(CAST(final_files AS BLOB)),0)+COALESCE(length(CAST(checkpoint_files AS BLOB)),0)),0) FROM classroom_projects WHERE class_code=?",(record["class_code"],)).fetchone()[0]
+        prior=db.execute("SELECT COALESCE(length(CAST(draft_files AS BLOB)),0)+COALESCE(length(CAST(final_files AS BLOB)),0)+COALESCE(length(CAST(checkpoint_files AS BLOB)),0) FROM classroom_projects WHERE class_code=? AND student_id=? AND week_id=?",(record["class_code"],record["student_id"],record["week_id"])).fetchone()
+        prior_bytes=prior[0] if prior else 0
+        candidate_current=len(draft_json.encode())+(len(final_json.encode()) if final_json else 0)+(len(checkpoint_json.encode()) if checkpoint_json else 0)
+        projected=version_bytes-pruned_bytes+len(encoded_files.encode())+current_bytes-prior_bytes+candidate_current
+        if projected>COURSE_STORAGE_QUOTA_BYTES:
+            raise VersionLimitError(f"本課程已達 {COURSE_STORAGE_QUOTA_BYTES//(1024*1024)} MB 儲存上限，請聯絡老師整理舊版本。")
+        for old_version_id,_,_,_ in pruned:
+            db.execute("DELETE FROM classroom_versions WHERE class_code=? AND student_id=? AND week_id=? AND version_id=?",(record["class_code"],record["student_id"],record["week_id"],old_version_id))
+        db.execute("INSERT INTO classroom_versions VALUES(?,?,?,?,?,?,?,?,?)",(record["class_code"],record["student_id"],record["display_name"],record["week_id"],version_id,kind,record["project_name"],encoded_files,created_at))
+    if pruned:
+        record["_pruned"]=[{"week_id":record["week_id"],"version_id":row[0]} for row in pruned]
     return record
 def version_history(class_code,student_id):
     with lock,sqlite3.connect(DB) as db:rows=db.execute("SELECT week_id,version_id,kind,project_name,files,created_at FROM classroom_versions WHERE class_code=? AND student_id=? ORDER BY created_at DESC,version_id DESC",(class_code,student_id)).fetchall()
@@ -230,11 +329,20 @@ def persist_catalog(message,deletions=None):
 def persist_version(record):
     if not TOKEN:return "版本已保存在教室，但尚未永久寫入 Space；請設定 HF_TOKEN。"
     try:
-        from huggingface_hub import CommitOperationAdd,HfApi
-        content=(json.dumps(record,ensure_ascii=False,indent=2)+"\n").encode()
+        from huggingface_hub import CommitOperationAdd,CommitOperationDelete,HfApi
+        pruned=record.get("_pruned",[])
+        payload={key:value for key,value in record.items() if key!="_pruned"}
+        content=(json.dumps(payload,ensure_ascii=False,indent=2)+"\n").encode()
         path=PurePosixPath("classroom_data","versions",clean(record["class_code"],""),clean(record["student_id"],""),clean(record["week_id"],"week"),f"{clean(record['version_id'],'version')}.json").as_posix()
         label="Checkpoint" if record["kind"]=="checkpoint" else "Submission"
-        with persist_lock:HfApi(token=TOKEN).create_commit(repo_id=REPO,repo_type="space",operations=[CommitOperationAdd(path_in_repo=path,path_or_fileobj=content)],commit_message=f"{label} {record['class_code']} {record['student_id']} {record['week_id']}")
+        api=HfApi(token=TOKEN);operations=[]
+        if pruned:
+            existing=set(api.list_repo_files(repo_id=REPO,repo_type="space"))
+            for old in pruned:
+                old_path=PurePosixPath("classroom_data","versions",clean(record["class_code"],""),clean(record["student_id"],""),clean(old["week_id"],"week"),f"{clean(old['version_id'],'version')}.json").as_posix()
+                if old_path in existing:operations.append(CommitOperationDelete(path_in_repo=old_path))
+        operations.append(CommitOperationAdd(path_in_repo=path,path_or_fileobj=content))
+        with persist_lock:api.create_commit(repo_id=REPO,repo_type="space",operations=operations,commit_message=f"{label} {record['class_code']} {record['student_id']} {record['week_id']}")
         return ""
     except Exception as exc:
         logger.exception("Could not persist student version to %s",REPO)
@@ -308,6 +416,31 @@ async def create_students(req:StudentCreate):
     for class_code,week_id in list(teachers):
         if class_code==code:await broadcast(code,week_id)
     return {"ok":True,"created":created,"warning":warning}
+@router.put("/api/classroom/students")
+async def update_student(req:StudentUpdate):
+    check_password(req.password);code=clean(req.class_code,"");student_id=clean(req.student_id,"student");name=clean_label(req.display_name,"")
+    if not code or not student_id:raise HTTPException(400,"找不到班級或學生")
+    if not name:raise HTTPException(400,"請輸入學生姓名")
+    with lock,sqlite3.connect(DB) as db:
+        members=db.execute("SELECT student_id,display_name FROM classroom_members WHERE class_code=?",(code,)).fetchall()
+        current=next((member for member in members if member[0]==student_id),None)
+        if not current:raise HTTPException(404,"找不到這位學生")
+        if any(member_id!=student_id and display_name.casefold()==name.casefold() for member_id,display_name in members):
+            raise HTTPException(409,"這個班級已有相同姓名，請確認名單")
+        db.execute("UPDATE classroom_members SET display_name=? WHERE class_code=? AND student_id=?",(name,code,student_id))
+        db.execute("UPDATE classroom_projects SET display_name=? WHERE class_code=? AND student_id=?",(name,code,student_id))
+        db.execute("UPDATE classroom_versions SET display_name=? WHERE class_code=? AND student_id=?",(name,code,student_id))
+    for key,state in list(live.items()):
+        if key[0]!=code or key[1]!=student_id:continue
+        state["display_name"]=name
+        target=students.get(key)
+        if target:
+            try:await target.send_json({"type":"identity","display_name":name})
+            except Exception:pass
+    warning=persist_catalog(f"Rename classroom student {student_id} in {code}")
+    for class_code,week_id in list(teachers):
+        if class_code==code:await broadcast(code,week_id)
+    return {"ok":True,"student_id":student_id,"display_name":name,"warning":warning}
 @router.delete("/api/classroom/students")
 async def delete_student(req:StudentDelete):
     check_password(req.password); code=clean(req.class_code,"L6A"); student_id=clean(req.student_id,"student");deletions=archived_paths(code,student_id)
@@ -356,6 +489,8 @@ def publish(req:TeacherRequest):
 
 @router.websocket("/ws/classroom/student")
 async def student_ws(ws:WebSocket):
+    remote_ip=ws.client.host if ws.client else "unknown"
+    if not allow_student_connection(remote_ip):await ws.close(code=4429,reason="connection rate limited");return
     c=clean(ws.query_params.get("class_code"),"L6A");s=clean(ws.query_params.get("student_id"),"student");requested_name=clean_label(ws.query_params.get("display_name"),"");w=clean(ws.query_params.get("week_id"),"week02");await ws.accept()
     member=find_member(c,requested_name,s)
     if not member:await ws.close(code=4404,reason="not on roster");return
@@ -367,15 +502,27 @@ async def student_ws(ws:WebSocket):
     students[key]=ws;state=load(c,s,n,w);state["connected"]=True;live[key]=state;save(state);await ws.send_json({"type":"restore","state":state});await broadcast(c,w)
     try:
         while True:
-            m=await ws.receive_json();kind=m.get("type");version=None
+            m=await ws.receive_json()
+            if not allow_student_message(key):
+                await ws.close(code=4429,reason="message rate limited");break
+            kind=m.get("type");version=None
             if kind=="project":
                 state["files"]=norm_files(m.get("files"));state["project_name"]=clean_label(m.get("project_name"),"");active=safe_path(m.get("active_file","main.py"));state["active_file"]=active if active in state["files"] else "main.py";state["updated_at"]=now()
             elif kind=="output":state["output"]=str(m.get("output",""))[-40000:]
             elif kind=="status":state["status"]=m.get("status") if m.get("status") in {"idle","running","success","error"} else "idle"
             elif kind=="help":state["needs_help"]=bool(m.get("needs_help"))
             elif kind=="checkpoint":
-                state["files"]=norm_files(m.get("files",state["files"]));state["project_name"]=clean_label(m.get("project_name",state["project_name"]),"");state["checkpoint_files"]=dict(state["files"]);state["checkpoint_at"]=now();state["updated_at"]=state["checkpoint_at"];version=record_version(state,"checkpoint")
-            elif kind=="submit":state["files"]=norm_files(m.get("files",state["files"]));state["project_name"]=clean_label(m.get("project_name",state["project_name"]),"");state["final_files"]=dict(state["files"]);state["submitted_at"]=now();state["updated_at"]=state["submitted_at"];version=record_version(state,"submit")
+                try:
+                    consume_version_write(c,s,w,"checkpoint")
+                    state["files"]=norm_files(m.get("files",state["files"]));state["project_name"]=clean_label(m.get("project_name",state["project_name"]),"");state["checkpoint_files"]=dict(state["files"]);state["checkpoint_at"]=now();state["updated_at"]=state["checkpoint_at"];version=record_version(state,"checkpoint")
+                except VersionLimitError as exc:
+                    await ws.send_json({"type":"write_rejected","message":str(exc)});continue
+            elif kind=="submit":
+                try:
+                    consume_version_write(c,s,w,"submit")
+                    state["files"]=norm_files(m.get("files",state["files"]));state["project_name"]=clean_label(m.get("project_name",state["project_name"]),"");state["final_files"]=dict(state["files"]);state["submitted_at"]=now();state["updated_at"]=state["submitted_at"];version=record_version(state,"submit")
+                except VersionLimitError as exc:
+                    await ws.send_json({"type":"write_rejected","message":str(exc)});continue
             elif kind=="ping":await ws.send_json({"type":"pong","needs_help":state["needs_help"],"submitted_at":state["submitted_at"],"checkpoint_at":state.get("checkpoint_at")});continue
             else:continue
             save(state)

classroom_static/admin.css

@@ -56,6 +56,7 @@
 .classroom-manager { min-width:0;min-height:0;display:grid;grid-template-rows:auto auto minmax(0,1fr);overflow:hidden; }
 .classroom-fields { display:grid;grid-template-columns:minmax(150px,.7fr) minmax(220px,1fr) auto;gap:1rem;align-items:end;padding:.8rem 1.5rem;border-bottom:1px solid var(--line);background:var(--surface); }
 .classroom-fields>label,.backup-controls label,.manager-add>label { display:grid;gap:.35rem;color:var(--muted);font-size:.76rem;font-weight:800; }
+.classroom-fields>label small { color:var(--muted);font-size:.68rem;font-weight:500;line-height:1.35; }
 .backup-controls { display:flex;align-items:end;gap:.5rem; }
 .backup-controls select { min-width:220px; }
 .classroom-workspace { min-height:0;display:grid;grid-template-columns:280px minmax(0,1fr); }
@@ -68,9 +69,14 @@
 .manager-title strong,.manager-title small { display:block; }
 .manager-title small,.manager-title span { color:var(--muted);font-size:.75rem; }
 .manager-list { min-height:0;overflow:auto;padding:.4rem; }
-.manager-person-row { display:grid;grid-template-columns:minmax(0,1fr) 36px;align-items:center;border-radius:var(--radius-sm); }
+.manager-person-row { display:grid;grid-template-columns:minmax(0,1fr) auto 36px;align-items:center;border-radius:var(--radius-sm); }
 .manager-person { width:100%;min-height:40px;padding:0 .7rem;border:0;border-radius:var(--radius-sm);background:transparent;color:var(--ink);text-align:left;font-weight:700; }
 .manager-person:hover,.manager-person.active { background:var(--action-soft);color:var(--navy); }
+.student-edit-button { min-height:32px;padding-inline:.5rem;font-size:.72rem;white-space:nowrap; }
+.student-edit-form { display:grid;grid-template-columns:minmax(0,1fr) auto auto;gap:.35rem;padding:.4rem;border-radius:var(--radius-sm);background:var(--surface-subtle); }
+.student-edit-form input { grid-column:1/-1;min-width:0;min-height:36px; }
+.student-edit-form .btn,.student-edit-form .copy-button { min-height:32px;padding-inline:.65rem; }
+.student-edit-error { grid-column:1/-1;margin:0;color:var(--danger);font-size:.72rem;line-height:1.4; }
 .manager-person-row .remove-file { min-height:36px;border:0;background:transparent;color:var(--muted);font-size:1.1rem; }
 .manager-person-row .remove-file:hover { color:var(--danger); }
 .submission-manager { min-width:0;min-height:0;display:grid;grid-template-rows:auto minmax(0,1fr);overflow:hidden; }

classroom_static/admin.html

@@ -4,8 +4,8 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width,initial-scale=1">
   <title>Telearn 內容管理後台</title>
-  <link rel="stylesheet" href="/classroom-assets/classroom.css?v=2026fall-7">
-  <link rel="stylesheet" href="/classroom-assets/admin.css?v=2026fall-6">
+  <link rel="stylesheet" href="/classroom-assets/classroom.css?v=2026fall-9">
+  <link rel="stylesheet" href="/classroom-assets/admin.css?v=2026fall-7">
 </head>
 <body class="admin-body">
   <header class="app-header">
@@ -28,7 +28,7 @@
       <aside class="admin-sidebar classroom-sidebar"><div class="admin-sidebar-head"><div><strong>我的班級</strong><small id="classroomTotal">尚未建立班級</small></div><button class="copy-button" id="newClassroomButton">＋新增</button></div><div class="admin-list" id="classroomList"></div></aside>
       <section class="classroom-manager">
         <header class="admin-editor-head"><div><h1 id="classroomHeading">選擇班級</h1><p>管理班級、學生名單與已提交的正式版本。</p></div><div class="admin-actions"><button class="copy-button danger-action" id="deleteClassroomButton" disabled>刪除班級</button><button class="btn" id="saveClassroomButton" disabled>儲存班級</button></div></header>
-        <div class="classroom-fields"><label>班級代碼<input class="text-field" id="classroomCode" disabled></label><label>班級名稱<input class="text-field" id="classroomName" disabled></label><div class="backup-controls"><label>備份 Lesson<select class="text-field" id="backupWeek" disabled></select></label><button class="copy-button" id="backupSubmissionsButton" disabled>備份 Lesson 提交</button></div></div>
+        <div class="classroom-fields"><label>班級代碼<input class="text-field" id="classroomCode" disabled><small>建立後固定，避免作品與進度失去關聯。</small></label><label>班級名稱<input class="text-field" id="classroomName" disabled></label><div class="backup-controls"><label>備份 Lesson<select class="text-field" id="backupWeek" disabled></select></label><button class="copy-button" id="backupSubmissionsButton" disabled>備份 Lesson 提交</button></div></div>
         <div class="classroom-workspace">
           <aside class="student-manager"><form class="manager-add" id="adminStudentForm"><label for="adminStudentNames">新增學生（多人可用逗號分開）</label><div><input class="text-field" id="adminStudentNames" disabled><button class="btn compact" id="adminAddStudentsButton" disabled>加入</button></div></form><div class="manager-title"><strong>學生名單</strong><span id="adminStudentTotal">0 人</span></div><div class="manager-list" id="adminStudentList"></div></aside>
           <section class="submission-manager"><div class="manager-title"><div><strong id="submissionHeading">已提交內容</strong><small id="submissionTotal">0 份</small></div></div><div class="submission-workspace"><div class="submission-list" id="submissionList"></div><div class="submission-detail"><header><div><strong id="submissionProject">尚未選擇提交</strong><small id="submissionMeta"></small></div><button class="copy-button danger-action" id="deleteSubmissionButton" disabled>刪除提交</button></header><nav class="submission-files" id="submissionFiles"></nav><pre id="submissionCode">選擇一份提交查看內容。</pre></div></div></section>
@@ -48,6 +48,6 @@
 
   <dialog id="adminLoginDialog"><form class="dialog-content form-stack" id="adminLoginForm"><div><h1>登入內容管理後台</h1><p>使用與教師控制台相同的密碼。</p></div><label><span class="field-label">教師密碼</span><input class="text-field" id="adminPassword" type="password" required autofocus></label><p class="form-error" id="adminLoginError"></p><button class="btn" type="submit">登入</button></form></dialog>
   <div class="toast" id="toast"></div>
-  <script src="/classroom-assets/admin.js?v=2026fall-7"></script>
+  <script src="/classroom-assets/admin.js?v=2026fall-8"></script>
 </body>
 </html>

classroom_static/admin.js

@@ -28,6 +28,7 @@ let demoFile = "";
 let demoAssets = [];
 let selectedClassroom = "";
 let selectedClassroomStudent = "";
+let editingClassroomStudent = "";
 let selectedSubmission = null;
 let submissionFiles = {};
 let submissionFile = "";
@@ -363,6 +364,7 @@ function renderClassrooms() {
   E.classroomList.querySelectorAll("[data-classroom]").forEach(button => button.onclick = () => {
     selectedClassroom = button.dataset.classroom;
     selectedClassroomStudent = "";
+    editingClassroomStudent = "";
     selectedSubmission = null;
     renderClassrooms();
   });
@@ -377,6 +379,8 @@ function renderClassroomDetail() {
   E.classroomName.disabled = !enabled && selectedClassroom !== "__new__";
   E.saveClassroomButton.disabled = !enabled && selectedClassroom !== "__new__";
   E.deleteClassroomButton.disabled = !enabled;
+  E.saveClassroomButton.textContent = selectedClassroom === "__new__" ? "建立班級" : "儲存班級名稱";
+  E.saveClassroomButton.dataset.label = E.saveClassroomButton.textContent;
   [E.backupWeek, E.backupSubmissionsButton, E.adminStudentNames, E.adminAddStudentsButton].forEach(element => element.disabled = !enabled);
   if (selectedClassroom === "__new__") {
     E.classroomCode.value = "";
@@ -391,10 +395,22 @@ function renderClassroomDetail() {
 function renderClassroomStudents() {
   const members = currentClassroom()?.students || [];
   if (selectedClassroomStudent && !members.some(item => item.student_id === selectedClassroomStudent)) selectedClassroomStudent = "";
+  if (editingClassroomStudent && !members.some(item => item.student_id === editingClassroomStudent)) editingClassroomStudent = "";
   E.adminStudentTotal.textContent = `${members.length} 人`;
-  E.adminStudentList.innerHTML = members.length ? `<button class="manager-person ${selectedClassroomStudent ? "" : "active"}" data-student="">全部學生</button>` + members.map(member => `<div class="manager-person-row"><button class="manager-person ${member.student_id === selectedClassroomStudent ? "active" : ""}" data-student="${esc(member.student_id)}">${esc(member.display_name)}</button><button class="remove-file" data-remove-student="${esc(member.student_id)}" aria-label="刪除 ${esc(member.display_name)}">×</button></div>`).join("") : '<div class="admin-empty">這個班級尚無學生。</div>';
+  E.adminStudentList.innerHTML = members.length ? `<button class="manager-person ${selectedClassroomStudent ? "" : "active"}" data-student="">全部學生</button>` + members.map(member => {
+    if (member.student_id === editingClassroomStudent) return `<form class="student-edit-form" data-student-edit-form="${esc(member.student_id)}"><input class="text-field" name="display_name" aria-label="學生姓名" maxlength="80" value="${esc(member.display_name)}" required><button class="btn compact" type="submit">儲存</button><button class="copy-button" type="button" data-cancel-student-edit>取消</button><p class="student-edit-error" role="alert"></p></form>`;
+    return `<div class="manager-person-row"><button class="manager-person ${member.student_id === selectedClassroomStudent ? "active" : ""}" data-student="${esc(member.student_id)}">${esc(member.display_name)}</button><button class="copy-button student-edit-button" type="button" data-edit-student="${esc(member.student_id)}" aria-label="編輯 ${esc(member.display_name)} 的姓名">改名</button><button class="remove-file" type="button" data-remove-student="${esc(member.student_id)}" aria-label="刪除 ${esc(member.display_name)}">×</button></div>`;
+  }).join("") : '<div class="admin-empty">這個班級尚無學生。</div>';
   E.adminStudentList.querySelectorAll("[data-student]").forEach(button => button.onclick = () => { selectedClassroomStudent = button.dataset.student; selectedSubmission = null; renderClassroomStudents(); });
   E.adminStudentList.querySelectorAll("[data-remove-student]").forEach(button => button.onclick = () => removeClassroomStudent(button.dataset.removeStudent));
+  E.adminStudentList.querySelectorAll("[data-edit-student]").forEach(button => button.onclick = () => {
+    editingClassroomStudent = button.dataset.editStudent;
+    renderClassroomStudents();
+    const input = E.adminStudentList.querySelector('[data-student-edit-form] input[name="display_name"]');
+    input?.focus(); input?.select();
+  });
+  E.adminStudentList.querySelectorAll("[data-cancel-student-edit]").forEach(button => button.onclick = () => { editingClassroomStudent = ""; renderClassroomStudents(); });
+  E.adminStudentList.querySelectorAll("[data-student-edit-form]").forEach(form => form.onsubmit = event => renameClassroomStudent(event, form));
   renderSubmissions();
 }
 
@@ -444,6 +460,7 @@ function resetSubmissionDetail() {
 E.newClassroomButton.onclick = () => {
   selectedClassroom = "__new__";
   selectedClassroomStudent = "";
+  editingClassroomStudent = "";
   resetSubmissionDetail();
   renderClassrooms();
   E.classroomCode.focus();
@@ -483,6 +500,31 @@ E.adminStudentForm.onsubmit = async event => {
   finally { setBusy(E.adminAddStudentsButton, false); }
 };
 
+async function renameClassroomStudent(event, form) {
+  event.preventDefault();
+  const studentId = form.dataset.studentEditForm;
+  const displayName = form.querySelector('[name="display_name"]').value.trim();
+  const errorLabel = form.querySelector(".student-edit-error");
+  if (!displayName) { errorLabel.textContent = "請輸入學生姓名"; return; }
+  const button = form.querySelector('button[type="submit"]');
+  const previousSubmission = selectedSubmission;
+  setBusy(button, true, "儲存中…");
+  errorLabel.textContent = "";
+  try {
+    const data = await request("/api/classroom/students", { class_code: selectedClassroom, student_id: studentId, display_name: displayName }, "PUT");
+    editingClassroomStudent = "";
+    await refreshClassrooms(selectedClassroom, studentId);
+    if (previousSubmission?.student_id === studentId) {
+      const updated = visibleSubmissions().find(item => item.student_id === studentId && item.week_id === previousSubmission.week_id);
+      if (updated) await selectSubmission(updated);
+      else resetSubmissionDetail();
+    }
+    toast(data.warning || "學生姓名已更新；既有作品與進度已保留");
+  } catch (error) {
+    errorLabel.textContent = error.message;
+  } finally { setBusy(button, false); }
+}
+
 async function removeClassroomStudent(studentId) {
   const member = currentClassroom()?.students.find(item => item.student_id === studentId);
   if (!member || !confirm(`從這個班級刪除「${member.display_name}」？\n\n教室進度與提交封存也會被移除。`)) return;

classroom_static/classroom.css

@@ -153,11 +153,11 @@ button:disabled { cursor: not-allowed; opacity: .48; }
 
 .panel { min-width: 0; min-height: 0; overflow: hidden; background: var(--surface); }
 .reference-panel { grid-area: reference; display:grid;grid-template-rows:44px minmax(0,1fr); }
-.editor-panel { grid-area: editor; display:grid;grid-template-rows:auto minmax(0,1fr);background:var(--editor); }
+.editor-panel { grid-area: editor; display:grid;grid-template-columns:minmax(0,1fr);grid-template-rows:auto minmax(0,1fr);background:var(--editor); }
 .console-panel { grid-area: console; display:grid;grid-template-rows:52px minmax(0,1fr); }
 .panel-resizer { position:relative;min-width:9px;min-height:0;background:var(--shell);cursor:col-resize;touch-action:none; }
-.panel-resizer::after { content:"";position:absolute;inset:0 auto 0 4px;width:1px;background:var(--line);transition:background-color 160ms ease,width 160ms ease; }
-.panel-resizer:hover::after,.panel-resizer:focus-visible::after,.panel-resizer.dragging::after { width:2px;background:var(--action); }
+.panel-resizer::after { content:"";position:absolute;inset:0 auto 0 4px;width:1px;background:var(--line);transform:scaleX(1);transform-origin:left center;transition:background-color 160ms ease,transform 160ms ease; }
+.panel-resizer:hover::after,.panel-resizer:focus-visible::after,.panel-resizer.dragging::after { transform:scaleX(2);background:var(--action); }
 .panel-resizer:focus-visible { outline:3px solid var(--help);outline-offset:-3px; }
 .reference-resizer { grid-area:reference-resizer; }
 .console-resizer { grid-area:console-resizer; }
@@ -182,7 +182,8 @@ body.panel-resizing { cursor:col-resize;user-select:none; }
   padding: 0 var(--space-lg);
   border-bottom: 1px solid var(--line);
 }
-.panel-heading h1, .panel-heading h2 { margin: 0; font-size: 1rem; }
+.panel-heading h1 { margin: 0; font-size: 1.5rem; }
+.panel-heading h2 { margin: 0; font-size: 1.1875rem; }
 .panel-heading.dark { min-width:0;padding-block:6px;flex-wrap:wrap;border-color:var(--editor-line);background:var(--editor-raised);color:var(--editor-ink); }
 .side-tabs { height:44px;display:flex;border-bottom:1px solid var(--line); }
 .side-tab { flex:1;border:0;background:var(--surface);color:var(--muted);font-size:.8rem;font-weight:800; }
@@ -257,14 +258,23 @@ body.panel-resizing { cursor:col-resize;user-select:none; }
 .checkpoint-action:hover { background: var(--success-soft); }
 
 .file-name { min-width:0;flex:1 1 100px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:700 .875rem/1 "SFMono-Regular",Consolas,monospace;color:oklch(.82 .025 255); }
-.editor-host { min-height:0; }
+.editor-host { min-width:0;min-height:0; }
 .CodeMirror { height: 100%; font: 500 1rem/1.7 "SFMono-Regular", Consolas, monospace; background: var(--editor); }
 .CodeMirror-gutters { background: var(--editor); border-right: 1px solid var(--editor-line); }
 
-.console-body { min-height:0;display:grid;grid-template-rows:minmax(120px,1fr) auto auto; }
-.console-stream { min-height:0;display:grid;grid-template-rows:minmax(0,1fr) auto;background:var(--editor); }
+.console-body { min-height:0;display:grid;grid-template-rows:auto minmax(120px,1fr) auto auto; }
+.console-tabs { min-height:38px;display:flex;align-items:stretch;gap:2px;padding:var(--space-xs) var(--space-sm);border-bottom:1px solid var(--line);background:var(--surface); }
+.console-tabs[hidden],#pygameFrame[hidden] { display:none; }
+.console-tab { min-width:88px;padding:0 var(--space-md);border:0;border-radius:var(--radius-sm);background:transparent;color:var(--muted);font-size:.78rem;font-weight:800; }
+.console-tab:hover { background:var(--surface-subtle);color:var(--navy); }
+.console-tab.active { background:var(--action-soft);color:var(--navy); }
+.console-tab:focus-visible { outline:2px solid var(--action);outline-offset:1px; }
+.console-stream { position:relative;min-height:0;display:grid;grid-template-columns:minmax(0,1fr);grid-template-rows:minmax(0,1fr) auto;background:var(--editor); }
 .field-help { margin: var(--space-sm) 0 0; color: var(--muted); font-size: .75rem; line-height: 1.45; }
 .console-output {
+  grid-area:1 / 1;
+  min-width:0;
+  min-height:0;
   margin: 0;
   padding: var(--space-lg);
   overflow: auto;
@@ -274,6 +284,11 @@ body.panel-resizing { cursor:col-resize;user-select:none; }
   white-space: pre-wrap;
   word-break: break-word;
 }
+.console-stream[data-view="pygame"] .console-output { visibility:hidden; }
+.console-stream[data-view="pygame"] .console-output[hidden] { display:none; }
+#pygameFrame { display:block;grid-area:1 / 1;z-index:1;width:100%;height:100%;min-width:0;min-height:0;border:0;background:var(--editor);visibility:hidden; }
+.console-stream[data-view="pygame"] #pygameFrame { visibility:visible; }
+.console-input-row { grid-area:2 / 1; }
 .console-input-row { display:grid;grid-template-columns:auto minmax(0,1fr) auto;align-items:center;gap:var(--space-sm);padding:var(--space-sm) var(--space-md);border-top:1px solid var(--editor-line);background:var(--editor-raised);color:var(--editor-ink); }
 .console-input-row>span { color:oklch(.76 .15 150);font:800 1.1rem/1 monospace; }
 .console-input-row input { min-width:0;height:38px;padding:0 var(--space-md);border:1px solid var(--editor-line);border-radius:var(--radius-sm);background:var(--editor);color:var(--editor-ink);font:500 .875rem/1.4 "SFMono-Regular",Consolas,monospace; }
@@ -349,10 +364,14 @@ dialog::backdrop { background: oklch(0.16 0.04 255 / .72); }
 .toast.visible { opacity: 1; transform: translateX(-50%) translateY(0); }
 
 @media (max-width: 980px) {
-  .project-bar{align-items:stretch;flex-direction:column;padding:var(--space-md)}.project-actions{overflow-x:auto;flex-wrap:nowrap}.project-actions>*{flex:none}
+  html.student-page { height:auto;min-height:100%;overflow-x:hidden;overflow-y:auto; }
+  html.student-page body { height:auto;min-height:100vh;min-height:100dvh;overflow:visible;padding-bottom:env(safe-area-inset-bottom); }
+  .student-page .project-bar { align-items:stretch;flex-direction:column;padding:var(--space-md); }
+  .student-page .project-actions { overflow:visible;flex-wrap:wrap;align-items:stretch;justify-content:flex-start; }
+  .student-page .project-actions>* { flex:0 1 auto;min-width:0;max-width:100%; }
   .editor-toggle { display:none; }
   .panel-resizer { display:none; }
-  .student-layout { display:block;min-height:0; }
+  .student-layout { display:block;height:min(68dvh,700px);min-height:360px;flex:none; }
   .mobile-tabs { display:flex;flex:none;background:var(--surface);border-bottom:1px solid var(--line); }
   .mobile-tab { flex: 1; min-height: 46px; border: 0; background: var(--surface); color: var(--muted); font-weight: 800; }
   .mobile-tab[aria-selected="true"] { color: var(--navy); box-shadow: inset 0 -3px 0 var(--action); }
@@ -362,9 +381,25 @@ dialog::backdrop { background: oklch(0.16 0.04 255 / .72); }
 }
 
 @media (max-width: 720px) {
-  .brand-copy span, .connection-state span { display: none; }
-  .app-header { padding-inline: var(--space-md); }
-  .btn { padding-inline: var(--space-md); }
+  .student-page .app-header { min-height:0;flex-wrap:wrap;gap:var(--space-sm);padding:var(--space-sm) var(--space-md); }
+  .student-page .brand { width:100%;min-width:0; }
+  .student-page .brand-copy { min-width:0; }
+  .student-page .brand-copy span { display:block;max-width:calc(100vw - 72px);overflow:hidden;text-overflow:ellipsis;white-space:nowrap; }
+  .student-page .header-actions { width:100%;flex-wrap:wrap;justify-content:space-between;gap:var(--space-xs); }
+  .student-page .connection-state { min-height:44px;padding-inline:var(--space-sm); }
+  .student-page .header-actions .btn { min-height:44px;padding-inline:.6rem; }
+  .student-page .project-context { display:grid;width:100%;grid-template-columns:max-content minmax(0,1fr);align-items:center; }
+  .student-page .project-context select,.student-page .project-context input { width:100%;min-width:0;max-width:none; }
+  .student-page .project-actions { display:grid;width:100%;grid-template-columns:repeat(2,minmax(0,1fr));align-items:stretch; }
+  .student-page .project-actions>* { width:100%;min-width:0;min-height:44px;padding:.4rem .5rem;line-height:1.3;white-space:normal;overflow-wrap:anywhere; }
+  .student-page .student-layout { height:min(68dvh,680px);min-height:360px; }
+  .mobile-tab { min-height:48px; }
+  .student-page dialog { max-height:calc(100dvh - 32px);overflow:auto; }
+  .student-page .dialog-content { padding:var(--space-xl); }
+  .student-page .progress-item { align-items:flex-start;flex-direction:column; }
+  .student-page .progress-item span { min-width:0;overflow-wrap:anywhere; }
+  .student-page .console-status { min-height:56px;flex-wrap:wrap;row-gap:4px;padding-block:var(--space-sm); }
+  .student-page .toast { left:max(12px,env(safe-area-inset-left));right:max(12px,env(safe-area-inset-right));max-width:calc(100vw - 24px);text-align:center;overflow-wrap:anywhere; }
   .teacher-layout { display: block; }
   .roster-panel { height:100%;min-height:0;border-right:0; }
   .teacher-detail { position: fixed; inset: 60px 0 0; z-index: 18; display: none; }

classroom_static/py-worker.js

@@ -4,8 +4,8 @@ let inputBytes = null;
 
 async function initialize() {
   try {
-    importScripts("https://cdn.jsdelivr.net/pyodide/v0.27.7/full/pyodide.js");
-    pyodide = await loadPyodide({ indexURL: "https://cdn.jsdelivr.net/pyodide/v0.27.7/full/" });
+    importScripts("/classroom-assets/vendor/pyodide/pyodide.js");
+    pyodide = await loadPyodide({ indexURL: "/classroom-assets/vendor/pyodide/" });
     pyodide.setStdout({
       write(buffer) {
         postMessage({ type: "stream", channel: "stdout", bytes: buffer });

classroom_static/pygame-runner.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="zh-Hant">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <meta name="color-scheme" content="dark">
+  <title>瀏覽器版 Pygame 執行器</title>
+  <style>
+    :root { color-scheme: dark; font: 14px/1.5 system-ui, sans-serif; background: #111923; color: #e8edf4; }
+    * { box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; margin: 0; overflow: hidden; }
+    body { display: grid; grid-template-rows: auto minmax(0, 1fr); }
+    .runner-note { padding: 8px 12px; border-bottom: 1px solid #303a49; color: #aeb9c8; font-size: 12px; }
+    .stage { min-width: 0; min-height: 0; display: grid; place-items: center; overflow: auto; padding: 10px; }
+    canvas { display: block; width: min(100%, 800px); height: auto; max-height: 100%; aspect-ratio: 4 / 3; background: #090e14; outline: none; }
+    #runnerMessage { max-width: 38rem; color: #c4cfdb; text-align: center; white-space: pre-wrap; }
+    #runnerMessage[hidden] { display: none; }
+  </style>
+</head>
+<body>
+  <div class="runner-note">瀏覽器版 Pygame · 點遊戲畫面後可用鍵盤操作</div>
+  <main class="stage">
+    <canvas id="canvas" width="640" height="480" tabindex="0" aria-label="Pygame 遊戲畫面"></canvas>
+    <p id="runnerMessage" aria-live="polite">正在準備 Pygame…</p>
+  </main>
+  <script src="/classroom-assets/vendor/pyodide/pyodide.js"></script>
+  <script src="/classroom-assets/pygame-runner.js?v=2026fall-1"></script>
+</body>
+</html>

classroom_static/pygame-runner.js

@@ -0,0 +1,128 @@
+(() => {
+  const canvas = document.getElementById("canvas");
+  const message = document.getElementById("runnerMessage");
+  const PYODIDE_URL = "/classroom-assets/vendor/pyodide/";
+  let pyodide = null;
+  let busy = false;
+  let outputDecoders = {};
+
+  function tell(type, details = {}) {
+    window.parent.postMessage({ type, ...details }, "*");
+  }
+
+  function showMessage(text) {
+    message.textContent = text;
+    message.hidden = false;
+  }
+
+  function hideMessage() {
+    message.hidden = true;
+  }
+
+  function setStream(channel) {
+    return {
+      isatty: false,
+      write(bytes) {
+        const decoder = outputDecoders[channel];
+        const text = decoder.decode(bytes, { stream: true });
+        if (text) tell("output", { runId: window.currentRunId, text });
+        return bytes.length;
+      },
+    };
+  }
+
+  async function initialize() {
+    try {
+      if (typeof loadPyodide !== "function") throw new Error("Pyodide 主程式沒有載入");
+      pyodide = await loadPyodide({ indexURL: PYODIDE_URL });
+      pyodide.canvas.setCanvas2D(canvas);
+      pyodide._api._skip_unwind_fatal_error = true;
+      tell("ready");
+      showMessage("Pygame 已就緒，按下「執行」開始遊戲。");
+    } catch (error) {
+      const text = `瀏覽器版 Pygame 載入失敗：${String(error)}`;
+      showMessage(text);
+      tell("load_error", { text });
+    }
+  }
+
+  async function run(files, runId) {
+    if (!pyodide || busy) return;
+    busy = true;
+    window.currentRunId = runId;
+    outputDecoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+    pyodide.setStdout(setStream("stdout"));
+    pyodide.setStderr(setStream("stderr"));
+    pyodide.setStdin({ stdin: () => { throw new Error("瀏覽器版 Pygame 不支援 input()；請改用 pygame 的鍵盤或滑鼠事件。"); } });
+    showMessage("正在載入 Pygame…");
+    tell("status", { runId, label: "載入 Pygame 套件…" });
+
+    try {
+      await pyodide.loadPackage("pygame-ce");
+      pyodide.runPython(`
+import os, shutil, sys
+root = "/home/pyodide/classroom_pygame"
+shutil.rmtree(root, ignore_errors=True)
+os.makedirs(root, exist_ok=True)
+for name, module in list(sys.modules.items()):
+    if str(getattr(module, "__file__", "")).startswith(root):
+        del sys.modules[name]
+`);
+      for (const [path, content] of Object.entries(files || {})) {
+        if (path.startsWith("/") || path.split(/[\\/]/).includes("..")) continue;
+        const fullPath = `/home/pyodide/classroom_pygame/${path}`;
+        pyodide.FS.mkdirTree(fullPath.slice(0, fullPath.lastIndexOf("/")));
+        pyodide.FS.writeFile(fullPath, content, { encoding: "utf8" });
+      }
+      pyodide.globals.set("classroom_entry", "main.py");
+      canvas.focus();
+      hideMessage();
+      tell("status", { runId, label: "遊戲執行中" });
+      const succeeded = await pyodide.runPythonAsync(`
+import asyncio, inspect, os, sys, traceback
+root = "/home/pyodide/classroom_pygame"
+os.chdir(root)
+if root not in sys.path:
+    sys.path.insert(0, root)
+entry = os.path.join(root, classroom_entry)
+namespace = {"__name__": "__main__", "__file__": entry}
+try:
+    with open(entry, "r", encoding="utf-8") as source:
+        exec(compile(source.read(), entry, "exec"), namespace)
+    main = namespace.get("main")
+    if inspect.iscoroutinefunction(main):
+        await main()
+    True
+except BaseException:
+    traceback.print_exc()
+    raise
+finally:
+    import pygame
+    pygame.quit()
+`);
+      for (const channel of ["stdout", "stderr"]) {
+        const rest = outputDecoders[channel].decode();
+        if (rest) tell("output", { runId, text: rest });
+      }
+      tell(succeeded ? "done" : "error", { runId });
+      showMessage(succeeded ? "遊戲已結束。按「執行」可重新開始。" : "遊戲發生錯誤，請查看文字輸出。" );
+    } catch (error) {
+      for (const channel of ["stdout", "stderr"]) {
+        const rest = outputDecoders[channel].decode();
+        if (rest) tell("output", { runId, text: rest });
+      }
+      const text = String(error);
+      tell("error", { runId, text });
+      showMessage("遊戲發生錯誤，請查看文字輸出。");
+    } finally {
+      busy = false;
+    }
+  }
+
+  window.addEventListener("message", event => {
+    if (event.source !== window.parent || event.data?.type !== "run") return;
+    run(event.data.files, event.data.runId);
+  });
+
+  initialize();
+})();

classroom_static/pygame-support.js

@@ -0,0 +1,96 @@
+(() => {
+  let frame = null;
+  let ready = false;
+  let bootPromise = null;
+  let resolveBoot = null;
+  let rejectBoot = null;
+  let timeout = null;
+  let runId = 0;
+  let activeRunId = 0;
+  let onMessage = () => {};
+
+  function receive(event) {
+    if (!frame || event.source !== frame.contentWindow) return;
+    const message = event.data || {};
+    if (message.type === "ready") {
+      ready = true;
+      clearTimeout(timeout);
+      timeout = null;
+      resolveBoot?.();
+      resolveBoot = null;
+      rejectBoot = null;
+      bootPromise = null;
+      return;
+    }
+    if (message.type === "load_error") {
+      const error = new Error(message.text || "無法載入瀏覽器版 Pygame");
+      clearTimeout(timeout);
+      timeout = null;
+      rejectBoot?.(error);
+      resolveBoot = null;
+      rejectBoot = null;
+      bootPromise = null;
+      onMessage({ ...message, runId: activeRunId });
+      return;
+    }
+    if (message.runId && message.runId !== activeRunId) return;
+    onMessage(message);
+  }
+
+  window.addEventListener("message", receive);
+
+  window.ClassroomPygame = {
+    attach(target, handler) {
+      frame = target;
+      onMessage = handler;
+    },
+
+    isPygame(files) {
+      return Object.entries(files || {}).some(([path, code]) =>
+        path.toLowerCase().endsWith(".py") &&
+        /^\s*(?:import\s+pygame(?:\s|,|$)|from\s+pygame(?:\.|\s+import\s))/m.test(code)
+      );
+    },
+
+    async run(files) {
+      const thisRun = ++runId;
+      activeRunId = thisRun;
+      frame.hidden = false;
+      if (!ready) {
+        if (!bootPromise) {
+          bootPromise = new Promise((resolve, reject) => {
+            resolveBoot = resolve;
+            rejectBoot = reject;
+            timeout = setTimeout(() => {
+              const error = new Error("Pygame 載入逾時，請確認網路連線後重試。");
+              bootPromise = null;
+              resolveBoot = null;
+              rejectBoot = null;
+              reject(error);
+            }, 60000);
+            frame.src = "/classroom-assets/pygame-runner.html?v=2026fall-1";
+          });
+        }
+        await bootPromise;
+      }
+      if (thisRun !== runId) return;
+      frame.contentWindow.postMessage({ type: "run", runId: thisRun, files }, "*");
+    },
+
+    stop() {
+      ++runId;
+      activeRunId = runId;
+      ready = false;
+      clearTimeout(timeout);
+      timeout = null;
+      if (rejectBoot) rejectBoot(new Error("Pygame 已停止"));
+      resolveBoot = null;
+      rejectBoot = null;
+      bootPromise = null;
+      if (frame) {
+        frame.hidden = true;
+        frame.src = "about:blank";
+      }
+    },
+  };
+})();

classroom_static/student.html

@@ -1,12 +1,142 @@
-<!doctype html><html lang="zh-Hant"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light"><title>Python 專案教室｜學生工作區</title><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/codemirror.min.css"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/theme/material-darker.min.css"><link rel="stylesheet" href="/classroom-assets/classroom.css?v=2026fall-9"></head><body>
-<header class="app-header"><div class="brand"><div class="brand-mark">Py</div><div class="brand-copy"><strong>Python 專案教室</strong><span id="studentIdentity">尚未進入教室</span></div></div><div class="header-actions"><div class="connection-state"><i class="status-dot" id="connectionDot"></i><span id="connectionText">未連線</span></div><button class="btn help compact" id="helpButton">請老師協助</button><button class="btn secondary compact" id="identityButton">更換身分</button></div></header>
-<section class="project-bar"><div class="project-context"><label for="weekSelect">Lesson</label><select id="weekSelect"></select><label for="projectName">專案</label><input id="projectName" maxlength="36"></div><div class="project-actions"><button class="copy-button" id="templateButton">匯入專案起始套版</button><button class="copy-button" id="progressButton">選擇舊進度</button><button class="copy-button" id="importButton">匯入 .py / ZIP</button><button class="copy-button" id="exportButton">匯出專案</button><button class="copy-button checkpoint-action" id="checkpointButton">暫存本週進度</button><button class="btn compact" id="submitButton">提交正式版本</button><input id="fileImport" type="file" accept=".py,.zip" hidden></div></section>
-<nav class="mobile-tabs" role="tablist"><button class="mobile-tab" data-panel="referencePanel">專案／語法</button><button class="mobile-tab" data-panel="editorPanel" aria-selected="true">程式</button><button class="mobile-tab" data-panel="consolePanel">執行結果</button></nav>
-<main class="student-layout" id="studentLayout"><aside class="panel reference-panel" id="referencePanel"><div class="side-tabs"><button class="side-tab active" data-side="filesView">專案檔案</button><button class="side-tab" data-side="syntaxView">語法查詢</button></div><section class="side-view" id="filesView"><div class="panel-heading"><h1>檔案夾</h1><button class="copy-button" id="newFileButton">+新增</button></div><div class="file-list" id="fileList"></div><p class="side-note">入口固定為 <code>main.py</code>，可用 <code>import</code> 引入其他 Python 檔。</p></section><section class="side-view" id="syntaxView" hidden><div class="panel-heading"><h1>Python 語法查詢</h1><span id="snippetCount">0 項</span></div><div class="search-wrap"><label class="field-label" for="syntaxSearch">輸入語法或用途</label><input class="text-field" id="syntaxSearch" type="search"><div class="chip-row" id="categoryFilters"></div></div><div class="snippet-list" id="snippetList"></div></section></aside>
-<div class="panel-resizer reference-resizer" id="referenceResizer" role="separator" aria-label="調整專案側欄寬度" aria-orientation="vertical" tabindex="0" title="拖曳調整寬度；雙擊恢復預設"></div>
-<section class="panel editor-panel mobile-active" id="editorPanel"><div class="panel-heading dark"><span class="file-name" id="activeFileLabel">main.py</span><div class="editor-toolbar"><button class="editor-toggle" id="toggleReferenceButton" aria-pressed="false">隱藏側欄</button><button class="editor-toggle" id="toggleConsoleButton" aria-pressed="false">隱藏 Console</button><button class="btn stop compact" id="stopButton" disabled>停止</button><button class="btn compact" id="runButton" disabled>載入 Python…</button></div></div><div class="editor-host"><textarea id="codeEditor" aria-label="程式碼"></textarea></div></section>
-<div class="panel-resizer console-resizer" id="consoleResizer" role="separator" aria-label="調整 Console 寬度" aria-orientation="vertical" tabindex="0" title="拖曳調整寬度；雙擊恢復預設"></div>
-<aside class="panel console-panel" id="consolePanel"><div class="panel-heading"><h2>互動式 Console</h2><button class="copy-button" id="clearOutputButton">清除</button></div><div class="console-body"><div class="console-stream"><pre class="console-output" id="consoleOutput">Python 執行環境載入中…</pre><form class="console-input-row" id="consoleInputForm" hidden><span aria-hidden="true">›</span><label class="sr-only" for="consoleInput">Python 程式要求輸入</label><input id="consoleInput" autocomplete="off"><button class="btn compact" type="submit">送出</button></form></div><p class="console-hint">執行 <code>main.py</code>；遇到 <code>input()</code> 時會在這裡詢問。</p><div class="console-status"><i class="status-dot" id="runStatusDot"></i><span id="runStatusText">準備環境</span><span>·</span><span id="saveStatus">尚未同步</span><span>·</span><span id="submitStatus">尚未暫存或提交</span></div></div></aside></main>
-<dialog id="identityDialog"><form class="dialog-content form-stack" id="identityForm"><div><h1>進入程式教室</h1><p>選擇班級並輸入自己在名單上的姓名。</p></div><div><label class="field-label" for="classCode">課程</label><select class="text-field" id="classCode" required></select></div><div><label class="field-label" for="displayName">姓名</label><input class="text-field" id="displayName" autocomplete="name" required><p class="field-help">姓名必須與老師建立的名單一致。</p></div><p class="form-error" id="identityError" role="alert"></p><button class="btn" type="submit">進入教室</button></form></dialog>
-<dialog id="progressDialog"><div class="dialog-content"><h2>選擇已儲存版本</h2><p>每次暫存與正式提交都會保留；載入只會建立工作副本，不會刪除其他版本。</p><div class="progress-list" id="progressList"></div><button class="btn secondary dialog-close">關閉</button></div></dialog><div class="toast" id="toast"></div>
-<script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/codemirror.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.65.16/mode/python/python.min.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/jszip/3.10.1/jszip.min.js"></script><script src="/classroom-assets/student.js?v=2026fall-11"></script></body></html>
+<!doctype html>
+<html lang="zh-Hant" class="student-page">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+  <meta name="color-scheme" content="light">
+  <title>Python 專案教室｜學生工作區</title>
+  <link rel="stylesheet" href="/classroom-assets/vendor/codemirror/codemirror.css">
+  <link rel="stylesheet" href="/classroom-assets/vendor/codemirror/material-darker.css">
+  <link rel="stylesheet" href="/classroom-assets/classroom.css?v=2026fall-16">
+</head>
+<body>
+  <header class="app-header">
+    <div class="brand">
+      <div class="brand-mark">Py</div>
+      <div class="brand-copy">
+        <strong>Python 專案教室</strong>
+        <span id="studentIdentity">尚未進入教室</span>
+      </div>
+    </div>
+    <div class="header-actions">
+      <div class="connection-state"><i class="status-dot" id="connectionDot"></i><span id="connectionText">未連線</span></div>
+      <button class="btn help compact" id="helpButton">請老師協助</button>
+      <button class="btn secondary compact" id="identityButton">更換身分</button>
+    </div>
+  </header>
+
+  <section class="project-bar">
+    <div class="project-context">
+      <label for="weekSelect">Lesson</label><select id="weekSelect"></select>
+      <label for="projectName">專案</label><input id="projectName" maxlength="36">
+    </div>
+    <div class="project-actions">
+      <button class="copy-button" id="templateButton">匯入專案起始套版</button>
+      <button class="copy-button" id="progressButton">選擇舊進度</button>
+      <button class="copy-button" id="importButton">匯入 .py / ZIP</button>
+      <button class="copy-button" id="exportButton">匯出專案</button>
+      <button class="copy-button checkpoint-action" id="checkpointButton">暫存本週進度</button>
+      <button class="btn compact" id="submitButton">提交正式版本</button>
+      <input id="fileImport" type="file" accept=".py,.zip" hidden>
+    </div>
+  </section>
+
+  <nav class="mobile-tabs" role="tablist">
+    <button class="mobile-tab" data-panel="referencePanel">專案／語法</button>
+    <button class="mobile-tab" data-panel="editorPanel" aria-selected="true">程式</button>
+    <button class="mobile-tab" data-panel="consolePanel">執行結果</button>
+  </nav>
+
+  <main class="student-layout" id="studentLayout">
+    <aside class="panel reference-panel" id="referencePanel">
+      <div class="side-tabs">
+        <button class="side-tab active" data-side="filesView">專案檔案</button>
+        <button class="side-tab" data-side="syntaxView">語法查詢</button>
+      </div>
+      <section class="side-view" id="filesView">
+        <div class="panel-heading"><h1>檔案夾</h1><button class="copy-button" id="newFileButton">+新增</button></div>
+        <div class="file-list" id="fileList"></div>
+        <p class="side-note">入口固定為 <code>main.py</code>，可用 <code>import</code> 引入其他 Python 檔。</p>
+      </section>
+      <section class="side-view" id="syntaxView" hidden>
+        <div class="panel-heading"><h1>Python 語法查詢</h1><span id="snippetCount">0 項</span></div>
+        <div class="search-wrap">
+          <label class="field-label" for="syntaxSearch">輸入語法或用途</label>
+          <input class="text-field" id="syntaxSearch" type="search">
+          <div class="chip-row" id="categoryFilters"></div>
+        </div>
+        <div class="snippet-list" id="snippetList"></div>
+      </section>
+    </aside>
+
+    <div class="panel-resizer reference-resizer" id="referenceResizer" role="separator" aria-label="調整專案側欄寬度" aria-orientation="vertical" tabindex="0" title="拖曳調整寬度；雙擊恢復預設"></div>
+
+    <section class="panel editor-panel mobile-active" id="editorPanel">
+      <div class="panel-heading dark">
+        <span class="file-name" id="activeFileLabel">main.py</span>
+        <div class="editor-toolbar">
+          <button class="editor-toggle" id="toggleReferenceButton" aria-pressed="false">隱藏側欄</button>
+          <button class="editor-toggle" id="toggleConsoleButton" aria-pressed="false">隱藏 Console</button>
+          <button class="btn stop compact" id="stopButton" disabled>停止</button>
+          <button class="btn compact" id="runButton" disabled>載入 Python…</button>
+        </div>
+      </div>
+      <div class="editor-host"><textarea id="codeEditor" aria-label="程式碼"></textarea></div>
+    </section>
+
+    <div class="panel-resizer console-resizer" id="consoleResizer" role="separator" aria-label="調整 Console 寬度" aria-orientation="vertical" tabindex="0" title="拖曳調整寬度；雙擊恢復預設"></div>
+
+    <aside class="panel console-panel" id="consolePanel">
+      <div class="panel-heading"><h2>執行結果</h2><button class="copy-button" id="clearOutputButton">清除</button></div>
+      <div class="console-body">
+        <div class="console-tabs" id="consoleTabs" role="tablist" aria-label="執行結果檢視" hidden>
+          <button class="console-tab active" id="consoleOutputTab" role="tab" aria-selected="true">文字輸出</button>
+          <button class="console-tab" id="pygameOutputTab" role="tab" aria-selected="false">遊戲畫面</button>
+        </div>
+        <div class="console-stream" id="consoleStream" data-view="console">
+          <pre class="console-output" id="consoleOutput">Python 執行環境載入中…</pre>
+          <iframe id="pygameFrame" title="Pygame 遊戲畫面" sandbox="allow-scripts" hidden></iframe>
+          <form class="console-input-row" id="consoleInputForm" hidden>
+            <span aria-hidden="true">›</span>
+            <label class="sr-only" for="consoleInput">Python 程式要求輸入</label>
+            <input id="consoleInput" autocomplete="off">
+            <button class="btn compact" type="submit">送出</button>
+          </form>
+        </div>
+        <p class="console-hint" id="consoleHint">一般 Python 可使用 <code>input()</code>。Pygame 使用瀏覽器畫布，需用 <code>async main()</code> 與 <code>await asyncio.sleep()</code>；目前支援程式繪圖，不支援 <code>input()</code> 或外部圖片／音效檔。範例請在語法查詢搜尋 Pygame。</p>
+        <div class="console-status">
+          <i class="status-dot" id="runStatusDot"></i><span id="runStatusText">準備環境</span>
+          <span>·</span><span id="saveStatus">尚未同步</span>
+          <span>·</span><span id="submitStatus">尚未暫存或提交</span>
+        </div>
+      </div>
+    </aside>
+  </main>
+
+  <dialog id="identityDialog">
+    <form class="dialog-content form-stack" id="identityForm">
+      <div><h1>進入程式教室</h1><p>選擇班級並輸入自己在名單上的姓名。</p></div>
+      <div><label class="field-label" for="classCode">課程</label><select class="text-field" id="classCode" required></select></div>
+      <div><label class="field-label" for="displayName">姓名</label><input class="text-field" id="displayName" autocomplete="name" required><p class="field-help">姓名必須與老師建立的名單一致。</p></div>
+      <p class="form-error" id="identityError" role="alert"></p>
+      <button class="btn" type="submit">進入教室</button>
+    </form>
+  </dialog>
+
+  <dialog id="progressDialog">
+    <div class="dialog-content">
+      <h2>選擇已儲存版本</h2>
+      <p>每次暫存與正式提交都會保留；載入只會建立工作副本，不會刪除其他版本。</p>
+      <div class="progress-list" id="progressList"></div>
+      <button class="btn secondary dialog-close">關閉</button>
+    </div>
+  </dialog>
+  <div class="toast" id="toast"></div>
+
+  <script src="/classroom-assets/vendor/codemirror/codemirror.js"></script>
+  <script src="/classroom-assets/vendor/codemirror/python.js"></script>
+  <script src="/classroom-assets/vendor/jszip/jszip.min.js"></script>
+  <script src="/classroom-assets/pygame-support.js?v=2026fall-1"></script>
+  <script src="/classroom-assets/student.js?v=2026fall-14"></script>
+</body>
+</html>

classroom_static/student.js

@@ -1,8 +1,8 @@
-const SNIPPETS=[["基礎","輸入與輸出",'name = input("名字：")\nprint("你好", name)'],["判斷","if / elif / else",'if score >= 90:\n    print("A")\nelse:\n    print("繼續加油")'],["迴圈","for 與 range",'for number in range(1, 6):\n    print(number)'],["迴圈","while",'while True:\n    choice = input("選擇：")\n    if choice == "q":\n        break'],["資料","list",'items = []\nitems.append("線索")\nfor item in items:\n    print(item)'],["資料","dict",'student = {"name": "Alex"}\nprint(student.get("team", "未分組"))'],["函式","def / return",'def add(a, b):\n    return a + b'],["檔案","引入自己的模組",'from clues import find_clue'],["檔案","讀取 JSON",'import json\nwith open("data.json", encoding="utf-8") as file:\n    data = json.load(file)'],["錯誤","try / except",'try:\n    age = int(input("年齡："))\nexcept ValueError:\n    print("請輸入整數")']].map(([category,title,code])=>({category,title,code}));
-const $=id=>document.getElementById(id),E={};["identityDialog","identityForm","identityError","classCode","displayName","studentIdentity","identityButton","connectionDot","connectionText","helpButton","weekSelect","projectName","templateButton","progressButton","importButton","exportButton","checkpointButton","submitButton","fileImport","fileList","newFileButton","activeFileLabel","syntaxSearch","categoryFilters","snippetList","snippetCount","runButton","stopButton","toggleReferenceButton","toggleConsoleButton","studentLayout","editorPanel","referencePanel","consolePanel","referenceResizer","consoleResizer","consoleInputForm","consoleInput","consoleOutput","clearOutputButton","runStatusDot","runStatusText","saveStatus","submitStatus","toast","progressDialog","progressList"].forEach(id=>E[id]=$(id));
+const SNIPPETS=[["基礎","輸入與輸出",'name = input("名字：")\nprint("你好", name)'],["判斷","if / elif / else",'if score >= 90:\n    print("A")\nelse:\n    print("繼續加油")'],["迴圈","for 與 range",'for number in range(1, 6):\n    print(number)'],["迴圈","while",'while True:\n    choice = input("選擇：")\n    if choice == "q":\n        break'],["資料","list",'items = []\nitems.append("線索")\nfor item in items:\n    print(item)'],["資料","dict",'student = {"name": "Alex"}\nprint(student.get("team", "未分組"))'],["函式","def / return",'def add(a, b):\n    return a + b'],["檔案","引入自己的模組",'from clues import find_clue'],["檔案","讀取 JSON",'import json\nwith open("data.json", encoding="utf-8") as file:\n    data = json.load(file)'],["錯誤","try / except",'try:\n    age = int(input("年齡："))\nexcept ValueError:\n    print("請輸入整數")'],["Pygame","瀏覽器版 Pygame 入門",'import asyncio\nimport pygame\n\nasync def main():\n    pygame.init()\n    screen = pygame.display.set_mode((640, 480))\n    pygame.display.set_caption("我的第一個遊戲")\n    clock = pygame.time.Clock()\n    x = 300\n    running = True\n\n    while running:\n        for event in pygame.event.get():\n            if event.type == pygame.QUIT:\n                running = False\n\n        keys = pygame.key.get_pressed()\n        if keys[pygame.K_LEFT]:\n            x -= 4\n        if keys[pygame.K_RIGHT]:\n            x += 4\n\n        screen.fill((24, 34, 52))\n        pygame.draw.circle(screen, (255, 190, 80), (x, 240), 28)\n        pygame.display.flip()\n        await asyncio.sleep(1 / 60)\n\n    pygame.quit()\n\n# 瀏覽器版會自動呼叫 async main()，不用另外加 asyncio.run(main())']].map(([category,title,code])=>({category,title,code}));
+const $=id=>document.getElementById(id),E={};["identityDialog","identityForm","identityError","classCode","displayName","studentIdentity","identityButton","connectionDot","connectionText","helpButton","weekSelect","projectName","templateButton","progressButton","importButton","exportButton","checkpointButton","submitButton","fileImport","fileList","newFileButton","activeFileLabel","syntaxSearch","categoryFilters","snippetList","snippetCount","runButton","stopButton","toggleReferenceButton","toggleConsoleButton","studentLayout","editorPanel","referencePanel","consolePanel","referenceResizer","consoleResizer","consoleInputForm","consoleInput","consoleOutput","consoleTabs","consoleOutputTab","pygameOutputTab","consoleStream","pygameFrame","consoleHint","clearOutputButton","runStatusDot","runStatusText","saveStatus","submitStatus","toast","progressDialog","progressList"].forEach(id=>E[id]=$(id));
 const editor=CodeMirror.fromTextArea($("codeEditor"),{mode:"python",theme:"material-darker",lineNumbers:true,indentUnit:4,tabSize:4,extraKeys:{Tab:cm=>cm.replaceSelection("    ")}});
 let studentId=localStorage.getItem("classroom_student_id")||"",allowLegacyDraft=!!studentId,catalog={courses:[]};
-let course,files={"main.py":"# 在這裡寫 Python\n"},activeFile="main.py",socket,worker,workerReady=false,running=false,needsHelp=false,checkpointAt=null,submittedAt=null,output="",suppress=false,timer,reconnect,category="全部",inputBuffer,inputControl,inputBytes,stdoutDecoder=new TextDecoder(),stderrDecoder=new TextDecoder();
+let course,files={"main.py":"# 在這裡寫 Python\n"},activeFile="main.py",socket,worker,workerReady=false,running=false,pygameRunning=false,needsHelp=false,checkpointAt=null,submittedAt=null,output="",suppress=false,timer,reconnect,category="全部",inputBuffer,inputControl,inputBytes,stdoutDecoder=new TextDecoder(),stderrDecoder=new TextDecoder();
 const clean=v=>String(v||"").trim().replace(/[^0-9A-Za-z_\-一-鿿]/g,"").slice(0,48),lesson=()=>E.weekSelect.value||"week02",lessonInfo=()=>course?.weeks.find(item=>item.id===lesson()),workspace=()=>lessonInfo()?.workspace_id||lesson(),key=()=>`classroom_project_${localStorage.getItem("classroom_code")}_${studentId}_${workspace()}`,legacyKey=()=>`classroom_project_${localStorage.getItem("classroom_code")}_${workspace()}`;
 function toast(t){E.toast.textContent=t;E.toast.classList.add("visible");setTimeout(()=>E.toast.classList.remove("visible"),1900)}
 function send(m){if(socket?.readyState!==WebSocket.OPEN)return false;socket.send(JSON.stringify(m));return true}
@@ -32,8 +32,14 @@ function connect(){
       const src=local&&Number(local.savedAt||0)>Number(s.updated_at||0)?local:server;
       output=src.output||"";E.consoleOutput.textContent=output||"尚無執行結果。";checkpointAt=s.checkpoint_at;submittedAt=s.submitted_at;needsHelp=!!s.needs_help;renderState();setProject(src.files,src.projectName,src.activeFile);send({type:"output",output});
     }
+    if(m.type==="identity"&&typeof m.display_name==="string"){
+      localStorage.setItem("classroom_name",m.display_name);
+      E.studentIdentity.textContent=`${clean(localStorage.getItem("classroom_code"))} · ${m.display_name}`;
+      toast("老師已更新你的名單姓名");
+    }
     if(m.type==="help_ack"){needsHelp=false;renderState();toast("老師已看到你的協助請求")}
-    if(["ack","pong"].includes(m.type)){if(typeof m.needs_help==="boolean"){const seen=needsHelp&&!m.needs_help;needsHelp=m.needs_help;if(seen)toast("老師已看到你的協助請求")}if(m.checkpoint_at)checkpointAt=m.checkpoint_at;if(m.submitted_at)submittedAt=m.submitted_at;renderState();if(m.type==="ack")E.saveStatus.textContent="已同步";if(m.version_warning)toast(m.version_warning)}
+    if(m.type==="write_rejected"){E.saveStatus.textContent="未儲存";toast(m.message||"儲存受到限制，請稍後再試");send({type:"ping"})}
+    if(["ack","pong"].includes(m.type)){if(typeof m.needs_help==="boolean"){const seen=needsHelp&&!m.needs_help;needsHelp=m.needs_help;if(seen)toast("老師已看到你的協助請求")}if(Object.prototype.hasOwnProperty.call(m,"checkpoint_at"))checkpointAt=m.checkpoint_at;if(Object.prototype.hasOwnProperty.call(m,"submitted_at"))submittedAt=m.submitted_at;renderState();if(m.type==="ack")E.saveStatus.textContent="已同步";if(m.version_warning)toast(m.version_warning)}
   };
   current.onclose=async e=>{if(socket!==current)return;E.connectionDot.className="status-dot error";E.connectionText.textContent="已離線";E.saveStatus.textContent="保存在此裝置";if(e.code===4004||e.code===4404){localStorage.removeItem("classroom_student_id");localStorage.removeItem("classroom_name");studentId="";await loadCatalog();E.identityError.textContent=e.code===4004?"老師已將你從名單移除。":"姓名與班級名單不符，請重新輸入。";E.identityDialog.showModal();return}reconnect=setTimeout(connect,2500)};
 }
@@ -74,6 +80,8 @@ function initResizablePanels(){
 }
 function setLayout(referenceHidden,consoleHidden){E.studentLayout.classList.toggle("reference-hidden",referenceHidden);E.studentLayout.classList.toggle("console-hidden",consoleHidden);E.toggleReferenceButton.setAttribute("aria-pressed",String(referenceHidden));E.toggleConsoleButton.setAttribute("aria-pressed",String(consoleHidden));E.toggleReferenceButton.textContent=referenceHidden?"顯示側欄":"隱藏側欄";E.toggleConsoleButton.textContent=consoleHidden?"顯示 Console":"隱藏 Console";localStorage.setItem("classroom_hide_reference",String(referenceHidden));localStorage.setItem("classroom_hide_console",String(consoleHidden));requestAnimationFrame(()=>{syncPanelWidths(false);refreshEditorLayout()})}
 function renderLesson(){const item=lessonInfo(),shared=item?.workspace_id&&item.workspace_id!==item.id;E.templateButton.disabled=!item?.template;E.templateButton.textContent=item?.template?"匯入專案起始套版":shared?"沿用目前專案":"尚未提供套版"}
+function setConsoleView(view){E.consoleStream.dataset.view=view;E.consoleOutputTab.classList.toggle("active",view==="console");E.pygameOutputTab.classList.toggle("active",view==="pygame");E.consoleOutputTab.setAttribute("aria-selected",String(view==="console"));E.pygameOutputTab.setAttribute("aria-selected",String(view==="pygame"))}
+ClassroomPygame.attach(E.pygameFrame,message=>{if(message.type==="output"&&message.text)append(message.text);if(message.type==="status"&&message.label)E.runStatusText.textContent=message.label;if(message.type==="done"){pygameRunning=false;runState("success","遊戲已結束")}if(message.type==="error"||message.type==="load_error"){pygameRunning=false;if(message.text)append(`${message.text}\n`);runState("error","Pygame 執行錯誤");setConsoleView("console")}});
 function initWorker(){worker?.terminate();workerReady=false;running=false;E.consoleInputForm.hidden=true;E.runButton.disabled=true;E.runButton.textContent="載入 Python…";if(!crossOriginIsolated||typeof SharedArrayBuffer==="undefined"){append("瀏覽器未啟用互動式 Python。請重新整理，並使用最新版 Chrome、Edge 或 Safari。\n");runState("error","環境不支援");return}inputBuffer=new SharedArrayBuffer(16392);inputControl=new Int32Array(inputBuffer,0,2);inputBytes=new Uint8Array(inputBuffer,8);worker=new Worker("/classroom-assets/py-worker.js?v=2026fall-4");worker.onmessage=e=>{const m=e.data;if(m.type==="ready"){workerReady=true;E.runButton.disabled=false;E.runButton.textContent="執行";runState("online","準備完成")}else if(m.type==="stream"){const decoder=m.channel==="stderr"?stderrDecoder:stdoutDecoder;append(decoder.decode(m.bytes,{stream:true}))}else if(m.type==="input_request"){E.consoleInputForm.hidden=false;E.consoleInput.value="";E.runStatusText.textContent="等待輸入";E.consoleInput.focus()}else if(m.type==="done"){E.consoleInputForm.hidden=true;runState("success","執行成功")}else if(m.type==="python_error"){E.consoleInputForm.hidden=true;if(m.text)append(`${m.text}\n`);runState("error","程式錯誤")}else if(m.type==="load_error"){append(`Python 載入失敗：${m.text}\n`);runState("error","載入失敗")}};worker.onerror=e=>{append(`Python 執行器錯誤：${e.message}\n`);runState("error","執行器錯誤")}}
 function runState(s,t){running=s==="running";E.runStatusDot.className=`status-dot ${s}`;E.runStatusText.textContent=t;E.runButton.disabled=!workerReady||running;E.stopButton.disabled=!running;send({type:"status",status:s==="online"?"idle":s})}
 function append(t){output=(output+t).slice(-40000);E.consoleOutput.textContent=output;E.consoleOutput.scrollTop=E.consoleOutput.scrollHeight;saveLocal();send({type:"output",output})}
@@ -87,6 +95,6 @@ E.importButton.onclick=()=>E.fileImport.click();E.fileImport.onchange=async()=>{
 E.exportButton.onclick=async()=>{files[activeFile]=editor.getValue();const z=new JSZip();Object.entries(files).forEach(([p,t])=>z.file(p,t));const blob=await z.generateAsync({type:"blob"}),a=document.createElement("a");a.href=URL.createObjectURL(blob);a.download=`${clean(E.projectName.value)||"project"}.zip`;a.click();URL.revokeObjectURL(a.href)};
 E.checkpointButton.onclick=()=>{files[activeFile]=editor.getValue();if(!files["main.py"].trim())return toast("main.py 不能為空");saveLocal();if(!send({type:"checkpoint",files,project_name:E.projectName.value}))return toast("目前離線，請連線後再暫存");checkpointAt=Date.now();renderState();toast("已新增一個暫存版本，不會發布到 Demo")};
 E.submitButton.onclick=()=>{files[activeFile]=editor.getValue();if(!files["main.py"].trim())return toast("main.py 不能為空");if(!confirm("新增一個正式提交版本？之前的暫存與提交都會保留。"))return;saveLocal();if(!send({type:"submit",files,project_name:E.projectName.value}))return toast("目前離線，請連線後再提交");submittedAt=Date.now();renderState();toast("已新增一個正式提交版本")};E.helpButton.onclick=()=>{needsHelp=!needsHelp;renderState();send({type:"help",needs_help:needsHelp})};
-E.runButton.onclick=()=>{if(!workerReady||running)return;files[activeFile]=editor.getValue();output="";E.consoleOutput.textContent="";E.consoleInputForm.hidden=true;stdoutDecoder=new TextDecoder();stderrDecoder=new TextDecoder();Atomics.store(inputControl,0,0);runState("running","執行中");worker.postMessage({type:"run",files,entry:"main.py",inputBuffer})};E.consoleInputForm.onsubmit=e=>{e.preventDefault();if(!running||E.consoleInputForm.hidden)return;const encoded=new TextEncoder().encode(E.consoleInput.value);if(encoded.length>inputBytes.length)return toast("單次輸入內容太長");inputBytes.fill(0);inputBytes.set(encoded);Atomics.store(inputControl,1,encoded.length);append(`${E.consoleInput.value}\n`);E.consoleInputForm.hidden=true;E.runStatusText.textContent="執行中";Atomics.store(inputControl,0,1);Atomics.notify(inputControl,0,1)};E.stopButton.onclick=()=>{append("\n[已停止]\n");runState("idle","已停止");initWorker()};E.clearOutputButton.onclick=()=>{output="";E.consoleOutput.textContent="尚無執行結果。";send({type:"output",output:""})};E.syntaxSearch.oninput=renderSyntax;editor.on("change",()=>{if(!suppress){files[activeFile]=editor.getValue();sync()}});
+E.runButton.onclick=async()=>{if(!workerReady||running)return;files[activeFile]=editor.getValue();output="";E.consoleOutput.textContent="";E.consoleInputForm.hidden=true;stdoutDecoder=new TextDecoder();stderrDecoder=new TextDecoder();if(ClassroomPygame.isPygame(files)){pygameRunning=true;E.consoleTabs.hidden=false;E.pygameFrame.hidden=false;setConsoleView("pygame");runState("running","準備瀏覽器版 Pygame");try{await ClassroomPygame.run(files)}catch(error){if(!running)return;pygameRunning=false;append(`Pygame 載入失敗：${error.message}\n`);runState("error","Pygame 載入失敗");setConsoleView("console")}return}ClassroomPygame.stop();pygameRunning=false;E.consoleTabs.hidden=true;E.pygameFrame.hidden=true;setConsoleView("console");Atomics.store(inputControl,0,0);runState("running","執行中");worker.postMessage({type:"run",files,entry:"main.py",inputBuffer})};E.consoleInputForm.onsubmit=e=>{e.preventDefault();if(!running||E.consoleInputForm.hidden)return;const encoded=new TextEncoder().encode(E.consoleInput.value);if(encoded.length>inputBytes.length)return toast("單次輸入內容太長");inputBytes.fill(0);inputBytes.set(encoded);Atomics.store(inputControl,1,encoded.length);append(`${E.consoleInput.value}\n`);E.consoleInputForm.hidden=true;E.runStatusText.textContent="執行中";Atomics.store(inputControl,0,1);Atomics.notify(inputControl,0,1)};E.stopButton.onclick=()=>{append("\n[已停止]\n");if(pygameRunning){ClassroomPygame.stop();pygameRunning=false;setConsoleView("console");runState("idle","已停止");return}runState("idle","已停止");initWorker()};E.consoleOutputTab.onclick=()=>setConsoleView("console");E.pygameOutputTab.onclick=()=>setConsoleView("pygame");E.clearOutputButton.onclick=()=>{output="";E.consoleOutput.textContent="尚無執行結果。";send({type:"output",output:""})};E.syntaxSearch.oninput=renderSyntax;editor.on("change",()=>{if(!suppress){files[activeFile]=editor.getValue();sync()}});
 E.toggleReferenceButton.onclick=()=>setLayout(!E.studentLayout.classList.contains("reference-hidden"),E.studentLayout.classList.contains("console-hidden"));E.toggleConsoleButton.onclick=()=>setLayout(E.studentLayout.classList.contains("reference-hidden"),!E.studentLayout.classList.contains("console-hidden"));document.querySelectorAll(".side-tab").forEach(b=>b.onclick=()=>{document.querySelectorAll(".side-tab").forEach(x=>x.classList.toggle("active",x===b));document.querySelectorAll(".side-view").forEach(v=>v.hidden=v.id!==b.dataset.side)});document.querySelectorAll(".mobile-tab").forEach(b=>b.onclick=()=>{document.querySelectorAll(".mobile-tab").forEach(x=>x.setAttribute("aria-selected",String(x===b)));document.querySelectorAll(".student-layout>.panel").forEach(p=>p.classList.toggle("mobile-active",p.id===b.dataset.panel));if(b.dataset.panel==="editorPanel")refreshEditorLayout()});setInterval(()=>send({type:"ping"}),4000);
 (async()=>{[course]=await Promise.all([(await fetch("/api/classroom/course")).json(),loadCatalog()]);E.weekSelect.innerHTML=course.weeks.map(w=>`<option value="${w.id}">Lesson ${w.lesson??w.week}｜${esc(w.title)}${w.workspace_id&&w.workspace_id!==w.id?"（同一專案）":""}</option>`).join("");const saved=localStorage.getItem("classroom_week");E.weekSelect.value=course.weeks.some(w=>w.id===saved)?saved:"week02";renderLesson();renderFiles();renderSyntax();initResizablePanels();setLayout(localStorage.getItem("classroom_hide_reference")==="true",localStorage.getItem("classroom_hide_console")==="true");initWorker();connect()})();

runner.py

@@ -1,8 +1,8 @@
 """
 Headless runner for student Pygame / OpenCV projects.
 
-Connects back to the server over localhost TCP, monkeypatches display/input
-APIs, and streams JPEG frames + logs to the browser.
+Connects back to the server over a private Unix socket, monkeypatches
+display/input APIs, and streams JPEG frames + logs to the browser.
 """
 from __future__ import annotations
 
@@ -22,7 +22,7 @@ import numpy as np
 # Parse CLI before importing pygame/opencv (env must be set first)
 parser = argparse.ArgumentParser()
 parser.add_argument("--project_path", required=True, help="Path to the student's main.py")
-parser.add_argument("--port", type=int, required=True, help="Internal TCP communication port")
+parser.add_argument("--socket-path", required=True, help="Private Unix socket used for IPC")
 parser.add_argument(
     "--models_dir",
     default=None,
@@ -101,10 +101,10 @@ def _adjust_frame_interval(queue_depth: int) -> None:
         _current_frame_interval = max(_min_frame_interval, _current_frame_interval * 0.95)
 
 
-# ----------------- TCP threads -----------------
+# ----------------- private IPC threads -----------------
 def reader_thread_func(sock):
     global shared_webcam_frame, shared_keys, shared_mouse_pos, shared_mouse_buttons
-    print("[Runner-TCP] Reader thread started.")
+    print("[Runner-IPC] Reader thread started.")
     try:
         while True:
             type_bytes = sock.recv(4)
@@ -213,9 +213,9 @@ def reader_thread_func(sock):
                     pass
 
     except Exception as e:
-        print(f"[Runner-TCP] Reader error: {e}", file=sys.__stderr__)
+        print(f"[Runner-IPC] Reader error: {e}", file=sys.__stderr__)
     finally:
-        print("[Runner-TCP] Reader thread finished.", file=sys.__stderr__)
+        print("[Runner-IPC] Reader thread finished.", file=sys.__stderr__)
         try:
             sock.close()
         except Exception:
@@ -223,7 +223,7 @@ def reader_thread_func(sock):
 
 
 def writer_thread_func(sock):
-    print("[Runner-TCP] Writer thread started.")
+    print("[Runner-IPC] Writer thread started.")
     try:
         while True:
             msg_type, payload = send_queue.get()
@@ -238,20 +238,20 @@ def writer_thread_func(sock):
             sock.sendall(len(payload).to_bytes(4, byteorder="big"))
             sock.sendall(payload)
     except Exception as e:
-        print(f"[Runner-TCP] Writer error: {e}", file=sys.__stderr__)
+        print(f"[Runner-IPC] Writer error: {e}", file=sys.__stderr__)
     finally:
-        print("[Runner-TCP] Writer thread finished.", file=sys.__stderr__)
+        print("[Runner-IPC] Writer thread finished.", file=sys.__stderr__)
         try:
             sock.close()
         except Exception:
             pass
 
 
-sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
 try:
-    sock.connect(("127.0.0.1", args.port))
+    sock.connect(args.socket_path)
 except Exception as e:
-    print(f"Error connecting to server on port {args.port}: {e}")
+    print(f"Error connecting to server IPC socket: {e}")
     sys.exit(1)
 
 reader_thread = threading.Thread(target=reader_thread_func, args=(sock,), daemon=True)
@@ -261,7 +261,7 @@ writer_thread.start()
 
 
 # ----------------- Buffered stdout/stderr -----------------
-class StreamToTCP:
+class StreamToIPC:
     """Buffer log fragments and flush on newline or timer to reduce IPC chatter."""
 
     def __init__(self, original_stream, flush_interval=0.05):
@@ -306,8 +306,8 @@ class StreamToTCP:
             self._flush_unlocked()
 
 
-sys.stdout = StreamToTCP(sys.stdout)
-sys.stderr = StreamToTCP(sys.stderr)
+sys.stdout = StreamToIPC(sys.stdout)
+sys.stderr = StreamToIPC(sys.stderr)
 
 # ----------------- Stdin / input() -----------------
 import builtins

scripts/vendor_pyodide_packages.mjs

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const [distributionDir, packageBaseUrl] = process.argv.slice(2);
+if (!distributionDir || !packageBaseUrl) {
+  throw new Error("Usage: vendor_pyodide_packages.mjs <pyodide-dir> <package-base-url>");
+}
+
+const normalize = (name) => name.toLowerCase().replace(/[-_.]+/g, "-");
+const lock = JSON.parse(await readFile(path.join(distributionDir, "pyodide-lock.json"), "utf8"));
+const records = lock.packages || {};
+const names = new Map(Object.keys(records).map((name) => [normalize(name), name]));
+const pygameKey = names.get("pygame-ce");
+if (!pygameKey) throw new Error("Pinned Pyodide lock does not contain pygame-ce");
+
+const pending = [pygameKey];
+const required = new Set();
+while (pending.length) {
+  const name = pending.pop();
+  if (required.has(name)) continue;
+  required.add(name);
+  for (const dependency of records[name].depends || []) {
+    const dependencyKey = names.get(normalize(dependency));
+    if (!dependencyKey) throw new Error(`Unknown Pyodide dependency ${dependency} required by ${name}`);
+    pending.push(dependencyKey);
+  }
+}
+
+const base = packageBaseUrl.endsWith("/") ? packageBaseUrl : `${packageBaseUrl}/`;
+for (const name of required) {
+  const record = records[name];
+  if (!record.file_name) continue;
+  const response = await fetch(new URL(encodeURIComponent(record.file_name), base));
+  if (!response.ok) throw new Error(`Could not fetch pinned Pyodide package ${name}: HTTP ${response.status}`);
+  const bytes = Buffer.from(await response.arrayBuffer());
+  const digest = createHash("sha256").update(bytes).digest("hex");
+  if (!record.sha256 || digest !== record.sha256) {
+    throw new Error(`Pyodide package integrity check failed for ${name}`);
+  }
+  await writeFile(path.join(distributionDir, record.file_name), bytes, { mode: 0o644 });
+  console.log(`Vendored ${name} ${record.version} (${bytes.length} bytes)`);
+}

server.py

@@ -13,10 +13,19 @@ import json
 import logging
 import os
 import signal
+import socket
+import shutil
+import stat
 import subprocess
 import sys
+import tempfile
 import time
+import secrets
+import re
+from collections import deque
+from pathlib import Path
 from typing import Any, Optional
+from urllib.parse import urlsplit
 
 from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, RedirectResponse
@@ -45,11 +54,25 @@ HEARTBEAT_TIMEOUT_SEC = max(
 )
 PROJECT_CACHE_TTL_SEC = float(os.environ.get("PROJECT_CACHE_TTL_SEC", "10"))
 RUNNER_CONNECT_TIMEOUT_SEC = float(os.environ.get("RUNNER_CONNECT_TIMEOUT_SEC", "8"))
+RUNNER_TMP_DIR = os.environ.get("RUNNER_TMP_DIR", "/tmp/telearn_runner")
+RUNNER_MEMORY_LIMIT_MB = max(512, int(os.environ.get("RUNNER_MEMORY_LIMIT_MB", "3072")))
+RUNNER_CPU_LIMIT_SEC = max(30, int(os.environ.get("RUNNER_CPU_LIMIT_SEC", "900")))
+RUNNER_TMP_LIMIT_MB = max(64, int(os.environ.get("RUNNER_TMP_LIMIT_MB", "256")))
+RUNNER_PROJECT_LIMIT_MB = max(8, int(os.environ.get("RUNNER_PROJECT_LIMIT_MB", "128")))
+RUNNER_PROJECT_FILE_LIMIT = max(20, int(os.environ.get("RUNNER_PROJECT_FILE_LIMIT", "2000")))
+RUNNER_STARTS_PER_IP_PER_HOUR = max(1, int(os.environ.get("RUNNER_STARTS_PER_IP_PER_HOUR", "120")))
+RUNNER_START_COOLDOWN_SEC = max(0.5, float(os.environ.get("RUNNER_START_COOLDOWN_SEC", "0.75")))
+ENABLE_HSTS = os.environ.get("ENABLE_HSTS", "false").lower() in {"1", "true", "yes"}
+HSTS_MAX_AGE_SEC = max(0, int(os.environ.get("HSTS_MAX_AGE_SEC", "31536000")))
+BWRAP_PATH = shutil.which("bwrap")
+PRLIMIT_PATH = shutil.which("prlimit")
 
 os.makedirs(PROJECTS_DIR, exist_ok=True)
 os.makedirs(TEMPLATES_DIR, exist_ok=True)
 os.makedirs(STATIC_DIR, exist_ok=True)
 os.makedirs(MODELS_DIR, exist_ok=True)
+os.makedirs(RUNNER_TMP_DIR, mode=0o700, exist_ok=True)
+os.chmod(RUNNER_TMP_DIR, 0o700)
 
 logging.basicConfig(
     level=logging.INFO,
@@ -67,10 +90,40 @@ app.include_router(admin_router)
 
 @app.middleware("http")
 async def browser_runtime_headers(request: Request, call_next):
-    """Enable SharedArrayBuffer for interactive input inside the Python worker."""
+    """Set browser isolation and response security policies."""
+    nonce = secrets.token_urlsafe(18)
+    request.scope.setdefault("state", {})["csp_nonce"] = nonce
     response = await call_next(request)
     response.headers["Cross-Origin-Opener-Policy"] = "same-origin"
     response.headers["Cross-Origin-Embedder-Policy"] = "credentialless"
+    response.headers["X-Content-Type-Options"] = "nosniff"
+    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+    response.headers["Permissions-Policy"] = "camera=(self), microphone=(), geolocation=(), payment=(), usb=()"
+    response.headers["Content-Security-Policy"] = (
+        "default-src 'self'; base-uri 'self'; object-src 'none'; "
+        f"script-src 'self' 'nonce-{nonce}' 'wasm-unsafe-eval'; "
+        "style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; "
+        "img-src 'self' data: blob: https://api.qrserver.com; "
+        "font-src 'self' data: https://fonts.gstatic.com; "
+        "connect-src 'self' ws: wss:; "
+        "worker-src 'self' blob:; "
+        "frame-src 'self' https://appetize.io https://*.appetize.io https://makecode.com https://*.makecode.com; "
+        "frame-ancestors 'self'; form-action 'self'"
+    )
+    # Student-authored web projects need JavaScript, but must remain an
+    # opaque-origin sandbox even when opened directly instead of in the player.
+    if request.url.path.startswith("/static_projects/"):
+        response.headers["Content-Security-Policy"] = (
+            "sandbox allow-scripts allow-forms allow-pointer-lock; "
+            "default-src 'self' data: blob: https:; "
+            "script-src 'self' 'unsafe-inline' 'unsafe-eval' https:; "
+            "style-src 'self' 'unsafe-inline' https:; "
+            "img-src 'self' data: blob: https:; font-src 'self' data: https:; "
+            "connect-src 'self' https: wss:; media-src 'self' data: blob: https:; "
+            "object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'self'"
+        )
+    if HSTS_MAX_AGE_SEC and (ENABLE_HSTS or request.url.scheme == "https"):
+        response.headers["Strict-Transport-Security"] = f"max-age={HSTS_MAX_AGE_SEC}"
     return response
 
 # Concurrency + live session metrics
@@ -88,6 +141,32 @@ _metrics = {
 
 # Project tree cache
 _project_cache: dict[str, Any] = {"tree": None, "built_at": 0.0, "signature": None}
+_runner_start_windows: dict[str, deque] = {}
+
+
+def allow_runner_start(remote_ip: str) -> bool:
+    """Limit public server-side Python starts per client IP across sessions."""
+    current = time.monotonic()
+    window = _runner_start_windows.get(remote_ip)
+    if window is None:
+        window = deque()
+        _runner_start_windows[remote_ip] = window
+    while window and current - window[0] >= 3600:
+        window.popleft()
+    if window and current - window[-1] < RUNNER_START_COOLDOWN_SEC:
+        return False
+    if len(window) >= RUNNER_STARTS_PER_IP_PER_HOUR:
+        return False
+    window.append(current)
+    if len(_runner_start_windows) > 4096:
+        for key, old_window in list(_runner_start_windows.items()):
+            while old_window and current - old_window[0] >= 3600:
+                old_window.popleft()
+            if not old_window:
+                _runner_start_windows.pop(key, None)
+            if len(_runner_start_windows) <= 3072:
+                break
+    return True
 
 
 def _session_idle_state(
@@ -194,7 +273,7 @@ def _scan_projects_uncached() -> dict:
                     try:
                         with open(link_txt, "r", encoding="utf-8") as f:
                             url = f.read().strip()
-                        if url:
+                        if _safe_external_url(url):
                             projects.append({"name": project_name, "type": "external", "url": url})
                     except OSError:
                         pass
@@ -290,6 +369,140 @@ def _safe_project_path(*parts: str) -> Optional[str]:
     return abs_path
 
 
+def _resolve_python_project(class_name: str, student_name: str, project_name: str) -> str:
+    """Resolve only catalogued Python projects beneath their student's folder."""
+    student_projects = scan_projects().get(class_name, {}).get(student_name, [])
+    allowed = any(item["name"] == project_name and item["type"] == "python" for item in student_projects)
+    student_root = os.path.realpath(os.path.join(PROJECTS_DIR, class_name, student_name))
+    project_root = os.path.realpath(os.path.join(student_root, project_name))
+    if not allowed or os.path.commonpath((student_root, project_root)) != student_root:
+        raise FileNotFoundError("project is not a listed Python project")
+    main_file = os.path.join(project_root, "main.py")
+    if not os.path.isfile(main_file):
+        raise FileNotFoundError("project has no main.py")
+    return project_root
+
+
+def _safe_external_url(value: str) -> str:
+    """Only expose absolute HTTPS project links to browser navigation/iframes."""
+    value = value.strip()
+    try:
+        parsed = urlsplit(value)
+        if parsed.scheme == "https" and parsed.hostname and not parsed.username and not parsed.password:
+            return value
+    except ValueError:
+        pass
+    return ""
+
+
+def _stage_runner_project(source_root: str) -> tuple[str, str]:
+    """Copy regular project files into an ephemeral, per-run writable directory."""
+    session_root = tempfile.mkdtemp(prefix="run-", dir=RUNNER_TMP_DIR)
+    os.chmod(session_root, 0o700)
+    workspace = os.path.join(session_root, "project")
+    os.mkdir(workspace, 0o700)
+    total_bytes = 0
+    total_files = 0
+    ignored_dirs = {".git", ".venv", "venv", "__pycache__", "node_modules"}
+    for current, dirs, files in os.walk(source_root, followlinks=False):
+        dirs[:] = [name for name in dirs if name not in ignored_dirs and not os.path.islink(os.path.join(current, name))]
+        relative = os.path.relpath(current, source_root)
+        target_dir = workspace if relative == "." else os.path.join(workspace, relative)
+        if target_dir != workspace:
+            os.makedirs(target_dir, mode=0o700, exist_ok=True)
+        for name in files:
+            source = os.path.join(current, name)
+            try:
+                info = os.lstat(source)
+            except OSError:
+                continue
+            if not stat.S_ISREG(info.st_mode):
+                continue
+            lowered = name.casefold()
+            if lowered == ".env" or lowered.startswith(".env.") or lowered in {
+                "credentials.json", "service-account.json", "secrets.json", "token.txt",
+            }:
+                continue
+            total_files += 1
+            total_bytes += info.st_size
+            if total_files > RUNNER_PROJECT_FILE_LIMIT:
+                shutil.rmtree(session_root, ignore_errors=True)
+                raise ValueError(f"專案檔案數超過上限（{RUNNER_PROJECT_FILE_LIMIT} 個）")
+            if total_bytes > RUNNER_PROJECT_LIMIT_MB * 1024 * 1024:
+                shutil.rmtree(session_root, ignore_errors=True)
+                raise ValueError(f"專案資料超過執行上限（{RUNNER_PROJECT_LIMIT_MB} MB）")
+            destination = os.path.join(target_dir, name)
+            shutil.copyfile(source, destination)
+            os.chmod(destination, 0o600)
+        os.chmod(target_dir, 0o700)
+    if not os.path.isfile(os.path.join(workspace, "main.py")):
+        shutil.rmtree(session_root, ignore_errors=True)
+        raise FileNotFoundError("專案沒有可執行的 main.py")
+    return session_root, workspace
+
+
+def _runner_sandbox_command(workspace: str, socket_path: str) -> list[str]:
+    """Build a fail-closed bubblewrap command with no network or app secrets."""
+    if sys.platform != "linux" or not BWRAP_PATH or not PRLIMIT_PATH:
+        raise RuntimeError("伺服器缺少 Linux bubblewrap/prlimit，已拒絕未隔離執行。")
+
+    bwrap = [
+        BWRAP_PATH,
+        "--die-with-parent",
+        "--new-session",
+        "--unshare-user",
+        "--unshare-pid",
+        "--unshare-ipc",
+        "--unshare-net",
+        "--unshare-uts",
+        "--unshare-cgroup-try",
+        "--disable-userns",
+    ]
+    for system_path in ("/usr", "/lib", "/lib64", "/bin", "/sbin", "/etc", "/opt"):
+        if os.path.exists(system_path):
+            bwrap.extend(("--ro-bind", system_path, system_path))
+    bwrap.extend((
+        "--dev", "/dev",
+        "--proc", "/proc",
+        "--size", str(RUNNER_TMP_LIMIT_MB * 1024 * 1024),
+        "--tmpfs", "/tmp",
+        "--dir", "/workspace",
+        "--dir", "/workspace/project",
+        "--bind", workspace, "/workspace/project",
+        "--ro-bind", os.path.join(BASE_DIR, "runner.py"), "/runner.py",
+        "--ro-bind", MODELS_DIR, "/models",
+        "--ro-bind", os.path.dirname(socket_path), "/run-ipc",
+        "--clearenv",
+        "--setenv", "PATH", "/usr/local/bin:/usr/bin:/bin",
+        "--setenv", "HOME", "/tmp",
+        "--setenv", "LANG", "C.UTF-8",
+        "--setenv", "PYTHONNOUSERSITE", "1",
+        "--setenv", "PYTHONDONTWRITEBYTECODE", "1",
+        "--setenv", "SDL_VIDEODRIVER", "dummy",
+        "--setenv", "SDL_AUDIODRIVER", "dummy",
+        "--chdir", "/workspace/project",
+        "--",
+        sys.executable,
+        "/runner.py",
+        "--project_path", "/workspace/project/main.py",
+        "--socket-path", "/run-ipc/runner.sock",
+        "--models_dir", "/models",
+    ))
+    memory_bytes = RUNNER_MEMORY_LIMIT_MB * 1024 * 1024
+    file_bytes = 128 * 1024 * 1024
+    return [
+        PRLIMIT_PATH,
+        f"--cpu={RUNNER_CPU_LIMIT_SEC}:{RUNNER_CPU_LIMIT_SEC}",
+        f"--as={memory_bytes}:{memory_bytes}",
+        f"--fsize={file_bytes}:{file_bytes}",
+        "--nproc=64:64",
+        "--nofile=128:128",
+        "--core=0:0",
+        "--",
+        *bwrap,
+    ]
+
+
 # ---------------------------------------------------------------------------
 # Static / logo
 # ---------------------------------------------------------------------------
@@ -465,14 +678,17 @@ async def run_project_page(request: Request, student_token: str, project_name: s
         if os.path.exists(appetize_path):
             try:
                 with open(appetize_path, "r", encoding="utf-8") as f:
-                    appetize_key = f.read().strip()
+                    candidate_key = f.read().strip()
+                    if re.fullmatch(r"[A-Za-z0-9_-]{1,256}", candidate_key):
+                        appetize_key = candidate_key
             except OSError:
                 pass
     elif os.path.exists(os.path.join(proj_dir, "link.txt")):
-        proj_type = "external"
         try:
             with open(os.path.join(proj_dir, "link.txt"), "r", encoding="utf-8") as f:
-                external_url = f.read().strip()
+                external_url = _safe_external_url(f.read())
+            if external_url:
+                proj_type = "external"
         except OSError:
             pass
 
@@ -571,10 +787,9 @@ async def play_project_ws_internal(
         await websocket.close()
         return
 
-    project_path = os.path.join(
-        PROJECTS_DIR, real_class, real_student, project_name, "main.py"
-    )
-    if not os.path.exists(project_path):
+    try:
+        source_root = _resolve_python_project(real_class, real_student, project_name)
+    except (OSError, ValueError):
         await websocket.accept()
         await websocket.send_json(
             {"type": "log", "data": "錯誤: 找不到該專案的 main.py 檔案！\n"}
@@ -603,6 +818,17 @@ async def play_project_ws_internal(
         await websocket.close(code=1013)
         return
 
+    remote_ip = websocket.client.host if websocket.client else "unknown"
+    if not allow_runner_start(remote_ip):
+        runner_semaphore.release()
+        acquired = False
+        _metrics["sessions_rejected"] += 1
+        await websocket.accept()
+        await websocket.send_json({"type": "log", "data": "這個網路來源的專案啟動次數已達上限，請稍後再試。\n"})
+        await websocket.send_json({"type": "status", "data": "rate_limited"})
+        await websocket.close(code=4429, reason="runner start rate limited")
+        return
+
     await websocket.accept()
     session_id = f"{real_class}/{real_student}/{project_name}/{time.time():.0f}"
     started_at = time.time()
@@ -621,8 +847,9 @@ async def play_project_ws_internal(
         _metrics["sessions_started"] += 1
 
     process = None
-    tcp_server = None
+    ipc_server = None
     runner_writer = None
+    session_root = None
 
     try:
         connected_event = asyncio.Event()
@@ -634,20 +861,21 @@ async def play_project_ws_internal(
             runner_writer = writer
             connected_event.set()
 
-        tcp_server = await asyncio.start_server(handle_runner_conn, "127.0.0.1", 0)
-        tcp_port = tcp_server.sockets[0].getsockname()[1]
-
-        runner_script = os.path.join(BASE_DIR, "runner.py")
-        cmd = [
-            sys.executable,
-            runner_script,
-            "--project_path",
-            project_path,
-            "--port",
-            str(tcp_port),
-            "--models_dir",
-            MODELS_DIR,
-        ]
+        try:
+            session_root, workspace = _stage_runner_project(source_root)
+            ipc_dir = os.path.join(session_root, "ipc")
+            os.mkdir(ipc_dir, 0o700)
+            socket_path = os.path.join(ipc_dir, "runner.sock")
+            cmd = _runner_sandbox_command(workspace, socket_path)
+            ipc_server = await asyncio.start_unix_server(
+                handle_runner_conn, path=socket_path
+            )
+            os.chmod(socket_path, 0o600)
+        except (OSError, RuntimeError, ValueError) as exc:
+            log.warning("Refused to start unsandboxed runner: %s", exc)
+            await websocket.send_json({"type": "log", "data": f"安全執行環境無法啟動，已停止執行：{exc}\n"})
+            await websocket.send_json({"type": "status", "data": "error"})
+            return
 
         popen_kwargs: dict[str, Any] = {
             "stdout": subprocess.DEVNULL,
@@ -657,18 +885,13 @@ async def play_project_ws_internal(
             popen_kwargs["start_new_session"] = True
 
         process = await asyncio.create_subprocess_exec(*cmd, **popen_kwargs)
-        log.info(
-            "Started runner pid=%s session=%s port=%s",
-            process.pid,
-            session_id,
-            tcp_port,
-        )
+        log.info("Started sandboxed runner pid=%s session=%s", process.pid, session_id)
 
         try:
             await asyncio.wait_for(
                 connected_event.wait(), timeout=RUNNER_CONNECT_TIMEOUT_SEC
             )
-            log.info("Runner pid=%s connected via TCP", process.pid)
+            log.info("Runner pid=%s connected via private IPC", process.pid)
             await websocket.send_json(
                 {"type": "status", "data": "running"}
             )
@@ -680,9 +903,9 @@ async def play_project_ws_internal(
             )
         except asyncio.TimeoutError:
             _metrics["sessions_failed_connect"] += 1
-            log.error("Runner pid=%s connect timeout", process.pid)
+            log.error("Runner pid=%s sandbox IPC connect timeout; returncode=%s", process.pid, process.returncode)
             await websocket.send_json(
-                {"type": "log", "data": "伺服器錯誤: 執行模擬器連線超時！\n"}
+                {"type": "log", "data": "安全執行環境無法連線（可能是主機未啟用 Linux namespace）；已拒絕未隔離執行。\n"}
             )
             await websocket.send_json({"type": "status", "data": "error"})
             return
@@ -878,9 +1101,11 @@ async def play_project_ws_internal(
                 await runner_writer.wait_closed()
             except Exception:
                 pass
-        if tcp_server is not None:
-            tcp_server.close()
-            await tcp_server.wait_closed()
+        if ipc_server is not None:
+            ipc_server.close()
+            await ipc_server.wait_closed()
+        if session_root is not None:
+            shutil.rmtree(session_root, ignore_errors=True)
         try:
             await websocket.close()
         except Exception:

static/css/index.css

@@ -3,9 +3,9 @@
             --panel-bg: #111827;
             --border-color: #1f2937;
             --border-hover: #374151;
-            --primary: #6366f1;
-            --secondary: #0ea5e9;
-            --accent: #a855f7;
+            --primary: #f3b64a;
+            --secondary: #57b8a5;
+            --accent: #ef8068;
             --text-main: #f9fafb;
             --text-muted: #9ca3af;
         }
@@ -76,7 +76,7 @@
         }
 
         .brand-logo:hover .brand-name {
-            color: #818cf8;
+            color: var(--primary);
         }
 
         .nav-links {
@@ -120,7 +120,7 @@
         }
 
         .badge-top span {
-            color: #a5b4fc;
+            color: #f6ca78;
             font-weight: 600;
             font-size: 0.75rem;
             letter-spacing: 1px;
@@ -142,10 +142,8 @@
             }
         }
 
-        header h1 span.gradient-text {
-            background: linear-gradient(135deg, #6366f1 30%, #a855f7 90%);
-            -webkit-background-clip: text;
-            -webkit-text-fill-color: transparent;
+        header h1 span.headline-emphasis {
+            color: var(--primary);
         }
 
         header p {
@@ -166,7 +164,6 @@
             max-width: 1350px;
             width: calc(100% - 4rem);
             margin: 0 auto 2rem;
-            box-shadow: 0 10px 30px rgba(0, 0, 0, 0.2);
             display: flex;
             flex-direction: column;
             gap: 1rem;
@@ -182,7 +179,7 @@
             padding-bottom: 0.6rem;
         }
 
-        .generator-header h3 {
+        .generator-header h2 {
             font-size: 0.95rem;
             font-weight: 700;
             color: #ffffff;
@@ -257,7 +254,7 @@
 
         .result-group button {
             background: var(--primary);
-            color: #ffffff;
+            color: #17212b;
             border: none;
             padding: 0.7rem 1.5rem;
             border-radius: 12px;
@@ -302,7 +299,6 @@
             padding: 2rem;
             display: flex;
             flex-direction: column;
-            box-shadow: 0 15px 35px rgba(0, 0, 0, 0.25);
             transition: all 0.2s ease;
             height: 620px;
             overflow: hidden; /* Prevent parent scrolling */
@@ -387,16 +383,16 @@
             border-left-color: var(--primary);
         }
         #panel-classes .item-card.active {
-            background: rgba(99, 102, 241, 0.05);
-            border-color: rgba(99, 102, 241, 0.15);
+            background: rgba(243, 182, 74, 0.07);
+            border-color: rgba(243, 182, 74, 0.2);
         }
 
         #panel-students .item-card:hover, #panel-students .item-card.active {
             border-left-color: var(--accent);
         }
         #panel-students .item-card.active {
-            background: rgba(168, 85, 247, 0.05);
-            border-color: rgba(168, 85, 247, 0.15);
+            background: rgba(239, 128, 104, 0.07);
+            border-color: rgba(239, 128, 104, 0.2);
         }
 
         /* Project Cards */
@@ -421,7 +417,7 @@
 
         .project-card.hover-python:hover {
             border-left-color: var(--primary);
-            border-color: rgba(99, 102, 241, 0.15);
+            border-color: rgba(243, 182, 74, 0.2);
         }
 
         .project-card.hover-scratch:hover {
@@ -430,8 +426,8 @@
         }
 
         .project-card.hover-makecode:hover {
-            border-left-color: #0ea5e9;
-            border-color: rgba(14, 165, 233, 0.15);
+            border-left-color: var(--secondary);
+            border-color: rgba(87, 184, 165, 0.2);
         }
 
         .project-card.hover-html:hover {
@@ -440,8 +436,8 @@
         }
 
         .project-card.hover-apk:hover {
-            border-left-color: #a855f7;
-            border-color: rgba(168, 85, 247, 0.15);
+            border-left-color: var(--accent);
+            border-color: rgba(239, 128, 104, 0.2);
         }
 
         .project-meta {
@@ -469,9 +465,9 @@
         }
 
         .tag-python {
-            background: rgba(99, 102, 241, 0.08);
-            color: #a5b4fc;
-            border: 1px solid rgba(99, 102, 241, 0.15);
+            background: rgba(243, 182, 74, 0.1);
+            color: #f6ca78;
+            border: 1px solid rgba(243, 182, 74, 0.2);
         }
 
         .tag-scratch {
@@ -481,9 +477,9 @@
         }
 
         .tag-makecode {
-            background: rgba(14, 165, 233, 0.08);
-            color: #bae6fd;
-            border: 1px solid rgba(14, 165, 233, 0.15);
+            background: rgba(87, 184, 165, 0.1);
+            color: #a7e2d6;
+            border: 1px solid rgba(87, 184, 165, 0.2);
         }
 
         .tag-html {
@@ -493,9 +489,9 @@
         }
 
         .tag-apk {
-            background: rgba(168, 85, 247, 0.08);
-            color: #d8b4fe;
-            border: 1px solid rgba(168, 85, 247, 0.15);
+            background: rgba(239, 128, 104, 0.1);
+            color: #ffb9aa;
+            border: 1px solid rgba(239, 128, 104, 0.2);
         }
 
         /* Action launch button */
@@ -521,9 +517,10 @@
 
         .btn-launch-python {
             background: var(--primary);
+            color: #17212b;
         }
         .btn-launch-python:hover {
-            background: #4f46e5;
+            background: #dfa12f;
         }
 
         .btn-launch-scratch {
@@ -549,9 +546,10 @@
 
         .btn-launch-apk {
             background: var(--accent);
+            color: #17212b;
         }
         .btn-launch-apk:hover {
-            background: #9333ea;
+            background: #dc6e58;
         }
 
         /* Placeholder */
@@ -592,4 +590,3 @@
             z-index: 1;
             margin-top: auto;
         }
-    

static/css/player.css

@@ -3,9 +3,9 @@
             --panel-bg: #111827;
             --border-color: #1f2937;
             --border-hover: #374151;
-            --primary: #6366f1;
-            --secondary: #0ea5e9;
-            --accent: #a855f7;
+            --primary: #f3b64a;
+            --secondary: #57b8a5;
+            --accent: #ef8068;
             --text-main: #f9fafb;
             --text-muted: #9ca3af;
             --success: #10b981;
@@ -99,9 +99,8 @@
         }
 
         .project-path {
-            font-size: 0.72rem;
+            font-size: 0.75rem;
             color: var(--text-muted);
-            text-transform: uppercase;
             letter-spacing: 0.5px;
             font-weight: 600;
         }
@@ -118,11 +117,11 @@
             align-items: center;
             gap: 8px;
             font-size: 0.82rem;
-            background: rgba(16, 185, 129, 0.06);
-            color: var(--success);
+            background: rgba(243, 182, 74, 0.06);
+            color: var(--text-muted);
             padding: 0.35rem 0.9rem;
             border-radius: 30px;
-            border: 1px solid rgba(16, 185, 129, 0.15);
+            border: 1px solid rgba(243, 182, 74, 0.15);
             font-weight: 600;
         }
 
@@ -130,6 +129,20 @@
             width: 7px;
             height: 7px;
             border-radius: 50%;
+            background-color: #7d8798;
+        }
+
+        .status-connecting .status-dot {
+            background-color: var(--primary);
+        }
+
+        .status-running {
+            background: rgba(16, 185, 129, 0.06);
+            color: var(--success);
+            border-color: rgba(16, 185, 129, 0.15);
+        }
+
+        .status-running .status-dot {
             background-color: var(--success);
             animation: pulse 1.5s infinite;
         }
@@ -144,6 +157,12 @@
             animation: none;
         }
 
+        .status-idle {
+            background: rgba(255, 255, 255, 0.03);
+            color: var(--text-muted);
+            border-color: var(--border-color);
+        }
+
         /* Main Grid Wrapper */
         .main-container {
             display: grid;
@@ -237,8 +256,8 @@
         
         .focus-prompt.active {
             color: var(--secondary);
-            border-color: rgba(14, 165, 233, 0.3);
-            background: rgba(14, 165, 233, 0.05);
+            border-color: rgba(87, 184, 165, 0.3);
+            background: rgba(87, 184, 165, 0.05);
         }
 
         /* Right Panel styling */
@@ -290,7 +309,7 @@
         }
 
         .btn-webcam.active {
-            background: rgba(14, 165, 233, 0.06);
+            background: rgba(87, 184, 165, 0.06);
             border-color: var(--secondary);
             color: var(--secondary);
         }
@@ -318,7 +337,7 @@
 
         .btn-restart {
             background: var(--primary);
-            color: #fff;
+            color: #17212b;
         }
         .btn-restart:hover {
             opacity: 0.9;
@@ -330,7 +349,7 @@
             border: 1px solid rgba(239, 68, 68, 0.15);
         }
         .btn-stop:hover {
-            background: var(--danger);
+            background: #b91c1c;
             color: #fff;
         }
 
@@ -455,11 +474,12 @@
         /* APK Card Tag / Button */
         .btn-launch-apk {
             background: var(--accent) !important;
+            color: #17212b !important;
         }
         .btn-launch-apk:hover {
-            background: #9333ea !important;
+            background: #dc6e58 !important;
             transform: translateY(-1px);
-            box-shadow: 0 4px 12px rgba(168, 85, 247, 0.25);
+            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.28);
         }
 
         /* Smartphone Mockup Container */
@@ -534,7 +554,7 @@
 
         .phone-screen {
             flex-grow: 1;
-            background: linear-gradient(135deg, #1e1b4b 0%, #0f172a 100%);
+            background: linear-gradient(135deg, #2b271f 0%, #0f172a 100%);
             display: flex;
             flex-direction: column;
             align-items: center;
@@ -558,23 +578,21 @@
         .android-icon-wrapper {
             width: 80px;
             height: 80px;
-            background: rgba(168, 85, 247, 0.15);
-            border: 2px solid rgba(168, 85, 247, 0.3);
+            background: rgba(239, 128, 104, 0.15);
+            border: 2px solid rgba(239, 128, 104, 0.3);
             border-radius: 50%;
             display: flex;
             align-items: center;
             justify-content: center;
-            animation: pulse-glow 2s infinite ease-in-out;
+            animation: icon-breathe 2.4s ease-in-out infinite;
         }
 
-        @keyframes pulse-glow {
+        @keyframes icon-breathe {
             0%, 100% {
                 transform: scale(1);
-                box-shadow: 0 0 0 0 rgba(168, 85, 247, 0.4);
             }
             50% {
-                transform: scale(1.05);
-                box-shadow: 0 0 20px 5px rgba(168, 85, 247, 0.2);
+                transform: scale(1.035);
             }
         }
 
@@ -663,8 +681,8 @@
         }
 
         .guide-step-number {
-            background: rgba(168, 85, 247, 0.15);
-            color: #c084fc;
+            background: rgba(239, 128, 104, 0.15);
+            color: #ef8068;
             width: 22px;
             height: 22px;
             border-radius: 50%;
@@ -683,7 +701,7 @@
         }
 
         .guide-link {
-            color: #c084fc;
+            color: #ef8068;
             text-decoration: underline;
             transition: color 0.2s;
         }
@@ -722,8 +740,8 @@
 .loading-spinner {
     width: 36px;
     height: 36px;
-    border: 3px solid rgba(99, 102, 241, 0.2);
-    border-top-color: #6366f1;
+    border: 3px solid rgba(243, 182, 74, 0.2);
+    border-top-color: #f3b64a;
     border-radius: 50%;
     animation: telearn-spin 0.8s linear infinite;
 }
@@ -772,7 +790,7 @@
     width: min(420px, 100%);
     box-sizing: border-box;
     padding: 2rem;
-    border: 1px solid rgba(168, 85, 247, 0.35);
+    border: 0;
     border-radius: 20px;
     background: #111827;
     box-shadow: 0 24px 70px rgba(0, 0, 0, 0.5);
@@ -807,8 +825,8 @@
     padding: 0.85rem 1rem;
     border: 0;
     border-radius: 12px;
-    background: #7c3aed;
-    color: #fff;
+    background: var(--primary);
+    color: #17212b;
     font: inherit;
     font-weight: 700;
     cursor: pointer;
@@ -816,7 +834,7 @@
 
 .idle-dialog-card button:hover,
 .idle-dialog-card button:focus-visible {
-    background: #8b5cf6;
-    outline: 3px solid rgba(167, 139, 250, 0.35);
+    background: #dfa12f;
+    outline: 3px solid rgba(243, 182, 74, 0.45);
     outline-offset: 3px;
 }

static/js/index.js

@@ -177,10 +177,10 @@
             classes.forEach(cls => {
                 const card = document.createElement('div');
                 card.className = `item-card ${activeClass === cls ? 'active' : ''}`;
-                card.innerHTML = `
-                    <span>${cls}</span>
-                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M9 18l6-6-6-6"/></svg>
-                `;
+                const label = document.createElement('span');
+                label.textContent = cls;
+                card.append(label);
+                card.insertAdjacentHTML('beforeend', '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M9 18l6-6-6-6"/></svg>');
                 card.onclick = () => selectClass(cls);
                 classList.appendChild(card);
             });
@@ -216,10 +216,10 @@
             students.forEach(std => {
                 const card = document.createElement('div');
                 card.className = `item-card ${activeStudent === std ? 'active' : ''}`;
-                card.innerHTML = `
-                    <span>${std}</span>
-                    <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M9 18l6-6-6-6"/></svg>
-                `;
+                const label = document.createElement('span');
+                label.textContent = std;
+                card.append(label);
+                card.insertAdjacentHTML('beforeend', '<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M9 18l6-6-6-6"/></svg>');
                 card.onclick = () => selectStudent(std);
                 studentList.appendChild(card);
             });
@@ -288,16 +288,22 @@
 
                 const card = document.createElement('div');
                 card.className = `project-card ${hoverClass}`;
-                card.innerHTML = `
-                    <div class="project-meta">
-                        <span class="project-title">${proj.name}</span>
-                        <span class="project-tag ${tagClass}">${tagText}</span>
-                    </div>
-                    <button class="btn-launch ${btnClass}" onclick="launchProject('${proj.name}')">
-                        <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3.5"><path d="M5 3l14 9-14 9V3z"/></svg>
-                        啟動專題專區
-                    </button>
-                `;
+                const meta = document.createElement('div');
+                meta.className = 'project-meta';
+                const title = document.createElement('span');
+                title.className = 'project-title';
+                title.textContent = proj.name;
+                const tag = document.createElement('span');
+                tag.className = `project-tag ${tagClass}`;
+                tag.textContent = tagText;
+                meta.append(title, tag);
+                const launch = document.createElement('button');
+                launch.type = 'button';
+                launch.className = `btn-launch ${btnClass}`;
+                launch.insertAdjacentHTML('afterbegin', '<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3.5"><path d="M5 3l14 9-14 9V3z"/></svg>');
+                launch.append(document.createTextNode('啟動專題專區'));
+                launch.addEventListener('click', () => launchProject(proj.name));
+                card.append(meta, launch);
                 projectList.appendChild(card);
             });
         }
@@ -310,5 +316,5 @@
             window.open(url, '_blank');
         }
 
-        window.onload = fetchProjects;
-    
+        document.getElementById("btn-copy-url")?.addEventListener("click", copyGeneratedUrl);
+        window.addEventListener("load", fetchProjects, { once: true });

static/js/player.js

@@ -128,15 +128,24 @@
 
             if (projectType === "python") {
                 if (viewOnly) {
-                    statusWrapper.classList.add("status-stopped");
+                    statusWrapper.classList.remove("status-connecting");
+                    statusWrapper.classList.add("status-idle");
                     statusText.innerText = "僅供預覽";
                     document.getElementById("python-device-section").style.display = "none";
                     const img = document.createElement("div");
                     img.style.cssText = "color:#94a3b8;text-align:center;padding:2rem;max-width:28rem;line-height:1.6;";
-                    img.innerHTML = `<h3 style="color:#fff;margin-bottom:0.75rem;">${projectName}</h3>
-                        <p>班級：${className}<br>學生：${studentName}</p>
-                        <p style="margin-top:1rem;font-size:0.9rem;">此連結為「僅預覽」模式，不會在伺服器上執行程式。<br>
-                        若要實際操作，請使用不含 <code>?view=1</code> 的連結。</p>`;
+                    const title = document.createElement("h3");
+                    title.textContent = projectName;
+                    title.style.cssText = "color:#fff;margin-bottom:0.75rem;";
+                    const identity = document.createElement("p");
+                    identity.textContent = `班級：${className}｜學生：${studentName}`;
+                    const note = document.createElement("p");
+                    note.style.cssText = "margin-top:1rem;font-size:0.9rem;";
+                    note.append("此連結為「僅預覽」模式，不會在伺服器上執行程式。若要實際操作，請使用不含 ");
+                    const query = document.createElement("code");
+                    query.textContent = "?view=1";
+                    note.append(query, " 的連結。");
+                    img.append(title, identity, note);
                     viewportFrame.appendChild(img);
                     appendConsole("[系統] view=1 僅預覽模式，未啟動執行器。\n");
                 } else {
@@ -167,7 +176,10 @@
 
                 // Generate QR code
                 const qrUrl = `https://api.qrserver.com/v1/create-qr-code/?size=180x180&data=${encodeURIComponent(dlUrl)}`;
-                document.getElementById("apk-qr-image").src = qrUrl;
+                const apkQrImage = document.createElement("img");
+                apkQrImage.src = qrUrl;
+                apkQrImage.alt = "QR Code";
+                document.getElementById("apk-qr-image").replaceChildren(apkQrImage);
 
                 // Setup Phone mockup
                 viewportFrame.classList.add("iframe-mode");
@@ -205,26 +217,34 @@
                     const iframe = document.createElement("iframe");
                     iframe.className = "phone-screen-iframe";
                     iframe.src = `https://appetize.io/embed/${encodeURIComponent(appetizeKey)}?device=pixel4&scale=auto&autoplay=false&orientation=portrait&deviceColor=black`;
+                    iframe.referrerPolicy = "no-referrer";
                     screen.appendChild(iframe);
                 } else {
                     screen.innerHTML = `
                         <div class="android-icon-wrapper">
-                            <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="#c084fc" stroke-width="1.8">
+                            <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="#ef8068" stroke-width="1.8">
                                 <path d="M4 10v6m16-6v6M6 18c0 1.1.9 2 2 2h8c1.1 0 2-.9 2-2V9H6v9zm3-13l-1.5-2M15 5l1.5-2M9 13v.01M15 13v.01" stroke-linecap="round" stroke-linejoin="round"/>
                             </svg>
                         </div>
                         <div>
-                            <h4 style="font-weight: 800; font-size: 1.25rem; color: #ffffff; margin-bottom: 0.5rem; text-shadow: 0 2px 4px rgba(0,0,0,0.3);">${projectName}</h4>
+                            <h4 id="apk-project-title" style="font-weight: 800; font-size: 1.25rem; color: #ffffff; margin-bottom: 0.5rem; text-shadow: 0 2px 4px rgba(0,0,0,0.3);"></h4>
                             <p style="font-size: 0.8rem; color: rgba(255,255,255,0.7); line-height: 1.4; padding: 0 1rem;">本專案為 Android 應用程式</p>
                         </div>
                         <div style="background: rgba(0,0,0,0.2); border: 1px solid rgba(255,255,255,0.05); padding: 0.8rem; border-radius: 12px; width: 100%; box-sizing: border-box; display: flex; flex-direction: column; align-items: center; gap: 8px;">
                             <span style="font-size: 0.72rem; color: var(--text-muted); line-height: 1.3;">掃描此條碼以安裝至您的實體手機</span>
-                            <img src="${qrUrl}" alt="QR Code" style="width: 100px; height: 100px; border-radius: 6px; border: 4px solid #ffffff; display: block;" />
+                            <div id="apk-qr-slot"></div>
                         </div>
-                        <a href="${dlUrl}" class="btn-launch btn-launch-apk" style="text-decoration: none; width: 100%; font-size: 0.82rem;" download>
+                        <a id="apk-download-link" class="btn-launch btn-launch-apk" style="text-decoration: none; width: 100%; font-size: 0.82rem;" download>
                             下載 APK 安裝檔
                         </a>
                     `;
+                    screen.querySelector("#apk-project-title").textContent = projectName;
+                    const qrImage = document.createElement("img");
+                    qrImage.src = qrUrl;
+                    qrImage.alt = "QR Code";
+                    qrImage.style.cssText = "width:100px;height:100px;border-radius:6px;border:4px solid #fff;display:block;";
+                    screen.querySelector("#apk-qr-slot").append(qrImage);
+                    screen.querySelector("#apk-download-link").href = dlUrl;
                 }
                 phone.appendChild(screen);
                 viewportFrame.appendChild(phone);
@@ -237,7 +257,14 @@
                     helper.style.textAlign = "center";
                     helper.style.maxWidth = "320px";
                     helper.style.lineHeight = "1.5";
-                    helper.innerHTML = `⚠️ 因 Appetize.io 免費方案限制內嵌功能，若畫面顯示「未啟用內嵌」，請 <a href="https://appetize.io/app/${encodeURIComponent(appetizeKey)}" target="_blank" style="color: #c084fc; text-decoration: underline; font-weight: 600;">點此在新分頁中打開模擬器</a>。`;
+                    helper.append("⚠️ 因 Appetize.io 免費方案限制內嵌功能，若畫面顯示「未啟用內嵌」，請 ");
+                    const openAppetize = document.createElement("a");
+                    openAppetize.href = `https://appetize.io/app/${encodeURIComponent(appetizeKey)}`;
+                    openAppetize.target = "_blank";
+                    openAppetize.rel = "noopener noreferrer";
+                    openAppetize.textContent = "點此在新分頁中打開模擬器";
+                    openAppetize.style.cssText = "color:#ef8068;text-decoration:underline;font-weight:600;";
+                    helper.append(openAppetize, "。");
                     viewportFrame.appendChild(helper);
                 }
             } else {
@@ -251,7 +278,9 @@
                     viewportFrame.classList.add("iframe-mode");
                     const iframe = document.createElement("iframe");
                     iframe.className = "iframe-viewport";
-                    iframe.allow = "autoplay; fullscreen; microphone; camera";
+                    iframe.setAttribute("sandbox", "allow-scripts allow-forms allow-pointer-lock");
+                    iframe.referrerPolicy = "no-referrer";
+                    iframe.allow = "autoplay; fullscreen";
                     iframe.src = `/static_projects/${encodeURIComponent(studentToken)}/${encodeURIComponent(projectName)}/index.html`;
                     viewportFrame.appendChild(iframe);
                 } else if (projectType === "external") {
@@ -266,6 +295,7 @@
                         iframe.allow = "autoplay; fullscreen; gamepad";
                         iframe.setAttribute("allowfullscreen", "true");
                         iframe.setAttribute("credentialless", "");
+                        iframe.referrerPolicy = "no-referrer";
                         iframe.src = externalUrl;
                         viewportFrame.appendChild(iframe);
                         return;
@@ -304,7 +334,8 @@
             stopReason = null;
 
             socket.onopen = () => {
-                statusWrapper.classList.remove("status-stopped");
+                statusWrapper.classList.remove("status-stopped", "status-connecting", "status-idle");
+                statusWrapper.classList.add("status-running");
                 statusText.innerText = "已連線 (運作中)";
                 appendConsole("[系統] 連線成功，學生專案已啟動。\n");
                 appendConsole(`[系統] 閒置 ${Math.round(idleWarningSec/60)} 分鐘會提醒，${Math.round(idleTimeoutSec/60)} 分鐘後自動釋放名額。\n`);
@@ -337,11 +368,12 @@
                         } else if (data.type === "idle_resumed") {
                             hideIdleWarning();
                         } else if (data.type === "status") {
-                            if (["stopped", "timeout", "idle_timeout", "connection_timeout", "error", "busy"].includes(data.data)) {
+                            if (["stopped", "timeout", "idle_timeout", "connection_timeout", "error", "busy", "rate_limited"].includes(data.data)) {
                                 setStoppedStatus(data.data);
                                 setLoading(false);
                             } else if (data.data === "running") {
-                                statusWrapper.classList.remove("status-stopped");
+                                statusWrapper.classList.remove("status-stopped", "status-connecting", "status-idle");
+                                statusWrapper.classList.add("status-running");
                                 statusText.innerText = "已連線 (運作中)";
                             }
                         }
@@ -367,6 +399,7 @@
 
         function setStoppedStatus(reason) {
             if (reason) stopReason = reason;
+            statusWrapper.classList.remove("status-running", "status-connecting", "status-idle");
             statusWrapper.classList.add("status-stopped");
             const labels = {
                 stopped: "已停止",
@@ -374,7 +407,8 @@
                 idle_timeout: "閒置結束",
                 connection_timeout: "連線已離開",
                 error: "錯誤",
-                busy: "名額已滿"
+                busy: "名額已滿",
+                rate_limited: "啟動太頻繁"
             };
             statusText.innerText = labels[reason] || "已停止";
             stopWebcamStream();
@@ -596,6 +630,10 @@
         }
 
         window.onload = initViewport;
+        document.getElementById("btn-back")?.addEventListener("click", () => window.close());
+        document.getElementById("btn-restart")?.addEventListener("click", restartProject);
+        document.getElementById("btn-stop")?.addEventListener("click", stopProjectElegant);
+        document.getElementById("btn-clear-console")?.addEventListener("click", clearConsole);
         setupActivityTracking();
         window.onbeforeunload = () => {
             stopWebcamStream();

templates/index.html

@@ -27,10 +27,10 @@
     <!-- Top Banner -->
     <header>
         <div class="badge-top">
-            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="color: #a5b4fc; margin-right: 8px;"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/><path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/></svg>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="color: #f3b64a; margin-right: 8px;"><path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/><path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/></svg>
             <span>學生創意專案展示場</span>
         </div>
-        <h1>發揮程式創意<br><span class="gradient-text">展現無限可能</span></h1>
+        <h1>發揮程式創意<br><span class="headline-emphasis">展現無限可能</span></h1>
         <p>得能教育學生成果展示場，匯集了學生們的邏輯程式設計、趣味互動遊戲與多元網頁創作成果。</p>
     </header>
 
@@ -38,8 +38,8 @@
     {% if not restrict_class and not restrict_student %}
     <div class="link-generator-panel" id="link-generator">
         <div class="generator-header">
-            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="color: #a5b4fc;"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>
-            <h3 style="margin-left: 8px;">分享連結產生器</h3>
+            <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="color: #f3b64a;"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>
+            <h2 style="margin-left: 8px;">分享連結產生器</h2>
         </div>
         <div class="generator-body">
             <div class="select-group">
@@ -56,7 +56,7 @@
             </div>
             <div class="result-group">
                 <input type="text" id="gen-url-result" readonly />
-                <button id="btn-copy-url" onclick="copyGeneratedUrl()">複製連結</button>
+                <button id="btn-copy-url">複製連結</button>
             </div>
         </div>
     </div>
@@ -108,7 +108,7 @@
         <p>&copy; 2026 得能教育 Telearn Education. All rights reserved.</p>
     </footer>
 
-    <script>
+    <script nonce="{{ request.state.csp_nonce }}">
         window.TELEARN_INDEX = {
             restrictClass: {{ restrict_class|tojson }},
             restrictStudent: {{ restrict_student|tojson }}

templates/player.html

@@ -17,7 +17,7 @@
                 <img src="/images/logo-light.png" alt="Telearn Logo" class="logo-img" />
                 <span class="brand-name">Telearn 得能教育</span>
             </a>
-            <button class="btn-back" onclick="window.close()">
+            <button class="btn-back" id="btn-back">
                 <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M19 12H5M12 19l-7-7 7-7"/></svg>
                 返回大廳
             </button>
@@ -27,7 +27,7 @@
             </div>
         </div>
 
-        <div class="status-wrapper" id="server-status">
+        <div class="status-wrapper status-connecting" id="server-status">
             <div class="status-dot"></div>
             <span id="status-text">連線中...</span>
         </div>
@@ -66,11 +66,11 @@
                 </button>
 
                 <div class="action-buttons">
-                    <button class="btn-action btn-restart" onclick="restartProject()">
+                    <button class="btn-action btn-restart" id="btn-restart">
                         <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><path d="M21.5 2v6h-6M21.34 15.57a10 10 0 1 1-.57-8.38l5.67-5.67"/></svg>
                         重設
                     </button>
-                    <button class="btn-action btn-stop" onclick="stopProjectElegant()">
+                    <button class="btn-action btn-stop" id="btn-stop">
                         <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3"><rect x="3" y="3" width="18" height="18" rx="2" ry="2"/></svg>
                         終止
                     </button>
@@ -80,7 +80,7 @@
             <div class="terminal-section" id="python-terminal-section">
                 <div class="terminal-header-bar">
                     <h3 class="device-title">終端機日誌</h3>
-                    <button class="btn-clear" onclick="clearConsole()">清除</button>
+                    <button class="btn-clear" id="btn-clear-console">清除</button>
                 </div>
                 <div class="terminal-box" id="console-logs"></div>
                 <div class="terminal-input-wrapper">
@@ -94,7 +94,7 @@
                 <div style="display: flex; flex-direction: column; gap: 1rem;">
                     <h3 class="device-title">Android APK 專案</h3>
                     <div class="apk-download-card">
-                        <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="#a855f7" stroke-width="1.5">
+                        <svg width="40" height="40" viewBox="0 0 24 24" fill="none" stroke="#ef8068" stroke-width="1.5">
                             <path d="M12 2v16m0 0l-4-4m4 4l4-4M4 22h16" stroke-linecap="round" stroke-linejoin="round"/>
                         </svg>
                         <div class="apk-info-text">
@@ -111,7 +111,7 @@
                 <div class="qr-section">
                     <h3 class="device-title">掃描二維碼安裝</h3>
                     <div class="qr-code-wrapper">
-                        <img id="apk-qr-image" src="" alt="QR Code" />
+                        <div id="apk-qr-image"></div>
                     </div>
                     <span class="qr-tip">使用 Android 裝置掃描此條碼，即可直接下載並安裝此應用程式</span>
                 </div>
@@ -149,7 +149,7 @@
     <video id="webcam-video" autoplay playsinline width="640" height="480"></video>
     <canvas id="webcam-canvas" width="640" height="480"></canvas>
 
-    <script>
+    <script nonce="{{ request.state.csp_nonce }}">
         window.TELEARN_PLAYER = {
             className: {{ class_name|tojson }},
             studentName: {{ student_name|tojson }},

tests/test_classroom.py

@@ -16,7 +16,11 @@ class ClassroomServiceTests(unittest.TestCase):
         classroom.RUNTIME = Path(self.temp_dir.name)
         classroom.DB = classroom.RUNTIME / "classroom.sqlite3"
         classroom.live.clear()
+        classroom._student_connection_windows.clear()
+        classroom._student_message_windows.clear()
         classroom.init_db()
+        with classroom.lock, classroom.sqlite3.connect(classroom.DB) as db:
+            db.execute("INSERT OR IGNORE INTO classroom_courses VALUES(?,?,?)", ("L6A", "2026 Fall 進階專題", 0))
 
     def tearDown(self):
         self.temp_dir.cleanup()
@@ -71,12 +75,13 @@ class ClassroomServiceTests(unittest.TestCase):
         with zipfile.ZipFile(io.BytesIO(classroom.make_zip("L6A", "week02"))) as archive:
             self.assertEqual(archive.namelist(), [])
 
-    def test_bootstrap_keeps_new_checkpoint_ahead_of_legacy_repair(self):
+    def test_bootstrap_preserves_checkpoint_separately_from_later_repair(self):
         classroom.init_db()
         loaded = classroom.load("L6Sat", "李合盛", "李合盛", "week02")
 
-        self.assertEqual(loaded["files"], loaded["checkpoint_files"])
-        self.assertNotEqual(loaded["files"], loaded["final_files"])
+        repaired = (classroom.REPAIRS / "L6Sat" / "week02" / "李合盛.py").read_text(encoding="utf-8")
+        self.assertEqual(loaded["files"]["main.py"], repaired)
+        self.assertNotEqual(loaded["files"], loaded["checkpoint_files"])
         matching = [
             item
             for item in classroom.version_history("L6Sat", "李合盛")
@@ -84,6 +89,7 @@ class ClassroomServiceTests(unittest.TestCase):
             and item["submitted_at"] == loaded["checkpoint_at"]
         ]
         self.assertEqual(len(matching), 1)
+        self.assertEqual(matching[0]["files"], loaded["checkpoint_files"])
 
     def test_progress_picker_lists_every_checkpoint_and_submission_newest_first(self):
         state = classroom.empty("L6A", "student-1", "Alex", "week02")
@@ -173,6 +179,119 @@ class ClassroomServiceTests(unittest.TestCase):
         self.assertEqual(classroom.snapshot("L6A", "week01"), [])
         self.assertEqual(classroom.snapshot("L6A", "week02"), [])
 
+    def test_teacher_can_rename_student_without_changing_identity_or_work(self):
+        old_password, old_token = classroom.PASSWORD, classroom.TOKEN
+        try:
+            classroom.PASSWORD = "teacher-test"
+            classroom.TOKEN = ""
+            state = classroom.empty("L6A", "student-1", "舊姓名", "week02")
+            state["project_name"] = "校園謎案"
+            state["files"] = {"main.py": 'print("目前進度")\n'}
+            state["checkpoint_files"] = dict(state["files"])
+            state["checkpoint_at"] = 100
+            state["final_files"] = {"main.py": 'print("正式提交")\n'}
+            state["submitted_at"] = 200
+            classroom.record_version(state, "checkpoint")
+            classroom.record_version(state, "submit")
+            classroom.save(state)
+
+            request = classroom.StudentUpdate(
+                class_code="L6A", student_id="student-1",
+                display_name="新姓名", password="teacher-test",
+            )
+            result = asyncio.run(classroom.update_student(request))
+            self.assertTrue(result["ok"])
+            self.assertEqual(result["student_id"], "student-1")
+
+            member = classroom.catalog()["courses"]
+            course = next(item for item in member if item["class_code"] == "L6A")
+            self.assertEqual(course["students"], [{"student_id": "student-1", "display_name": "新姓名"}])
+            restored = classroom.load("L6A", "student-1", "新姓名", "week02")
+            self.assertEqual(restored["files"], state["files"])
+            self.assertEqual(restored["final_files"], state["final_files"])
+            submitted = next(item for item in classroom.submission_catalog() if item["class_code"] == "L6A")
+            self.assertEqual(submitted["display_name"], "新姓名")
+            with classroom.sqlite3.connect(classroom.DB) as db:
+                names = db.execute(
+                    "SELECT DISTINCT display_name FROM classroom_versions WHERE class_code=? AND student_id=?",
+                    ("L6A", "student-1"),
+                ).fetchall()
+            self.assertEqual(names, [("新姓名",)])
+            classroom.init_db()
+            submitted = next(item for item in classroom.submission_catalog() if item["class_code"] == "L6A")
+            self.assertEqual(submitted["display_name"], "新姓名")
+        finally:
+            classroom.PASSWORD, classroom.TOKEN = old_password, old_token
+
+    def test_teacher_cannot_rename_student_to_an_existing_name(self):
+        old_password, old_token = classroom.PASSWORD, classroom.TOKEN
+        try:
+            classroom.PASSWORD = "teacher-test"
+            classroom.TOKEN = ""
+            classroom.save(classroom.empty("L6A", "student-1", "Alex", "week02"))
+            classroom.save(classroom.empty("L6A", "student-2", "Sam", "week02"))
+            request = classroom.StudentUpdate(
+                class_code="L6A", student_id="student-1",
+                display_name=" sam ", password="teacher-test",
+            )
+            with self.assertRaises(classroom.HTTPException) as error:
+                asyncio.run(classroom.update_student(request))
+            self.assertEqual(error.exception.status_code, 409)
+            self.assertEqual(
+                classroom.find_member("L6A", "Alex", "student-1")["display_name"],
+                "Alex",
+            )
+        finally:
+            classroom.PASSWORD, classroom.TOKEN = old_password, old_token
+
+    def test_current_roster_name_wins_over_older_snapshot_names_on_startup(self):
+        old_paths = classroom.DATA, classroom.TEMPLATES, classroom.CHECKPOINTS, classroom.VERSIONS, classroom.REPAIRS
+        data = Path(self.temp_dir.name) / "seeded-classroom-data"
+        submission_root = data / "submissions" / "C1" / "student-1"
+        version_root = data / "versions" / "C1" / "student-1" / "week02"
+        submission_root.mkdir(parents=True)
+        version_root.mkdir(parents=True)
+        (data / "classes.json").write_text(json.dumps([{
+            "code": "C1", "name": "測試班",
+            "students": [{"student_id": "student-1", "display_name": "新姓名"}],
+        }], ensure_ascii=False), encoding="utf-8")
+        files = {"main.py": 'print("保留作品")\n'}
+        old_submission = {
+            "class_code": "C1", "student_id": "student-1", "display_name": "舊姓名",
+            "week_id": "week02", "project_name": "校園謎案", "submitted_at": 100, "files": files,
+        }
+        old_version = {
+            "class_code": "C1", "student_id": "student-1", "display_name": "舊姓名",
+            "week_id": "week02", "version_id": "100-submit-one", "kind": "submit",
+            "project_name": "校園謎案", "created_at": 100, "files": files,
+        }
+        (submission_root / "week02.json").write_text(json.dumps(old_submission, ensure_ascii=False), encoding="utf-8")
+        (version_root / "100-submit-one.json").write_text(json.dumps(old_version, ensure_ascii=False), encoding="utf-8")
+        try:
+            classroom.DATA = data
+            classroom.TEMPLATES = data / "templates"
+            classroom.CHECKPOINTS = data / "checkpoints"
+            classroom.VERSIONS = data / "versions"
+            classroom.REPAIRS = data / "repairs"
+            classroom.init_db()
+
+            course = next(item for item in classroom.catalog()["courses"] if item["class_code"] == "C1")
+            self.assertEqual(course["students"], [{"student_id": "student-1", "display_name": "新姓名"}])
+            current_submission = next(
+                item for item in classroom.submission_catalog()
+                if item["class_code"] == "C1"
+            )
+            self.assertEqual(current_submission["display_name"], "新姓名")
+            with classroom.sqlite3.connect(classroom.DB) as db:
+                version_name = db.execute(
+                    "SELECT display_name FROM classroom_versions WHERE class_code='C1' AND student_id='student-1'"
+                ).fetchone()[0]
+            self.assertEqual(version_name, "新姓名")
+            restored = classroom.load("C1", "student-1", "新姓名", "week02")
+            self.assertEqual(restored["final_files"], files)
+        finally:
+            classroom.DATA, classroom.TEMPLATES, classroom.CHECKPOINTS, classroom.VERSIONS, classroom.REPAIRS = old_paths
+
     def test_course_is_available_even_when_repo_persistence_is_unavailable(self):
         old_password, old_token = classroom.PASSWORD, classroom.TOKEN
         try:
@@ -240,7 +359,7 @@ class ClassroomServiceTests(unittest.TestCase):
         course = next(item for item in classroom.catalog()["courses"] if item["class_code"] == "L6Sat")
         submissions = [item for item in classroom.submission_catalog() if item["class_code"] == "L6Sat"]
         self.assertEqual(len(course["students"]), 8)
-        self.assertEqual(len(submissions), 7)
+        self.assertEqual(len(submissions), 8)
         restored = classroom.get_submission("L6Sat", "胡惟媗", "week02")
         self.assertEqual(restored["project_name"], "校園謎案調查局")
         self.assertEqual(set(restored["final_files"]), {"main.py", "case_data.json"})
@@ -276,6 +395,69 @@ class ClassroomServiceTests(unittest.TestCase):
         self.assertEqual(progress[0]["source"], "published")
         self.assertIn("已發布", progress[0]["files"]["main.py"])
 
+    def test_version_write_rate_limit_is_persisted_per_student_and_lesson(self):
+        old_limit, old_cooldown = classroom.CHECKPOINTS_PER_HOUR, classroom.VERSION_WRITE_COOLDOWN_MS
+        try:
+            classroom.CHECKPOINTS_PER_HOUR = 1
+            classroom.VERSION_WRITE_COOLDOWN_MS = 0
+            classroom.consume_version_write("L6A", "student-1", "week02", "checkpoint")
+            with self.assertRaises(classroom.VersionLimitError):
+                classroom.consume_version_write("L6A", "student-1", "week02", "checkpoint")
+            classroom.consume_version_write("L6A", "student-2", "week02", "checkpoint")
+        finally:
+            classroom.CHECKPOINTS_PER_HOUR, classroom.VERSION_WRITE_COOLDOWN_MS = old_limit, old_cooldown
+
+    def test_version_retention_prunes_only_oldest_versions_of_same_kind(self):
+        old_limit = classroom.MAX_VERSIONS_PER_KIND
+        try:
+            classroom.MAX_VERSIONS_PER_KIND = 2
+            state = classroom.empty("L6A", "student-1", "Alex", "week02")
+            for stamp in (100, 200, 300):
+                state["files"] = {"main.py": f"print({stamp})\n"}
+                state["checkpoint_files"] = dict(state["files"])
+                state["checkpoint_at"] = stamp
+                classroom.record_version(state, "checkpoint")
+            state["final_files"] = {"main.py": "print('submission')\n"}
+            state["submitted_at"] = 400
+            classroom.record_version(state, "submit")
+        finally:
+            classroom.MAX_VERSIONS_PER_KIND = old_limit
+
+        history = classroom.version_history("L6A", "student-1")
+        checkpoints = [item for item in history if item["source"] == "checkpoint"]
+        submissions = [item for item in history if item["source"] == "submit"]
+        self.assertEqual([item["submitted_at"] for item in checkpoints], [300, 200])
+        self.assertEqual(len(submissions), 1)
+
+    def test_course_quota_rejects_before_inserting_version(self):
+        old_quota = classroom.COURSE_STORAGE_QUOTA_BYTES
+        try:
+            classroom.COURSE_STORAGE_QUOTA_BYTES = 1
+            state = classroom.empty("L6A", "student-1", "Alex", "week02")
+            state["files"] = {"main.py": "print('too large')\n"}
+            state["checkpoint_files"] = dict(state["files"])
+            state["checkpoint_at"] = 123
+            with self.assertRaises(classroom.VersionLimitError):
+                classroom.record_version(state, "checkpoint")
+        finally:
+            classroom.COURSE_STORAGE_QUOTA_BYTES = old_quota
+        self.assertEqual(classroom.version_history("L6A", "student-1"), [])
+
+    def test_websocket_connection_and_message_budgets_are_shared_across_reconnects(self):
+        old_connections, old_messages = classroom.STUDENT_WS_CONNECTIONS_PER_MINUTE, classroom.STUDENT_WS_MESSAGES_PER_MINUTE
+        try:
+            classroom.STUDENT_WS_CONNECTIONS_PER_MINUTE = 2
+            classroom.STUDENT_WS_MESSAGES_PER_MINUTE = 2
+            self.assertTrue(classroom.allow_student_connection("198.51.100.7"))
+            self.assertTrue(classroom.allow_student_connection("198.51.100.7"))
+            self.assertFalse(classroom.allow_student_connection("198.51.100.7"))
+            key = ("L6A", "student-1", "week02")
+            self.assertTrue(classroom.allow_student_message(key))
+            self.assertTrue(classroom.allow_student_message(key))
+            self.assertFalse(classroom.allow_student_message(key))
+        finally:
+            classroom.STUDENT_WS_CONNECTIONS_PER_MINUTE, classroom.STUDENT_WS_MESSAGES_PER_MINUTE = old_connections, old_messages
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_security.py

@@ -0,0 +1,58 @@
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+import server
+
+
+class ServerSecurityTests(unittest.TestCase):
+    def setUp(self):
+        server._runner_start_windows.clear()
+
+    def test_only_absolute_https_links_are_exposed(self):
+        self.assertEqual(server._safe_external_url("https://arcade.makecode.com/_abc"), "https://arcade.makecode.com/_abc")
+        self.assertEqual(server._safe_external_url("javascript:alert(1)"), "")
+        self.assertEqual(server._safe_external_url("https://user:pass@example.com/"), "")
+        self.assertEqual(server._safe_external_url("http://example.com/"), "")
+
+    def test_public_runner_starts_are_limited_per_ip(self):
+        old_limit, old_cooldown = server.RUNNER_STARTS_PER_IP_PER_HOUR, server.RUNNER_START_COOLDOWN_SEC
+        try:
+            server.RUNNER_STARTS_PER_IP_PER_HOUR = 2
+            server.RUNNER_START_COOLDOWN_SEC = 0.5
+            with patch("server.time.monotonic", side_effect=[100, 101, 102, 103]):
+                self.assertTrue(server.allow_runner_start("198.51.100.8"))
+                self.assertTrue(server.allow_runner_start("198.51.100.8"))
+                self.assertFalse(server.allow_runner_start("198.51.100.8"))
+                self.assertTrue(server.allow_runner_start("198.51.100.9"))
+        finally:
+            server.RUNNER_STARTS_PER_IP_PER_HOUR = old_limit
+            server.RUNNER_START_COOLDOWN_SEC = old_cooldown
+
+    def test_runner_staging_skips_credentials_but_keeps_unrelated_named_files(self):
+        with tempfile.TemporaryDirectory() as source_temp, tempfile.TemporaryDirectory() as scratch_temp:
+            source = Path(source_temp)
+            (source / "main.py").write_text("print('ok')\n", encoding="utf-8")
+            (source / ".env").write_text("HF_TOKEN=should-not-copy\n", encoding="utf-8")
+            (source / "credentials.json").write_text("{}", encoding="utf-8")
+            (source / "secret_notes.py").write_text("NOTE = 'ordinary project file'\n", encoding="utf-8")
+            with patch.object(server, "RUNNER_TMP_DIR", scratch_temp):
+                session_root, workspace = server._stage_runner_project(str(source))
+            try:
+                self.assertTrue((Path(workspace) / "main.py").is_file())
+                self.assertTrue((Path(workspace) / "secret_notes.py").is_file())
+                self.assertFalse((Path(workspace) / ".env").exists())
+                self.assertFalse((Path(workspace) / "credentials.json").exists())
+            finally:
+                import shutil
+                shutil.rmtree(session_root, ignore_errors=True)
+
+    def test_sandbox_refuses_non_linux_execution(self):
+        with patch.object(server.sys, "platform", "darwin"):
+            with self.assertRaisesRegex(RuntimeError, "拒絕未隔離執行"):
+                server._runner_sandbox_command("/tmp/project", "/tmp/session/runner.sock")
+
+
+if __name__ == "__main__":
+    unittest.main()