add embed query parameter for practice quiz (elearning v2025)

rschlaefli · rschlaefli · commit 9ea766295f4d · 2026-01-24T17:32:10.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,124 @@
+# AGENTS.md
+
+This repository is a **pnpm + Turborepo monorepo** for **KlickerUZH v3**.
+
+## Repo layout
+
+- `apps/*` — deployable apps/services (frontends, backend services, Azure Functions)
+- `packages/*` — shared libraries (e.g. `graphql`, `prisma`, `util`)
+- `cypress/` — end-to-end tests
+
+## Tooling / prerequisites
+
+- **Node.js 20** (see `package.json` `engines` / `volta`)
+- **pnpm 10.x** (repo is pinned to `pnpm@10.15.0`)
+
+## Common commands (run from repo root)
+
+- Install dependencies: `pnpm install`
+- Format: `pnpm run format` / Check: `pnpm run format:check`
+- Lint: `pnpm run lint`
+- Typecheck (CI-style): `pnpm run check`
+- Build: `pnpm run build`
+
+## Running a single workspace
+
+Use filters:
+
+- `pnpm --filter <workspace> <script>` (example: `pnpm --filter @klicker-uzh/graphql build`)
+
+## Dev notes
+
+Some dev scripts load secrets via `./util/_run_with_infisical.sh` (e.g. `pnpm run dev`). Avoid starting long-running dev servers or anything requiring credentials unless explicitly requested.
+
+## Apps & URLs
+
+Local development uses Traefik to route `*.klicker.com` hostnames to apps running on the host (see `util/traefik/rules_docker.yaml` / `util/traefik/rules_wsl.yaml`).
+
+| URL                                         | App / code                                  | Local port | Notes                            |
+| ------------------------------------------- | ------------------------------------------- | ---------: | -------------------------------- |
+| https://pwa.klicker.com                     | Student PWA (`apps/frontend-pwa`)           |       3001 |                                  |
+| https://manage.klicker.com                  | Lecturer UI (`apps/frontend-manage`)        |       3002 |                                  |
+| https://control.klicker.com                 | Mobile controller (`apps/frontend-control`) |       3003 |                                  |
+| https://chat.klicker.com                    | Chat UI (`apps/chat`)                       |       3004 |                                  |
+| https://auth.klicker.com                    | Auth UI (`apps/auth`)                       |       3010 |                                  |
+| https://api.klicker.com                     | Backend / GraphQL (`apps/backend-docker`)   |       3000 | GraphQL endpoint: `/api/graphql` |
+| https://assessment.klicker.com              | Assessment PWA (same service as PWA)        |       3001 |                                  |
+| https://assessment-api.klicker.com          | Assessment API (same service as API)        |       3000 |                                  |
+| https://response-api.klicker.com            | Response API (`apps/response-api`)          |       7078 |                                  |
+| https://response-api-assessment.klicker.com | Response API (assessment)                   |       7078 |                                  |
+
+If Traefik is not used, the apps are still reachable directly via `http://localhost:<port>`, but the `*.klicker.com` domains better mirror production cookie/domain behavior.
+
+## Factory skills (AI assistance)
+
+This repo includes Factory skills under `.factory/skills/` (mirrored in `.github/skills/`).
+
+- `agent-browser` — browser automation for UI verification (see `.factory/skills/agent-browser/SKILL.md`).
+- `web-design-guidelines` — UI/UX/accessibility review (see `.factory/skills/web-design-guidelines/SKILL.md`).
+- `vercel-react-best-practices` — React/Next performance guidance (see `.factory/skills/vercel-react-best-practices/SKILL.md`).
+
+### Using agent-browser to verify changes
+
+Use `agent-browser` when changes affect browser behavior and need real UI validation, especially:
+
+- Auth/login/redirect/cookie-domain changes
+- UI/UX changes (layout, navigation, forms)
+- Cross-app flows (e.g. manage ↔ auth, pwa ↔ auth)
+- Browser-only behavior (localStorage, service worker/PWA, media queries)
+
+**Screenshots are required** (snapshots alone miss visual regressions). Take a screenshot before and after the action you’re verifying and review it with the `Read` tool.
+
+Prereqs: the app is running locally in **dev mode** and the database is **seeded**.
+
+If `agent-browser` is missing entirely:
+
+```bash
+npm i -g agent-browser
+```
+
+If the browser executable is missing on a new machine, run once:
+
+```bash
+agent-browser install
+```
+
+For automated runs, **do not use Edu-ID** (it will not work with `agent-browser`). Always use **Delegated login**:
+
+- Username: `lecturer`
+- Password: `abcd`
+
+For Student PWA testing in local seeded dev environments, you can log in with the seeded participants (see `packages/prisma-data/src/data/seedTEST.ts`):
+
+- Usernames: `testuser1`–`testuser50` (enrolled in course **Testkurs**)
+- Password: `abcdabcd`
+
+Additional seeded participants exist (`testuser51`–`testuser52`), but they are not enrolled in any course by default.
+
+### Example: delegated login (Manage)
+
+Note: on the first screen, **“Delegated Access” is disabled until the Terms checkbox is checked**.
+
+```bash
+agent-browser open https://manage.klicker.com
+agent-browser screenshot /tmp/klicker-manage-01.png --full
+agent-browser snapshot -i -c
+
+# 1) Check the Terms checkbox (if needed)
+# 2) Click “Delegated Access”
+# 3) Fill username/password and submit
+# (Use the @e* refs from the latest snapshot output)
+
+agent-browser wait --load domcontentloaded
+agent-browser screenshot /tmp/klicker-manage-02.png --full
+agent-browser get url
+agent-browser close
+```
+
+These credentials are intended for local seeded dev environments only.
+
+## Change hygiene
+
+- Keep changes small and follow existing patterns in the touched app/package.
+- Don’t add/update dependencies (or churn lockfiles) unless required for the task.
+- Never commit secrets (tokens, `.env` files, credentials).
diff --git a/apps/frontend-pwa/src/components/Layout.tsx b/apps/frontend-pwa/src/components/Layout.tsx
@@ -15,6 +15,7 @@ import MobileMenuBar from './common/MobileMenuBar'
 interface LayoutProps {
   children?: React.ReactNode
   displayName?: string
+  embedded?: boolean
   course?:
     | Partial<Omit<Course, 'awards' | 'owner' | 'groupActivities'>>
     | (Omit<StudentCourse, 'owner'> & { owner: { shortname: string } })
@@ -36,6 +37,7 @@ interface LayoutProps {
 function Layout({
   children,
   displayName = 'KlickerUZH',
+  embedded = false,
   course,
   mobileMenuItems,
   setActiveMobilePage,
@@ -45,6 +47,7 @@ function Layout({
   const { data: dataParticipant } = useQuery(SelfDocument, {
     variables: { liveQuizId },
     fetchPolicy: 'cache-and-network',
+    skip: embedded,
   })
 
   const pageInFrame =
@@ -70,40 +73,45 @@ function Layout({
         ></meta>
       </Head>
 
-      <div className={twMerge('flex-none', className?.header)}>
-        <Header
-          participant={
-            dataParticipant?.self &&
-            (dataParticipant.self.role === UserRole.Participant || liveQuizId)
-              ? dataParticipant.self
-              : undefined
-          }
-          title={displayName}
-          course={course}
-          liveQuizId={liveQuizId}
-        />
-      </div>
+      {!embedded && (
+        <div className={twMerge('flex-none', className?.header)}>
+          <Header
+            participant={
+              dataParticipant?.self &&
+              (dataParticipant.self.role === UserRole.Participant || liveQuizId)
+                ? dataParticipant.self
+                : undefined
+            }
+            title={displayName}
+            course={course}
+            liveQuizId={liveQuizId}
+          />
+        </div>
+      )}
 
       <div
         className={twMerge(
-          'flex min-h-0 flex-1 flex-col overflow-y-auto p-4',
-          pageInFrame && 'px-0',
+          'flex min-h-0 flex-1 flex-col overflow-y-auto',
+          embedded ? 'p-0' : 'p-4',
+          !embedded && pageInFrame && 'px-0',
           className?.body
         )}
       >
         {children}
       </div>
 
-      <div className="flex-none md:hidden">
-        <MobileMenuBar
-          menuItems={mobileMenuItems}
-          onClick={(value) => setActiveMobilePage?.(value as any)}
-          participantMissing={
-            !dataParticipant?.self ||
-            dataParticipant.self.role === UserRole.TemporaryParticipant
-          }
-        />
-      </div>
+      {!embedded && (
+        <div className="flex-none md:hidden">
+          <MobileMenuBar
+            menuItems={mobileMenuItems}
+            onClick={(value) => setActiveMobilePage?.(value as any)}
+            participantMissing={
+              !dataParticipant?.self ||
+              dataParticipant.self.role === UserRole.TemporaryParticipant
+            }
+          />
+        </div>
+      )}
     </>
   )
 }
diff --git a/apps/frontend-pwa/src/components/practiceQuiz/PracticeQuiz.tsx b/apps/frontend-pwa/src/components/practiceQuiz/PracticeQuiz.tsx
@@ -41,6 +41,7 @@ interface PracticeQuizProps {
   currentIx: number
   setCurrentIx: (ix: number) => void
   handleNextElement: () => void
+  onAllStacksCompletion?: () => void
   showResetLocalStorage?: boolean
   previewOnly?: boolean
 }
@@ -50,6 +51,7 @@ function PracticeQuiz({
   currentIx,
   setCurrentIx,
   handleNextElement,
+  onAllStacksCompletion,
   showResetLocalStorage = false,
   previewOnly = false,
 }: PracticeQuizProps) {
@@ -60,6 +62,16 @@ function PracticeQuiz({
     skip: previewOnly,
   })
 
+  const handleAllStacksCompletion = () => {
+    if (onAllStacksCompletion) {
+      onAllStacksCompletion()
+      return
+    }
+
+    // TODO: re-introduce summary page for practice quiz
+    router.push(`/`)
+  }
+
   const [progressState, setProgressState] = useLocalStorage<
     Record<
       string,
@@ -173,10 +185,7 @@ function PracticeQuiz({
               !!dataParticipant?.self &&
               dataParticipant.self.role !== UserRole.TemporaryParticipant
             }
-            onAllStacksCompletion={() =>
-              // TODO: re-introduce summary page for practice quiz
-              router.push(`/`)
-            }
+            onAllStacksCompletion={handleAllStacksCompletion}
             bookmarks={bookmarksData?.getBookmarksPracticeQuiz}
             previewOnly={previewOnly}
           />
diff --git a/apps/frontend-pwa/src/pages/course/[courseId]/practiceQuizzes/[id].tsx b/apps/frontend-pwa/src/pages/course/[courseId]/practiceQuizzes/[id].tsx
@@ -22,11 +22,13 @@ function PracticeQuizPage({
   id,
   participantToken,
   cookiesAvailable,
+  embedded,
 }: {
   courseId: string
   id: string
   participantToken?: string
   cookiesAvailable?: boolean
+  embedded: boolean
 }) {
   const t = useTranslations()
   const [currentIx, setCurrentIx] = useState(-1)
@@ -42,14 +44,14 @@ function PracticeQuizPage({
 
   if (loading)
     return (
-      <Layout>
+      <Layout embedded={embedded}>
         <Loader />
       </Layout>
     )
 
   if (!data?.practiceQuiz) {
     return (
-      <Layout>
+      <Layout embedded={embedded}>
         <UserNotification
           type="error"
           message={t('pwa.practiceQuiz.notFound')}
@@ -59,7 +61,9 @@ function PracticeQuizPage({
   }
 
   if (error) {
-    return <Layout>{t('shared.generic.systemError')}</Layout>
+    return (
+      <Layout embedded={embedded}>{t('shared.generic.systemError')}</Layout>
+    )
   }
 
   // show notification with activity start date
@@ -69,6 +73,7 @@ function PracticeQuizPage({
   ) {
     return (
       <Layout
+        embedded={embedded}
         displayName={data.practiceQuiz.displayName}
         course={data.practiceQuiz.course ?? undefined}
       >
@@ -92,6 +97,7 @@ function PracticeQuizPage({
 
   return (
     <Layout
+      embedded={embedded}
       displayName={data.practiceQuiz.displayName}
       course={data.practiceQuiz.course ?? undefined}
     >
@@ -104,11 +110,20 @@ function PracticeQuizPage({
         currentIx={currentIx}
         setCurrentIx={setCurrentIx}
         handleNextElement={handleNextQuestion}
+        onAllStacksCompletion={
+          embedded
+            ? () => {
+                setCurrentIx(-1)
+              }
+            : undefined
+        }
         previewOnly={data.practiceQuiz.isOwner ?? undefined}
       />
-      <Footer
-        browserLink={`${process.env.NEXT_PUBLIC_PWA_URL}/course/${courseId}/practiceQuizzes/${id}`}
-      />
+      {!embedded && (
+        <Footer
+          browserLink={`${process.env.NEXT_PUBLIC_PWA_URL}/course/${courseId}/practiceQuizzes/${id}`}
+        />
+      )}
     </Layout>
   )
 }
@@ -129,6 +144,10 @@ export async function getServerSideProps(ctx: GetServerSidePropsContext) {
 
     const apolloClient = initializeApollo()
 
+    const embedParam = ctx.query.embed
+    const embedValue = Array.isArray(embedParam) ? embedParam[0] : embedParam
+    const embedded = embedValue === 'true' || embedValue === '1'
+
     const { participantToken, cookiesAvailable } = await getParticipantToken({
       apolloClient,
       courseId: ctx.params.courseId,
@@ -142,6 +161,7 @@ export async function getServerSideProps(ctx: GetServerSidePropsContext) {
           cookiesAvailable,
           id: ctx.params.id,
           courseId: ctx.params.courseId,
+          embedded,
           messages: (await import(`@klicker-uzh/i18n/messages/${ctx.locale}`))
             .default,
         },
@@ -152,6 +172,7 @@ export async function getServerSideProps(ctx: GetServerSidePropsContext) {
       props: {
         id: ctx.params.id,
         courseId: ctx.params.courseId,
+        embedded,
         messages: (await import(`@klicker-uzh/i18n/messages/${ctx.locale}`))
           .default,
       },
