Add more details

jaykim1213 · jaykim1213 · commit 8d3f9a828ff8 · 2026-05-07T09:26:41.000-06:00
diff --git a/docs/tutorial/config.json.md b/docs/tutorial/config.json.md
@@ -48,8 +48,8 @@ Open `public/tutorial/config.json`. The starter file already has the main parts
 - [`$schema`](../typedoc/interfaces/StudyConfig.md#schema) points to the Study Config schema.
 - [`studyMetadata`](../typedoc/interfaces/StudyMetadata.md) describes the study.
 - [`uiConfig`](../typedoc/interfaces/UIConfig.md) controls reVISit interface behavior, such as the contact email, help text, progress bar, sidebar, logo, and recording settings.
-- [`components`](../typedoc/interfaces/BaseIndividualComponent.md) defines the stimuli and tasks that the Participant can see.
-- [`sequence`](../typedoc/interfaces/Sequence.md) decides which components appear and in what order.
+- [`components`](../typedoc/interfaces/StudyConfig.md#components) defines the stimuli and tasks that the Participant can see.
+- [`sequence`](../typedoc/interfaces/StudyConfig.md#sequence) decides which components appear and in what order.
 
 The tutorial is mostly about the last two pieces: add a component, then add that component's id to the sequence.
 
@@ -543,6 +543,10 @@ This component renders `ReactExample.tsx`. The `parameters` object tells the Rea
 Values in `parameters` are passed into the `.tsx` file as the `parameters` prop, alongside reVISit's `setAnswer` callback. The same React file can therefore power many trials with different data, fields, or behavior.
 :::
 
+:::info
+React component paths are relative to `src/public/`, not the root `public/` folder. The path `tutorial/assets/ReactExample.tsx` points to `src/public/tutorial/assets/ReactExample.tsx`.
+:::
+
 Add `reactExampleCars` to the sequence.
 
 ![The tutorial study with the reactExampleCars trial](./img/config.json/step10.png)
@@ -897,6 +901,9 @@ import StructuredLinks from '@site/src/components/StructuredLinks/StructuredLink
     referenceLinks={[
         {name: "Pre Tutorial", url: "../tutorial/"},
         {name: "replication-config.json Tutorial", url: "../replication-config.json/"},
-        {name: "How Does It Work?", url: "../../getting-started/how-does-it-work/"}
+        {name: "How Does It Work?", url: "../../getting-started/how-does-it-work/"},
+        {name: "Study Config Reference", url: "../../typedoc/interfaces/StudyConfig/"},
+        {name: "Forms Reference", url: "../../designing-studies/forms/"},
+        {name: "Study Sequences", url: "../../designing-studies/sequences/study-sequences/"}
     ]}
 />
diff --git a/docs/tutorial/replication-config.json.md b/docs/tutorial/replication-config.json.md
@@ -13,6 +13,10 @@ The completed version is [`public/tutorial/_answers/replication-config.json`](ht
 This exercise shows how to make a reusable base component, create several practice trials from it, and then hand off to a dynamic block that chooses later trials.
 :::
 
+:::tip
+If you have not completed the [config.json tutorial](./config.json.md), do that first. This page assumes you already understand the basic loop: define a component, add it to the sequence, save, refresh, and preview with **Next participant**.
+:::
+
 ## Starting point
 
 The starter file ends with:
@@ -33,6 +37,10 @@ You will fill these sections in order:
 3. Add those components to the sequence.
 4. Add the dynamic sequence block.
 
+:::warning
+The component names in this exercise intentionally include spaces and correlation values, such as `practice T1 A:0.3 B:0.7`. That is allowed, but the name must match exactly everywhere it is used in the sequence.
+:::
+
 ## Step 1: Add the reusable scatter plot base component
 
 Replace the empty `baseComponents` object with `scatterBase`:
@@ -65,9 +73,17 @@ Replace the empty `baseComponents` object with `scatterBase`:
 }
 ```
 
-This base component defines the stimulus once. It points to the React component that renders the scatter plots and defines the response Participants will use for every trial.
+This [base component](../typedoc/interfaces/StudyConfig.md#basecomponents) defines the stimulus once. It points to the [React component](../typedoc/interfaces/ReactComponent.md) that renders the scatter plots and defines the response Participants will use for every trial.
 
-The response uses `buttons` because Participants choose between two clear options. The stored values are `left` and `right`, which you will use in `correctAnswer` later.
+The response uses [`buttons`](../typedoc/interfaces/ButtonsResponse.md) because Participants choose between two clear options. The stored values are `left` and `right`, which you will use in `correctAnswer` later.
+
+:::tip
+`baseComponents` are templates — they are not added to the sequence directly. Other components inherit from them via `"baseComponent": "scatterBase"` and override only the fields that change (typically `parameters` and `correctAnswer`).
+:::
+
+:::info
+React component paths are relative to `src/public/`. The path `tutorial/assets/replication/ScatterWrapper.tsx` points to `src/public/tutorial/assets/replication/ScatterWrapper.tsx`.
+:::
 
 ## Step 2: Add the first practice trial
 
@@ -92,28 +108,31 @@ Replace the empty `components` object with the first practice trial:
 }
 ```
 
-This trial inherits the stimulus and response from `scatterBase`. The `parameters` values tell the React component which correlations to show in the left and right plots.
+This trial [inherits](../typedoc/type-aliases/InheritedComponent.md) the stimulus and response from `scatterBase`. The `parameters` values tell the React component which correlations to show in the left and right plots.
 
-For this practice trial, `r2` is larger than `r1`, so the correct answer is `"right"`. The `id` in `correctAnswer` must match the response id from the base component: `buttonsResponse`.
+For this practice trial, `r2` is larger than `r1`, so the correct answer is `"right"`. The `id` in [`correctAnswer`](../typedoc/interfaces/Answer.md) must match the response id from the base component: `buttonsResponse`.
 
 ## Step 3: Add the second practice trial
 
 Add a comma after the first practice trial, then add:
 
 ```json title="public/tutorial/replication-config.json"
-"practice T2 A:0.9 B:0.6": {
-  "baseComponent": "scatterBase",
-  "parameters": {
-    "r1": 0.9,
-    "r2": 0.6
-  },
-  "correctAnswer": [
-    {
-      "id": "buttonsResponse",
-      "answer": "left"
-    }
-  ],
-  "provideFeedback": true
+"components": {
+  "practice T1 A:0.3 B:0.7": { ... },
+  "practice T2 A:0.9 B:0.6": {
+    "baseComponent": "scatterBase",
+    "parameters": {
+      "r1": 0.9,
+      "r2": 0.6
+    },
+    "correctAnswer": [
+      {
+        "id": "buttonsResponse",
+        "answer": "left"
+      }
+    ],
+    "provideFeedback": true
+  }
 }
 ```
 
@@ -126,19 +145,23 @@ This is the main benefit of `baseComponents`: the shared stimulus and response a
 Add the third practice trial after the second:
 
 ```json title="public/tutorial/replication-config.json"
-"practice T3 A:0.6 B:0.3": {
-  "baseComponent": "scatterBase",
-  "parameters": {
-    "r1": 0.6,
-    "r2": 0.3
-  },
-  "correctAnswer": [
-    {
-      "id": "buttonsResponse",
-      "answer": "left"
-    }
-  ],
-  "provideFeedback": true
+"components": {
+  "practice T1 A:0.3 B:0.7": { ... },
+  "practice T2 A:0.9 B:0.6": { ... },
+  "practice T3 A:0.6 B:0.3": {
+    "baseComponent": "scatterBase",
+    "parameters": {
+      "r1": 0.6,
+      "r2": 0.3
+    },
+    "correctAnswer": [
+      {
+        "id": "buttonsResponse",
+        "answer": "left"
+      }
+    ],
+    "provideFeedback": true
+  }
 }
 ```
 
@@ -151,15 +174,24 @@ All three practice trials use `provideFeedback: true` so Participants can learn
 Add one more component after the practice trials:
 
 ```json title="public/tutorial/replication-config.json"
-"trial": {
-  "baseComponent": "scatterBase"
+"components": {
+  "practice T1 A:0.3 B:0.7": { ... },
+  "practice T2 A:0.9 B:0.6": { ... },
+  "practice T3 A:0.6 B:0.3": { ... },
+  "trial": {
+    "baseComponent": "scatterBase"
+  }
 }
 ```
 
 This component also inherits from `scatterBase`, but it does not define fixed parameters or a fixed correct answer. The dynamic block will provide those values while the study runs.
 
 Use this pattern when many trials share the same display and response format, but the exact trial values are generated or selected dynamically.
 
+:::note
+`trial` deliberately omits `parameters` and `correctAnswer` — both are injected at runtime by the dynamic block's function. This keeps a single reusable component definition for an arbitrary number of trials.
+:::
+
 ## Step 6: Add the fixed practice sequence
 
 Replace the empty top-level sequence with a fixed block:
@@ -184,16 +216,31 @@ This shows the three practice trials in order. The component names in this seque
 
 At this point, the Study Config has a complete practice section.
 
+:::tip
+Preview the study here before adding the dynamic block. You should see the three practice trials in order, and each should provide feedback after the Participant answers.
+:::
+
 ## Step 7: Add the dynamic JND block
 
-Inside the nested fixed block, add the dynamic block after the three practice trials:
+Inside the nested fixed block, add the [dynamic block](../typedoc/interfaces/DynamicBlock.md) after the three practice trials:
 
 ```json title="public/tutorial/replication-config.json"
-{
-  "order": "dynamic",
-  "id": "steppedSequence",
-  "functionPath": "tutorial/assets/replication/JNDDynamic.tsx",
-  "parameters": {}
+"sequence": {
+  "order": "fixed",
+  "components": [
+    {
+      "order": "fixed",
+      "components": [
+        ...,
+        {
+          "order": "dynamic",
+          "id": "steppedSequence",
+          "functionPath": "tutorial/assets/replication/JNDDynamic.tsx",
+          "parameters": {}
+        }
+      ]
+    }
+  ]
 }
 ```
 
@@ -225,19 +272,13 @@ The dynamic block calls the function at `tutorial/assets/replication/JNDDynamic.
 
 The `id` gives the dynamic block a stable name in the study sequence. The empty `parameters` object is still included so the block has the same shape as dynamic blocks that do receive custom settings.
 
-## Step 8: Compare with the completed config
-
-Open [`public/tutorial/_answers/replication-config.json`](https://github.com/revisit-studies/template/blob/main/public/tutorial/_answers/replication-config.json) and check:
-
-- `baseComponents.scatterBase` defines the React stimulus and the shared button response.
-- Each practice component uses `"baseComponent": "scatterBase"`.
-- Each practice component passes `r1` and `r2` through `parameters`.
-- Each practice component has a `correctAnswer` that uses `buttonsResponse`.
-- `trial` inherits from `scatterBase` without fixed parameters.
-- The sequence shows three practice trials before the dynamic block.
-- The dynamic block uses `functionPath: "tutorial/assets/replication/JNDDynamic.tsx"`.
+:::tip
+The function at `functionPath` returns the next component id (typically `"trial"` here) plus the `parameters` and `correctAnswer` to inject. Use dynamic blocks for adaptive procedures like staircases, JND/QUEST, or branching based on prior responses. See the [Dynamic Blocks guide](../designing-studies/sequences/dynamic-blocks.md) for the full function contract.
+:::
 
-When those pieces match, the replication Study Config is complete.
+:::info
+Dynamic block function paths are also relative to `src/public/`. In the repository, `tutorial/assets/replication/JNDDynamic.tsx` lives at `src/public/tutorial/assets/replication/JNDDynamic.tsx`.
+:::
 
 <!-- Importing links -->
 import StructuredLinks from '@site/src/components/StructuredLinks/StructuredLinks.tsx';
@@ -251,6 +292,8 @@ import StructuredLinks from '@site/src/components/StructuredLinks/StructuredLink
     referenceLinks={[
         {name: "Pre Tutorial", url: "../tutorial/"},
         {name: "config.json Tutorial", url: "../config.json/"},
-        {name: "Dynamic Blocks", url: "../../designing-studies/sequences/dynamic-blocks/"}
+        {name: "Dynamic Blocks", url: "../../designing-studies/sequences/dynamic-blocks/"},
+        {name: "Study Config Reference", url: "../../typedoc/interfaces/StudyConfig/"},
+        {name: "React Components", url: "../../typedoc/interfaces/ReactComponent/"}
     ]}
 />
diff --git a/docs/tutorial/tutorial.md b/docs/tutorial/tutorial.md
@@ -19,7 +19,7 @@ By the end of this page, you should know:
 
 ## Tutorial Roadmap
 
-This tutorial follows the same general structure as the ReVISit visualization tutorial worksheet. You will start by getting the template running locally, then build and test a Study Config, and then look at analysis and deployment topics.
+This tutorial follows the same general structure as the reVISit visualization tutorial worksheet. You will start by getting the template running locally, then build and test a Study Config, and then look at analysis and deployment topics.
 
 The main sections are:
 
@@ -37,7 +37,7 @@ Use these links during the tutorial:
 
 | Resource | Link |
 | --- | --- |
-| ReVISit Slack team | [Join Slack](https://join.slack.com/t/revisit-nsf/shared_invite/zt-25mrh5ppi-6sDAL6HqcWJh_uvt2~~DMQ) |
+| reVISit Slack team | [Join Slack](https://join.slack.com/t/revisit-nsf/shared_invite/zt-25mrh5ppi-6sDAL6HqcWJh_uvt2~~DMQ) |
 | reVISit home page | [https://revisit.dev/](https://revisit.dev/) |
 | reVISit GitHub organization | [https://github.com/reVISit-studies/](https://github.com/reVISit-studies/) |
 | Installation guide | [Installation](../getting-started/installation.md) |
@@ -202,7 +202,7 @@ When you compare your starter file to an answer file, focus on the section you j
 
 ## Step 5: Know what starts empty
 
-Both starter configs already include the basic Study Config structure: schema, study metadata, UI config, empty components, and an empty sequence.
+Both starter configs already include the basic [Study Config](../typedoc/interfaces/StudyConfig.md) structure: [`$schema`](../typedoc/interfaces/StudyConfig.md#schema), [`studyMetadata`](../typedoc/interfaces/StudyMetadata.md), [`uiConfig`](../typedoc/interfaces/UIConfig.md), empty [`components`](../typedoc/interfaces/StudyConfig.md#components), and an empty [`sequence`](../typedoc/interfaces/StudyConfig.md#sequence).
 
 In `public/tutorial/config.json`, the main work starts here:
 
@@ -225,6 +225,8 @@ In `public/tutorial/replication-config.json`, the main work starts here:
 }
 ```
 
+The replication config adds [`baseComponents`](../typedoc/interfaces/StudyConfig.md#basecomponents) on top of the standard structure — these are reusable templates that other components inherit from.
+
 These empty sections are intentional. They make it easier to see exactly what each tutorial step adds.
 
 ## Step 6: Use the videos as references
@@ -282,6 +284,10 @@ Common mistakes are usually small:
 - A response `id` in `correctAnswer` or `skip` that does not match the response definition.
 - Editing a file in `_answers` instead of the starter file.
 
+:::tip
+With the `$schema` line at the top of each Study Config, VS Code (or any IDE that supports JSON Schema) will underline most of these mistakes as you type — missing commas, wrong types, unknown fields, and even mismatched component ids in the sequence. That's faster than catching them via reVISit's error page after refresh.
+:::
+
 ## Step 8: Move to the first config tutorial
 
 Once your local site runs and you understand the file layout, continue to [config.json](./config.json.md).
