euterpe 0.1.1 → 0.1.2

package/README.md

@@ -61,20 +61,38 @@ The agent runs in a Web Worker, so models (TF.js, onnxruntime-web, your own WebG
 | `processAudioBuffer(frame, ctx)` | every microphone frame |
 | `renderAudio(frames, ctx)` | audio output |
 | `updateParameter(change, ctx)` | a Settings widget changed |
+| `processPageMessage(data, ctx)` | the project's page code called `sendToAgent(data)` |
 
 `agent/config.yaml`, `widgets.yaml` and `players.yaml` choose the interaction mode, the clock, the UI and the instruments. They're validated against the JSON schemas in `schema/` at dev and build time.
 
+## Page code
+
+The project owns `index.html`, so a widget of its own (a custom controller, a canvas) can talk to the agent through the handle `mount()` returns:
+
+```js
+import {mount} from 'euterpe';
+
+const euterpe = mount('#app');
+euterpe.sendToAgent({button: 3});                  // -> the agent's processPageMessage(data, ctx)
+euterpe.onAgentMessage((data) => {});               // <- {page: data} from a hook or ctx.send
+```
+
+See [docs/page-code.md](docs/page-code.md).
+
 ## What's in the package
 
 | Export / command | What it is |
 |---|---|
 | `euterpe/vite` | The Vite plugin. It loads the agent and its YAML, serves and copies the instrument samples, and sets the cross-origin isolation headers. |
+| `euterpe` | `mount()`, which returns `{vm, sendToAgent, onAgentMessage}` |
 | `euterpe/agent` | `defineAgent`, `NoteEvent`, small helpers and the type enums |
 | `npx euterpe smoke [--build]` | A headless-browser check: the page is isolated, the agent is ready, the clock ticks, the agent answers a phrase, and there are no errors |
 | `npx euterpe eject` | Copies Euterpe into the project, to change it freely |
 
 TypeScript types ship in `types/`, including the YAML config types (generated from the schemas).
 
+Short guides ship in `docs/` (`node_modules/euterpe/docs/`): [models.md](docs/models.md) (TF.js and onnxruntime-web in the agent worker), [hosting.md](docs/hosting.md) (cross-origin isolation), [testing.md](docs/testing.md) (`npm run smoke`, Playwright, `window.__euterpe`, harmless console messages), [page-code.md](docs/page-code.md) (the page's own widgets and the agent).
+
 ## Deploying
 
 A built project (`npm run build`, then `dist/`) is a static site. It must be served with these headers:
@@ -84,7 +102,7 @@ Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-Euterpe uses SharedArrayBuffer between the page, the agent worker and the audio thread. The templates include `netlify.toml` and `vercel.json` with these headers.
+Euterpe uses SharedArrayBuffer between the page, the agent worker and the audio thread. The templates include `netlify.toml` and `vercel.json` with these headers; for hosts without custom headers see [docs/hosting.md](docs/hosting.md).
 
 ## Requirements
 

package/cli/index.js

@@ -89,6 +89,10 @@ async function smokeCommand() {
             `  ${options.expectAnswer ? mark(false) : yellow('-')} agent played nothing in answer to the phrase`);
         console.log(`  ${mark(report.failedRequests.length === 0)} ${report.samplesLoaded} samples loaded, ${report.failedRequests.length} failed requests`);
         for (const f of report.failedRequests) console.log(`      ${f}`);
+        if (!report.midi) {
+            console.log(`  ${dim('i')} no Web MIDI in the headless browser (not counted as errors: ` +
+                `${report.midiMessages.join('; ')})`);
+        }
         console.log(`  ${mark(report.errors.length === 0)} ${report.errors.length} console errors`);
         for (const e of report.errors) console.log(`      ${e}`);
         for (const w of [...new Set(report.warnings)]) console.log(`  ${yellow('!')} ${w.replace(/^\[\w+\] warning: /, '')}`);

package/cli/smoke.js

@@ -5,6 +5,12 @@
  * or Playwright's own Chromium if Chrome isn't installed.
  */
 
+// A headless browser may have no Web MIDI (no devices, or the permission refused): not the agent's fault, so
+// these messages are not counted as errors (the report says report.midi = false instead).
+const MIDI_UNAVAILABLE = [/WebMidi is not enabled/i, /NotAllowedError.*MIDI/i, /WebMIDI Error/i,
+    /\[euterpe\] Web MIDI is not available/, /\[euterpe\] Web MIDI output failed/];
+const midiUnavailable = (text) => MIDI_UNAVAILABLE.some((pattern) => pattern.test(text));
+
 /** Playwright's chromium, from the project's playwright or playwright-core. */
 async function loadChromium() {
     for (const name of ['playwright', 'playwright-core']) {
@@ -51,12 +57,17 @@ export async function smoke(url, {expectAnswer = false, set = [], wait = 4000, s
         const logs = [];
         const failed = [];
         let samples = 0;
+        const midiMessages = [];
         const onConsole = (source) => (m) => {
             logs.push(`[${source}] ${m.type()}: ${m.text()}`);
-            if (m.type() === 'error') errors.push(`[${source}] ${m.text()} ${m.location()?.url ?? ''}`.trim());
+            if (midiUnavailable(m.text())) midiMessages.push(m.text());
+            else if (m.type() === 'error') errors.push(`[${source}] ${m.text()} ${m.location()?.url ?? ''}`.trim());
         };
         page.on('console', onConsole('page'));
-        page.on('pageerror', (e) => errors.push('[pageerror] ' + e.message));
+        page.on('pageerror', (e) => {
+            if (midiUnavailable(e.message)) midiMessages.push(e.message);
+            else errors.push('[pageerror] ' + e.message);
+        });
         page.on('worker', (w) => w.on('console', onConsole('worker')));
         context.on('response', (r) => {
             if (r.status() >= 400) failed.push(`${r.status()} ${r.url()}`);
@@ -115,7 +126,10 @@ export async function smoke(url, {expectAnswer = false, set = [], wait = 4000, s
         report.samplesLoaded = samples;
         report.failedRequests = failed;
         report.errors = errors;
-        report.warnings = logs.filter((l) => l.includes('[euterpe]'));
+        report.warnings = logs.filter((l) => l.includes('[euterpe]') && !midiUnavailable(l));
+        // whether the page had Web MIDI; without it, the MIDI messages that were not counted as errors
+        report.midi = midiMessages.length === 0;
+        report.midiMessages = [...new Set(midiMessages)];
         report.ok = Boolean(report.crossOriginIsolated && report.started && report.ticksPerSecond > 0 &&
             failed.length === 0 && errors.length === 0 &&
             (!expectAnswer || report.agentNoteOns.length > 0 || (report.audioOut?.peakDuringPhrase ?? 0) > 0.01));

package/docs/hosting.md

@@ -0,0 +1,34 @@
+# Hosting: cross-origin isolation
+
+Euterpe passes audio, widget values and the live canvas between the page, the agent worker and the audio thread through `SharedArrayBuffer`s, and threaded WASM (TF.js, onnxruntime-web) needs them too. Browsers allow `SharedArrayBuffer` only on a **cross-origin isolated** page, one served with:
+
+```text
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Check in the browser console: `self.crossOriginIsolated` must be `true`. Without it `SharedArrayBuffer` is undefined and the UI fails to start.
+
+## Who sets the headers
+
+| Where | Headers |
+|---|---|
+| `npm run dev`, `npm run preview` | set by `euterpe/vite` |
+| `npm run smoke -- --build` | set by its static server |
+| Netlify | the project's `netlify.toml` (or a `public/_headers` file) |
+| Vercel | the project's `vercel.json` |
+| GitHub Pages, `python3 -m http.server`, any host without custom headers | not set: use coi-serviceworker (below) |
+
+## Hosts that can't set headers: coi-serviceworker
+
+[coi-serviceworker](https://github.com/gzuidhof/coi-serviceworker) is a small service worker that adds the two headers to every response. Copy `coi-serviceworker.js` (from the npm package `coi-serviceworker` or its repository) into the project's `public/`, and load it first in `index.html`'s `<head>`:
+
+```html
+<script src="/coi-serviceworker.js"></script>
+```
+
+The first visit installs the worker and reloads the page once; from then on the page is isolated. It needs HTTPS (or `localhost`).
+
+## Cross-origin files under COEP
+
+With `require-corp`, files from another origin (a model on a CDN or a bucket, an image) load only if that server allows it: CORS (`Access-Control-Allow-Origin`) for `fetch`, or `Cross-Origin-Resource-Policy: cross-origin`. Files in the project's `public/` are same-origin and always load. A blocked file shows as a network error in the console (`ERR_BLOCKED_BY_RESPONSE`).

package/docs/models.md

@@ -0,0 +1,85 @@
+# Loading a model in the agent
+
+The hooks run in a module Web Worker, so a model never blocks the UI.
+
+- **Worker, not page.** `fetch`, `WebAssembly` and (in Chrome) WebGPU work; the DOM, `window` and `document` don't.
+- **Files.** Put weights and data in the project's `public/`. They are served from the site root: `public/model/model.json` is `fetch('/model/model.json')`. (Under a Vite `base` other than `/`, prefix it: `import.meta.env.BASE_URL`.)
+- **When.** Load in `loadAlgorithm(ctx)`. The start button appears only when it resolves; if it throws, the error is shown on the loading screen. Send progress with `ctx.send({text: 'Loading...'})` (shown on the loading screen). Run one warm-up inference there too: the first call is much slower (compilation, buffer allocation).
+- **Per tick.** `processClockEvent` has one tick to answer (150 ms at 100 BPM in 16ths). Keep the model's state (RNN hidden state, KV cache) in module-level variables between ticks. The console warns when the hook is slower than a tick.
+- **Dependencies.** `npm install` the runtime and import it in `agent/`. Euterpe's Vite plugin pre-bundles what the agent imports.
+
+## WASM files: let Vite serve them
+
+ML runtimes fetch their `.wasm` binaries at run time, by default from a CDN or next to the script, which breaks in a bundled worker. Import each binary with Vite's `?url` suffix (Vite copies it into the build and gives you its URL) and hand the URLs to the runtime, before the first model loads.
+
+### TF.js (WASM backend)
+
+```bash
+npm install @tensorflow/tfjs @tensorflow/tfjs-backend-wasm   # the same version for both (tested: 4.22.0)
+```
+
+```js
+// agent/hooks.js
+import {defineAgent} from 'euterpe/agent';
+import * as tf from '@tensorflow/tfjs';
+import {setWasmPaths} from '@tensorflow/tfjs-backend-wasm';
+import wasm from '@tensorflow/tfjs-backend-wasm/dist/tfjs-backend-wasm.wasm?url';
+import wasmSimd from '@tensorflow/tfjs-backend-wasm/dist/tfjs-backend-wasm-simd.wasm?url';
+import wasmThreadedSimd from '@tensorflow/tfjs-backend-wasm/dist/tfjs-backend-wasm-threaded-simd.wasm?url';
+
+setWasmPaths({
+    'tfjs-backend-wasm.wasm': wasm,
+    'tfjs-backend-wasm-simd.wasm': wasmSimd,
+    'tfjs-backend-wasm-threaded-simd.wasm': wasmThreadedSimd,
+});
+
+let model = null;
+
+export default defineAgent({
+    async loadAlgorithm(ctx) {
+        ctx.send({text: 'Loading the model...'});
+        // WASM, or plain JS if it can't start
+        let ok = false;
+        try {
+            ok = await tf.setBackend('wasm');
+        } catch (error) {
+            console.warn('TF.js wasm backend failed', error);
+        }
+        if (!ok) await tf.setBackend('cpu');
+        await tf.ready();
+        model = await tf.loadLayersModel('/model/model.json');
+        tf.tidy(() => model.predict(tf.zeros([1, 16])));   // warm-up
+    },
+    processClockEvent(clock, ctx) {
+        // tf.tidy frees the step's intermediate tensors; dispose() what you keep across ticks
+        const next = tf.tidy(() => model.predict(input(clock)).argMax(-1).dataSync()[0]);
+        // ...
+    },
+});
+```
+
+The threaded binary is used only when the page is cross-origin isolated (see [hosting.md](hosting.md)); Euterpe's dev server and deploy configs make sure it is.
+
+### onnxruntime-web
+
+```bash
+npm install onnxruntime-web   # tested: 1.30.0
+```
+
+```js
+// agent/ort.js: ORT's WASM settings are global and fixed by the first session, so set them in one module
+import * as ort from 'onnxruntime-web/wasm';
+import ortWasm from 'onnxruntime-web/ort-wasm-simd-threaded.wasm?url';
+
+ort.env.wasm.wasmPaths = {wasm: ortWasm};
+ort.env.wasm.numThreads = 1;     // more threads need a cross-origin isolated page
+ort.env.wasm.proxy = false;      // already in a worker
+export {ort};
+```
+
+```js
+// in loadAlgorithm
+session = await ort.InferenceSession.create('/model/model.onnx');
+```
+
+Tensors: `new ort.Tensor('float32', data, dims)`; `await session.run({input: tensor})`.

package/docs/page-code.md

@@ -0,0 +1,56 @@
+# Your own page code: widgets that talk to the agent
+
+The project owns `index.html`, which calls `mount()` from `euterpe`. Anything else on that page (a custom controller, buttons, a canvas, a camera feed) is the project's own code, and can talk to the agent without changing Euterpe:
+
+```js
+// index.html (or a module it imports)
+import {mount} from 'euterpe';
+
+const euterpe = mount('#app');
+euterpe.sendToAgent({button: 3, down: true});      // -> the agent's processPageMessage(data, ctx)
+const stop = euterpe.onAgentMessage((data) => {     // <- what the agent sends as {page: data}
+    console.log('from the agent', data);
+});
+```
+
+```js
+// agent/hooks.js
+export default defineAgent({
+    processPageMessage(data, ctx) {
+        if (!data.down) return [ctx.noteOff(60 + data.button)];
+        return {
+            notes: [ctx.noteOn(60 + data.button)],
+            page: {lit: data.button},              // to the page's onAgentMessage listeners
+        };
+    },
+});
+```
+
+| API | |
+|---|---|
+| `mount(el = '#app')` | Returns `{vm, sendToAgent, onAgentMessage}` (`EuterpeApp` in the types); `vm` is the root Vue instance |
+| `sendToAgent(data)` | `data`: anything structured-cloneable (plain objects, arrays, numbers, strings, typed arrays). Delivered in order. Sent before the agent has loaded, it waits until `loadAlgorithm` has finished |
+| `processPageMessage(data, ctx)` | The agent's hook. Returns what any hook returns (notes, `{notes, text, ...}`), plus `page` |
+| `{page: data}` | From any hook's return value, or `ctx.send({page: data})` at any time (e.g. `{page: {ready: true}}` at the end of `loadAlgorithm`) |
+| `onAgentMessage(listener)` | Calls `listener(data)` for each `{page: data}`. Returns a function that removes the listener |
+
+Agents written the original way (named exports using `self.*`) get `processPageMessage(data)` without `ctx` and return MICP messages; the page key is `self.messageType.PAGE`.
+
+Notes the agent plays show on the keyboard and piano roll as the agent's. Input sent this way is not a user note: it doesn't light the on-screen keyboard or appear in the piano roll or score as the user's. (`window.__euterpe.noteOn` is a test handle that plays a user note, see [testing.md](testing.md).)
+
+## Keys
+
+Euterpe's laptop keyboard listens on `document`: the bottom row `Z S X D C V G B H N J M , L . ; /` plays C4 to E5 and the top row `Q 2 W 3 E R 5 T 6 Y 7 U I 9 O 0 P [ = ]` plays C5 to G6; Space starts and stops the clock. Of the digits, `2 3 5 6 7 9 0` are notes; `1 4 8` are free. To use a key Euterpe also uses, take it first with a capture-phase listener on `window` and stop it there:
+
+```js
+window.addEventListener('keydown', (e) => {
+    if (e.code !== 'Digit2' || e.target.closest?.('input, textarea')) return;
+    e.stopPropagation();           // Euterpe's listener on document never sees it
+    if (!e.repeat) euterpe.sendToAgent({button: 1, down: true});
+}, true);
+// and the same for keyup
+```
+
+## Layout
+
+Euterpe's UI fills the page. Place your widget with `position: fixed` and a `z-index` above it (e.g. 1000).

package/docs/testing.md

@@ -0,0 +1,60 @@
+# Testing an agent in a browser
+
+## npm run smoke
+
+```bash
+npm run smoke                 # starts the dev server, checks the page in headless Chrome
+npm run smoke -- --build      # the same on the production build, served with the COOP/COEP headers
+npm run smoke -- --json       # the full report (add --logs for the console)
+npm run smoke -- --set=slider:1:40 --screenshot=shot.png --wait=6000
+```
+
+It checks: the page is cross-origin isolated, the agent loads, the start button works, the clock ticks; then it plays C5 D5 E5 F5 G5 F5 E5 D5 C5 on the laptop keyboard (`q w e r t`) and reports what the agent played, console errors and Euterpe's `[euterpe]` warnings. `--expect-answer` fails if the agent plays nothing. It uses the system Chrome; without one, run `npx playwright install chromium` once.
+
+## Your own tests: Playwright + window.__euterpe
+
+Use the system Chrome (no browser download) and drive the page through `window.__euterpe` rather than clicking through the UI:
+
+```js
+import {chromium} from 'playwright-core';   // already in the project's devDependencies
+
+const browser = await chromium.launch({channel: 'chrome'});
+const page = await browser.newPage();
+await page.goto('http://localhost:5173/');
+await page.waitForFunction(() => window.__euterpe);
+await page.evaluate(() => __euterpe.whenReady());   // the agent loaded (loadAlgorithm resolved)
+await page.evaluate(() => __euterpe.enter());       // what the start button does; it opens the intro dialog
+await page.keyboard.press('Escape');                // close the intro dialog
+await page.evaluate(() => __euterpe.startClock());
+const n = await page.evaluate(() => __euterpe.agentMessageCount);
+await page.evaluate(() => __euterpe.noteOn(60));
+await page.waitForTimeout(500);
+await page.evaluate(() => __euterpe.noteOff(60));
+const notes = await page.evaluate((k) => __euterpe.agentMessages(k).flatMap((m) => m.message[4] ?? []), n);
+```
+
+`window.__euterpe` (types: `EuterpeHandle` in `euterpe`):
+
+| | |
+|---|---|
+| `ready`, `whenReady(timeoutMs = 180000)` | The agent has loaded and the permissions are granted |
+| `entered`, `enter()` | The start button was pressed / press it |
+| `clockRunning`, `startClock()`, `stopClock()` | The clock (grid mode) |
+| `tick` | `{local, global}`: the position in the bar, ticks since the start |
+| `bpm`, `setBPM(bpm)` | The tempo |
+| `params`, `setParam(kind, id, value)` | Widget values as the agent's `ctx.params` sees them; `kind`: `'slider'`, `'switch'`, `'dropdown'`, `'button'` (presses it), `'text'` |
+| `noteOn(midi, velocity = 127)`, `noteOff(midi)` | A user note, as from the laptop keyboard (lights the on-screen key) |
+| `agentMessages(since = 0)`, `agentMessageCount` | What the agent sent: `[{t, hookType, message}]`, numbered from the first message. `message` is keyed by `messageType` number: `message[4]` is the note list, `message[13]` the text |
+| `audioOut` | The agent's audio output: `{played, underruns, playing, quantum, peak}`, or `null` |
+| `config` | The merged YAML config |
+
+Notes in `agentMessages` are serialized `NoteEvent`s: read `n._midi`, `n._type` (1 on, -1 off), `n._playAfter`.
+
+The controls carry `data-testid`s: `euterpe-start`, `euterpe-clock`, `euterpe-settings`, `euterpe-slider-1`, `euterpe-dropdown-1`, `euterpe-text-1`, ...
+
+## Messages that look like errors but aren't
+
+- **`WebMidi is not enabled`, `NotAllowedError ... MIDI`, `[euterpe] Web MIDI is not available`.** Headless Chrome has no Web MIDI (no devices, or the permission refused). MIDI devices are simply off; the laptop keyboard, the on-screen keyboard and `__euterpe.noteOn` still work. `npm run smoke` doesn't count these as errors.
+- **`The AudioContext was not allowed to start`.** The browser's autoplay policy, before the start button (the user gesture that resumes audio).
+- **The intro dialog.** `enter()` (the start button) opens it. While it is open it covers the middle of the page and Space doesn't start or stop the clock (Euterpe's shortcuts are off while any dialog is open); laptop-keyboard notes still play. Close it with Escape before clicking or pressing Space in a test.
+- **Icons shown as words** (e.g. `settings`, `play_arrow`). Euterpe's icon font comes from Google Fonts; offline it doesn't load and the icon names show as text. Nothing else is affected.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "euterpe",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A browser framework for real-time interactive music agents: write the agent's hooks and YAML, Euterpe does MIDI and audio input, the clock, quantization, samplers and the UI.",
   "license": "MIT",
   "type": "module",
@@ -27,6 +27,7 @@
     "types",
     "schema",
     "assets",
+    "docs",
     "LICENSE",
     "README.md"
   ],

package/src/agent.js

@@ -16,7 +16,7 @@ export {liveCanvasState} from './utils/liveCanvasState.js';
 export const AGENT_MARK = Symbol.for('euterpe.agent');
 
 export const HOOK_NAMES = ['loadAlgorithm', 'processClockEvent', 'processNoteEvent', 'processAudioBuffer',
-    'updateParameter', 'renderAudio'];
+    'updateParameter', 'renderAudio', 'processPageMessage'];
 
 /**
  * Declares the agent. agent/hooks.js does `export default defineAgent({...})`; every hook is optional and may be
@@ -31,8 +31,11 @@ export const HOOK_NAMES = ['loadAlgorithm', 'processClockEvent', 'processNoteEve
  *                                       updated)
  *   renderAudio(frames, ctx)            audio output (interactionMode.audioOut): return `frames` frames,
  *                                       called whenever the output queue holds less than audioOut.latency
+ *   processPageMessage(data, ctx)       the project's page code called sendToAgent(data) (the handle mount()
+ *                                       returns), e.g. from its own widget
  *
- * A hook returns the agent's output: an array of notes, or {notes, text, label, vector, key, audio}, or nothing.
+ * A hook returns the agent's output: an array of notes, or {notes, text, label, vector, key, audio, page}, or
+ * nothing. `page` goes to the page code's onAgentMessage listeners.
  * @param {Object} hooks
  * @return {Object} The agent, as the worker runtime calls it.
  */

package/src/components/Settings.vue

@@ -1,7 +1,7 @@
 <template>
     <div>
         <modal name="settingsModal" width="90%" height="85%" :maxWidth="1200" :minWidth="320" :minHeight="300"
-            :adaptive="true">
+            :adaptive="true" @before-open="$emit('modal-open', true)" @closed="$emit('modal-open', false)">
             <div class="settingsContainer">
                 <div class="settingsHeader">
                     <p class="settingsTitle">
@@ -71,10 +71,10 @@
                             </div>
                         </div>
                         <span v-else>
-                            Currently, Using MIDI devices in browser is only supported by Google
-                            Chrome v43+, Opera v30+ and Microsoft Edge v79+. Please update to
-                            one of those browsers if you want to use Web MIDI
-                            functionalities.</span>
+                            Web MIDI is not available: this browser does not support it, or the
+                            permission to use MIDI devices was not given. Chrome, Edge, Opera and
+                            Firefox support MIDI devices; the laptop and on-screen keyboards
+                            work everywhere.</span>
                     </div>
                     <!-- <modal name="settingsModal" :minWidth="700" :minHeight="600" :adaptive="true"> -->
                     <div style="display: flex; flex-direction:column;">
@@ -238,6 +238,15 @@ export default {
             type: Boolean,
             default: false,
         },
+        // the devices in use (Euterpe.vue picks the first MIDI input until the user chooses one)
+        selectedMIDIInput: {
+            type: [String, Number],
+            default: 1123581321, // the "None" option
+        },
+        selectedMIDIOutput: {
+            type: [String, Number],
+            default: 1123581321,
+        },
         maxBPM: Number,
         initBPM: Number
     },
@@ -245,11 +254,20 @@ export default {
     data() {
         return {
             currentBPM: this.$props.initBPM,
-            selectedMIDIInputDevice: 1123581321, // id for "None" option 
-            selectedMIDIOutputDevice: 1123581321 // id for "None" option
+            selectedMIDIInputDevice: this.$props.selectedMIDIInput,
+            selectedMIDIOutputDevice: this.$props.selectedMIDIOutput,
         };
     },
 
+    watch: {
+        selectedMIDIInput(id) {
+            this.selectedMIDIInputDevice = id;
+        },
+        selectedMIDIOutput(id) {
+            this.selectedMIDIOutputDevice = id;
+        },
+    },
+
     // TODO: Use the sortedCollection to render the controls in the correct order
     computed: {
         sortedCollections() {

package/src/index.js

@@ -12,6 +12,7 @@ import 'vue-material/dist/theme/default.css';
 import 'remixicon/fonts/remixicon.css';
 import Dropdown from 'vue-simple-search-dropdown';
 import MarkdownItVue from 'markdown-it-vue'
+import {sendToAgent, onAgentMessage} from './utils/pageBridge.js';
 
 Vue.use(MdButton);
 Vue.use(MdIcon);
@@ -42,8 +43,18 @@ const FONT_STYLESHEETS = [
 
 /**
  * Mounts the Euterpe UI, running the agent in the project's agent/ folder (bundled by euterpe/vite).
+ *
+ * The handle it returns lets the project's own page code (e.g. a widget of its own in index.html) talk to the
+ * agent:
+ *
+ *   const euterpe = mount('#app');
+ *   euterpe.sendToAgent({button: 3});             // the agent's processPageMessage(data, ctx)
+ *   euterpe.onAgentMessage((data) => {...});      // what the agent sends as {page: data}; returns an unsubscribe
+ *
+ * Messages sent before the agent has loaded wait for it.
  * @param {string|Element} [el='#app'] - The element to mount into.
- * @return {Vue} The root Vue instance.
+ * @return {{vm: Vue, sendToAgent: function(*): void, onAgentMessage: function(function(*): void): function(): void}}
+ *     The handle; `vm` is the root Vue instance.
  */
 export function mount(el = '#app') {
     // problems in the agent's YAML files (also printed by the dev server and the build)
@@ -55,8 +66,9 @@ export function mount(el = '#app') {
         link.href = href;
         document.head.appendChild(link);
     }
-    return new Vue({
+    const vm = new Vue({
         store,
         render: (h) => h(App),
     }).$mount(el);
+    return {vm, sendToAgent, onAgentMessage};
 }

package/src/store/modules/global-settings.js

@@ -6,7 +6,8 @@ const state = {
     currentBPM: null,
     frequency: null,
     // randomness: null,
-    modalStatus: false,
+    // the names of the dialogs (vue-js-modal) that are open; the keyboard shortcuts are off while any is
+    openModals: [],
     // Key estimate from the agent ('E♭ major'), used to spell notes (C♯ vs D♭); null spells with sharps
     estimatedKey: null,
 };
@@ -27,8 +28,9 @@ const getters = {
     // getRandomness(state){
     //   return state.randomness;
     // },
+    // true while a dialog is open
     getModalStatus(state) {
-        return state.modalStatus;
+        return state.openModals.length > 0;
     },
     getEstimatedKey(state) {
         return state.estimatedKey;
@@ -82,8 +84,11 @@ const mutations = {
         console.debug('setBPM: ' + bpm);
         state.currentBPM = bpm;
     },
-    changeModalStatus(state) {
-        state.modalStatus = !state.modalStatus;
+    // a dialog opened or closed: set from its before-open and closed events, idempotent (a dialog closed
+    // during its opening transition gets no "opened" event, so a toggle would go out of step)
+    setModalOpen(state, {name, open}) {
+        const others = state.openModals.filter((n) => n !== name);
+        state.openModals = open ? [...others, name] : others;
     },
 };
 

package/src/utils/pageBridge.js

@@ -0,0 +1,54 @@
+/**
+ * Page messages: the project's own page code (its index.html, its widgets) talking to the agent, outside
+ * Euterpe's UI. mount() returns sendToAgent / onAgentMessage (src/index.js); the agent gets the data in its
+ * processPageMessage hook and answers with {page: data}, which reaches the onAgentMessage listeners.
+ */
+
+// messages sent before the agent worker exists (mount() returns before the UI's chunk has loaded)
+const pending = [];
+const listeners = new Set();
+let worker = null;
+
+/**
+ * Sends data to the agent's processPageMessage hook.
+ * @param {*} data - Anything structured-cloneable (plain objects, arrays, numbers, strings, typed arrays).
+ */
+export function sendToAgent(data) {
+    // a copy now, as postMessage would make: the data can't change while it waits
+    if (worker) worker.postMessage({control: 'pageMessage', data});
+    else pending.push(structuredClone(data));
+}
+
+/**
+ * Calls `listener(data)` for every {page: data} the agent sends.
+ * @param {function(*): void} listener
+ * @return {function(): void} Removes the listener.
+ */
+export function onAgentMessage(listener) {
+    if (typeof listener !== 'function') throw new TypeError('onAgentMessage: the listener must be a function');
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+
+/**
+ * Connects the agent worker (Euterpe.vue, after the INIT_AGENT message) and sends what was waiting.
+ * @param {Worker} agentWorker
+ */
+export function attachWorker(agentWorker) {
+    worker = agentWorker;
+    for (const data of pending.splice(0)) worker.postMessage({control: 'pageMessage', data});
+}
+
+/**
+ * Passes a page message from the agent (messageType.PAGE) to the listeners.
+ * @param {*} data
+ */
+export function deliverToPage(data) {
+    for (const listener of listeners) {
+        try {
+            listener(data);
+        } catch (error) {
+            console.error('[euterpe] an onAgentMessage listener failed', error);
+        }
+    }
+}

package/src/utils/types.js

@@ -36,6 +36,7 @@ export const messageType = {
     SESSION: 16, // a recorded session (see src/agent/sessionLog.js), downloaded by the UI
     TIMING_RESET: 18, // the agent switched to another model: the UI restarts its max-BPM estimate
     HUMAN_TOKEN: 19, // the live canvas: the user's note for the next tick, {tick, midi, artic, candidate, ...}
+    PAGE: 20, // data for the project's page code (mount()'s onAgentMessage listeners)
     CLOCK_TIME: 1,
     INFERENCE_TIME: 2,
 };

package/src/views/Euterpe.vue

@@ -23,6 +23,8 @@ import '../css/main.css';
 import * as Tone from 'tone';
 import {Midi} from '@tonaljs/tonal';
 import {WebMidi} from 'webmidi';
+// the id of the "None" entry of the MIDI device menus
+const NO_MIDI_DEVICE = 1123581321;
 import AudioKeys from 'audiokeys';
 
 import * as rb from 'ringbuf.js';
@@ -36,6 +38,7 @@ import {
 import {isMobile, isNotChrome} from '../utils/helpers.js';
 import {NoteEvent} from '../utils/NoteEvent.js';
 import {installHandle} from '../utils/handle.js';
+import {attachWorker, deliverToPage} from '../utils/pageBridge.js';
 // import { selectedAgent } from '../agent-examples/selectedAgent.js'
 
 // the agent's YAML configs and intro text, from the project's agent/ folder (see euterpe/vite)
@@ -138,8 +141,11 @@ export default {
             pageLoadTime: null,
             modelLoadTime: null,
             activeDevices: [],
-            selectedMIDIDevice: 1123581321, // id for the "None" device
-            selectedMIDIOutputDevice: 1123581321, // id for the "None" device
+            selectedMIDIDevice: NO_MIDI_DEVICE,
+            selectedMIDIOutputDevice: NO_MIDI_DEVICE,
+            // the MIDI input the user chose in Settings (an id, or NO_MIDI_DEVICE); null: not chosen yet, so
+            // Euterpe uses the first connected input
+            midiInputChoice: null,
             activeMidiOutputDevices: [], // To store MIDI output devices
 
             noteOffEventForNextTick: null,
@@ -373,6 +379,8 @@ export default {
                 sabLiveCanvas: vm.liveCanvas?.sab ?? null,
             },
         });
+        // the page code's sendToAgent (mount()'s handle): from now on straight to the worker, after the config
+        attachWorker(vm.agent);
         if (audioOut) {
             vm.startAudioOut(audioOut).catch((error) => {
                 // e.g. a Content-Security-Policy that blocks the worklet: tell the agent, and the user
@@ -393,7 +401,8 @@ export default {
         // Initialize Clock Worker (module)
         vm.clockWorker = new Worker(new URL('../worker/clock.js', import.meta.url), {type: 'module'});
         vm.clockWorker.onmessage = vm.tickBehavior;
-        vm.clockWorker.postMessage({action: 'setBPM', bpm: vm.localBPM});
+        vm.clockWorker.postMessage({action: 'setBPM', bpm: vm.localBPM, ticksPerBeat: vm.config.clockSettings.ticksPerBeat,
+            clockPeriod: vm.config.clockSettings.clockPeriod ?? null});
         vm.$store.commit('initializeClock');
 
         if (vm.config.interactionMode.audioMode) {
@@ -497,16 +506,11 @@ export default {
         //         .then(vm.onEnabled)
         //         .catch((err) => console.debug('WebMIDI Error: ' + err));
         // }
-        try {
-            if (navigator.requestMIDIAccess) {
-                // Await MIDI permission
-                await this.initializeMIDI();
-                console.debug('MIDI initialized');
-                vm.permissionMIDI = true;
-            }
-        } catch (error) {
-            console.error('Error initializing MIDI: ', error);
+        // MIDI devices are optional: without Web MIDI (Safari, a denied permission) the page still starts
+        if (navigator.requestMIDIAccess) {
+            await this.initializeMIDI(); // never throws
         }
+        vm.permissionMIDI = true;
 
         /*
         * Initialize computer keyboard logic
@@ -586,18 +590,20 @@ export default {
             const vm = this;
             if (vm.$store.getters.getClockStatus) {
                 vm.$store.commit('incrementTick');
+                // The side effects of a tick (the live canvas, the metronome and its MIDI out, the agent's
+                // sampler) run guarded: a throw in one of them must never stop the tick reaching the agent.
                 // the live canvas plays the user's note for this tick before the quantizer runs
-                vm.liveCanvas?.onTick(vm.$store.getters.getGlobalTick);
+                vm.guardedTickStep('liveCanvas', () => vm.liveCanvas?.onTick(vm.$store.getters.getGlobalTick));
 
                 // Trigger the metronome only if there is a "metronome" entry in config_players.yaml
                 if (vm.config.players.metronome) {
-                    vm.metronomeTrigger();
+                    vm.guardedTickStep('metronome', () => vm.metronomeTrigger());
                 }
 
-                vm.calculateMaxBPM();
+                vm.guardedTickStep('calculateMaxBPM', () => vm.calculateMaxBPM());
 
                 // in grid-based mode, the agent's sampler is triggered in sync with the clock
-                vm.triggerAgentSamplerSync(); // UNCOMMENT
+                vm.guardedTickStep('agentSampler', () => vm.triggerAgentSamplerSync());
 
 
                 // run the agent with a small delay of tick/4 in order to include
@@ -628,9 +634,23 @@ export default {
             }
         },
 
+        // runs one step of a tick; a throw is logged (the first time per step) instead of ending the tick
+        guardedTickStep(name, step) {
+            try {
+                step();
+            } catch (error) {
+                this.tickStepErrors ??= new Set();
+                if (!this.tickStepErrors.has(name)) {
+                    this.tickStepErrors.add(name);
+                    console.error(`[euterpe] ${name} failed on a tick (the tick still reached the agent)`, error);
+                }
+            }
+        },
+
         async toggleClock() {
             const vm = this;
             if (!vm.localSyncClockStatus) {
+                vm.clearUserInput();
                 vm.startRecording();
                 vm.clockWorker.postMessage({action: 'startClock'});
             } else {
@@ -653,7 +673,14 @@ export default {
             this.$store.commit('clearPianoState');
         },
 
+        // Notes played while the clock was stopped must not reach the first ticks of the take
+        clearUserInput() {
+            this.$store.commit('clearContinuousBuffers');
+            this.noteOffEventForNextTick = null;
+        },
+
         startClock() {
+            this.clearUserInput();
             this.startRecording();
             this.clockWorker.postMessage({action: 'startClock'});
             this.localSyncClockStatus = true;
@@ -1106,6 +1133,10 @@ export default {
                         // the live canvas: the user's note for the next tick
                         vm.liveCanvas?.onHumanToken(messageValue);
                         break;
+                    case vm.messageType.PAGE:
+                        // {page: data}: for the project's page code (mount()'s onAgentMessage)
+                        deliverToPage(messageValue);
+                        break;
                     case vm.messageType.CLOCK_TIME:
                         break;
                     case vm.messageType.INFERENCE_TIME:
@@ -1315,90 +1346,72 @@ export default {
         */
         async initializeMIDI() {
             try {
-                const access = await navigator.requestMIDIAccess();
-                this.WebMIDISupport = true;
-
-                access.onstatechange = (event) => {
-                    this.onMidiStateChange(event);
-                };
-
                 await WebMidi.enable();
-                this.onEnabled();
+                this.WebMIDISupport = true;
+                // a device plugged in (or out) later: update the menus, and pick up a keyboard if none is chosen
+                WebMidi.addListener('portschanged', () => this.refreshMIDIDevices());
+                this.refreshMIDIDevices();
             } catch (err) {
-                console.error('WebMIDI Error:', err);
+                // permission denied, a headless browser, or no Web MIDI (Safari): MIDI devices are off,
+                // the laptop keyboard and the on-screen keyboard still work
+                console.warn(`[euterpe] Web MIDI is not available (${err?.name ?? err}): MIDI devices are off`);
             }
         },
 
-        onMidiStateChange(state) {
-            if (state.port.state === 'connected') {
-                console.debug('MIDI device connected:', state.port.name);
-            } else if (state.port.state === 'disconnected') {
-                console.debug('MIDI device disconnected:', state.port.name);
+        // the device menus from the connected devices. MIDI input: the device the user chose in Settings
+        // (when it is connected), or, until the user chooses one, the first connected input.
+        refreshMIDIDevices() {
+            const vm = this;
+            vm.activeDevices = [{id: NO_MIDI_DEVICE, name: 'None'},
+                ...WebMidi.inputs.map((device) => ({id: device.id, name: device.name}))];
+            vm.activeMidiOutputDevices = [{id: NO_MIDI_DEVICE, name: 'None'},
+                ...WebMidi.outputs.map((device) => ({id: device.id, name: device.name}))];
+
+            const inputIds = WebMidi.inputs.map((device) => device.id);
+            const choice = vm.midiInputChoice;
+            let input;
+            if (choice === null) input = inputIds[0] ?? NO_MIDI_DEVICE;
+            else input = inputIds.includes(choice) ? choice : NO_MIDI_DEVICE;
+            vm.selectMIDIInput(input);
+
+            if (vm.selectedMIDIOutputDevice != NO_MIDI_DEVICE &&
+                !WebMidi.outputs.some((device) => device.id === vm.selectedMIDIOutputDevice)) {
+                vm.selectedMIDIOutputDevice = NO_MIDI_DEVICE;
             }
-            // this.onEnabled();
-            // Find a non-buggy way to correctly update the MIDI devices
         },
 
-        onEnabled() {
+        // listen to this MIDI input (an id, or NO_MIDI_DEVICE for none), and stop listening to the previous one
+        selectMIDIInput(id) {
             const vm = this;
-            vm.activeDevices = [];
-            vm.activeDevices.push({id: 1123581321, name: 'None'})
-            WebMidi.inputs.forEach((device) => {
-                vm.activeDevices.push({id: device.id, name: device.name});
-            });
-            vm.selectedMIDIDevice = vm.activeDevices[0].id;
-
-            vm.activeMidiOutputDevices = [];
-            vm.activeMidiOutputDevices.push({id: 1123581321, name: 'None'})
-            WebMidi.outputs.forEach((device) => {
-                vm.activeMidiOutputDevices.push({id: device.id, name: device.name});
-            });
-            vm.selectedMIDIOutputDevice = vm.activeMidiOutputDevices[0].id;
-
+            const device = id == NO_MIDI_DEVICE ? null : WebMidi.getInputById(id);
+            if (vm.midiInputPort && vm.midiInputPort !== device) {
+                vm.midiInputPort.removeListener();
+                vm.midiInputPort = null;
+            }
+            vm.selectedMIDIDevice = device ? id : NO_MIDI_DEVICE;
+            if (device && vm.midiInputPort !== device) {
+                vm.midiInputPort = device;
+                vm.messageListener(device);
+                console.debug(`MIDI input: ${device.name}`);
+            }
         },
 
+        // the user chose a MIDI input in Settings: keep it (also when devices change), never auto-select over it
         onMIDIDeviceSelectedChange(state) {
-            const vm = this;
-            if (state.currentTarget.value) {
-                if (vm.selectedMIDIDevice !== state.currentTarget.value) {
-
-                    if (vm.selectedMIDIDevice != 1123581321) {
-                        const inputDevice = WebMidi.getInputById(this.selectedMIDIDevice);
-                        // iterate over all channels in inputDevice.channels
-                        // and do channel.removeListener();  
-                        for (let i = 1; i <= 16; i++) {
-                            let channel = inputDevice.channels[i];
-                            if (channel)
-                                channel.removeListener();
-                        }
-                    }
-                    vm.selectedMIDIDevice = state.currentTarget.value;
-                    if (state.currentTarget.value != 1123581321) {
-                        vm.messageListener();
-                    }
-                    
-                }
-            }
+            const value = state.currentTarget.value;
+            if (!value) return;
+            this.midiInputChoice = value == NO_MIDI_DEVICE ? NO_MIDI_DEVICE : value;
+            if (WebMidi.enabled) this.selectMIDIInput(this.midiInputChoice);
         },
         onMIDIOutputDeviceSelectedChange(state) {
-            const vm = this;
-            if (state.currentTarget.value) {
-                if (vm.selectedMIDIOutputDevice !== state.currentTarget.value) {
-                    if (state.currentTarget.value == 1123581321) {
-                        vm.selectedMIDIOutputDevice = 1123581321;
-                    } 
-                    else {
-                        vm.selectedMIDIOutputDevice = state.currentTarget.value;
-                    }
-                    // vm.sendNoteOn();
-                }
-            }
+            const value = state.currentTarget.value;
+            if (!value) return;
+            this.selectedMIDIOutputDevice = value == NO_MIDI_DEVICE ? NO_MIDI_DEVICE : value;
         },
 
         // listens for midi messages from a midi keyboard
-        messageListener() {
+        messageListener(inputDevice) {
             const vm = this;
-            const inputDevice = WebMidi.getInputById(this.selectedMIDIDevice);
             inputDevice.addListener('noteon', (message) => {
                 const newNoteEvent = new NoteEvent();
                 newNoteEvent.player = vm.playerType.HUMAN;
@@ -1446,54 +1459,51 @@ export default {
             });
         },
 
+        /*
+        * MIDI out. Every path goes through withMIDIOutput: without Web MIDI (permission denied, a headless
+        * browser, Safari) or without a selected output device it does nothing, and a failure to
+        * send is logged once, never thrown (the metronome and the agent's notes call it on the clock's path).
+        */
+        withMIDIOutput(send) {
+            if (!WebMidi.enabled || this.selectedMIDIOutputDevice == NO_MIDI_DEVICE) return;
+            try {
+                const outputDevice = WebMidi.getOutputById(this.selectedMIDIOutputDevice);
+                if (outputDevice) send(outputDevice);
+            } catch (error) {
+                if (!this.midiOutputWarned) {
+                    this.midiOutputWarned = true;
+                    console.warn('[euterpe] Web MIDI output failed; MIDI out is skipped', error);
+                }
+            }
+        },
+
         // Method to send MIDI messages (for example, a Note On message)
         sendNoteOn(noteEvent, channel = 1) {
-            const outputDevice = WebMidi.getOutputById(this.selectedMIDIOutputDevice);
-            if (outputDevice) {
-                // Note On message is sent as [0x90 + channel, noteNumber, velocity]
-                // outputDevice.send([0x90, noteNumber, velocity]);
+            this.withMIDIOutput((outputDevice) => {
                 outputDevice.playNote(noteEvent.midi, {channels: [channel]});
-                console.debug(`Sent Note On to external device`);
-            // } else {
-            //     console.error('No output device selected.');
-            }
+            });
         },
 
         sendNoteOnOff(noteEvent, channel = 1, duration = 1000) {
-            const outputDevice = WebMidi.getOutputById(this.selectedMIDIOutputDevice);
-            if (outputDevice) {
-                // Note On message is sent as [0x90 + channel, noteNumber, velocity]
-                // outputDevice.send([0x90, noteNumber, velocity]);
-                if (noteEvent.midi)
-                    outputDevice.playNote(noteEvent.midi, {channels: [channel], duration: duration});
-                else
-                    outputDevice.playNote(noteEvent.name, {channels: [channel], duration: duration});
-                console.debug(`Sent Note On to external device`);
-            // } else {
-            //     console.error('No output device selected.');
-            }
+            this.withMIDIOutput((outputDevice) => {
+                outputDevice.playNote(noteEvent.midi || noteEvent.name, {channels: [channel], duration: duration});
+            });
         },
 
         // Method to send MIDI messages (for example, a Note Off message)
-        sendNoteOff(noteEvent, channel = 1, after = "+0") {
-            const outputDevice = WebMidi.getOutputById(this.selectedMIDIOutputDevice);
-            if (outputDevice) {
-                // Note Off message is sent as [0x80 + channel, noteNumber, 0]
+        sendNoteOff(noteEvent, channel = 1, after = '+0') {
+            this.withMIDIOutput((outputDevice) => {
                 outputDevice.stopNote(noteEvent.midi, {time: after, channels: [channel]});
-                // console.debug(`Sent Note Off: Note ${noteEvent.midi} to external device`);
-            // } else {
-            //     console.error('No output device selected.');
-            }
+            });
         },
 
         // kill all notes on the external midi device
         killAllNotes() {
-            // use the sendNoteOff method to send a note off message to all notes
-            // that are currently playing on the external midi device
-            for (let i = 0; i < 128; i++) {
-                this.sendNoteOff({midi: i}, 1, "+200");
-            }
-            console.debug('Killed all notes on the external midi device');
+            this.withMIDIOutput((outputDevice) => {
+                for (let i = 0; i < 128; i++) {
+                    outputDevice.stopNote(i, {time: '+200', channels: [1]});
+                }
+            });
         },
 
         startRecording() {
@@ -1650,9 +1660,9 @@ export default {
             this.keyboardMinRangeDisplayed = false;
         },
 
-        modalCallback(eventName) {
-            console.debug('modal callback', eventName);
-            this.$store.commit('changeModalStatus');
+        // a dialog's before-open / closed event: the store knows which dialogs are open (Space is off then)
+        setModalOpen(name, open) {
+            this.$store.commit('setModalOpen', {name, open});
         },
 
         calculateMaxBPM() {
@@ -1673,7 +1683,7 @@ export default {
                 this.stopClock();
             }
             revertToDefault = true;
-            this.clockWorker.postMessage({action: 'setBPM', bpm: value});
+            this.clockWorker.postMessage({action: 'setBPM', bpm: value, ticksPerBeat: this.config.clockSettings.ticksPerBeat});
             if (revertToDefault) {
                 this.startClock();
             }
@@ -1933,8 +1943,8 @@ export default {
                 :minHeight="100"
                 :resizable="true"
                 :scrollable="true"
-                @opened="modalCallback"
-                @closed="modalCallback">
+                @before-open="setModalOpen('introModal', true)"
+                @closed="setModalOpen('introModal', false)">
                 <div class="babyParent">
                     <div class="window-header">
                         <p class="modalTitle">
@@ -1959,11 +1969,14 @@ export default {
                 :WebMIDISupport="WebMIDISupport"
                 :activeDevices="activeDevices"
                 :activeMidiOutputDevices="activeMidiOutputDevices"
+                :selectedMIDIInput="selectedMIDIDevice"
+                :selectedMIDIOutput="selectedMIDIOutputDevice"
                 @button-click="buttonAction"
                 @text-change="textFieldChanged"
                 @midi-device-change="onMIDIDeviceSelectedChange"
                 @midi-output-device-change="onMIDIOutputDeviceSelectedChange"
                 @bpm-change="bpmValueChanged"
+                @modal-open="(open) => setModalOpen('settingsModal', open)"
             ></SettingsModal>
 
             <!-- <div v-if="config.gui.pianoRoll.status"> -->

package/src/worker/agentWorker.js

@@ -25,6 +25,8 @@ let ctx = null;
 let renderLoop = null;
 // widget changes made while loadAlgorithm runs, for updateParameter once it has finished
 const pendingChanges = [];
+// page messages (sendToAgent) that arrive while loadAlgorithm runs, for processPageMessage once it has finished
+const pendingPageMessages = [];
 const missing = (name) => () => console.warn(`agent/hooks.js does not define ${name}()`);
 const hook = (name, fallback) => (typeof agent[name] === 'function' ? agent[name] : fallback ?? missing(name));
 const loadExternalFiles = hook('loadExternalFiles', () => undefined);
@@ -37,6 +39,8 @@ const updateParameter = hook('updateParameter', () => undefined);
 const processClockEvent = hook('processClockEvent', () => ({}));
 const processNoteEvent = hook('processNoteEvent', () => undefined);
 const processAudioBuffer = hook('processAudioBuffer', () => undefined);
+const processPageMessage = hook('processPageMessage', () => warnOnce('the page sent the agent a message ' +
+    '(sendToAgent), but agent/hooks.js defines no processPageMessage'));
 
 import {LIFOQueue} from '../utils/dataStructures.js';
 import {NoteEvent} from '../utils/NoteEvent.js';
@@ -79,6 +83,8 @@ let uiParameterIntervalID = null;
 let clockQueue = Promise.resolve();
 // and note events too
 let noteQueue = Promise.resolve();
+// and page messages
+let pageQueue = Promise.resolve();
 
 self.param_reader = null;
 self.param_writer = null;
@@ -147,6 +153,22 @@ function runUpdateParameter(change) {
     }).catch((error) => console.error('updateParameter failed', error));
 }
 
+/**
+ * Passes a page message (sendToAgent on the page) to processPageMessage, in order; what the hook returns (notes,
+ * text, page, ...) is sent like any hook's.
+ * @param {*} data
+ * @return {Promise<void>}
+ */
+function runPageMessage(data) {
+    pageQueue = pageQueue.then(async () => {
+        const message = defined ?
+            toMessage(await processPageMessage(data, ctx), 'processPageMessage', ctx) :
+            await processPageMessage(data);
+        if (message && Object.keys(message).length) postMessage({hookType: self.agentHookType.NOTE_EVENT, message});
+    }).catch((error) => console.error('processPageMessage failed', error));
+    return pageQueue;
+}
+
 /**
  * This function is called regularily to check if there are any
  * new parameters from the UI.
@@ -264,6 +286,12 @@ async function onMessageFunction(obj) {
         if (defined) dispatchChange({kind: 'text', id, value});
         return;
     }
+    if (obj.data?.control === 'pageMessage') {
+        // the page's sendToAgent(data): held while a defineAgent agent loads, like widget changes
+        if (!ctx || (defined && ctx._loading)) pendingPageMessages.push(obj.data.data);
+        else runPageMessage(obj.data.data);
+        return;
+    }
     if (obj.data?.control === 'audioInStart') {
         audioInStart = obj.data.time;
         return;
@@ -376,6 +404,7 @@ async function initAgent(content) {
         } else {
             const externalFilesLoaded = loadExternalFiles();
             loadAlgorithm(externalFilesLoaded);
+            for (const data of pendingPageMessages.splice(0)) runPageMessage(data);
             initAudio(content);
             initParameterSharing(content);
         }
@@ -400,6 +429,7 @@ async function loadDefinedAgent() {
         if (typeof agent.loadAlgorithm === 'function') await agent.loadAlgorithm(ctx);
         ctx._loading = false;
         for (const change of pendingChanges.splice(0)) await runUpdateParameter(change);
+        for (const data of pendingPageMessages.splice(0)) runPageMessage(data);
         if (typeof agent.renderAudio === 'function') {
             if (ctx.audioOut) {
                 renderLoop = startRenderLoop(agent.renderAudio, ctx, (error) => console.error('renderAudio failed', error));

package/src/worker/clock.js

@@ -1,12 +1,15 @@
 /* eslint-disable require-jsdoc */
 let bpm = 100;
+// clockSettings.ticksPerBeat, and clockSettings.clockPeriod (ms, free time: overrides bpm and ticksPerBeat)
+let ticksPerBeat = 4;
+let clockPeriod = null;
 let isRunning = false;
 let intervalId = null;
 
 function startClock() {
     if (!isRunning) {
         isRunning = true;
-        intervalId = setInterval(tick, 1000 * 60 / bpm / 4);
+        intervalId = setInterval(tick, clockPeriod ?? 1000 * 60 / bpm / ticksPerBeat);
     }
 }
 
@@ -26,6 +29,8 @@ self.onmessage = function(msg) {
     const data = msg.data;
     if (data.action === 'setBPM') {
         bpm = data.bpm;
+        if (data.ticksPerBeat) ticksPerBeat = data.ticksPerBeat;
+        if (data.clockPeriod !== undefined) clockPeriod = data.clockPeriod || null;
         // if (isRunning) {
         //   stopClock();
         //   startClock();

package/src/worker/context.js

@@ -14,7 +14,7 @@ const INSTRUMENTS = {piano: instrumentType.PIANO, drums: instrumentType.DRUMS, b
 const MESSAGE_KEYS = {
     notes: messageType.NOTE_LIST, text: messageType.TEXT, label: messageType.LABEL, vector: messageType.VECTOR,
     key: messageType.KEY, session: messageType.SESSION, timingReset: messageType.TIMING_RESET,
-    status: messageType.STATUS, humanToken: messageType.HUMAN_TOKEN,
+    status: messageType.STATUS, humanToken: messageType.HUMAN_TOKEN, page: messageType.PAGE,
 };
 
 // uiParameterType index -> {kind, id}, e.g. 0 -> {kind: 'slider', id: 1}

package/types/agent.d.ts

@@ -15,7 +15,7 @@ export declare const messageType: {
     readonly STATUS: 0; readonly CLOCK_TIME: 1; readonly INFERENCE_TIME: 2; readonly NOTE_LIST: 4;
     readonly AUDIO_BUFFER: 7; readonly CHROMA_VECTOR: 10; readonly VECTOR: 11; readonly CHORD_LABEL: 12;
     readonly TEXT: 13; readonly LABEL: 14; readonly KEY: 15; readonly SESSION: 16; readonly TIMING_RESET: 18;
-    readonly HUMAN_TOKEN: 19;
+    readonly HUMAN_TOKEN: 19; readonly PAGE: 20;
 };
 export declare const statusType: {
     readonly LOADED: 0; readonly WARMUP: 1; readonly SUCCESS: 2; readonly ERROR: 3; readonly REPORT: 4;
@@ -98,6 +98,8 @@ export type HookOutput = void | null | undefined | Array<NoteEvent | PlainNote>
     humanToken?: HumanToken;
     /** A recorded session for the UI to download. */
     session?: unknown;
+    /** Data for the project's page code: the onAgentMessage listeners of the handle mount() returns. */
+    page?: unknown;
     /** The original protocol: values keyed by messageType number. */
     [messageType: number]: unknown;
 };
@@ -260,6 +262,11 @@ export interface AgentHooks {
      * all). Called whenever less than audioOut.latency seconds are queued, one call at a time.
      */
     renderAudio?(frames: number, ctx: Ctx): Awaitable<Float32Array | Float32Array[] | void>;
+    /**
+     * The project's page code sent `data` (sendToAgent on the handle mount() returns), e.g. from a widget of its
+     * own. In order; held until loadAlgorithm has finished. Return `{page: data}` to answer the page.
+     */
+    processPageMessage?(data: any, ctx: Ctx): Awaitable<HookOutput>;
 }
 
 export declare const AGENT_MARK: unique symbol;

package/types/index.d.ts

@@ -1,8 +1,22 @@
 /**
  * euterpe: the UI. A project's index.html calls mount(); the agent comes from agent/ through euterpe/vite.
  */
-/** Mounts the Euterpe UI into `el` (default '#app') and returns the root Vue instance. */
-export declare function mount(el?: string | Element): unknown;
+/** Mounts the Euterpe UI into `el` (default '#app'). */
+export declare function mount(el?: string | Element): EuterpeApp;
+
+/** What mount() returns: the project's page code talks to the agent through it. */
+export interface EuterpeApp {
+    /** The root Vue instance. */
+    readonly vm: unknown;
+    /**
+     * Sends `data` to the agent's processPageMessage(data, ctx) hook, e.g. a press on the page's own widget.
+     * `data` must be structured-cloneable (plain objects, arrays, numbers, strings, typed arrays). Messages sent
+     * before the agent has loaded wait for it.
+     */
+    sendToAgent(data: unknown): void;
+    /** Calls `listener` with every `{page: data}` the agent sends (a hook's return value or ctx.send). Returns an unsubscribe. */
+    onAgentMessage(listener: (data: any) => void): () => void;
+}
 
 /** window.__euterpe: the running UI's handle for tests and scripts. */
 export interface EuterpeHandle {