@adriansteffan/reactive 0.0.43 → 0.1.0

package/src/utils/bytecode.ts

@@ -11,6 +11,8 @@ type BaseTrialData = {
 export type ComponentResultData = BaseTrialData & {
   type: string;
   name: string;
+  /** Per-trial override for which CSV file(s) this trial's data goes into. When set on a timeline item, overrides the component type's default from the flattener registry. */
+  csv?: string | string[];
   responseData?: any;
   metadata?: Record<string, any>;
 };
@@ -21,16 +23,16 @@ export type CanvasResultData = BaseTrialData & {
   reactionTime: number | null;
 };
 
-export type RefinedTrialData = ComponentResultData | CanvasResultData;
+export type TrialResult = ComponentResultData | CanvasResultData;
 
 export interface MarkerItem {
   type: 'MARKER';
   id: string;
 }
 
-export type ConditionalFunction = (data?: RefinedTrialData[], store?: Store) => boolean;
+export type ConditionalFunction = (data?: TrialResult[], store?: Store) => boolean;
 
-export type StoreUpdateFunction = (data?: RefinedTrialData[], store?: Store) => Record<string, any>;
+export type StoreUpdateFunction = (data?: TrialResult[], store?: Store) => Record<string, any>;
 
 export interface IfGotoItem {
   type: 'IF_GOTO';
@@ -65,12 +67,12 @@ export interface ExecuteContentInstruction {
 }
 export interface IfGotoInstruction {
   type: 'IfGoto';
-  cond: (store: Store, data: RefinedTrialData[]) => boolean;
+  cond: (store: Store, data: TrialResult[]) => boolean;
   marker: string;
 }
 export interface UpdateStoreInstruction {
   type: 'UpdateStore';
-  fun: (store: Store, data: RefinedTrialData[]) => Store;
+  fun: (store: Store, data: TrialResult[]) => Store;
 }
 export type UnifiedBytecodeInstruction =
   | ExecuteContentInstruction
@@ -95,16 +97,16 @@ export function compileTimeline(timeline: TimelineItem[]): {
 
   function adaptCondition(
     userCondition: ConditionalFunction,
-  ): (store: Store, data: RefinedTrialData[]) => boolean {
-    return (runtimeStore: Store, runtimeData: RefinedTrialData[]): boolean => {
+  ): (store: Store, data: TrialResult[]) => boolean {
+    return (runtimeStore: Store, runtimeData: TrialResult[]): boolean => {
       return userCondition(runtimeData, runtimeStore);
     };
   }
 
   function adaptUpdate(
     userUpdateFunction: StoreUpdateFunction,
-  ): (store: Store, data: RefinedTrialData[]) => Store {
-    return (runtimeStore: Store, runtimeData: RefinedTrialData[]): Store => {
+  ): (store: Store, data: TrialResult[]) => Store {
+    return (runtimeStore: Store, runtimeData: TrialResult[]): Store => {
       const updates = userUpdateFunction(runtimeData, runtimeStore);
       if (typeof updates === 'object' && updates !== null) {
         return {
@@ -207,3 +209,53 @@ export function compileTimeline(timeline: TimelineItem[]): {
 
   return { instructions, markers };
 }
+
+/**
+ * Walks bytecode from `fromPointer`, processing IfGoto and UpdateStore instructions,
+ * and returns the pointer of the next ExecuteContent (or past-end if none found).
+ */
+export function applyMetadata<T extends Record<string, any>>(
+  trialData: T,
+  content: { metadata?: any; nestMetadata?: boolean },
+  data: TrialResult[],
+  store: Store,
+): T {
+  const metadata = typeof content.metadata === 'function' ? content.metadata(data, store) : content.metadata;
+  if (content.nestMetadata) return { ...trialData, metadata };
+  if (metadata) return { ...metadata, ...trialData };
+  return trialData;
+}
+
+export function advanceToNextContent(
+  bytecode: { instructions: UnifiedBytecodeInstruction[]; markers: Record<string, number> },
+  fromPointer: number,
+  getStore: () => Store,
+  getData: () => TrialResult[],
+  onUpdateStore: (newStore: Store) => void,
+): number {
+  let pointer = fromPointer;
+  while (pointer < bytecode.instructions.length) {
+    const instr = bytecode.instructions[pointer];
+    switch (instr.type) {
+      case 'ExecuteContent':
+        return pointer;
+      case 'IfGoto':
+        if (instr.cond(getStore(), getData())) {
+          const target = bytecode.markers[instr.marker];
+          if (target !== undefined) {
+            pointer = target;
+            continue;
+          }
+        }
+        pointer++;
+        break;
+      case 'UpdateStore':
+        onUpdateStore(instr.fun(getStore(), getData()));
+        pointer++;
+        break;
+      default:
+        pointer++;
+    }
+  }
+  return pointer;
+}

package/src/utils/common.ts

@@ -24,6 +24,8 @@ export interface TrialData {
   trialNumber: number;
   type: string;
   name: string;
+  /** Populated from the timeline item's csv field. Overrides the component type's default CSV target from the flattener registry. */
+  csv?: string | string[];
   responseData: any;
   start: number;
   end: number;
@@ -68,13 +70,14 @@ export function getParam<T extends ParamType>(
   defaultValue: ParamValue<T>,
   type: T = 'string' as T,
   description?: string,
+  uiDefault?: string,
 ): ParamValue<T> {
   let registryEntry = sharedRegistry.find((p) => p.name === name);
 
   if (!registryEntry) {
     registryEntry = {
       name,
-      defaultValue,
+      defaultValue: uiDefault !== undefined ? uiDefault : defaultValue,
       type,
       description,
       value: undefined,

package/src/utils/simulation.ts

@@ -0,0 +1,269 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import {
+  compileTimeline,
+  advanceToNextContent,
+  applyMetadata,
+  TrialResult,
+  ComponentResultData,
+  TimelineItem,
+  Store,
+} from './bytecode';
+
+
+export type ParticipantState = Record<string, any>;
+
+export type SimulatorResult = {
+  responseData: any;
+  participantState: ParticipantState;
+  storeUpdates?: Record<string, any>;
+  duration?: number;
+};
+
+export type SimulateFunction = (
+  trialProps: Record<string, any>,
+  experimentState: {
+    data: TrialResult[];
+    store: Store;
+  },
+  simulators: Record<string, any>,
+  participant: ParticipantState,
+) => SimulatorResult | Promise<SimulatorResult>;
+
+
+interface ComponentSimulation {
+  simulate: SimulateFunction;
+  defaultSimulators: Record<string, any>;
+}
+
+const simulationRegistry: Record<string, ComponentSimulation> = {};
+
+export function registerSimulation(
+  type: string,
+  simulate: SimulateFunction,
+  defaultSimulators: Record<string, any>,
+) {
+  simulationRegistry[type] = { simulate, defaultSimulators };
+}
+
+export function getSimulation(type: string): ComponentSimulation | undefined {
+  return simulationRegistry[type];
+}
+
+export const noopSimulate: SimulateFunction = (_trialProps, _experimentState, _simulators, participant) => ({
+  responseData: {},
+  participantState: participant,
+});
+
+export function resolveSimulation(content: any, data: TrialResult[], store: Store) {
+  const trialProps =
+    typeof content.props === 'function' ? content.props(data, store) : content.props || {};
+  const registration = simulationRegistry[content.type];
+  const simulateFn = typeof content.simulate === 'function' ? content.simulate : registration?.simulate;
+
+  if (!simulateFn) {
+    throw new Error(`No simulation registered for trial type '${content.type}' (name: '${content.name ?? 'unnamed'}'). Register one with registerSimulation() or add a simulate function to the timeline item.`);
+  }
+
+  const simulators = { ...registration?.defaultSimulators, ...content.simulators };
+  return { trialProps, simulateFn, simulators };
+}
+
+let _backendUrl = 'http://localhost:8001/backend';
+export function setBackendUrl(url: string) { _backendUrl = url; }
+export function getBackendUrl() { return _backendUrl; }
+
+let _initialParticipant: ParticipantState | undefined;
+export function getInitialParticipant() { return _initialParticipant; }
+
+
+export async function simulateParticipant(
+  timeline: TimelineItem[],
+  participant: ParticipantState,
+): Promise<TrialResult[]> {
+  _initialParticipant = { ...participant };
+  let currentParticipantState = { ...participant };
+  const bytecode = compileTimeline(timeline);
+  let store: Store = {};
+  const data: TrialResult[] = [
+    {
+      index: -1,
+      trialNumber: -1,
+      start: 0,
+      end: 0,
+      duration: 0,
+      type: '',
+      name: '',
+      responseData: { userAgent: 'simulated', params: {} },
+    },
+  ];
+  
+  const getStore = () => store;
+  const getData = () => data;
+  const onUpdateStore = (s: Store) => { store = s; };
+
+  let trialNumber = 0;
+  let currentTime = 0;
+
+  let pointer = advanceToNextContent(bytecode, 0, getStore, getData, onUpdateStore);
+
+  while (pointer < bytecode.instructions.length) {
+    const content = (bytecode.instructions[pointer] as any).content;
+    if (typeof content !== 'object' || content === null || typeof content.type !== 'string') {
+      pointer = advanceToNextContent(bytecode, pointer + 1, getStore, getData, onUpdateStore);
+      continue;
+    }
+
+    const { trialProps, simulateFn, simulators } = resolveSimulation(content, data, store);
+
+    const result = await simulateFn(
+      trialProps,
+      { data, store },
+      simulators,
+      currentParticipantState,
+    );
+    currentParticipantState = result.participantState;
+    if (result.storeUpdates) store = { ...store, ...result.storeUpdates };
+
+    trialNumber++;
+    const duration = result.duration ?? 0;
+    const startTime = currentTime;
+    currentTime += duration;
+
+    let trialData: ComponentResultData = {
+      index: pointer,
+      trialNumber,
+      start: startTime,
+      end: currentTime,
+      duration,
+      type: content.type,
+      name: content.name ?? '',
+      ...(content.csv !== undefined ? { csv: content.csv } : {}),
+      responseData: result.responseData,
+    };
+
+    data.push(applyMetadata(trialData, content, data, store));
+    pointer = advanceToNextContent(bytecode, pointer + 1, getStore, getData, onUpdateStore);
+  }
+
+  return data;
+}
+
+
+export interface RunSimulationConfig {
+  participants: ParticipantState[] | { generator: (index: number) => ParticipantState; count: number };
+  backendPort?: number;
+  concurrency?: number;
+}
+
+export async function orchestrateSimulation(config: RunSimulationConfig, scriptPath: string): Promise<void> {
+  const { spawn } = await import('child_process');
+
+  const port = config.backendPort ?? 8001;
+  const backendUrl = `http://localhost:${port}/backend`;
+
+  const participantCount = Array.isArray(config.participants)
+    ? config.participants.length
+    : config.participants.count;
+
+  const backend = spawn('npx', ['tsx', 'src/backend.ts'], {
+    cwd: './backend',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+
+  // Wait for backend to signal readiness before spawning workers
+  await new Promise<void>((resolve, reject) => {
+    backend.on('error', reject);
+
+    backend.stdout?.on('data', (data: any) => {
+      const msg = data.toString();
+      if (msg.includes('REACTIVE_BACKEND_READY')) {
+        resolve();
+      }
+    });
+
+    backend.stderr?.on('data', (data: any) => {
+      console.error(`[backend] ${data.toString().trim()}`);
+    });
+
+    setTimeout(() => reject(new Error('Backend did not start within 10 seconds')), 10000);
+  });
+
+  console.log(`Backend running on port ${port}`);
+
+  try {
+    const concurrency = config.concurrency ?? (await import('os')).cpus().length;
+    console.log(`Simulating ${participantCount} participants (concurrency: ${concurrency})...`);
+
+    let completed = 0;
+    const errors: { index: number; error: string }[] = [];
+
+    const writeProgress = () => {
+      const pct = Math.min(100, Math.round((completed / participantCount) * 100));
+      const filled = Math.floor(pct / 2);
+      const bar = '█'.repeat(filled) + '░'.repeat(50 - filled);
+      process.stdout.write(`\r  ${bar} ${completed}/${participantCount} (${pct}%)`);
+    };
+
+    const spawnWorker = (i: number) => new Promise<void>((resolve) => {
+      let stderr = '';
+      const worker = spawn('npx', ['tsx', scriptPath], {
+        env: {
+          ...process.env,
+          _REACTIVE_WORKER_INDEX: String(i),
+          _REACTIVE_BACKEND_URL: backendUrl,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      worker.stderr?.on('data', (data: any) => { stderr += data.toString(); });
+
+      worker.on('close', (code: number) => {
+        if (code !== 0) {
+          errors.push({ index: i, error: stderr.trim() || `exited with code ${code}` });
+        }
+        completed++;
+        writeProgress();
+        resolve();
+      });
+      worker.on('error', (err: Error) => {
+        errors.push({ index: i, error: err.message });
+        completed++;
+        writeProgress();
+        resolve();
+      });
+    });
+
+    writeProgress();
+
+    // Worker pool: always keep `concurrency` workers running
+    let nextIndex = 0;
+    await new Promise<void>((resolveAll) => {
+      const startNext = () => {
+        if (nextIndex >= participantCount) {
+          if (completed >= participantCount) resolveAll();
+          return;
+        }
+        const i = nextIndex++;
+        spawnWorker(i).then(startNext);
+      };
+      for (let j = 0; j < Math.min(concurrency, participantCount); j++) {
+        startNext();
+      }
+    });
+
+    process.stdout.write('\n');
+
+    if (errors.length > 0) {
+      console.error(`\n${errors.length} participant(s) failed:`);
+      for (const { index, error } of errors) {
+        console.error(`  Participant ${index}: ${error}`);
+      }
+    }
+
+    console.log(`Simulation complete. ${completed - errors.length}/${participantCount} participants simulated successfully.`);
+  } finally {
+    backend.kill();
+    console.log('Backend stopped.');
+  }
+}

package/src/utils/upload.ts

@@ -0,0 +1,201 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { FileUpload, Store, TrialData } from './common';
+
+type DataObject = {
+  [key: string]: string | number | boolean | null | undefined;
+};
+
+
+const flattenerRegistry: Record<string, {
+  csv: string | null;
+  flatten?: (item: TrialData) => any[];
+}[]> = {};
+
+export function registerFlattener(
+  type: string,
+  csv: string | null,
+  flatten?: (item: TrialData) => any[],
+) {
+  if (!flattenerRegistry[type]) flattenerRegistry[type] = [];
+  flattenerRegistry[type].push({ csv, flatten });
+}
+
+export function escapeCsvValue(value: any): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  const stringValue = String(value);
+
+  if (stringValue.includes(',') || stringValue.includes('"') || stringValue.includes('\n')) {
+    const escapedValue = stringValue.replace(/"/g, '""');
+    return `"${escapedValue}"`;
+  }
+
+  return stringValue;
+}
+
+export function convertArrayOfObjectsToCSV(data: DataObject[]): string {
+  if (!data || data.length === 0) {
+    return '';
+  }
+
+  const headerSet = new Set<string>();
+  data.forEach((obj) => {
+    Object.keys(obj).forEach((key) => {
+      headerSet.add(key);
+    });
+  });
+  const headers = Array.from(headerSet);
+
+  const headerRow = headers.map((header) => escapeCsvValue(header)).join(',');
+
+  const dataRows = data.map((obj) => {
+    return headers
+      .map((header) => {
+        const value = obj[header];
+        return escapeCsvValue(value);
+      })
+      .join(',');
+  });
+
+  return [headerRow, ...dataRows].join('\n');
+}
+
+// Extracts experiment parameter values (URL params / registered params) from the initial metadata trial.
+// Each param entry has { value, defaultValue, ... } — we pick value if set, otherwise the default.
+function extractParams(data: any[]): Record<string, any> {
+  const paramsSource = data?.[0]?.responseData?.params;
+  if (!paramsSource || typeof paramsSource !== 'object') return {};
+  const result: Record<string, any> = {};
+  for (const [name, details] of Object.entries(paramsSource) as [string, any][]) {
+    if (details && typeof details === 'object') {
+      result[name] = details.value ?? details.defaultValue;
+    }
+  }
+  return result;
+}
+
+// Built-in fields on every trial data object — not user data.
+// Used to distinguish user-provided metadata from framework fields when building CSVs.
+const trialBuiltinKeys = new Set(['index', 'trialNumber', 'start', 'end', 'duration', 'type', 'name', 'csv', 'responseData', 'metadata']);
+// Subset of builtins that represent trial identity/timing — included in non-session CSVs with trial_ prefix
+const trialInfoKeys = new Set(['index', 'trialNumber', 'start', 'end', 'duration', 'type', 'name']);
+
+// Automatically builds CSV files from trial data using the flattener registry.
+// Each trial is routed to a CSV file based on: item.csv override > registry default > skipped.
+// The 'session' group is special: all trials merge into a single row, with keys namespaced
+// by trial name (e.g. 'nickname_value', 'devicecheck_browser') to avoid collisions.
+// All other groups produce multi-row CSVs, one row per trial (or more if the flattener expands them).
+function autoBuildCSVs(sessionID: string, data: any[], sessionData?: Record<string, any>): FileUpload[] {
+  const files: FileUpload[] = [];
+
+  // Group trials by their target CSV file name.
+  // A component can register multiple targets, so one trial may appear in multiple groups.
+  // A per-item csv override replaces all registered targets.
+  const groups: Record<string, { item: any; flatten?: (item: TrialData) => any[] }[]> = {};
+  for (const item of data) {
+    if (item.index === -1) continue; // skip initial metadata entry
+    const csvOverride = item.csv;
+    const targets = csvOverride
+      ? (Array.isArray(csvOverride) ? csvOverride : [csvOverride]).map((csv: string) => ({ csv }))
+      : flattenerRegistry[item.type] ?? [];
+    for (const target of targets) {
+      if (!target.csv) continue;
+      if (!groups[target.csv]) groups[target.csv] = [];
+      groups[target.csv].push({ item, flatten: 'flatten' in target ? target.flatten : undefined });
+    }
+  }
+
+  // 'session' group: one row per participant with metadata + responseData namespaced by trial name
+  if (groups['session']) {
+    const row: Record<string, any> = {
+      sessionID,
+      userAgent: data?.[0]?.responseData?.userAgent,
+      ...extractParams(data),
+      ...sessionData,
+    };
+    for (const { item } of groups['session']) {
+      const prefix = item.name || item.type;
+      // Add user-provided metadata (non-builtin top-level keys), namespaced by trial name
+      for (const [key, value] of Object.entries(item)) {
+        if (!trialBuiltinKeys.has(key)) row[`${prefix}_${key}`] = value;
+      }
+      // Add responseData fields, namespaced by trial name
+      if (item.responseData && typeof item.responseData === 'object' && !Array.isArray(item.responseData)) {
+        for (const [key, value] of Object.entries(item.responseData)) {
+          row[`${prefix}_${key}`] = value;
+        }
+      }
+    }
+    files.push({
+      filename: `session.${sessionID}.${Date.now()}.csv`,
+      content: convertArrayOfObjectsToCSV([row]),
+      encoding: 'utf8' as const,
+    });
+    delete groups['session'];
+  }
+
+  // All other groups: multi-row CSVs using registered flatteners (or raw responseData spread).
+  // Each row is prepended with standard trial fields (prefixed trial_) plus any extra
+  // metadata fields (unprefixed). The flattener's output overwrites these if keys collide.
+  for (const [csvName, entries] of Object.entries(groups)) {
+    const rows = entries.flatMap(({ item, flatten }) => {
+      const base: Record<string, any> = {};
+      for (const [key, value] of Object.entries(item)) {
+        if (trialBuiltinKeys.has(key)) {
+          if (trialInfoKeys.has(key)) base[`trial_${key}`] = value;
+        } else {
+          base[key] = value;
+        }
+      }
+      // When no flatten function is registered, spread responseData directly.
+      const flatRows = flatten
+        ? flatten(item)
+        : [item.responseData && typeof item.responseData === 'object' ? { ...item.responseData } : {}];
+      return flatRows.map((row: any) => ({ ...base, ...row }));
+    });
+    if (rows.length > 0) {
+      files.push({
+        filename: `${csvName}.${sessionID}.${Date.now()}.csv`,
+        content: convertArrayOfObjectsToCSV(rows),
+        encoding: 'utf8' as const,
+      });
+    }
+  }
+
+  return files;
+}
+
+export function buildUploadFiles(config: {
+  sessionID: string;
+  data: any[];
+  store?: Store;
+  generateFiles?: (sessionID: string, data: any[], store?: Store) => FileUpload[];
+  sessionData?: Record<string, any>;
+  uploadRaw?: boolean;
+}): FileUpload[] {
+  const {
+    sessionID,
+    data,
+    store,
+    generateFiles,
+    sessionData,
+    uploadRaw = true,
+  } = config;
+
+  const files: FileUpload[] = generateFiles ? generateFiles(sessionID, data, store) : [];
+
+  if (uploadRaw) {
+    files.push({
+      filename: `${sessionID}.raw.json`,
+      content: JSON.stringify(data),
+      encoding: 'utf8',
+    });
+  }
+
+  files.push(...autoBuildCSVs(sessionID, data, sessionData));
+
+  return files;
+}

package/template/README.md

@@ -85,6 +85,65 @@ To update the app, simply stop the running containers, run a `git pull` and buil
 The server will create a "data" directory in the root directory of the cloned repo,
 
 
+## Simulation
+
+You can simulate your experiment headlessly to generate synthetic data, test your data pipeline, or plan sample sizes.
+
+### Setup
+
+Define your participant generator and simulation config in `Experiment.tsx`:
+
+```tsx
+export const simulationConfig = {
+  participants: {
+    generator: (i) => ({ id: i, nickname: `participant_${i}` }),
+    count: 10,
+  },
+};
+```
+
+### Running
+
+```
+npm run simulate
+```
+
+This starts the backend, simulates all participants through the experiment, and shuts down. The simulated data ends up in `backend/data/`.
+
+### Customizing participant behavior
+
+Each trial component has default decision functions that model participant behavior. Override them per-trial using the `simulators` property on a timeline item:
+
+```tsx
+{
+  type: 'PlainInput',
+  props: { content: <p>What is your name?</p> },
+  simulators: {
+    respond: (_trialProps, participant) => ({
+      value: participant.nickname,
+      participantState: participant,
+    }),
+  },
+}
+```
+
+### Custom components
+
+Register simulations for your custom trial components using `registerSimulation`. See the `CustomTrial` example in `Experiment.tsx` and the [reactive README](https://github.com/adriansteffan/reactive) for details.
+
+### Hybrid mode
+
+During development, auto-advance simulated trials while manually interacting with others:
+
+Add `?hybridSimulation=true` to the URL:
+
+```
+http://localhost:5173?hybridSimulation=true
+```
+
+Trials with `simulators` or `simulate: true` defined will auto-advance. Others render normally for human interaction. Hybrid mode is enabled by default during development. For production, set `VITE_DISABLE_HYBRID_SIMULATION=true` to disable it.
+
+
 ## Target: Windows or MacOS
 
 ### Development