bead 0.1.0__py3-none-any.whl

bead/deployment/jspsych/src/types/jspsych.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Type declarations for jsPsych 8.x plugin API.
+ *
+ * These types define the interfaces needed for creating jsPsych plugins
+ * and interacting with the jsPsych runtime.
+ */
+
+/** Parameter types available in jsPsych */
+export const ParameterType: {
+  readonly BOOL: 0;
+  readonly STRING: 1;
+  readonly INT: 2;
+  readonly FLOAT: 3;
+  readonly FUNCTION: 4;
+  readonly KEY: 5;
+  readonly KEYS: 6;
+  readonly SELECT: 7;
+  readonly HTML_STRING: 8;
+  readonly IMAGE: 9;
+  readonly AUDIO: 10;
+  readonly VIDEO: 11;
+  readonly OBJECT: 12;
+  readonly COMPLEX: 13;
+  readonly TIMELINE: 14;
+};
+
+export type ParameterTypeValue = (typeof ParameterType)[keyof typeof ParameterType];
+
+/** Definition of a single parameter in plugin info */
+export interface ParameterInfo {
+  type: ParameterTypeValue;
+  pretty_name?: string;
+  default?: unknown;
+  description?: string;
+  array?: boolean;
+  options?: readonly string[];
+  nested?: Record<string, ParameterInfo>;
+}
+
+/** Plugin info object that defines the plugin's parameters */
+export interface PluginInfo {
+  name: string;
+  parameters: Record<string, ParameterInfo>;
+}
+
+/** Keyboard response info returned by getKeyboardResponse callback */
+export interface KeyboardResponseInfo {
+  key: string;
+  rt: number;
+}
+
+/** Plugin API methods available to plugins */
+export interface PluginAPI {
+  getKeyboardResponse(options: {
+    callback_function: (info: KeyboardResponseInfo) => void;
+    valid_responses?: string[] | "ALL_KEYS" | "NO_KEYS";
+    rt_method?: "performance" | "date";
+    persist?: boolean;
+    allow_held_key?: boolean;
+    minimum_valid_rt?: number;
+  }): unknown;
+
+  cancelKeyboardResponse(listener: unknown): void;
+
+  cancelAllKeyboardResponses(): void;
+
+  compareKeys(key1: string | null, key2: string | null): boolean;
+
+  setTimeout(callback: () => void, delay: number): number;
+
+  clearAllTimeouts(): void;
+}
+
+/** Data API for accessing and modifying experiment data */
+export interface DataAPI {
+  get(): {
+    json(): string;
+    csv(): string;
+    values(): TrialData[];
+    filter(filters: Record<string, unknown> | ((trial: TrialData) => boolean)): DataAPI;
+    filterCustom(fn: (trial: TrialData) => boolean): DataAPI;
+    select(column: string): { values: unknown[] };
+    count(): number;
+  };
+
+  addProperties(properties: Record<string, unknown>): void;
+
+  write(data: TrialData): void;
+}
+
+/** Trial data object */
+export interface TrialData {
+  trial_type?: string;
+  trial_index?: number;
+  time_elapsed?: number;
+  [key: string]: unknown;
+}
+
+/** Extension interface for jsPsych extensions */
+export interface JsPsychExtension {
+  initialize?(params: Record<string, unknown>): Promise<void> | void;
+  on_start?(params: Record<string, unknown>): void;
+  on_load?(params: Record<string, unknown>): void;
+  on_finish?(params: Record<string, unknown>): Record<string, unknown> | undefined;
+}
+
+/** Extension info */
+export interface ExtensionInfo {
+  name: string;
+}
+
+/** Main jsPsych instance interface */
+export interface JsPsych {
+  version(): string;
+
+  pluginAPI: PluginAPI;
+
+  data: DataAPI;
+
+  run(timeline: TimelineNode[]): Promise<void>;
+
+  finishTrial(data?: Record<string, unknown>): void;
+
+  endExperiment(end_message?: string, data?: Record<string, unknown>): void;
+
+  getCurrentTrial(): TimelineNode | null;
+
+  getDisplayElement(): HTMLElement;
+
+  getProgressBarCompleted(): number;
+
+  setProgressBar(value: number): void;
+
+  timelineVariable(variable_name: string): unknown;
+
+  pauseExperiment(): void;
+
+  resumeExperiment(): void;
+
+  abortCurrentTimeline(): void;
+
+  abortExperiment(end_message?: string): void;
+
+  getStartTime(): number;
+
+  getTotalTime(): number;
+
+  getDisplayContainerElement(): HTMLElement;
+}
+
+/** Timeline node (trial) structure */
+export interface TimelineNode {
+  type?: unknown;
+  timeline?: TimelineNode[];
+  timeline_variables?: Record<string, unknown>[];
+  conditional_function?: () => boolean;
+  loop_function?: (data: DataAPI) => boolean;
+  on_start?: (trial: TimelineNode) => void;
+  on_load?: () => void;
+  on_finish?: (data: TrialData) => void;
+  data?: Record<string, unknown>;
+  extensions?: Array<{
+    type: unknown;
+    params?: Record<string, unknown>;
+  }>;
+  [key: string]: unknown;
+}
+
+/** jsPsych plugin class interface */
+export interface JsPsychPlugin<Info extends PluginInfo, TrialParams = Record<string, unknown>> {
+  trial(
+    display_element: HTMLElement,
+    trial: TrialParams,
+    on_load?: () => void,
+  ): void | Promise<void>;
+}
+
+/** Extract trial parameter types from plugin info */
+export type TrialType<Info extends PluginInfo> = {
+  [K in keyof Info["parameters"]]: Info["parameters"][K] extends {
+    default: infer D;
+  }
+    ? Info["parameters"][K]["type"] extends typeof ParameterType.STRING
+      ? string
+      : Info["parameters"][K]["type"] extends typeof ParameterType.INT
+        ? number
+        : Info["parameters"][K]["type"] extends typeof ParameterType.FLOAT
+          ? number
+          : Info["parameters"][K]["type"] extends typeof ParameterType.BOOL
+            ? boolean
+            : Info["parameters"][K]["type"] extends typeof ParameterType.OBJECT
+              ? Record<string, unknown>
+              : Info["parameters"][K]["type"] extends typeof ParameterType.HTML_STRING
+                ? string
+                : D
+    : unknown;
+};
+
+/** jsPsych module declaration for global access in browser */
+declare global {
+  const jsPsychModule: {
+    ParameterType: typeof ParameterType;
+  };
+
+  function initJsPsych(options?: {
+    display_element?: HTMLElement | string;
+    on_trial_start?: (trial: TimelineNode) => void;
+    on_trial_finish?: (data: TrialData) => void;
+    on_data_update?: (data: TrialData) => void;
+    on_interaction_data_update?: (data: Record<string, unknown>) => void;
+    on_close?: () => void;
+    on_finish?: (data: DataAPI) => void;
+    show_progress_bar?: boolean;
+    auto_update_progress_bar?: boolean;
+    message_progress_bar?: string;
+    extensions?: Array<{
+      type: unknown;
+      params?: Record<string, unknown>;
+    }>;
+    override_safe_mode?: boolean;
+    case_sensitive_responses?: boolean;
+    minimum_valid_rt?: number;
+    experiment_width?: number;
+  }): JsPsych;
+
+  /** jsPsych HTML keyboard response plugin */
+  const jsPsychHtmlKeyboardResponse: unknown;
+}

bead/deployment/jspsych/templates/experiment.css

@@ -0,0 +1 @@
+/* Minimal custom styles - let jsPsych handle the layout */

bead/deployment/jspsych/templates/experiment.js.template

@@ -0,0 +1,289 @@
+/**
+ * jsPsych 8.x Batch Experiment
+ * Generated by bead deployment system
+ *
+ * Experiment: {{ title }}
+ * Description: {{ description }}
+ */
+
+// Global variables
+let distributor = null;
+{% if slopit_enabled %}
+let slopitExtension = null;
+{% endif %}
+
+/**
+ * Main experiment entry point.
+ * Loads data, assigns list, and runs experiment.
+ */
+async function runExperiment() {
+    try {
+        // Load distribution config
+        const distConfig = await fetch('data/distribution.json').then(r => r.json());
+
+        // Load lists from JSONL
+        const lists = await loadLists('data/lists.jsonl');
+
+        // Load items from JSONL
+        const items = await loadItems('data/items.jsonl');
+
+        // Initialize list distributor
+        distributor = new ListDistributor(distConfig, lists);
+
+        // Assign list to this participant
+        const listIndex = await distributor.initialize();
+        const assignedList = distributor.getAssignedList();
+
+        console.log(`Assigned to list: ${assignedList.name} (index: ${listIndex})`);
+
+        {% if slopit_enabled %}
+        // Initialize slopit extension
+        slopitExtension = new SlopitExtension({
+            keystroke: {{ slopit_config.keystroke | tojson }},
+            focus: {{ slopit_config.focus | tojson }},
+            paste: {{ slopit_config.paste | tojson }},
+            targetSelectors: {{ slopit_config.target_selectors | tojson }}
+        });
+        {% endif %}
+
+        // Initialize jsPsych
+        const jsPsych = initJsPsych({
+            {% if slopit_enabled %}
+            extensions: [
+                { type: slopitExtension }
+            ],
+            {% endif %}
+            {% if use_jatos %}
+            on_trial_start: jatos.addAbortButton,
+            {% endif %}
+            on_finish: async function() {
+                // Mark as completed in batch session
+                if (distributor) {
+                    await distributor.markCompleted();
+                }
+
+                {% if use_jatos %}
+                // Submit data and end study
+                const resultData = jsPsych.data.get().json();
+                {% if on_finish_url %}
+                jatos.submitResultData(resultData)
+                    .then(() => jatos.endStudyAndRedirect("{{ on_finish_url }}"))
+                    .catch((error) => {
+                        console.error("Failed to submit data:", error);
+                        jatos.endStudyAndRedirect("{{ on_finish_url }}");
+                    });
+                {% else %}
+                jatos.submitResultData(resultData)
+                    .then(() => jatos.endStudy(true))
+                    .catch((error) => {
+                        console.error("Failed to submit data:", error);
+                        jatos.endStudy(false);
+                    });
+                {% endif %}
+                {% else %}
+                {% if on_finish_url %}
+                window.location.href = "{{ on_finish_url }}";
+                {% endif %}
+                {% endif %}
+            },
+            show_progress_bar: {{ 'true' if show_progress_bar else 'false' }},
+            auto_update_progress_bar: {{ 'true' if show_progress_bar else 'false' }}
+        });
+
+        {% if use_jatos %}
+        // Add JATOS metadata
+        jsPsych.data.addProperties({
+            experiment_title: "{{ title }}",
+            participant_id: jatos.urlQueryParameters.PROLIFIC_PID || jatos.workerId,
+            prolific_pid: jatos.urlQueryParameters.PROLIFIC_PID || null,
+            prolific_study_id: jatos.urlQueryParameters.STUDY_ID || null,
+            prolific_session_id: jatos.urlQueryParameters.SESSION_ID || null,
+            jatos_worker_id: jatos.workerId,
+            jatos_study_result_id: jatos.studyResultId,
+            jatos_component_result_id: jatos.componentResultId,
+            assigned_list_index: listIndex,
+            assigned_list_name: assignedList.name,
+            assigned_list_id: assignedList.id,
+            experiment_start_time: new Date().toISOString(),
+        });
+        {% else %}
+        jsPsych.data.addProperties({
+            experiment_title: "{{ title }}",
+            assigned_list_index: listIndex,
+            assigned_list_name: assignedList.name,
+            assigned_list_id: assignedList.id,
+            experiment_start_time: new Date().toISOString(),
+        });
+        {% endif %}
+
+        // Build timeline
+        const timeline = [];
+
+        // Demographics form (if enabled, appears before instructions)
+        {% if demographics_enabled %}
+        timeline.push({
+            type: jsPsychSurvey,
+            title: "{{ demographics_title }}",
+            pages: [
+                [
+                    {% for field in demographics_fields %}
+                    {
+                        name: "{{ field.name }}",
+                        prompt: "{{ field.label }}",
+                        required: {{ 'true' if field.required else 'false' }},
+                        {% if field.field_type == 'text' %}
+                        type: 'text'{% if field.placeholder %},
+                        placeholder: "{{ field.placeholder }}"{% endif %}
+                        {% elif field.field_type == 'number' %}
+                        type: 'text',
+                        input_type: 'number'{% if field.range_min is defined %},
+                        min: {{ field.range_min }},
+                        max: {{ field.range_max }}{% endif %}{% if field.placeholder %},
+                        placeholder: "{{ field.placeholder }}"{% endif %}
+                        {% elif field.field_type == 'dropdown' %}
+                        type: 'drop-down',
+                        options: {{ field.options | tojson }}
+                        {% elif field.field_type == 'radio' %}
+                        type: 'multi-choice',
+                        options: {{ field.options | tojson }}
+                        {% elif field.field_type == 'checkbox' %}
+                        type: 'multi-select',
+                        options: {{ field.options | tojson }}
+                        {% endif %}
+                    }{% if not loop.last %},{% endif %}
+                    {% endfor %}
+                ]
+            ],
+            button_label_finish: "{{ demographics_submit_text }}",
+            data: {
+                trial_type: 'demographics'
+            }
+        });
+        {% endif %}
+
+        // Instructions
+        {% if instructions_is_multi_page %}
+        // Multi-page instructions using jsPsych instructions plugin
+        timeline.push({
+            type: jsPsychInstructions,
+            pages: [
+                {% for page in instructions_pages %}
+                `<div class="instructions-page">
+                    {% if page.title %}<h2>{{ page.title }}</h2>{% endif %}
+                    <div>{{ page.content }}</div>
+                    {% if instructions_show_page_numbers and instructions_pages|length > 1 %}
+                    <p class="page-number">Page {{ loop.index }} of {{ instructions_pages|length }}</p>
+                    {% endif %}
+                </div>`{% if not loop.last %},{% endif %}
+                {% endfor %}
+            ],
+            show_clickable_nav: true,
+            allow_backward: {{ 'true' if instructions_allow_backwards else 'false' }},
+            button_label_next: "{{ instructions_button_next }}",
+            button_label_previous: "Previous",
+            button_label_finish: "{{ instructions_button_finish }}",
+            data: {
+                trial_type: 'instructions'
+            }
+        });
+        {% elif instructions %}
+        // Simple single-page instructions
+        timeline.push({
+            type: jsPsychHtmlKeyboardResponse,
+            stimulus: `
+                <div class="instructions">
+                    <h2>Instructions</h2>
+                    <p>{{ instructions }}</p>
+                    <p><em>Press any key to continue</em></p>
+                </div>
+            `,
+            data: {
+                trial_type: 'instructions'
+            }
+        });
+        {% endif %}
+
+        // Get items for assigned list
+        const listItemIds = assignedList.item_refs;
+        if (!listItemIds || listItemIds.length === 0) {
+            throw new Error(
+                `Assigned list '${assignedList.name}' has no items. ` +
+                `Check that lists were created with items before generate().`
+            );
+        }
+
+        // Look up items by UUID
+        const listItems = listItemIds.map(itemId => {
+            const item = items[itemId];
+            if (!item) {
+                throw new Error(
+                    `Item ${itemId} referenced in list '${assignedList.name}' not found in items.jsonl. ` +
+                    `Verify all items were serialized correctly.`
+                );
+            }
+            return item;
+        });
+
+        // Load pre-generated trials for this list
+        const trialsData = await fetch('data/trials.json').then(r => r.json());
+        const listTrials = trialsData[assignedList.id];
+        
+        if (!listTrials || listTrials.length === 0) {
+            throw new Error(
+                `No trials found for list '${assignedList.name}' (id: ${assignedList.id}). ` +
+                `Ensure trials were generated correctly.`
+            );
+        }
+
+        // Add pre-generated trials to timeline
+        for (const trial of listTrials) {
+            timeline.push(trial);
+        }
+
+        // Completion
+        timeline.push({
+            type: jsPsychHtmlKeyboardResponse,
+            stimulus: `
+                <div class="completion">
+                    <h2>✓ Complete</h2>
+                    <p>Thank you for participating!</p>
+                    <p>Your responses have been recorded.</p>
+                    {% if on_finish_url %}
+                    <p><em>You will be redirected shortly...</em></p>
+                    {% else %}
+                    <p><em>You may close this window.</em></p>
+                    {% endif %}
+                </div>
+            `,
+            choices: "NO_KEYS",
+            trial_duration: {% if on_finish_url %}2000{% else %}null{% endif %},
+            data: {
+                trial_type: 'completion'
+            }
+        });
+
+        // Run experiment
+        await jsPsych.run(timeline);
+
+    } catch (error) {
+        console.error('Experiment error:', error);
+        document.body.innerHTML = `
+            <div style="max-width: 600px; margin: 100px auto; padding: 20px; border: 2px solid #d00; background: #fee;">
+                <h2>Experiment Error</h2>
+                <p><strong>Error:</strong> ${error.message}</p>
+                <p>Please contact the experiment administrator.</p>
+                <pre style="background: #fff; padding: 10px; overflow: auto;">${error.stack}</pre>
+            </div>
+        `;
+    }
+}
+
+{% if use_jatos %}
+// Wait for JATOS to load
+jatos.onLoad(() => {
+    runExperiment();
+});
+{% else %}
+// Run immediately
+runExperiment();
+{% endif %}

bead/deployment/jspsych/templates/index.html

@@ -0,0 +1,51 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ title }}</title>
+
+    <!-- jsPsych 8.x CSS -->
+    <link href="https://unpkg.com/jspsych@8.0.0/css/jspsych.css" rel="stylesheet" type="text/css" />
+
+    <!-- Material Design Icons (optional) -->
+    <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+
+    <!-- Google Fonts -->
+    <link href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;700&display=swap" rel="stylesheet">
+
+    <!-- Custom experiment CSS -->
+    <link href="css/experiment.css" rel="stylesheet" type="text/css" />
+
+    <!-- jsPsych 8.x Core -->
+    <script src="https://unpkg.com/jspsych@8.0.0"></script>
+
+    <!-- jsPsych 8.x Plugins -->
+    <script src="https://unpkg.com/@jspsych/plugin-html-keyboard-response@2.0.0"></script>
+    <script src="https://unpkg.com/@jspsych/plugin-html-button-response@2.0.0"></script>
+    <script src="https://unpkg.com/@jspsych/plugin-html-slider-response@2.0.0"></script>
+    <script src="https://unpkg.com/@jspsych/plugin-preload@2.0.0"></script>
+
+    <!-- Seedrandom for reproducible randomization -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/seedrandom/3.0.5/seedrandom.min.js"></script>
+
+    {% if use_jatos %}
+    <!-- JATOS integration -->
+    <script src="jatos.js"></script>
+    {% endif %}
+
+    <!-- List distribution system -->
+    <script src="js/list_distributor.js"></script>
+
+    {% if slopit_enabled %}
+    <!-- Slopit behavioral capture -->
+    <script src="js/slopit-bundle.js"></script>
+    {% endif %}
+</head>
+<body class="theme-{{ ui_theme }}">
+    <div id="jspsych-target"></div>
+
+    <!-- Main experiment script -->
+    <script src="js/experiment.js"></script>
+</body>
+</html>