What is your name?
},\n simulators: {\n respond: (_trialProps, participant) => ({\n value: participant.nickname,\n participantState: participant,\n }),\n },\n}\n```\n\nThe override is merged with the registered defaults — you only need to specify the decision functions you want to change.\n\n### Custom components\n\nRegister a simulation for your custom components using `registerSimulation`:\n\n```tsx\nregisterSimulation('MyTrial',\n // Simulate function: uses shared trial logic + decision functions\n (trialProps, experimentState, simulators, participant) => {\n const choice = simulators.decide(trialProps, participant);\n return { responseData: { choice: choice.value }, participantState: choice.participantState };\n },\n // Default simulators: one per decision point\n {\n decide: (_trialProps, participant) => ({\n value: 'default_choice',\n participantState: participant,\n }),\n },\n);\n```\n\nThe simulate function orchestrates the trial logic. The decision functions are the parts where a human would interact — these are what users override to model different participant behaviors.\n\n### Hybrid mode\n\nDuring development, you can auto-advance simulated trials while manually interacting with others. Add `?hybridSimulation=true` to the URL during development:\n\n```\nhttp://localhost:5173?hybridSimulation=true\n```\n\nTrials with `simulators` or `simulate: true` defined on them will auto-advance. Trials without them render normally for human interaction.\n\nHybrid mode is enabled by default during development. For production, set `VITE_DISABLE_HYBRID_SIMULATION=true` to disable it regardless of URL parameters.\n\n### Reproducible simulations\n\nAdd `seed` to your simulation config to make runs fully reproducible:\n\n```tsx\nexport const simulationConfig = {\n seed: 42,\n participants: () => sampleParticipants('sobol', 100, {\n needForCognition: { distribution: 'normal', mean: 3.5, sd: 0.8 },\n agreeableness: { distribution: 'normal', mean: 3.0, sd: 1.0 },\n age: { distribution: 'uniform', min: 18, max: 65 },\n }),\n};\n```\n\nEach simulated participant runs in its own subprocess. The `seed` controls two separate phases:\n\n- **Participant generation**: The `participants` factory function is called with the base `seed` (same for all workers), so every worker generates the same participant list.\n- **Simulation behavior**: Module-level randomness (group assignment, trial order) and simulator callbacks are seeded with `seed + participantIndex`, so each participant gets a unique but reproducible random stream.\n\nWithout `seed`, simulations use random entropy and will vary between runs. When seeded, `Math.random()` is also patched to use the seeded PRNG, so existing code and third-party libraries are automatically reproducible.\n\n**Note:** Do not close over module-level random values into the factory function — module-level code runs with a per-worker seed, so captured values would differ between workers. Keep all participant generation logic inside the factory.\n\n```tsx\n// Good: all randomness is inside the factory\nparticipants: () => {\n const base = sampleParticipants('random', 100, {\n openness: { distribution: 'normal', mean: 3.5, sd: 0.8 },\n });\n return base.map((p, i) => ({\n ...p,\n curiosity: p.openness * 0.7 + normal(0, 0.3),\n id: i,\n }));\n},\n\n// Bad: module-level value captured into factory\nconst noise = normal(0, 1); // different per worker!\nparticipants: () => [{ trait: noise }],\n```\n\nTo model distinct populations, combine them inside the factory:\n\n```tsx\nparticipants: () => {\n const smokers = sampleParticipants('sobol', 50, {\n alertness: { distribution: 'normal', mean: 2.8, sd: 0.7 },\n }).map((p) => ({ ...p, smoker: true }));\n\n const nonSmokers = sampleParticipants('sobol', 50, {\n alertness: { distribution: 'normal', mean: 3.6, sd: 0.5 },\n }).map((p) => ({ ...p, smoker: false }));\n\n return [...smokers, ...nonSmokers];\n},\n```\n\n### Built-in simulator decision functions\n\n| Component | Decision functions | Default behavior |\n|---|---|---|\n| Text | `respond` | Click button, random reaction time |\n| PlainInput | `respond` | Returns `'simulated_input'` |\n| Quest | `answerQuestion` | Random valid answer per question type |\n| CanvasBlock | `respondToSlide` | Random key from `allowedKeys`, random RT |\n| Tutorial | `respondToSlide` | Advances through slides, no interaction data |\n| RandomDotKinematogram | `respond` | Random key from `validKeys`, random RT (may timeout) |\n| Upload | *(none)* | Builds CSVs and POSTs to backend |\n| StoreUI | *(none)* | Uses field default values |\n| CheckDevice | *(none)* | Returns simulated device info |\n| VoiceRecording | `respondTTS`, `respondBase64` | Platform TTS with default text; falls back to dummy sine tone |\n| EnterFullscreen, ExitFullscreen, MicrophoneCheck, ProlificEnding, RequestFilePermission | *(none)* | No-op, advances immediately |\n\n\n## Data Saving\n\nReactive automatically builds CSV files from experiment data using a registry-based system. Each component type registers a default CSV target, and the Upload component discovers these at the end of the experiment.\n\n### How it works\n\nEach component type registers where its data should go via `registerFlattener`:\n\n```tsx\nregisterFlattener('PlainInput', 'session'); // merge into session CSV\nregisterFlattener('CanvasBlock', 'canvas', flattenFn); // own CSV with custom flattener\nregisterFlattener('ProlificEnding', null); // no CSV output\n```\n\nBuilt-in components come pre-registered. The Upload component produces CSVs automatically with no props needed:\n\n```tsx\n{ name: 'upload', type: 'Upload' }\n```\n\n### Built-in defaults\n\n| Component | Default CSV | Notes |\n|---|---|---|\n| PlainInput, Quest, CheckDevice, EnterFullscreen, ExitFullscreen, MicrophoneCheck | `session` | Merged into single session row, namespaced by trial name |\n| Text | `text` | One row per Text component |\n| CanvasBlock | `canvas` | One row per slide, with built-in flattener |\n| StoreUI | `storeui` | One row per StoreUI occurrence |\n| Tutorial | `session` | Merged into session row |\n| RandomDotKinematogram | `rdk` | One row per RDK trial |\n| ProlificEnding, Upload, RequestFilePermission | *(none)* | No CSV output |\n\n### Output files\n\nFor a session `abc123`, the Upload component produces:\n- `abc123.raw.json` — full raw data\n- `session.abc123.{timestamp}.csv` — one row with params, userAgent, and all session-level trial data namespaced by trial name (e.g. `nickname_value`, `devicecheck_browser`)\n- `canvas.abc123.{timestamp}.csv` — multi-row CSV from CanvasBlock trials\n- One CSV per additional group (text, storeui, or any custom group)\n\n### Per-item CSV override\n\nOverride the default target on any timeline item:\n\n```tsx\n{ name: 'practice', type: 'CanvasBlock', csv: 'practice', ... } // separate from main canvas\n{ name: 'main', type: 'CanvasBlock', ... } // uses default 'canvas'\n```\n\nRoute a trial to multiple CSVs with an array:\n\n```tsx\n{ name: 'survey', type: 'Quest', csv: ['session', 'survey'], ... } // both session row and own file\n```\n\n### Adding session-level data\n\nUse `sessionData` on Upload to inject extra fields into the session CSV:\n\n```tsx\n// Static\n{\n type: 'Upload',\n props: {\n sessionData: { group: 'control', experimentVersion: 2 },\n },\n}\n\n// Dynamic (computed from store/data)\n{\n type: 'Upload',\n props: (data, store) => ({\n sessionData: { group: store.assignedGroup, condition: store.condition },\n }),\n}\n```\n\n### Custom flatteners\n\nRegister a flattener for custom components to control how `responseData` becomes CSV rows:\n\n```tsx\nregisterFlattener('MyGame', 'games', (item) => {\n return item.responseData.moves.map((move) => ({\n moveType: move.type,\n score: move.score,\n }));\n});\n```\n\nEach row automatically gets standard trial fields prefixed with `trial_` (`trial_index`, `trial_name`, `trial_start`, etc.) plus any metadata from the timeline item. The flattener output overwrites these if keys collide.\n\n### Array flattener\n\nFor components whose `responseData` is an array of objects (like CanvasBlock), use the built-in `arrayFlattener` instead of writing your own. Each array element becomes a CSV row with a `block` column set to the trial name:\n\n```tsx\nimport { registerFlattener, arrayFlattener } from '@adriansteffan/reactive';\n\nregisterFlattener('MyBlockTrial', 'blocks', arrayFlattener);\n```\n\n### Multi-CSV components\n\nCall `registerFlattener` multiple times for one component to produce multiple CSV files:\n\n```tsx\nregisterFlattener('SportsGame', 'sports_actions', (item) => flattenActions(item.responseData));\nregisterFlattener('SportsGame', 'sports_players', (item) => flattenPlayers(item.responseData));\nregisterFlattener('SportsGame', 'sports_matches', (item) => flattenMatches(item.responseData));\n```\n\n### Upload props\n\n| Prop | Type | Default | Description |\n|---|---|---|---|\n| `sessionID` | `string` | random UUID | Custom session identifier used in filenames and folder names |\n| `sessionData` | `RecordPlease describe what you saw.
,\n },\n}\n```\n\nWith minimum duration enforcement; shows a warning when paused if the recording is too short:\n\n```tsx\n{\n type: 'VoiceRecording',\n props: {\n content:Please describe your decision in detail.
,\n minDuration: 15000,\n },\n}\n```\n\nWhen `minDuration` is set, only pause and discard buttons are shown. When not set, pause, stop, and discard buttons appear with playback after stopping.\n\n| Prop | Default | Description |\n|---|---|---|\n| `content` | — | Prompt text/JSX |\n| `buttonText` | `'Continue'` / `'Save & Continue'` (with minDuration) | Button text |\n| `shortButtonText` | `'Continue without improving'` | Button text when recording is too short |\n| `shortRecordingWarning` | Generic message | Warning text for short recordings |\n| `minDuration` | — | Minimum recording duration in ms |\n| `showVisualizer` | `true` | Show volume level meter |\n| `eagerUpload` | `true` | Upload audio immediately after recording |\n| `animate` | `false` | Fade-in animation |\n\nAudio recordings are automatically extracted as separate `.webm` files during upload and eagerly uploaded to reduce final upload size. The trial `name` is used in the filename.\n\n\n## LLM Integration\n\n`invokeLLM` is a general-purpose function for calling LLM APIs. It works with any OpenAI-compatible endpoint (OpenAI, HuggingFace). Responses are cached to disk (`.reactive-cache/llm.json`) so repeated calls with the same arguments skip the API.\n\n```tsx\nimport { invokeLLM } from '@adriansteffan/reactive';\n\nconst text = await invokeLLM(\n { provider: 'openai', model: 'gpt-4o-mini', apiKey: process.env.OPENAI_API_KEY! },\n 'Describe a financial decision.'\n);\n```\n\n### Structured output\n\nPass a JSON Schema as the third argument to constrain the model's output:\n\n```tsx\nconst result = await invokeLLM(\n { provider: 'openai', model: 'gpt-4o-mini', apiKey: process.env.OPENAI_API_KEY! },\n 'Describe a decision.',\n {\n type: 'object',\n properties: {\n text: { type: 'string' },\n confidence: { type: 'number' },\n },\n required: ['text', 'confidence'],\n }\n);\nconst parsed = JSON.parse(result);\n// parsed.text and parsed.confidence are guaranteed to exist\n```\n\n### Configuration\n\n| Field | Type | Description |\n|---|---|---|\n| `provider` | `'openai' \\| 'huggingface'` | API provider |\n| `model` | `string` | Model name (e.g. `'gpt-4o-mini'`) |\n| `apiKey` | `string` | API key |\n| `baseUrl` | `string?` | Override the API endpoint |\n\nRequires `import 'dotenv/config'` at the top of `simulate.ts` to load `.env` files. Add `.reactive-cache/` to your `.gitignore`.\n\n\n## Development\n\n\nRun this to in the root of the repo to build the project locally (also needs to be run after every change):\n\n```\nnpm run build\n```\n\nThen create a global link (only needs to run once during setup);\n```\nnpm link\n```\n\nThen set up a local testing project (run from the parent directory so it's created as a sibling):\n\n```\ncd ..\nnode reactive/bin/setup.js\ncd