Update replication studies to 2.4.2

.dockerignore

@@ -0,0 +1,25 @@
+.git
+.github
+node_modules
+dist
+docs
+docsLibraries
+playwright-report
+test-results
+verbose
+supabase
+tests
+.vscode
+.husky
+.DS_Store
+*.log
+.claude
+.idea
+/playwright/.cache/
+coverage
+*.tsbuildinfo
+*.local
+.env.local
+.env.*.local
+public/__revisit-widget
+src/public/__revisit-widget

.github/workflows/playwright.yml

@@ -11,37 +11,45 @@ jobs:
     name: 🧪 ${{ matrix.project }} E2E Tests
     runs-on: ${{ matrix.os }}
     timeout-minutes: 20
+    env:
+      PLAYWRIGHT_BROWSERS_PATH: ${{ matrix.cache_dir }}
+      PW_CI_REPORTER: dot
+      PW_CI_WORKERS: ${{ matrix.workers }}
     strategy:
       fail-fast: false
       matrix:
         include:
           - project: chromium
             os: ubuntu-latest
-            cache_dir: ~/.cache/ms-playwright
+            cache_dir: /home/runner/.cache/ms-playwright
+            workers: 3
 
-          - project: firefox
-            os: ubuntu-latest
-            cache_dir: ~/.cache/ms-playwright
+          # - project: firefox
+          #   os: ubuntu-latest
+          #   cache_dir: ~/.cache/ms-playwright
 
           - project: webkit
             os: macos-14
-            cache_dir: ~/Library/Caches/ms-playwright
+            cache_dir: /Users/runner/Library/Caches/ms-playwright
+            workers: 2
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
           node-version: lts/*
           cache: "yarn"
 
       - name: Install dependencies
+        env:
+          PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 1
         run: yarn install --immutable
 
       - name: Write out playwright version
         run: yarn --silent playwright --version > .playwright-version
 
       - name: ⚡️ Cache playwright binaries
-        uses: actions/cache@v3
+        uses: actions/cache@v4
         id: playwright-cache
         with:
           path: ${{ matrix.cache_dir }}
@@ -53,10 +61,3 @@ jobs:
 
       - name: Run Playwright tests
         run: yarn test --project=${{ matrix.project }}
-
-      - name: Upload test results
-        if: failure()
-        uses: actions/upload-artifact@v4
-        with:
-          name: playwright-report
-          path: playwright-report

.github/workflows/vitest.yml

@@ -1,4 +1,4 @@
-name: Playwright Tests
+name: Unit Tests
 
 on:
   pull_request:
@@ -22,5 +22,5 @@ jobs:
       - name: Install dependencies
         run: yarn install --immutable
 
-      - name: Run Playwright tests
+      - name: Run unit tests
         run: yarn unittest

AGENTS.md

@@ -0,0 +1,47 @@
+Tech Stack
+- Yarn
+- React 18
+- TypeScript
+- Vite
+- Mantine UI
+- Firebase or Supabase as storage and database backends (.env selects the engine)
+- Redux for state management with our in-house library Trrack.js for provenance tracking
+- Lodash usage is restricted to: debounce, throttle, isEqual, merge
+- React Router for routing
+- Eslint and airbnb style guide for code quality
+
+Purpose
+The ReVISit project aims to create a robust platform for conducting and analyzing user studies focused on interactive data visualization tools. By leveraging modern web technologies and state management solutions, ReVISit provides researchers with the necessary tools to design, deploy, and evaluate visualization interfaces effectively.
+
+The goal is to expand the scope of user studies to beyond the visualization community, making it easier for researchers from various fields to conduct studies on interactive data visualizations. This means we need state management that can handle complex interactions and data flows, as well as a user-friendly interface for both study designers and participants.
+
+Verbiage
+- "Study Designer": The individual who creates and configures the user study.
+- "Participant": The user who takes part in the study.
+- "Analyst": The individual who reviews and analyzes the data collected from the study, both in the platform and externally.
+- "Study Config": The configuration file that defines the parameters and settings of a user study.
+
+Study Configs
+The study configurations are defined in JSON files with schemas. These configs specify various aspects of the study, including the visualization tools to be used, the tasks participants need to complete, and the data sources involved. You can find the full definition of the study config schema in the typescript file at src/parser/types.ts. The answers and participant data specifications are stored separately from the study config to allow for flexibility in data collection and analysis, at src/store/types.ts. Study config JSON files live in the public folder under the /public/{studyName}/config.json path.
+
+Imported Libraries
+We provide several libraries to facilitate the development of user studies, such as vlat, mini-vlat, nasa-tlx, color-blindness, and more. These libraries are components and sequences that are defined in public/libraries/. Each library has its own folder containing the necessary code and assets. Use only libraries that exist under public/libraries/ (no ad-hoc local component imports in study configs). You can import these libraries into your study configs to enhance the functionality and user experience of your studies by adding the libraries to the top level `importedLibraries` field in the study config, and then referencing the components in the `baseComponent` field or in sequences and the sequences in the `sequences` field. When referencing the components and sequences use the following syntax `"$libraryName.components.componentName"` and `"$libraryName.sequences.sequenceName"` respectively.
+
+Storage Engines
+ReVISit supports multiple storage backends for storing study data, including Firebase and Supabase. This allows researchers to choose the backend that best fits their needs in terms of scalability, ease of use, and integration with other tools. The storage engines are abstracted in the codebase, allowing for easy addition of new storage solutions in the future. The storage engine implementations can be found in src/storage/ directory.
+
+How you should interact with the codebase
+When working with the ReVISit codebase, work only with the source code files available to you. If you need an external library, please ask for approval first (and include how well used the library is). Make sure to follow best practices for React and TypeScript development, including proper state management, component structuring, and code documentation. Pay extra attention to lifecycle methods and hooks to ensure optimal performance and avoid memory leaks, including any updates to existing code. If you encounter any issues or have suggestions for improvements, feel free to bring them up for discussion. You can run git commands but don't run them unless asked to. Don't interact with GitHub directly. Always check package.json for the scripts available to you for building, testing, and running the project.
+
+Testing
+When adding a new feature or modifying code try to maximize unit test coverage. Unit tests should be colocated with the files they are testing, have the same names as the file with .spec., and use the vitest framework. Apply this to both UI/react code as well as non-UI code. For UI code, we use playwright for end-to-end testing. Try to add e2e tests for any new features that involve user interaction. E2E tests are located in the tests/ directory at the root of the project. Don't run `yarn test` directly; instead, describe the tests you want to run, and I'll handle executing them. You can run unittests locally using `yarn unittest`. Preferred commands are those listed in package.json (e.g., `yarn unittest`, `yarn lint`, `yarn typecheck`, `yarn serve`, `yarn build`).
+
+Parser
+When adding new features, sometimes it's required to update the parser and the associated types. The parser is located in src/parser/. The parser is responsible for validating and transforming the study config JSON files into a format that the application can use. When updating the parser, ensure that you also update the corresponding types in src/parser/types.ts to reflect any changes made to the study config schema. Make sure to add unit tests for any new parser functionality to ensure its correctness. Additionally, changes to the parser types will require updates to the generated JSON schema files located in src/schemas/. You can regenerate these schema files by running `yarn generate-schemas`.
+
+Sequence
+The sequence logic is a crucial part of the ReVISit platform, as it defines the flow of tasks and interactions for participants in a study. A participant's sequence is essentially flattened into a list and navigated through by index. The only exception to this is the dynamic blocks, which function as a nested sequence. The nested sequence has its own index and can be navigated through independently of the main sequence.
+
+DO NOT
+- DO NOT add import('...') statements inside src code and test logic. Import at the top of the file only, even for types.
+- DO NOT add new libraries without approval.

CITATION.cff

@@ -0,0 +1,59 @@
+cff-version: 1.2.0
+message: "If you use reVISit, please cite the paper below."
+title: "ReVISit study"
+url: "https://github.com/revisit-studies/study"
+repository-code: "https://github.com/revisit-studies/study"
+license: "BSD-3-Clause"
+authors:
+  - family-names: "Cutler"
+    given-names: "Zach"
+  - family-names: "Wilburn"
+    given-names: "Jack"
+  - family-names: "Shrestha"
+    given-names: "Hilson"
+  - family-names: "Ding"
+    given-names: "Yiren"
+  - family-names: "Bollen"
+    given-names: "Brian"
+  - family-names: "Nadib"
+    given-names: "Khandaker Abrar"
+  - family-names: "He"
+    given-names: "Tingying"
+  - family-names: "McNutt"
+    given-names: "Andrew"
+  - family-names: "Harrison"
+    given-names: "Lane"
+  - family-names: "Lex"
+    given-names: "Alexander"
+preferred-citation:
+  type: article
+  title: "ReVISit 2: A Full Experiment Life Cycle User Study Framework"
+  authors:
+    - family-names: "Cutler"
+      given-names: "Zach"
+    - family-names: "Wilburn"
+      given-names: "Jack"
+    - family-names: "Shrestha"
+      given-names: "Hilson"
+    - family-names: "Ding"
+      given-names: "Yiren"
+    - family-names: "Bollen"
+      given-names: "Brian"
+    - family-names: "Nadib"
+      given-names: "Khandaker Abrar"
+    - family-names: "He"
+      given-names: "Tingying"
+    - family-names: "McNutt"
+      given-names: "Andrew"
+    - family-names: "Harrison"
+      given-names: "Lane"
+    - family-names: "Lex"
+      given-names: "Alexander"
+  journal: "IEEE Transactions on Visualization and Computer Graphics"
+  year: 2026
+  volume: 32
+  issue: 1
+  start: 13
+  end: 23
+  doi: "10.1109/TVCG.2025.3633896"
+  url: "https://dx.doi.org/10.1109/TVCG.2025.3633896"

Dockerfile

@@ -0,0 +1,42 @@
+FROM node:lts AS builder
+
+WORKDIR /app
+
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile
+
+COPY . .
+
+RUN yarn build
+
+RUN node -e "const fs=require('node:fs');const key='VITE_BASE_PATH=';const lines=fs.readFileSync('.env','utf8').split(/\\r?\\n/);let v='';for(const line of lines){if(line.startsWith(key)) v=line.slice(key.length);}v=v.trim();if((v.startsWith('\"')&&v.endsWith('\"'))||(v.startsWith(\"'\")&&v.endsWith(\"'\"))){v=v.slice(1,-1);}if(!v){throw new Error('VITE_BASE_PATH must be defined in .env');}fs.writeFileSync('/tmp/base_path',v);"
+
+FROM nginx:stable AS runtime
+
+COPY --from=builder /app/dist /tmp/dist
+COPY --from=builder /tmp/base_path /tmp/base_path
+COPY nginx-docker.conf /tmp/nginx-docker.conf
+
+RUN set -eux; \
+  BASE_PATH="$(cat /tmp/base_path)"; \
+  rm -rf /usr/share/nginx/html/*; \
+  if [ "$BASE_PATH" = "/" ]; then \
+    LOCATION_PATH="/"; \
+    INDEX_FALLBACK="/index.html"; \
+    ROOT_REDIRECT_DIRECTIVE="try_files /index.html =404;"; \
+    cp -R /tmp/dist/. /usr/share/nginx/html/; \
+  else \
+    LOCATION_PATH="$BASE_PATH"; \
+    INDEX_FALLBACK="${BASE_PATH}index.html"; \
+    ROOT_REDIRECT_DIRECTIVE="return 302 ${BASE_PATH};"; \
+    TARGET_DIR="/usr/share/nginx/html${BASE_PATH}"; \
+    mkdir -p "$TARGET_DIR"; \
+    cp -R /tmp/dist/. "$TARGET_DIR"; \
+  fi; \
+  sed \
+    -e "s|__ROOT_REDIRECT_DIRECTIVE__|${ROOT_REDIRECT_DIRECTIVE}|g" \
+    -e "s|__LOCATION_PATH__|${LOCATION_PATH}|g" \
+    -e "s|__INDEX_FALLBACK__|${INDEX_FALLBACK}|g" \
+    /tmp/nginx-docker.conf > /etc/nginx/conf.d/default.conf
+
+EXPOSE 8080

README.md

@@ -1,21 +1,60 @@
-# reVISit study – Interactive, Web-Based User Studies.  
+# ReVISit study – Interactive, Web-Based User Studies.
 
-Create your own interactive, web-based data visualization user studies by cloning/forking and editing configuration files and adding stimuli in the `public` folder. 
+Create your own interactive, web-based data visualization user studies by cloning/forking and editing configuration files and adding stimuli in the `public` folder.
 
-reVISit introduces reVISit.spec a DSL for specifying study setups (consent forms, training, trials, etc) for interactive web based studies. You describe your experimental setup in reVISit.spec, add your stimuli as images, forms, html pages, or React components, build and deploy – and you're ready to run your study. For tutorials and documentation, see the [reVISit website](https://revisit.dev). 
+ReVISit introduces reVISit.spec, a DSL for specifying study setups (consent forms, training, trials, etc.) for interactive web based studies. You describe your experimental setup in reVISit.spec, add your stimuli as images, forms, HTML pages, or React components, build and deploy — and you're ready to run your study. For tutorials and documentation, see the [reVISit website](https://revisit.dev).
+
+## Paper
+
+If you are using reVISit for a paper, please cite:
+
+> Zach Cutler, Jack Wilburn, Hilson Shrestha, Yiren Ding, Brian Bollen, Khandaker Abrar Nadib, Tingying He, Andrew McNutt, Lane Harrison, Alexander Lex. [ReVISit 2: A Full Experiment Life Cycle User Study Framework](https://www.visdesignlab.net/publications/2025_vis_revisit/). IEEE Transactions on Visualization and Computer Graphics (VIS), 32(1): 13-23, [doi:10.1109/TVCG.2025.3633896](https://dx.doi.org/10.1109/TVCG.2025.3633896), 2026.
+
+**IEEE VIS 2025 Best Paper Award**
+
+GitHub citation metadata for this repository is available in [CITATION.cff](./CITATION.cff).
 
 ## Build Instructions
 
-To run this demo experiment locally, you will need to install node on your computer. 
+To run this demo experiment locally, you will need to install Node.js on your computer.
 
 * Clone `https://github.com/revisit-studies/study`
-* Run `yarn install`. If you don't have yarn installed, run `npm i -g yarn`. 
+* Run `yarn install`. If you don't have Yarn installed, run `npm i -g yarn`.
 * To run locally, run `yarn serve`.
-* Go to [http://localhost:8080](http://localhost:8080) to view it in your browser. The page will reload when you make changes. 
+* Go to [http://localhost:8080](http://localhost:8080) to view it in your browser. The page will reload when you make changes.
+
+## Adding Tests
+
+This repo uses two test types:
+
+* **Unit tests** with **Vitest** for parser, utility, and component logic.
+* **End-to-end (E2E) tests** with **Playwright** for participant/designer flows in a running app.
+
+### Unit tests (Vitest)
+
+* Co-locate unit tests with the source file they cover.
+* Use the same base filename and add `.spec.` (for example: `src/parser/parser.ts` -> `src/parser/parser.spec.ts`).
+* Use `vitest` APIs (`describe`, `test`/`it`, `expect`).
+* Run unit tests with:
+
+```bash
+yarn unittest
+```
+
+### E2E tests (Playwright)
+
+* Put E2E tests in the root `tests/` directory.
+* Name files with `.spec.ts` (for example: `tests/demo-vlat.spec.ts`).
+* Keep tests focused on user-observable behavior (navigation, input, progression, reviewer/designer behavior).
+* Run E2E tests with:
+
+```bash
+yarn test
+```
 
 ## Release Instructions
 
-Releasing reVISit.dev happens automatically when a PR is merged into the `main` branch. The name of the pull request should be the title of the release, e.g. `v1.0.0`. Releasing creates a tag with the same name as the PR, but the official GitGub release should be created manually. The `main` branch is protected and requires two reviews before merging.
+Releasing reVISit.dev happens automatically when a PR is merged into the `main` branch. The name of the pull request should be the title of the release, e.g. `v1.0.0`. Releasing creates a tag with the same name as the PR, but the official GitHub release should be created manually. The `main` branch is protected and requires two reviews before merging.
 
 The workflow for release looks as follows:
 Develop features on feature branch
@@ -24,4 +63,36 @@ Dev branch
 | PR (1 per release)
 Main branch
 | Run release workflow on merge
-References are updated and commit is tagged
+References are updated and commit is tagged
+
+### Release Follow-Up
+
+- [ ] Verify docs links in the [Study Repository](https://github.com/revisit-studies/study) are up to date and point to the current reVISit documentation pages.
+- [ ] After the release is complete, run the template update process so downstream study templates include the latest release changes.
+
+
+## QC Checklist
+
+### [Study Repository](https://github.com/revisit-studies/study)
+
+**Studies**
+- [ ] Review all studies for any crashes/bugs
+- [ ] Check provenance data (audio, screen, etc.)
+
+**File Download**
+- [ ] JSON export
+- [ ] Tidy download export
+- [ ] Download audio recordings
+- [ ] Download screen recordings
+- [ ] Download configs
+
+**Docs**
+- [ ] Update comments in `store/types.ts`, `parser/types.ts`, `storage/types.ts`, `storage/engines/types.ts`
+- [ ] Update `typedocReadMe.md`
+
+### [Documentation Repository](https://github.com/revisit-studies/reVISit-studies.github.io)
+- [ ] Review docs
+- [ ] Review [library list](https://revisit.dev/docs/designing-studies/plugin-libraries/)
+- [ ] Check for typos / outdated docs
+- [ ] Validate example code
+- [ ] Update screenshots

eslint.config.js

@@ -2,7 +2,6 @@ import { fixupConfigRules, fixupPluginRules } from '@eslint/compat';
 import typescriptEslint from '@typescript-eslint/eslint-plugin';
 import react from 'eslint-plugin-react';
 import globals from 'globals';
-// eslint-disable-next-line import/no-unresolved -- This is throwing a false positive
 import tsParser from '@typescript-eslint/parser';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,7 +17,7 @@ const compat = new FlatCompat({
 });
 
 export default [{
-  ignores: ['public/*'],
+  ignores: ['public/**', 'src/public/**'],
 }, ...fixupConfigRules(compat.extends(
   'airbnb-base',
   'airbnb/rules/react',
@@ -46,6 +45,9 @@ export default [{
 
   settings: {
     'import/resolver': {
+      typescript: {
+        alwaysTryTypes: true,
+      },
       node: {
         extensions: ['.js', '.jsx', '.ts', '.tsx', '.d.ts'],
       },
@@ -100,7 +102,9 @@ export default [{
     'react/react-in-jsx-scope': 0,
     'max-len': 0,
     'react/jsx-filename-extension': 0,
-    'import/extensions': ['error', 'never'],
+    'import/extensions': ['error', 'never', {
+      json: 'always',
+    }],
     '@typescript-eslint/ban-ts-comment': 'warn',
     'react/destructuring-assignment': 'off',
     'react/jsx-props-no-spreading': 'off',