feat(escape-room): ship generalized quiz mode

.agents/skills/klicker-environment-doctor/SKILL.md

@@ -73,6 +73,8 @@ devrouter exec . -- tail -n 50 /tmp/dev.log
 
 `devrouter doctor --repo .` provides static diagnostics. `devrouter ensure .` resolves the checkout-specific overlay and is the authoritative runtime proof.
 
+If LiveQuiz submissions return HTTP 404 while the response API health check is green, verify that `NEXT_PUBLIC_ADD_RESPONSE_URL` ends in `/AddResponse`. The response API host root accepts GET health checks only; the PWA must POST to `/AddResponse` in primary, workspace, and plain-localhost modes.
+
 ### Path B: Host-based Setup
 
 Manually boot the compose infrastructure:

.agents/skills/klicker-playwright-e2e/SKILL.md

@@ -58,6 +58,8 @@ volta run pnpm --filter @klicker-uzh/playwright exec playwright test --project=c
 volta run pnpm --filter @klicker-uzh/playwright test -- --project=chromium
 ```
 
+For a linked DevPod behind devrouter, run Playwright inside the exact application container and keep every URL on the same workspace suffix. The config accepts `PLAYWRIGHT_BROWSER_EXECUTABLE_PATH` when Chromium is installed outside Playwright's normal cache flow and `PLAYWRIGHT_HOST_RESOLVER_RULES` to map the namespaced `*.localhost` hosts to devrouter's `devnet` IP. Pass matching `URL_MANAGE`, `URL_STUDENT`, `URL_STUDENT_LOGIN`, `URL_API`, `URL_AUTH`, `APP_ORIGIN_AUTH`, and `COOKIE_DOMAIN` values; a primary-host redirect from a namespaced test is an environment mismatch, not a missing selector.
+
 For live quiz answer submission, response processing, scheduled microlearnings, or Hatchet workflow failures, start the missing services explicitly:
 
 ```bash
@@ -76,6 +78,7 @@ Ensure the response processor is not running with `ASSESSMENT_MODE=true` when va
 - Sudden Firefox/WebKit execution: Playwright is running all configured projects. Pass `--project=chromium` or keep non-Chromium projects commented in config if Chromium-only is desired.
 - UI mode does not automatically mean tests execute; prefer CLI runs for verification and use UI mode only for interactive debugging.
 - A passing `CLEANUP` followed by immediate failures often means frontend apps or auth URLs are unavailable after setup.
+- A failure screenshot on `auth.klicker.localhost` during a namespaced run means the frontend was compiled without the workspace-specific public auth URL. Restart that exact app with the post-start environment before changing locators.
 
 Before blaming a test, probe the apps:
 

.devcontainer/README.md

@@ -160,7 +160,10 @@ analytics image and lint CI so the root quality gate runs inside the container.
 - `node_modules` is a named volume (pnpm hoists natives into the root
   `node_modules/.pnpm`, so one root volume covers the monorepo).
 - Reset the DB: `pnpm --filter @klicker-uzh/prisma exec prisma migrate reset --skip-seed --force`.
-- `response-api` + both workers run `tsx --watch --env-file=.env`; node 24 errors
-  if `.env` is missing, so `post-create` seeds an **empty** `.env` in each dir
-  (the container env from `devcontainer.env` is what actually applies).
+- `response-api` runs `tsx --watch`; the Hatchet workers build with Rollup and
+  run the emitted JavaScript under nodemon. Hatchet's heartbeat worker threads
+  are incompatible with in-process watch loaders. Node 24 errors if an
+  `--env-file` is missing, so `post-create` seeds an **empty** `.env` in each
+  directory (the container env from `devcontainer.env` is what actually
+  applies).
 - Tier 3 (`chat`) needs an upstream LLM key: set `UPSTREAM_OPENAI_API_KEY`.

.devcontainer/devcontainer.env

@@ -74,7 +74,7 @@ NEXT_PUBLIC_MANAGE_URL=https://manage.klicker.localhost
 NEXT_PUBLIC_PWA_URL=https://pwa.klicker.localhost
 NEXT_PUBLIC_ASSESSMENT_URL=https://pwa.klicker.localhost
 NEXT_PUBLIC_CONTROL_URL=https://control.klicker.localhost
-NEXT_PUBLIC_ADD_RESPONSE_URL=https://response-api.klicker.localhost
+NEXT_PUBLIC_ADD_RESPONSE_URL=https://response-api.klicker.localhost/AddResponse
 
 # --- SSR app->app stays intra-container (bypasses devrouter, no cross-host TLS) ---
 API_URL_SSR=http://localhost:3000/api/graphql

.devcontainer/post-start.sh

@@ -34,7 +34,7 @@ if [ ! -s /etc/devrouter/mkcert-rootCA.pem ]; then
   export NEXT_PUBLIC_PWA_URL=http://localhost:3001
   export NEXT_PUBLIC_ASSESSMENT_URL=http://localhost:3001
   export NEXT_PUBLIC_CONTROL_URL=http://localhost:3003
-  export NEXT_PUBLIC_ADD_RESPONSE_URL=http://localhost:7078
+  export NEXT_PUBLIC_ADD_RESPONSE_URL=http://localhost:7078/AddResponse
   export NEXT_PUBLIC_CHAT_URL=http://localhost:3004
   export CORS_ALLOWED_ORIGINS=http://localhost:3001
   export NODE_EXTRA_CA_CERTS=""
@@ -58,7 +58,7 @@ elif [ -n "${WORKSPACE:-}" ]; then
   export NEXT_PUBLIC_PWA_URL=https://pwa.klicker.${WORKSPACE}.localhost
   export NEXT_PUBLIC_ASSESSMENT_URL=https://pwa.klicker.${WORKSPACE}.localhost
   export NEXT_PUBLIC_CONTROL_URL=https://control.klicker.${WORKSPACE}.localhost
-  export NEXT_PUBLIC_ADD_RESPONSE_URL=https://response-api.klicker.${WORKSPACE}.localhost
+  export NEXT_PUBLIC_ADD_RESPONSE_URL=https://response-api.klicker.${WORKSPACE}.localhost/AddResponse
   export CORS_ALLOWED_ORIGINS=https://pwa.klicker.${WORKSPACE}.localhost
   export AUTH_LECTURER_ALLOWED_HOSTS=manage.klicker.${WORKSPACE}.localhost,127.0.0.1:3002
   export AUTH_STUDENT_ALLOWED_HOSTS=pwa.klicker.${WORKSPACE}.localhost,127.0.0.1:3001

apps/analytics/prisma/schema/element.prisma

@@ -16,6 +16,7 @@ enum ElementType {
   FLASHCARD
   SELECTION
   CASE_STUDY
+  QR_SCAN
 }
 
 model Element {
@@ -40,6 +41,10 @@ model Element {
   status ElementStatus @default(READY)
   type   ElementType
 
+  // Opaque authoring/print secret for QR_SCAN elements. It is deliberately
+  // stored outside the participant-facing elementData JSON snapshot.
+  qrScanCode String? @unique
+
   tags Tag[]
 
   elementInstances ElementInstance[]
@@ -205,6 +210,9 @@ model ElementBlock {
   liveQuizId       String     @db.Uuid
   activeInLiveQuiz LiveQuiz[] @relation(name: "ActiveElementBlock")
 
+  escapeRoomConfig   EscapeRoomConfig?
+  escapeRoomAttempts EscapeRoomAttempt[]
+
   createdAt DateTime @default(now())
   updatedAt DateTime @updatedAt
 

apps/analytics/prisma/schema/participant.prisma

@@ -86,6 +86,7 @@ model Participant {
   participantCourseAnalytics      ParticipantCourseAnalytics[]
   participantActivityPerformances ParticipantActivityPerformance[]
   coursePerformances              ParticipantPerformance[]
+  escapeRoomAttempts              EscapeRoomAttempt[]
   groupAssignmentPoolEntries      GroupAssignmentPoolEntry[]
   messages                        GroupMessage[]
   chatThreads                     ChatThread[]
@@ -112,6 +113,7 @@ model ParticipantGroup {
 
   participants    Participant[]
   groupActivities GroupActivityInstance[]
+  escapeRoomAttempts EscapeRoomAttempt[]
   awards          AwardEntry[]
   achievements    GroupAchievementInstance[]
   messages        GroupMessage[]

apps/analytics/prisma/schema/quiz.prisma

@@ -40,6 +40,9 @@ model PracticeQuiz {
   isAssessmentEnabled   Boolean @default(false)
   isDeleted             Boolean @default(false)
 
+  escapeRoomConfig      EscapeRoomConfig?
+  escapeRoomAttempts    EscapeRoomAttempt[]
+
   stacks ElementStack[]
 
   responses               QuestionResponse[]
@@ -167,6 +170,9 @@ model MicroLearning {
   isAssessmentEnabled      Boolean @default(false)
   isDeleted                Boolean @default(false)
 
+  escapeRoomConfig      EscapeRoomConfig?
+  escapeRoomAttempts    EscapeRoomAttempt[]
+
   areInstancesOutdated Boolean @default(false) // flag to indicate if the any instances in this microlearning are outdated due to changes in the corresponding element
 
   stacks ElementStack[]
@@ -277,6 +283,9 @@ model GroupActivity {
   isAssessmentEnabled   Boolean @default(false)
   isDeleted             Boolean @default(false)
 
+  escapeRoomConfig      EscapeRoomConfig?
+  escapeRoomAttempts    EscapeRoomAttempt[]
+
   stacks ElementStack[]
 
   parameters        GroupActivityParameter[]
@@ -463,3 +472,71 @@ view UserActivities {
 }
 
 // #endregion
+
+enum EscapeRoomStatus {
+  IN_PROGRESS
+  COMPLETED
+  EXPIRED
+}
+
+model EscapeRoomConfig {
+  id             String  @id @default(uuid()) @db.Uuid
+  timeLimit      Int
+  hintPenalty    Int     @default(30)
+  lockoutSeconds Int     @default(5)
+  introText      String?
+
+  practiceQuiz   PracticeQuiz?  @relation(fields: [practiceQuizId], references: [id], onDelete: Cascade)
+  practiceQuizId String?        @unique @db.Uuid
+
+  microLearning   MicroLearning? @relation(fields: [microLearningId], references: [id], onDelete: Cascade)
+  microLearningId String?        @unique @db.Uuid
+
+  groupActivity   GroupActivity? @relation(fields: [groupActivityId], references: [id], onDelete: Cascade)
+  groupActivityId String?        @unique @db.Uuid
+
+  elementBlock    ElementBlock?  @relation(fields: [elementBlockId], references: [id], onDelete: Cascade)
+  elementBlockId  Int?           @unique
+}
+
+model EscapeRoomAttempt {
+  id String @id @default(uuid()) @db.Uuid
+
+  startedAt      DateTime         @default(now())
+  timeLimit      Int
+  penaltySeconds Int              @default(0)
+  hintsUsed      Json             @default("[]") // Store used hint IDs/keys
+  status         EscapeRoomStatus @default(IN_PROGRESS)
+  completedAt    DateTime?
+  lockoutUntil   DateTime?
+
+  // Set once the prune job has processed this finished attempt for retention.
+  // Response/instance statistics are owned by submission/event-time paths;
+  // completed/expired attempts remain the replay-integrity record until stale.
+  statsAggregatedAt DateTime?
+
+  // Individual Play (PracticeQuiz / MicroLearning / LiveQuiz block)
+  participant   Participant? @relation(fields: [participantId], references: [id], onDelete: Cascade)
+  participantId String?      @db.Uuid
+
+  // Group Play (GroupActivity)
+  group   ParticipantGroup? @relation(fields: [groupId], references: [id], onDelete: Cascade)
+  groupId String?           @db.Uuid
+
+  practiceQuiz   PracticeQuiz? @relation(fields: [practiceQuizId], references: [id], onDelete: Cascade)
+  practiceQuizId String?       @db.Uuid
+
+  microLearning   MicroLearning? @relation(fields: [microLearningId], references: [id], onDelete: Cascade)
+  microLearningId String?        @db.Uuid
+
+  groupActivity   GroupActivity? @relation(fields: [groupActivityId], references: [id], onDelete: Cascade)
+  groupActivityId String?        @db.Uuid
+
+  elementBlock    ElementBlock?  @relation(fields: [elementBlockId], references: [id], onDelete: Cascade)
+  elementBlockId  Int?
+
+  @@unique([participantId, practiceQuizId])
+  @@unique([participantId, microLearningId])
+  @@unique([groupId, groupActivityId])
+  @@unique([participantId, elementBlockId])
+}

apps/docs/docs/student_tutorials/escape_room.mdx

@@ -0,0 +1,41 @@
+---
+title: Escape Room
+---
+
+## What Is an Escape Room?
+
+An Escape Room is a timed challenge available in four activity types: Practice Quiz, Microlearning, Group Activity, and Live Quiz. Practice Quiz and Microlearning present questions in ordered stacks. Live Quiz runs the challenge question by question inside a single block. Group Activity gives the whole group one shared challenge to complete together.
+
+For a full overview of how lecturers set up Escape Rooms, see the [lecturer tutorial](/tutorials/escape_room).
+
+## Before Starting
+
+Students must be logged in and enrolled in the course before accessing an Escape Room. Group Activity Escape Rooms additionally require group membership. Live Quiz Escape Rooms require a regular participant account; temporary participation is not eligible.
+
+The activity may display introductory text before the attempt begins; reading that introduction does not start the timer. The countdown begins only when the student (or, in a Group Activity, any group member) selects **Start Attempt**.
+
+:::warning One attempt only – and the timer keeps running
+Each logged-in participant has exactly one attempt in Practice Quiz, Microlearning, and Live Quiz Escape Room blocks. In a Group Activity, the group shares a single attempt. The timer continues across browser closes, connection losses, and page reloads; it does not pause or reset. Plan accordingly before selecting **Start Attempt**.
+:::
+
+## Working Through the Challenge
+
+In Practice Quiz and Microlearning, questions are grouped into ordered stacks – a stack may contain more than one question, and the next stack unlocks only after every question in the current stack is answered correctly. In a Live Quiz Escape Room, questions progress one at a time within the block; the next question unlocks after the current answer is correct. In a Group Activity, the complete set of questions is visible from the start and all answers are submitted together when the group is ready.
+
+A wrong submission does not reset progress – the current question or shared task stays open, and a short lockout applies before another attempt can be made.
+
+If the lecturer added a hint to a question, a **Reveal hint** button appears. Selecting it deducts the corresponding number of seconds from the remaining time and displays the hint. Hints that have already been revealed are restored on reload.
+
+Reloading restores server-recorded progress. The timer keeps running during a reload, so there is no benefit to refreshing mid-attempt.
+
+## QR Scan Stages
+
+Some stages require scanning a QR code at a physical station in the room. To scan, select **Scan QR code** and grant camera access when prompted. If the camera is unavailable or if permission is denied, select **Enter code manually** instead – each station has its own code printed beside its QR code. Decoy stations may appear in the room; only the code from the real station advances the stage. Entering a decoy station's code is treated as a wrong answer and triggers the same lockout period as any other incorrect submission.
+
+## Group Activity: One Attempt, Shared by All
+
+The Group Activity Escape Room gives every group member access to the full set of questions from the start. Answers, revealed hints, any lockout period, and completion are shared across the group. Any group member may submit the shared answer set when the group is ready. Group members cannot reset the shared attempt themselves; a lecturer reset restores access to the entire group.
+
+## Completion and Results
+
+After completing an Escape Room, the result screen shows the escape time, hints used, and total penalty. If time expires, staged modes additionally show which stages were cleared. Group Activity has no cleared-stage data; the result reports the shared challenge outcome instead. Results are final unless a lecturer resets the attempt.