[snakajima]

Summary

render() no longer blocks the caller, and the GUI plugin shows its card before a long render's audio is ready. Both packages go to 1.0.0, because render() now returns a Promise (breaking).

1. render() returns a Promise and renders on a worker thread (Node)

• src/render-pool.ts / src/render-worker.ts: a small pool of worker threads (at most 2), reused between renders and unref'd while idle. The Node entry, renderToFiles and manage register it. NEUTRINO runs inside the worker, so an MCP server or GUI host keeps answering during a long piano piece or an uncached vocal.
• Output is bit-identical: the golden hashes pass unchanged, and a test compares worker vs. in-place rendering (renderNow, the internal synchronous core).
• Samples cross to the worker as data: loadSamples' sources can list what they hold. A caller's own SampleSource is asked for exactly the keys samplesNeeded reports.
• Errors keep their class across the thread (JingleScriptError, SamplesNotLoadedError, Neutrino*Error, …), so instanceof still works in the CLI and manage.
• Only RenderOptions' own fields cross the thread. A field added there is a type error until the pool passes it on, and anything else on the options object (e.g. renderToFiles' onDownload callback) stays behind.
• When a worker cannot run, the pool falls back to rendering in place, and says so once (process warning JINGLESCRIPT_NO_RENDER_WORKER): a bundle that left render-worker.js behind, or src/ on a Node that cannot strip types. The browser entry always renders in place. Sung renders run one at a time (NEUTRINO uses every core).
• Breaking: every render() call needs await. Tests, smoke, README, docs, eval and the playground worker are updated.

2. The card before the audio (GUI plugin)

• manage()'s deferAudio option, used only with player: renderScore waits at most DEFER_WAIT_MS (1 s) for the audio. A short jingle comes back finished, as before. Otherwise it answers at once with a pending PlayerData (score, lanes, cues, lyrics, sheet music; no audio). awaitDeferredPlayer(id) gives the finished one, why it failed, or gone (src/deferred-renders.ts). A finished render is kept in memory until a view collects it (then 1 min more, for another mount of the card), at most 30 min, and only the newest 20. NEUTRINO and its voice are checked before rendering (checkSinger), so a missing install always reaches the LLM.

• The plugin turns this on only when the host passes deferredAudio: true in its execute context. The view then:

  1. shows the pending card with play disabled and "Rendering the audio…";
  2. collects the audio through the host's runtime dispatch, as a { kind: "collectRenderedAudio", id } request that pluginCore.execute answers before treating the call as a tool call;
  3. saves it into the result with onUpdateResult;
  4. plays, autoplaying when asked. Freshness counts from when the audio was ready, and the voice-wait rules are unchanged.

  If the audio fails after the card appeared, the card says why and, for a fresh render, tells the LLM once. Hosts that don't set deferredAudio behave as before.

• gui-chat-protocol/vue is now external in the plugin build, so the view injects the host's runtime by the protocol's own PLUGIN_RUNTIME_KEY.

• CLAUDE.md: only the GUI plugin may lean on its host, and only as an opt-in. Used as a library (MulmoCast calls render()), nothing may depend on the host.

• To enable this, MulmoTerminal needs two changes (not in this PR; see gui-plugin README): wrap the view with wrapWithPluginRuntime, and add manageJingleScript: { deferredAudio: true } to EXTRA_CONTEXT_BY_TOOL.

Testing

• Root: 748 tests passed (100 skipped); typecheck, lint, prettier pass; scripts/smoke.sh (pack, install, render via CLI, library, browser entry, MCP) passes.
• gui-plugin: typecheck, 204 tests, build and playground build pass.
• Deferred path measured: a 42 s score answered in 1.2 s with a pending card; the audio arrived at 4.2 s.
• Browser (demo page with a stand-in runtime): the pending card shows lanes and cues with play disabled; 3 s later the waveform appears, play and the MP3 download are enabled, and autoplay starts. No console errors.
• Not done: running inside MulmoTerminal (needs the host change above).

Related: #43 (NEUTRINO render cache cleanup, follow-up from #42).

🤖 Generated with Claude Code

work in jinglescript