Quickstart: CoffeeScript DSL

CoffeeScript is a supported authoring syntax for PsyCloud. It is the DSL used throughout the repo's examples/canonical/ studies. A .coffee author file does not run a separate engine — it compiles to the same three canonical contracts every other language targets, and then plays back on the standard runtime:

design-program@0.1 — factors and trial generation
screen-program@0.1 — screens, events, and timing
bindings@0.1 — how trial data maps onto screen components

Canonical, not legacy

Author against the surface shown in examples/canonical/*/coffee/author.coffee (it uses the shared helpers in examples/canonical/_shared/coffee/routines.coffee). An older browser-globals Coffee runtime exists under src/design-builder/legacy/ but is dev/test-only and not part of the shipped bundle — don't build new studies on it.

Write an author file

Save this as author.coffee. It defines one factor (word), generates a trial per value, and shows each word as an HTML stimulus that ends on an f/j keypress (or after 1.5 s). It is the canonical hello-keypress example, verbatim.

author.coffee

{compile, trial} = require "../../_shared/coffee/routines"
 
bundle = compile
  Design:
    id: "design-03"
    phaseId: "phase-03"
    factors:
      word: ["alpha", "beta"]
    yield:
      trialTemplateId: "trial-03"
      rowMapping:
        html: "word"
  Screens:
    id: "screens-03"
  Routines:
    Trial:
      Events:
        1:
          id: "event-03"
          Html:
            id: "stim-03"
            html: trial.word
          Next:
            KeyPress:
              id: "resp-03"
              keys: ["f", "j"]
              timeoutMs: 1500
 
exports.designProgram = -> bundle.designProgram
exports.screenProgram = -> bundle.screenProgram
exports.bindings = -> bundle.bindings

The three exports.* functions are the contract: the CLI loads the module and reads designProgram, screenProgram, and bindings from it.

Run it locally
Because the file exports the canonical artifacts, the CLI compiles it to a Study Bundle and runs it in the browser:
```
node bin/psycloud run local examples/canonical/hello-keypress/coffee/author.coffee
```
Swap in serve instead of run local for a live-reload dev server on http://localhost:3333.
Inspect the compiled bundle (optional)
The golden bundle JSON for each example lives in its bundle/ directory. To regenerate it from your author file:
```
node examples/canonical/_shared/coffee/run_author.js hello-keypress
```
This prints the compiled designProgram / screenProgram / bindings — the same contract the parity tests check.

Verify your Coffee matches the contract

The repo's parity suite confirms a .coffee author produces the expected bundle:

PSYCLOUD_CROSSLANG_LANGS=ts,coffee npm test -- tests/unit/examples/canonical-crosslang-parity.test.ts

Where to look next in the repo

examples/canonical/ contains a study per paradigm — stroop, flanker, simple-rt, serial-sevens, and more — each with a spec.md, a coffee/author.coffee, and a golden bundle/. Read examples/canonical/README.md for the full layout and the parity workflow.