feat(debrief): make debrief page customizable via batch config (#1214)

* feat(debrief): make debrief page customizable via batch config (#1008)

Add a required `debrief` field to batch config that accepts a path to a
markdown file or "none". Custom markdown is fetched from CDN and rendered
on the final page; "none" shows a generic thank-you message.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(debrief): address Copilot review feedback

- Use `=== undefined` instead of falsy check for loading guard
- Handle `useText` error state (fall back to generic message)
- Show inline loading for debrief section instead of full-page Loading
- Use nullish coalescing (`??`) so empty markdown files render correctly
- Replace `waitForFunction(() => true)` with `expect.poll()` in tests
- Update DEBRIEF-007 test to verify exit code visible during debrief load

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: JamesPHoughton

client/src/intro-exit/Debrief.jsx

@@ -1,25 +1,34 @@
 /*
 Debrief page:
-States research purpose, includes CSSLab contact information
+Shows custom or generic debrief content, exit code, and close prompt.
 */
 
 import React, { useEffect } from "react";
 import { usePlayer } from "@empirica/core/player/classic/react";
-import { Loading } from "@empirica/core/player/react";
+import { useGlobal, Loading } from "@empirica/core/player/react";
 import { Markdown } from "../components/Markdown";
+import { useText } from "../components/hooks";
 import { useIdleContext } from "../components/IdleProvider";
 import { Button } from "../components/Button";
 
 export function Debrief() {
   const player = usePlayer();
+  const globals = useGlobal();
   const { setAllowIdle } = useIdleContext();
 
+  const batchConfig = globals?.get("recruitingBatchConfig");
+  const debriefPath =
+    batchConfig?.debrief && batchConfig.debrief !== "none"
+      ? batchConfig.debrief
+      : null;
+  const { text: debriefText, error: debriefError } = useText({
+    file: debriefPath,
+  });
+
   useEffect(() => {
-    // Set allowIdle to true when the component loads
     setAllowIdle(true);
     console.log("Set Allow Idle");
 
-    // Reset allowIdle to false when the component unloads
     return () => {
       setAllowIdle(false);
       console.log("Clear Allow Idle");
@@ -31,6 +40,11 @@ export function Debrief() {
   }
 
   const exitCodes = player.get("exitCodes");
+  const debriefLoading =
+    debriefPath && debriefText === undefined && !debriefError;
+  const debriefContent = debriefPath
+    ? debriefText ?? "Thank you for participating."
+    : "Thank you for participating.";
 
   const copyToClipboard = () => {
     navigator.clipboard.writeText(exitCodes.complete);
@@ -40,16 +54,6 @@ export function Debrief() {
     );
   };
 
-  const debriefStatements = `
-### About this study
-_Social scientists have tested different ways to improve small group conversations, like using a facilitator, setting an agenda, or creating ground rules. While some methods work better than others, it’s challenging to know which will be the most effective. What we do know is that different types of conversations need different kinds of support._
-
-_Instead of looking for one solution that works for all conversations, our research team is mapping out what helps each specific type of conversation. Your participation in this study provides valuable data that, combined with data from other discussions, will help us understand how the context of a discussion shapes its outcomes._
-
-_For any additional questions, please contact the University of Pennsylvania research team by 
-emailing **[deliberation-study@wharton.upenn.edu](mailto:deliberation-study@wharton.upenn.edu)**._
-`;
-
   return (
     <div className="grid justify-center">
       <h1>
@@ -78,7 +82,7 @@ emailing **[deliberation-study@wharton.upenn.edu](mailto:deliberation-study@whar
         </div>
       )}
 
-      <Markdown text={debriefStatements} />
+      {debriefLoading ? <Loading /> : <Markdown text={debriefContent} />}
 
       <h3>You may now close this window.</h3>
     </div>

cypress/e2e/00_Naked_URL.js

@@ -13,6 +13,7 @@ const configJson = `{
   "customIdInstructions": "none",
   "platformConsent": "US",
   "consentAddendum": "none",
+  "debrief": "none",
   "checkAudio": false,
   "checkVideo": false,
   "introSequence": "none",

cypress/e2e/01_Normal_Paths_Omnibus.js

@@ -17,6 +17,7 @@ describe(
         "customIdInstructions": {"MyId":"projects/example/customIdInstructions.md", "default":"projects/example/defaultIdInstructions.md"},
         "platformConsent": "US",
         "consentAddendum": "projects/example/consentAddendum.md",
+        "debrief": "projects/example/testDebrief.md",
         "checkAudio": true,
         "checkVideo": true,
         "introSequence": "cypress_intro",
@@ -940,6 +941,19 @@ describe(
         }
       );
 
+      // Verify custom debrief content from testDebrief.md is rendered
+      cy.get(`[data-player-id="${playerKeys[0]}"]`).contains(
+        "custom debrief message for testing purposes"
+      );
+      cy.get(`[data-player-id="${playerKeys[0]}"]`).contains(
+        "You may now close this window."
+      );
+      // Verify old hardcoded debrief text is NOT present
+      cy.get(`[data-player-id="${playerKeys[0]}"]`).should(
+        "not.contain",
+        "Social scientists have tested different ways"
+      );
+
       // wait for data to be saved (should be fast)
       cy.wait(3000);
 

cypress/e2e/02_Batch_Canceled.js

@@ -7,6 +7,7 @@ const configJsonA = `{
   "customIdInstructions": "none",
   "platformConsent": "US",
   "consentAddendum": "none",
+  "debrief": "none",
   "checkVideo": true,
   "checkAudio": true,
   "introSequence": "none",
@@ -46,6 +47,7 @@ const configJsonB = `{
   "customIdInstructions": {"MyId":"projects/example/customIdInstructions.md", "default":"projects/example/defaultIdInstructions.md"},
   "platformConsent": "US",
   "consentAddendum": "none",
+  "debrief": "none",
   "checkVideo": true,
   "checkAudio": true,
   "treatments": [

cypress/e2e/03_Text_Chat.js

@@ -13,6 +13,7 @@ describe(
         "customIdInstructions": "none",
         "platformConsent": "US",
         "consentAddendum": "none",
+        "debrief": "none",
         "checkAudio": false,
         "checkVideo": false,
         "introSequence": "none",

cypress/e2e/05_Mobile_Check.js

@@ -9,6 +9,7 @@ const configJson = `{
   "customIdInstructions": "none",
   "platformConsent": "US",
   "consentAddendum": "none",
+  "debrief": "none",
   "checkAudio": false,
   "checkVideo": false,
   "introSequence": "none",

cypress/e2e/06_Many_Games.js

@@ -5,6 +5,7 @@ const configJson = `{
   "customIdInstructions": "none",
   "platformConsent": "UK",
   "consentAddendum": "none",
+  "debrief": "none",
   "checkAudio": true,
   "checkVideo": true,
   "introSequence": "none",

cypress/e2e/07_Returning_Player.js

@@ -10,6 +10,7 @@ describe("Returning Player", { retries: { runMode: 2, openMode: 0 } }, () => {
       "customIdInstructions": "none",
       "platformConsent": "US",
       "consentAddendum": "none",
+      "debrief": "none",
       "checkAudio": false,
       "checkVideo": false,
       "introSequence": "none",

cypress/e2e/08_Invalid_configs.js

@@ -11,6 +11,7 @@ describe("Returning Player", { retries: { runMode: 2, openMode: 0 } }, () => {
       "customIdInstructions": "none",
       "platformConsent": "US",
       "consentAddendum": "none",
+      "debrief": "none",
       "checkAudio": true,
       "checkVideo": true,
       "introSequence": "none",
@@ -99,6 +100,7 @@ describe("Returning Player", { retries: { runMode: 2, openMode: 0 } }, () => {
       "customIdInstructions": "none",
       "platformConsent": "US",
       "consentAddendum": "none",
+      "debrief": "none",
       "checkAudio": false,
       "checkVideo": false,
       "introSequence": "none",

cypress/e2e/09_Many_Players.js

@@ -5,6 +5,7 @@ const configJson = `{
     "customIdInstructions": "none",
     "platformConsent": "US",
     "consentAddendum": "none",
+    "debrief": "none",
     "checkAudio": false,
     "checkVideo": false,
     "introSequence": "none",