jspsych 8.1.0 → 8.2.1

package/dist/index.cjs

@@ -2,72 +2,9 @@
 
 var autoBind = require('auto-bind');
 var rw = require('random-words');
-var seedrandom = require('seedrandom/lib/alea');
+var seedrandom = require('seedrandom/lib/alea.js');
 
-var _package = {
-  name: "jspsych",
-  version: "8.1.0",
-  description: "Behavioral experiments in a browser",
-  type: "module",
-  main: "dist/index.cjs",
-  exports: {
-    ".": {
-      import: "./dist/index.js",
-      require: "./dist/index.cjs"
-    },
-    "./css/*": "./css/*"
-  },
-  typings: "dist/index.d.ts",
-  unpkg: "dist/index.browser.min.js",
-  files: [
-    "src",
-    "dist",
-    "css"
-  ],
-  source: "src/index.ts",
-  scripts: {
-    test: "jest",
-    "test:watch": "npm test -- --watch",
-    tsc: "tsc",
-    "build:js": "rollup --config",
-    "build:styles": "webpack-cli",
-    build: "run-p build:js build:styles",
-    "build:watch": 'run-p "build:js -- --watch" "build:styles watch"',
-    prepack: "cp ../../README.md ."
-  },
-  repository: {
-    type: "git",
-    url: "git+https://github.com/jspsych/jsPsych.git",
-    directory: "packages/jspsych"
-  },
-  author: "Josh de Leeuw",
-  license: "MIT",
-  bugs: {
-    url: "https://github.com/jspsych/jsPsych/issues"
-  },
-  homepage: "https://www.jspsych.org",
-  dependencies: {
-    "auto-bind": "^4.0.0",
-    "random-words": "^1.1.1",
-    seedrandom: "^3.0.5",
-    "type-fest": "^2.9.0"
-  },
-  devDependencies: {
-    "@fontsource/open-sans": "4.5.3",
-    "@jspsych/config": "^3.0.1",
-    "@types/dom-mediacapture-record": "^1.0.11",
-    "base64-inline-loader": "^2.0.1",
-    "css-loader": "^6.6.0",
-    "mini-css-extract-plugin": "^2.5.3",
-    "npm-run-all": "^4.1.5",
-    "replace-in-file-webpack-plugin": "^1.0.6",
-    sass: "^1.43.5",
-    "sass-loader": "^12.4.0",
-    webpack: "^5.76.0",
-    "webpack-cli": "^4.9.2",
-    "webpack-remove-empty-scripts": "^0.7.2"
-  }
-};
+var version = "8.2.1";
 
 class ExtensionManager {
   constructor(dependencies, extensionsConfiguration) {
@@ -139,8 +76,7 @@ function unique(arr) {
   return [...new Set(arr)];
 }
 function deepCopy(obj) {
-  if (!obj)
-    return obj;
+  if (!obj) return obj;
   let out;
   if (Array.isArray(obj)) {
     out = [];
@@ -187,9 +123,9 @@ function deepMerge(obj1, obj2) {
 
 var utils = /*#__PURE__*/Object.freeze({
   __proto__: null,
-  unique: unique,
   deepCopy: deepCopy,
-  deepMerge: deepMerge
+  deepMerge: deepMerge,
+  unique: unique
 });
 
 class DataColumn {
@@ -335,10 +271,8 @@ function getQueryString() {
   const b = {};
   for (let i = 0; i < a.length; ++i) {
     const p = a[i].split("=", 2);
-    if (p.length == 1)
-      b[p[0]] = "";
-    else
-      b[p[0]] = decodeURIComponent(p[1].replace(/\+/g, " "));
+    if (p.length == 1) b[p[0]] = "";
+    else b[p[0]] = decodeURIComponent(p[1].replace(/\+/g, " "));
   }
   return b;
 }
@@ -362,26 +296,44 @@ class DataCollection {
       return new DataCollection([this.trials[this.trials.length - 1]]);
     }
   }
+  /**
+   * Queries the first n elements in a collection of trials.
+   *
+   * @param n A positive integer of elements to return. A value of
+   *          n that is less than 1 will throw an error.
+   *
+   * @return First n objects of a collection of trials. If fewer than
+   *         n trials are available, the trials.length elements will
+   *         be returned.
+   *
+   */
   first(n = 1) {
     if (n < 1) {
       throw `You must query with a positive nonzero integer. Please use a
                different value for n.`;
     }
-    if (this.trials.length === 0)
-      return new DataCollection();
-    if (n > this.trials.length)
-      n = this.trials.length;
+    if (this.trials.length === 0) return new DataCollection();
+    if (n > this.trials.length) n = this.trials.length;
     return new DataCollection(this.trials.slice(0, n));
   }
+  /**
+   * Queries the last n elements in a collection of trials.
+   *
+   * @param n A positive integer of elements to return. A value of
+   *          n that is less than 1 will throw an error.
+   *
+   * @return Last n objects of a collection of trials. If fewer than
+   *         n trials are available, the trials.length elements will
+   *         be returned.
+   *
+   */
   last(n = 1) {
     if (n < 1) {
       throw `You must query with a positive nonzero integer. Please use a
                different value for n.`;
     }
-    if (this.trials.length === 0)
-      return new DataCollection();
-    if (n > this.trials.length)
-      n = this.trials.length;
+    if (this.trials.length === 0) return new DataCollection();
+    if (n > this.trials.length) n = this.trials.length;
     return new DataCollection(this.trials.slice(this.trials.length - n, this.trials.length));
   }
   values() {
@@ -501,6 +453,7 @@ class DataCollection {
 class JsPsychData {
   constructor(dependencies) {
     this.dependencies = dependencies;
+    /** Data properties for all trials */
     this.dataProperties = {};
     this.interactionListeners = {
       blur: () => {
@@ -511,7 +464,10 @@ class JsPsychData {
       },
       fullscreenchange: () => {
         this.addInteractionRecord(
-          document.isFullScreen || document.webkitIsFullScreen || document.mozIsFullScreen || document.fullscreenElement ? "fullscreenenter" : "fullscreenexit"
+          // @ts-expect-error
+          document.isFullScreen || // @ts-expect-error
+          document.webkitIsFullScreen || // @ts-expect-error
+          document.mozIsFullScreen || document.fullscreenElement ? "fullscreenenter" : "fullscreenexit"
         );
       }
     };
@@ -605,6 +561,10 @@ class KeyboardListenerAPI {
     autoBind(this);
     this.registerRootListeners();
   }
+  /**
+   * If not previously done and `this.getRootElement()` returns an element, adds the root key
+   * listeners to that element.
+   */
   registerRootListeners() {
     if (!this.areRootListenersRegistered) {
       const rootElement = this.getRootElement();
@@ -736,8 +696,7 @@ class AudioPlayer {
     if (this.audio instanceof HTMLAudioElement) {
       this.audio.play();
     } else {
-      if (!this.audio)
-        this.audio = this.getAudioSourceNode(this.webAudioBuffer);
+      if (!this.audio) this.audio = this.getAudioSourceNode(this.webAudioBuffer);
       this.audio.start();
     }
   }
@@ -799,9 +758,12 @@ const preloadParameterTypes = [
 class MediaAPI {
   constructor(useWebaudio) {
     this.useWebaudio = useWebaudio;
+    // video //
     this.video_buffers = {};
+    // audio //
     this.context = null;
     this.audio_buffers = [];
+    // preloading stimuli //
     this.preload_requests = [];
     this.img_cache = {};
     this.preloadMap = /* @__PURE__ */ new Map();
@@ -1027,12 +989,25 @@ class SimulationAPI {
   dispatchEvent(event) {
     this.getDisplayContainerElement().dispatchEvent(event);
   }
+  /**
+   * Dispatches a `keydown` event for the specified key
+   * @param key Character code (`.key` property) for the key to press.
+   */
   keyDown(key) {
     this.dispatchEvent(new KeyboardEvent("keydown", { key }));
   }
+  /**
+   * Dispatches a `keyup` event for the specified key
+   * @param key Character code (`.key` property) for the key to press.
+   */
   keyUp(key) {
     this.dispatchEvent(new KeyboardEvent("keyup", { key }));
   }
+  /**
+   * Dispatches a `keydown` and `keyup` event in sequence to simulate pressing a key.
+   * @param key Character code (`.key` property) for the key to press.
+   * @param delay Length of time to wait (ms) before executing action
+   */
   pressKey(key, delay = 0) {
     if (delay > 0) {
       this.setJsPsychTimeout(() => {
@@ -1044,6 +1019,11 @@ class SimulationAPI {
       this.keyUp(key);
     }
   }
+  /**
+   * Dispatches `mousedown`, `mouseup`, and `click` events on the target element
+   * @param target The element to click
+   * @param delay Length of time to wait (ms) before executing action
+   */
   clickTarget(target, delay = 0) {
     if (delay > 0) {
       this.setJsPsychTimeout(() => {
@@ -1057,6 +1037,12 @@ class SimulationAPI {
       target.dispatchEvent(new MouseEvent("click", { bubbles: true }));
     }
   }
+  /**
+   * Sets the value of a target text input
+   * @param target A text input element to fill in
+   * @param text Text to input
+   * @param delay Length of time to wait (ms) before executing action
+   */
   fillTextInput(target, text, delay = 0) {
     if (delay > 0) {
       this.setJsPsychTimeout(() => {
@@ -1066,6 +1052,12 @@ class SimulationAPI {
       target.value = text;
     }
   }
+  /**
+   * Picks a valid key from `choices`, taking into account jsPsych-specific
+   * identifiers like "NO_KEYS" and "ALL_KEYS".
+   * @param choices Which keys are valid.
+   * @returns A key selected at random from the valid keys.
+   */
   getValidKey(choices) {
     const possible_keys = [
       "a",
@@ -1160,11 +1152,20 @@ class TimeoutAPI {
   constructor() {
     this.timeout_handlers = [];
   }
+  /**
+   * Calls a function after a specified delay, in milliseconds.
+   * @param callback The function to call after the delay.
+   * @param delay The number of milliseconds to wait before calling the function.
+   * @returns A handle that can be used to clear the timeout with clearTimeout.
+   */
   setTimeout(callback, delay) {
     const handle = window.setTimeout(callback, delay);
     this.timeout_handlers.push(handle);
     return handle;
   }
+  /**
+   * Clears all timeouts that have been created with setTimeout.
+   */
   clearAllTimeouts() {
     for (const handler of this.timeout_handlers) {
       clearTimeout(handler);
@@ -1419,10 +1420,8 @@ function randomWords(opts) {
 }
 function randn_bm() {
   var u = 0, v = 0;
-  while (u === 0)
-    u = Math.random();
-  while (v === 0)
-    v = Math.random();
+  while (u === 0) u = Math.random();
+  while (v === 0) v = Math.random();
   return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
 }
 function unpackArray(array) {
@@ -1440,21 +1439,21 @@ function unpackArray(array) {
 
 var randomization = /*#__PURE__*/Object.freeze({
   __proto__: null,
-  setSeed: setSeed,
-  repeat: repeat,
-  shuffle: shuffle,
-  shuffleNoRepeats: shuffleNoRepeats,
-  shuffleAlternateGroups: shuffleAlternateGroups,
-  sampleWithoutReplacement: sampleWithoutReplacement,
-  sampleWithReplacement: sampleWithReplacement,
   factorial: factorial,
   randomID: randomID,
   randomInt: randomInt,
+  randomWords: randomWords,
+  repeat: repeat,
   sampleBernoulli: sampleBernoulli,
-  sampleNormal: sampleNormal,
-  sampleExponential: sampleExponential,
   sampleExGaussian: sampleExGaussian,
-  randomWords: randomWords
+  sampleExponential: sampleExponential,
+  sampleNormal: sampleNormal,
+  sampleWithReplacement: sampleWithReplacement,
+  sampleWithoutReplacement: sampleWithoutReplacement,
+  setSeed: setSeed,
+  shuffle: shuffle,
+  shuffleAlternateGroups: shuffleAlternateGroups,
+  shuffleNoRepeats: shuffleNoRepeats
 });
 
 function turkInfo() {
@@ -1486,8 +1485,7 @@ function submitToTurk(data) {
   const turk = turkInfo();
   const assignmentId = turk.assignmentId;
   const turkSubmitTo = turk.turkSubmitTo;
-  if (!assignmentId || !turkSubmitTo)
-    return;
+  if (!assignmentId || !turkSubmitTo) return;
   const form = document.createElement("form");
   form.method = "POST";
   form.action = turkSubmitTo + "/mturk/externalSubmit?assignmentId=" + assignmentId;
@@ -1507,8 +1505,8 @@ function submitToTurk(data) {
 
 var turk = /*#__PURE__*/Object.freeze({
   __proto__: null,
-  turkInfo: turkInfo,
-  submitToTurk: submitToTurk
+  submitToTurk: submitToTurk,
+  turkInfo: turkInfo
 });
 
 class ProgressBar {
@@ -1518,6 +1516,7 @@ class ProgressBar {
     this._progress = 0;
     this.setupElements();
   }
+  /** Adds the progress bar HTML code into `this.containerElement` */
   setupElements() {
     this.messageSpan = document.createElement("span");
     this.innerDiv = document.createElement("div");
@@ -1529,6 +1528,7 @@ class ProgressBar {
     this.containerElement.appendChild(this.messageSpan);
     this.containerElement.appendChild(outerDiv);
   }
+  /** Updates the progress bar according to `this.progress` */
   update() {
     this.innerDiv.style.width = this._progress * 100 + "%";
     if (typeof this.message === "function") {
@@ -1537,6 +1537,10 @@ class ProgressBar {
       this.messageSpan.innerHTML = this.message;
     }
   }
+  /**
+   * The bar's current position as a number in the closed interval [0, 1]. Set this to update the
+   * progress bar accordingly.
+   */
   set progress(progress) {
     if (typeof progress !== "number" || progress < 0 || progress > 1) {
       throw new Error("jsPsych.progressBar.progress must be a number between 0 and 1");
@@ -1686,13 +1690,36 @@ class TimelineNode {
   getStatus() {
     return this.status;
   }
+  /**
+   * Initializes the parameter value cache with `this.description`. To be called by subclass
+   * constructors after setting `this.description`.
+   */
   initializeParameterValueCache() {
     this.parameterValueCache.initialize(this.description);
   }
+  /**
+   * Resets all cached parameter values in this timeline node and all of its parents. This is
+   * necessary to re-evaluate function parameters and timeline variables at each new trial.
+   */
   resetParameterValueCache() {
     this.parameterValueCache.reset();
     this.parent?.resetParameterValueCache();
   }
+  /**
+   * Retrieves a parameter value from the description of this timeline node, recursively falling
+   * back to the description of each parent timeline node unless `recursive` is set to `false`. If
+   * the parameter...
+   *
+   * * is a timeline variable, evaluates the variable and returns the result.
+   * * is not specified, returns `undefined`.
+   * * is a function and `evaluateFunctions` is not set to `false`, invokes the function and returns
+   *   its return value
+   * * has previously been looked up, return the cached result of the previous lookup
+   *
+   * @param parameterPath The path of the respective parameter in the timeline node description. If
+   * the path is an array, nested object properties or array items will be looked up.
+   * @param options See {@link GetParameterValueOptions}
+   */
   getParameterValue(parameterPath, options = {}) {
     const {
       evaluateFunctions = true,
@@ -1721,6 +1748,11 @@ class TimelineNode {
     }
     return result;
   }
+  /**
+   * Retrieves and evaluates the `data` parameter. It is different from other parameters in that
+   * it's properties may be functions that have to be evaluated, and parent nodes' data parameter
+   * properties are merged into the result.
+   */
   getDataParameter() {
     const data = this.getParameterValue("data", { recursive: false });
     return {
@@ -1744,7 +1776,12 @@ class Trial extends TimelineNode {
     this.initializeParameterValueCache();
     this.trialObject = deepCopy(description);
     this.pluginClass = this.getParameterValue("type", { evaluateFunctions: false });
-    this.pluginInfo = this.pluginClass["info"];
+    this.pluginInfo = this.pluginClass?.["info"];
+    if (!this.pluginInfo) {
+      throw new Error(
+        "Plugin not recognized. Please provide a valid plugin using the 'type' parameter."
+      );
+    }
     if (!("version" in this.pluginInfo) && !("data" in this.pluginInfo)) {
       console.warn(
         this.pluginInfo["name"],
@@ -1826,10 +1863,16 @@ class Trial extends TimelineNode {
       )
     };
   }
+  /**
+   * Cleanup the trial by removing the display element and removing event listeners
+   */
   cleanupTrial() {
     this.dependencies.clearAllTimeouts();
     this.dependencies.getDisplayElement().innerHTML = "";
   }
+  /**
+   * Add the CSS classes from the `css_classes` parameter to the display element
+   */
   addCssClasses() {
     const classes = this.getParameterValue("css_classes");
     const classList = this.dependencies.getDisplayElement().classList;
@@ -1839,6 +1882,9 @@ class Trial extends TimelineNode {
       classList.add(...classes);
     }
   }
+  /**
+   * Removes the provided css classes from the display element
+   */
   removeCssClasses() {
     const classes = this.getParameterValue("css_classes");
     if (classes) {
@@ -1887,6 +1933,12 @@ class Trial extends TimelineNode {
     }
     return result;
   }
+  /**
+   * Runs a callback function retrieved from a parameter value and returns its result.
+   *
+   * @param parameterName The name of the parameter to retrieve the callback function from.
+   * @param callbackParameters The parameters (if any) to be passed to the callback function
+   */
   runParameterCallback(parameterName, ...callbackParameters) {
     const callback = this.getParameterValue(parameterName, { evaluateFunctions: false });
     if (callback) {
@@ -1917,6 +1969,10 @@ class Trial extends TimelineNode {
     }
     return super.getParameterValue(parameterPath, options);
   }
+  /**
+   * Retrieves and evaluates the `simulation_options` parameter, considering nested properties and
+   * global simulation options.
+   */
   getSimulationOptions() {
     const simulationOptions = this.getParameterValue("simulation_options", {
       replaceResult: (result = {}) => {
@@ -1946,6 +2002,10 @@ class Trial extends TimelineNode {
     }
     return simulationOptions;
   }
+  /**
+   * Returns the result object of this trial or `undefined` if the result is not yet known or the
+   * `record_data` trial parameter is `false`.
+   */
   getResult() {
     return this.getParameterValue("record_data") === false ? void 0 : this.result;
   }
@@ -1953,6 +2013,12 @@ class Trial extends TimelineNode {
     const result = this.getResult();
     return result ? [result] : [];
   }
+  /**
+   * Checks that the parameters provided in the trial description align with the plugin's info
+   * object, resolves missing parameter values from the parent timeline, resolves timeline variable
+   * parameters, evaluates parameter functions if the expected parameter type is not `FUNCTION`, and
+   * sets default values for optional parameters.
+   */
   processParameters() {
     const assignParameterValues = (parameterObject, parameterInfos, parentParameterPath = []) => {
       for (const [parameterName, parameterConfig] of Object.entries(parameterInfos)) {
@@ -2087,6 +2153,9 @@ class Timeline extends TimelineNode {
       this.resumePromise.resolve();
     }
   }
+  /**
+   * If the timeline is running or paused, aborts the timeline after the current trial has completed
+   */
   abort() {
     if (this.status === TimelineNodeStatus.RUNNING || this.status === TimelineNodeStatus.PAUSED) {
       if (this.currentChild instanceof Timeline) {
@@ -2109,6 +2178,11 @@ class Timeline extends TimelineNode {
       ...index === null ? void 0 : this.description.timeline_variables[index]
     };
   }
+  /**
+   * If the timeline has timeline variables, returns the order of `timeline_variables` array indices
+   * to be used, according to the timeline's `sample` setting. If the timeline has no timeline
+   * variables, returns `[null]`.
+   */
   generateTimelineVariableOrder() {
     const timelineVariableLength = this.description.timeline_variables?.length;
     if (!timelineVariableLength) {
@@ -2135,7 +2209,8 @@ class Timeline extends TimelineNode {
           break;
         default:
           throw new Error(
-            `Invalid type "${sample.type}" in timeline sample parameters. Valid options for type are "custom", "with-replacement", "without-replacement", "fixed-repetitions", and "alternate-groups"`
+            `Invalid type "${// @ts-expect-error TS doesn't have a type for `sample` in this case
+            sample.type}" in timeline sample parameters. Valid options for type are "custom", "with-replacement", "without-replacement", "fixed-repetitions", and "alternate-groups"`
           );
       }
     }
@@ -2144,6 +2219,9 @@ class Timeline extends TimelineNode {
     }
     return order;
   }
+  /**
+   * Returns the current values of all timeline variables, including those from parent timelines
+   */
   getAllTimelineVariables() {
     return this.currentTimelineVariables;
   }
@@ -2167,6 +2245,10 @@ class Timeline extends TimelineNode {
     }
     return results;
   }
+  /**
+   * Returns the naive progress of the timeline (as a fraction), without considering conditional or
+   * loop functions.
+   */
   getNaiveProgress() {
     if (this.status === TimelineNodeStatus.PENDING) {
       return 0;
@@ -2181,6 +2263,10 @@ class Timeline extends TimelineNode {
     }
     return Math.min(completedTrials / this.getNaiveTrialCount(), 1);
   }
+  /**
+   * Recursively computes the naive number of trials in the timeline, without considering
+   * conditional or loop functions.
+   */
   getNaiveTrialCount() {
     const getTrialCount = (description) => {
       const getTimelineArrayTrialCount = (description2) => description2.map((childDescription) => getTrialCount(childDescription)).reduce((a, b) => a + b);
@@ -2226,7 +2312,17 @@ class JsPsych {
     this.turk = turk;
     this.randomization = randomization;
     this.utils = utils;
+    // prettier-ignore
+    this.citation = {
+      "apa": "de Leeuw, J. R., Gilbert, R. A., & Luchterhandt, B. (2023). jsPsych: Enabling an Open-Source Collaborative Ecosystem of Behavioral Experiments. Journal of Open Source Software, 8(85), 5351. https://doi.org/10.21105/joss.05351 ",
+      "bibtex": '@article{Leeuw2023jsPsych, 	author = {de Leeuw, Joshua R. and Gilbert, Rebecca A. and Luchterhandt, Bj{\\" o}rn}, 	journal = {Journal of Open Source Software}, 	doi = {10.21105/joss.05351}, 	issn = {2475-9066}, 	number = {85}, 	year = {2023}, 	month = {may 11}, 	pages = {5351}, 	publisher = {Open Journals}, 	title = {jsPsych: Enabling an {Open}-{Source} {Collaborative} {Ecosystem} of {Behavioral} {Experiments}}, 	url = {https://joss.theoj.org/papers/10.21105/joss.05351}, 	volume = {8}, }  '
+    };
+    /** Options */
     this.options = {};
+    /**
+     * Whether the page is retrieved directly via the `file://` protocol (true) or hosted on a web
+     * server (false)
+     */
     this.isFileProtocolUsed = false;
     this.finishTrialPromise = new PromiseWrapper();
     this.timelineDependencies = {
@@ -2319,8 +2415,14 @@ class JsPsych {
     );
   }
   version() {
-    return _package.version;
-  }
+    return version;
+  }
+  /**
+   * Starts an experiment using the provided timeline and returns a promise that is resolved when
+   * the experiment is finished.
+   *
+   * @param timeline The timeline to be run
+   */
   async run(timeline) {
     if (typeof timeline === "undefined") {
       console.error("No timeline declared in jsPsych.run(). Cannot start experiment.");
@@ -2334,7 +2436,7 @@ class JsPsych {
     await this.prepareDom();
     await this.extensionManager.initializeExtensions();
     document.documentElement.setAttribute("jspsych", "present");
-    this.experimentStartTime = new Date();
+    this.experimentStartTime = /* @__PURE__ */ new Date();
     await this.timeline.run();
     await Promise.resolve(this.options.on_finish(this.data.get()));
     if (this.endMessage) {
@@ -2361,7 +2463,7 @@ class JsPsych {
     if (!this.experimentStartTime) {
       return 0;
     }
-    return new Date().getTime() - this.experimentStartTime.getTime();
+    return (/* @__PURE__ */ new Date()).getTime() - this.experimentStartTime.getTime();
   }
   getDisplayElement() {
     return this.displayElement;
@@ -2385,6 +2487,11 @@ class JsPsych {
       currentTimeline.abort();
     }
   }
+  /**
+   * Aborts a named timeline. The timeline must be currently running in order to abort it.
+   *
+   * @param name The name of the timeline to abort. Timelines can be given names by setting the `name` parameter in the description of the timeline.
+   */
   abortTimelineByName(name) {
     const timeline = this.timeline?.getActiveTimelineByName(name);
     if (timeline) {
@@ -2419,6 +2526,36 @@ class JsPsych {
   getTimeline() {
     return this.timeline?.description.timeline;
   }
+  /**
+   * Prints out a string containing citations for the jsPsych library and all input plugins/extensions in the specified format.
+   * If called without input, prints citation for jsPsych library.
+   *
+   * @param plugins The plugins/extensions to generate citations for. Always prints the citation for the jsPsych library at the top.
+   * @param format The desired output citation format. Currently supports "apa" and "bibtex".
+   * @returns String containing citations separated with newline character.
+   */
+  getCitations(plugins = [], format = "apa") {
+    const formatOptions = ["apa", "bibtex"];
+    format = format.toLowerCase();
+    if (!Array.isArray(plugins)) {
+      throw new Error("Expected array of plugins/extensions");
+    } else if (!formatOptions.includes(format)) {
+      throw new Error("Unsupported citation format");
+    } else {
+      const jsPsychCitation = this.citation[format];
+      const citationSet = /* @__PURE__ */ new Set([jsPsychCitation]);
+      for (const plugin of plugins) {
+        try {
+          const pluginCitation = plugin["info"].citations[format];
+          citationSet.add(pluginCitation);
+        } catch {
+          console.error(`${plugin} does not have citation in ${format} format.`);
+        }
+      }
+      const citationList = Array.from(citationSet).join("\n");
+      return citationList;
+    }
+  }
   get extensions() {
     return this.extensionManager?.extensions ?? {};
   }
@@ -2519,6 +2656,7 @@ function initJsPsych(options) {
     init: "`jsPsych.init()` was replaced by `initJsPsych()` in jsPsych v7.",
     ALL_KEYS: 'jsPsych.ALL_KEYS was replaced by the "ALL_KEYS" string in jsPsych v7.',
     NO_KEYS: 'jsPsych.NO_KEYS was replaced by the "NO_KEYS" string in jsPsych v7.',
+    // Getter functions that were renamed
     currentTimelineNodeID: "`currentTimelineNodeID()` was renamed to `getCurrentTimelineNodeID()` in jsPsych v7.",
     progress: "`progress()` was renamed to `getProgress()` in jsPsych v7.",
     startTime: "`startTime()` was renamed to `getStartTime()` in jsPsych v7.",