tuneframes 0.1.1 → 0.2.0

package/src/cli.js

@@ -1,152 +1,261 @@
-#!/usr/bin/env node
-/**
- * TuneFrames CLI
- *
- * Commands:
- *   tuneframes render <file.html> [--output track.mp3]
- *   tuneframes init <project-name>
- *   tuneframes preview <file.html>
- *   tuneframes validate <file.html>
- *   tuneframes add <preset-name>
- */
-
-const { render } = require('./render');
-const fs = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-
-const PRESETS = ['drums-lofi', 'reverb-warm', 'chord-progression', 'bass-saw', 'lead-piano'];
-
-async function main() {
-  const [,, cmd, ...args] = process.argv;
-
-  switch (cmd) {
-    case 'render': {
-      const inputFile = args[0];
-      const outputArg = args.find(a => a.startsWith('--output='));
-      const outputFile = outputArg
-        ? outputArg.split('=')[1]
-        : inputFile.replace(/\.html$/, '.mp3');
-
-      if (!inputFile) {
-        console.error('Usage: tuneframes render <file.html> [--output=track.mp3] [--format wav]');
-        process.exit(1);
-      }
-
-      if (!fs.existsSync(inputFile)) {
-        console.error(`File not found: ${inputFile}`);
-        process.exit(1);
-      }
-
-      console.log(`Rendering ${inputFile} → ${outputFile}`);
-      const result = await render(inputFile, outputFile);
-      console.log(`Done. Output: ${result.output}`);
-      break;
-    }
-
-    case 'init': {
-      const [projectName] = args;
-      if (!projectName) {
-        console.error('Usage: tuneframes init <project-name>');
-        process.exit(1);
-      }
-
-      const dir = path.join(process.cwd(), projectName);
-      fs.mkdirSync(dir, { recursive: true });
-
-      const example = fs.readFileSync(
-        path.join(__dirname, '../examples/example-lofi.html'), 'utf8'
-      );
-      fs.writeFileSync(path.join(dir, 'composition.html'), example);
-      fs.writeFileSync(path.join(dir, 'README.md'),
-        `# ${projectName}\n\nRun: tuneframes render composition.html\n`);
-
-      console.log(`Initialized ${projectName}/`);
-      break;
-    }
-
-    case 'preview': {
-      const inputFile = args[0];
-      if (!inputFile) {
-        console.error('Usage: tuneframes preview <file.html>');
-        process.exit(1);
-      }
-      const url = `file://${path.resolve(inputFile)}`;
-      console.log(`Preview: ${url}`);
-      if (process.platform === 'darwin') {
-        spawn('open', [url]);
-      } else if (process.platform === 'linux') {
-        spawn('xdg-open', [url]);
-      }
-      break;
-    }
-
-    case 'validate': {
-      const inputFile = args[0];
-      if (!inputFile) {
-        console.error('Usage: tuneframes validate <file.html>');
-        process.exit(1);
-      }
-      if (!fs.existsSync(inputFile)) {
-        console.error(`File not found: ${inputFile}`);
-        process.exit(1);
-      }
-
-      const tmpOut = `/tmp/tuneframes-validate-${Date.now()}.mp3`;
-      try {
-        await render(inputFile, tmpOut);
-        const stats = fs.statSync(tmpOut);
-        if (stats.size < 5000) {
-          console.error(`FAIL: ${inputFile} rendered to ${stats.size} bytes (< 5000)`);
-          process.exit(1);
-        }
-        console.log(`OK: ${inputFile} — ${stats.size} bytes`);
-      } finally {
-        if (fs.existsSync(tmpOut)) fs.unlinkSync(tmpOut);
-      }
-      break;
-    }
-
-    case 'add': {
-      const [presetName] = args;
-      if (!presetName) {
-        console.error(`Usage: tuneframes add <preset>\nAvailable: ${PRESETS.join(', ')}`);
-        process.exit(1);
-      }
-      if (!PRESETS.includes(presetName)) {
-        console.error(`Unknown preset: ${presetName}\nAvailable: ${PRESETS.join(', ')}`);
-        process.exit(1);
-      }
-
-      const presetPath = path.join(__dirname, `../registry/presets/${presetName}.html`);
-      const content = fs.readFileSync(presetPath, 'utf8');
-
-      // Append to composition.html in current directory
-      const compPath = path.join(process.cwd(), 'composition.html');
-      if (!fs.existsSync(compPath)) {
-        console.error('No composition.html found. Run tuneframes init first.');
-        process.exit(1);
-      }
-
-      const existing = fs.readFileSync(compPath, 'utf8');
-      const insertMarker = '</script>';
-      if (existing.includes(insertMarker)) {
-        const newContent = existing.replace(insertMarker, content + '\n' + insertMarker);
-        fs.writeFileSync(compPath, newContent);
-      } else {
-        fs.appendFileSync(compPath, '\n' + content);
-      }
-
-      console.log(`Added ${presetName} to composition.html`);
-      break;
-    }
-
-    default:
-      console.log(`TuneFrames CLI\n\nCommands:\n  tuneframes render <file.html>  Render composition to MP3\n  tuneframes init <name>         Initialize new project\n  tuneframes preview <file.html> Open in browser\n  tuneframes validate <file.html> Validate composition (headless test render)\n  tuneframes add <preset>         Add preset to composition.html\n\nPresets: ${PRESETS.join(', ')}`);
-  }
-}
-
-main().catch(err => {
-  console.error('Error:', err.message);
-  process.exit(1);
+#!/usr/bin/env node
+/**
+ * TuneFrames CLI
+ *
+ * Commands:
+ *   tuneframes render <file.html> [--output track.mp3]
+ *   tuneframes init <project-name>
+ *   tuneframes preview <file.html>
+ *   tuneframes validate <file.html>
+ *   tuneframes add <preset-name>
+ */
+
+const { render } = require('./render');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const PRESETS = ['drums-lofi', 'reverb-warm', 'chord-progression', 'bass-saw', 'lead-piano'];
+
+async function main() {
+  const [,, cmd, ...args] = process.argv;
+
+  switch (cmd) {
+    case 'render': {
+      const inputFile = args[0];
+      const equalsArg = args.find(a => a.startsWith('--output='));
+      const separateIdx = args.indexOf('--output');
+      const formatIdx = args.indexOf('--format');
+      const outputFile = equalsArg
+        ? equalsArg.split('=')[1]
+        : separateIdx !== -1 && args[separateIdx + 1] && !args[separateIdx + 1].startsWith('--')
+        ? args[separateIdx + 1]
+        : inputFile.replace(/\.html$/, '.mp3');
+      const outputFormat = formatIdx !== -1 && args[formatIdx + 1] ? args[formatIdx + 1] : 'mp3';
+
+      const timeoutEqArg = args.find(a => a.startsWith('--timeout='));
+      const timeoutIdx = args.indexOf('--timeout');
+      const timeoutSec = timeoutEqArg
+        ? parseInt(timeoutEqArg.split('=')[1], 10)
+        : timeoutIdx !== -1 && args[timeoutIdx + 1] && !args[timeoutIdx + 1].startsWith('--')
+        ? parseInt(args[timeoutIdx + 1], 10)
+        : 60;
+      const timeoutMs = timeoutSec * 1000;
+
+      if (!inputFile) {
+        console.error('Usage: tuneframes render <file.html> [--output=track.mp3] [--format wav] [--timeout 60]');
+        process.exit(1);
+      }
+
+      if (!fs.existsSync(inputFile)) {
+        console.error(`File not found: ${inputFile}`);
+        process.exit(1);
+      }
+
+      console.log(`Rendering ${inputFile} → ${outputFile}`);
+      const result = await render(inputFile, outputFile, outputFormat, timeoutMs);
+      console.log(`Done. Output: ${result.output}`);
+      break;
+    }
+
+    case 'init': {
+      const [projectName] = args;
+      if (!projectName) {
+        console.error('Usage: tuneframes init <project-name>');
+        process.exit(1);
+      }
+
+      const dir = path.join(process.cwd(), projectName);
+      fs.mkdirSync(dir, { recursive: true });
+
+      const example = fs.readFileSync(
+        path.join(__dirname, '../examples/example-lofi.html'), 'utf8'
+      );
+      fs.writeFileSync(path.join(dir, 'composition.html'), example);
+      fs.writeFileSync(path.join(dir, 'README.md'),
+        `# ${projectName}\n\nRun: tuneframes render composition.html\n`);
+
+      console.log(`Initialized ${projectName}/`);
+      break;
+    }
+
+    case 'preview': {
+      const inputFile = args[0];
+      if (!inputFile) {
+        console.error('Usage: tuneframes preview <file.html>');
+        process.exit(1);
+      }
+      const url = `file://${path.resolve(inputFile)}`;
+      console.log(`Preview: ${url}`);
+      if (process.platform === 'darwin') {
+        spawn('open', [url]);
+      } else if (process.platform === 'linux') {
+        spawn('xdg-open', [url]);
+      }
+      break;
+    }
+
+    case 'validate': {
+      const inputFile = args[0];
+      if (!inputFile) {
+        console.error('Usage: tuneframes validate <file.html>');
+        process.exit(1);
+      }
+      if (!fs.existsSync(inputFile)) {
+        console.error(`File not found: ${inputFile}`);
+        process.exit(1);
+      }
+
+      const tmpOut = `/tmp/tuneframes-validate-${Date.now()}.mp3`;
+      try {
+        await render(inputFile, tmpOut);
+        const stats = fs.statSync(tmpOut);
+        if (stats.size < 5000) {
+          console.error(`FAIL: ${inputFile} rendered to ${stats.size} bytes (< 5000)`);
+          process.exit(1);
+        }
+        console.log(`OK: ${inputFile} — ${stats.size} bytes`);
+      } finally {
+        if (fs.existsSync(tmpOut)) fs.unlinkSync(tmpOut);
+      }
+      break;
+    }
+
+    case 'lint': {
+      const inputFile = args[0];
+      if (!inputFile) {
+        console.error('Usage: tuneframes lint <file.html>');
+        process.exit(1);
+      }
+      if (!fs.existsSync(inputFile)) {
+        console.error(`File not found: ${inputFile}`);
+        process.exit(1);
+      }
+
+      const content = fs.readFileSync(inputFile, 'utf8');
+      const errors = [];
+
+      // Check 1: must have <div id="tuneframes">
+      if (!content.includes('id="tuneframes"')) {
+        errors.push('Missing <div id="tuneframes"> metadata block');
+      }
+
+      // Check 2: metadata must be valid JSON
+      const metaMatch = content.match(/id="tuneframes"[^>]*>([^<]+)<\/div>/);
+      if (metaMatch) {
+        try {
+          JSON.parse(metaMatch[1].trim());
+        } catch (e) {
+          errors.push(`Invalid JSON in metadata block: ${e.message}`);
+        }
+      }
+
+      // Check 3: must load Tone.js
+      if (!content.includes('Tone.js') && !content.includes('tone')) {
+        errors.push('No Tone.js script reference found');
+      }
+
+      // Check 4: must have async function main()
+      if (!content.includes('async function main()')) {
+        errors.push('Missing async function main()');
+      }
+
+      // Check 5: main() should contain await Tone.start()
+      if (content.includes('async function main()') && !content.includes('Tone.start()')) {
+        errors.push('main() should call await Tone.start()');
+      }
+
+      if (errors.length === 0) {
+        console.log(`OK: ${inputFile}`);
+      } else {
+        errors.forEach(e => console.error(`FAIL: ${e}`));
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'add': {
+      const [presetName] = args;
+      if (!presetName) {
+        console.error(`Usage: tuneframes add <preset>\nAvailable: ${PRESETS.join(', ')}`);
+        process.exit(1);
+      }
+      if (!PRESETS.includes(presetName)) {
+        console.error(`Unknown preset: "${presetName}"\nAvailable presets: ${PRESETS.join(', ')}\n\nFor CDN soundfont instruments (Tone.Sampler), run: tuneframes instruments`);
+        process.exit(1);
+      }
+
+      const presetPath = path.join(__dirname, `../registry/presets/${presetName}.html`);
+      const content = fs.readFileSync(presetPath, 'utf8');
+
+      // Append to composition.html in current directory
+      const compPath = path.join(process.cwd(), 'composition.html');
+      if (!fs.existsSync(compPath)) {
+        console.error('No composition.html found. Run tuneframes init first.');
+        process.exit(1);
+      }
+
+      const existing = fs.readFileSync(compPath, 'utf8');
+      const insertMarker = '</script>';
+      if (existing.includes(insertMarker)) {
+        const newContent = existing.replace(insertMarker, content + '\n' + insertMarker);
+        fs.writeFileSync(compPath, newContent);
+      } else {
+        fs.appendFileSync(compPath, '\n' + content);
+      }
+
+      console.log(`Added ${presetName} to composition.html`);
+      break;
+    }
+
+    case 'instruments': {
+      const GLEITZ_BASE = 'https://gleitz.github.io/midi-js-soundfonts/MusyngKite/{instrument}-mp3/{note}.mp3';
+      const DRUMS_CDN = 'https://dave4mpls.github.io/midi-js-soundfonts-with-drums/FluidR3_GM/drums-mp3/{note}.mp3';
+
+      console.log('gleitz CDN instruments (MusyngKite, high quality)');
+      console.log(`URL pattern: ${GLEITZ_BASE}\n`);
+
+      const categories = {
+        'Piano':          ['acoustic_grand_piano','bright_acoustic_piano','electric_grand_piano','honkytonk_piano','electric_piano_1','electric_piano_2','harpsichord','clavinet'],
+        'Chromatic Perc': ['celesta','glockenspiel','music_box','vibraphone','marimba','xylophone','tubular_bells','dulcimer'],
+        'Organ':          ['drawbar_organ','percussive_organ','rock_organ','church_organ','reed_organ','accordion','harmonica','tango_accordion'],
+        'Guitar':         ['acoustic_guitar_nylon','acoustic_guitar_steel','electric_guitar_jazz','electric_guitar_clean','electric_guitar_muted','overdriven_guitar','distortion_guitar','guitar_harmonics'],
+        'Bass':           ['acoustic_bass','electric_bass_finger','electric_bass_pick','fretless_bass','slap_bass_1','slap_bass_2','synth_bass_1','synth_bass_2'],
+        'Strings':        ['violin','viola','cello','contrabass','tremolo_strings','pizzicato_strings','orchestral_harp','timpani'],
+        'Ensemble':       ['string_ensemble_1','string_ensemble_2','synth_strings_1','synth_strings_2','choir_aahs','voice_oohs','synth_choir','orchestra_hit'],
+        'Brass':          ['trumpet','trombone','tuba','muted_trumpet','french_horn','brass_section','synth_brass_1','synth_brass_2'],
+        'Reed':           ['soprano_sax','alto_sax','tenor_sax','baritone_sax','oboe','english_horn','bassoon','clarinet'],
+        'Pipe':           ['piccolo','flute','recorder','pan_flute','blown_bottle','shakuhachi','whistle','ocarina'],
+        'Synth Lead':     ['lead_1_square','lead_2_sawtooth','lead_3_calliope','lead_4_chiff','lead_5_charang','lead_6_voice','lead_7_fifths','lead_8_bass_and_lead'],
+        'Synth Pad':      ['pad_1_new_age','pad_2_warm','pad_3_polysynth','pad_4_choir','pad_5_bowed','pad_6_metallic','pad_7_halo','pad_8_sweep'],
+        'Synth FX':       ['fx_1_rain','fx_2_soundtrack','fx_3_crystal','fx_4_atmosphere','fx_5_brightness','fx_6_goblins','fx_7_echoes','fx_8_scifi'],
+        'Ethnic':         ['sitar','banjo','shamisen','koto','kalimba','bagpipe','fiddle','shanai'],
+        'Percussive':     ['tinkle_bell','agogo','steel_drums','woodblock','taiko_drum','melodic_tom','synth_drum','reverse_cymbal'],
+        'Sound FX':       ['guitar_fret_noise','breath_noise','seashore','bird_tweet','telephone_ring','helicopter','applause','gunshot'],
+      };
+
+      for (const [cat, list] of Object.entries(categories)) {
+        console.log(`${cat}:`);
+        console.log('  ' + list.join('  '));
+      }
+
+      console.log('\nDrums (dave4mpls fork — standard gleitz does not include GM drums):');
+      console.log(`  URL: ${DRUMS_CDN}`);
+      console.log('  Trigger notes: C2=Kick  D2=Snare  Gb2=Hi-Hat(closed)  Bb2=Hi-Hat(open)  Db3=Crash  Eb3=Ride');
+
+      console.log('\nNotes:');
+      console.log('  - All 88 notes present per instrument (A0–C8), flat notation only (Ab4.mp3, not G#4.mp3)');
+      console.log('  - Tone.Sampler accepts both Ab4 and G#4 as url keys — either works');
+      console.log('  - Set window.TUNEFRAMES_READY = Tone.loaded() so the renderer waits for samples');
+      break;
+    }
+
+    default:
+      console.log(`TuneFrames CLI\n\nCommands:\n  tuneframes render <file.html>  Render composition to MP3\n  tuneframes init <name>         Initialize new project\n  tuneframes preview <file.html> Open in browser\n  tuneframes validate <file.html> Validate composition (headless test render)\n  tuneframes lint <file.html>    Lint composition (static HTML analysis)\n  tuneframes add <preset>         Add preset to composition.html\n  tuneframes instruments          List gleitz CDN instruments for Tone.Sampler\n\nPresets: ${PRESETS.join(', ')}`);
+  }
+}
+
+main().catch(err => {
+  console.error('Error:', err.message);
+  process.exit(1);
 });

package/src/render.js

@@ -37,6 +37,60 @@ const HELPER_SCRIPT = `
 
   window.audioBufferToWav = audioBufferToWav;
 
+  // Tone.js CDN bundle defines exports as non-writable, non-configurable getter
+  // properties (rollup live-binding pattern). Direct assignment and Object.defineProperty
+  // both fail to override them. Proxy on window.Tone is the only reliable intercept.
+  //
+  // AudioWorklet effects (Freeverb, BitCrusher, Chebyshev) fail in headless offline
+  // rendering because worklet modules cannot load. The Proxy returns unity-gain
+  // passthroughs for those classes when inside a Tone.Offline() call (_inOff flag).
+  //
+  // Reverb tracking is also done in the Proxy get trap (rather than Tone.Reverb = ...)
+  // because Tone.Reverb is a non-configurable no-setter accessor — setting it would
+  // violate Proxy invariants. Instances pushed to window._tfRev; awaited after main().
+  window._patchToneWorklets = function() {
+    if (typeof Tone === 'undefined' || window._tonePatched) return;
+    window._tonePatched = true;
+
+    const _orig = window.Tone;
+    const _origOffline = _orig.Offline;
+
+    const _mkPass = () => class extends _orig.Gain {
+      constructor() { super(1); }
+      // Reverb-compat stubs: some skills call await reverb.generate() or await reverb.ready.
+      generate() { return Promise.resolve(this); }
+      get ready() { return Promise.resolve(this); }
+    };
+    // Reverb included: its IR generation calls the module-internal Offline() which
+    // creates a nested offline context and corrupts the outer timeline. Passthrough
+    // eliminates the nested context entirely. Audio flows through; dry-signal-only
+    // is acceptable for a headless render test.
+    const _fx = { Freeverb: _mkPass(), BitCrusher: _mkPass(), Chebyshev: _mkPass(), Reverb: _mkPass() };
+
+    let _inOff = false;
+
+    const _wOffline = async function(cb, ...args) {
+      _inOff = true;
+      try { return await _origOffline(cb, ...args); }
+      finally { _inOff = false; }
+    };
+
+    window.Tone = new Proxy(_orig, {
+      get(t, p) {
+        if (p === 'Offline') return _wOffline;
+        if (_inOff && p in _fx) return _fx[p];
+        return t[p];
+      },
+      set(t, p, v) {
+        // Return false for non-configurable no-setter accessors to honor Proxy invariant.
+        const d = Object.getOwnPropertyDescriptor(t, p);
+        if (d && !d.configurable && d.get && !d.set) return false;
+        try { t[p] = v; } catch(e) {}
+        return true;
+      }
+    });
+  };
+
   window.renderComposition = async function(wavPath) {
     // Wait for Tone.js to be ready
     let attempts = 0;
@@ -47,21 +101,79 @@ const HELPER_SCRIPT = `
     if (typeof Tone === 'undefined') throw new Error('Tone not loaded');
     if (typeof window.audioBufferToWav !== 'function') throw new Error('audioBufferToWav not injected');
 
-    let bpm = 120, duration = '4n';
+    window._patchToneWorklets();
+
+    // Wait for TUNEFRAMES_READY if composition uses Tone.Sampler / CDN samples
+    if ('TUNEFRAMES_READY' in window) {
+      const signal = window.TUNEFRAMES_READY;
+      if (signal && typeof signal.then === 'function') {
+        await signal;
+      } else {
+        let waited = 0;
+        while (!window.TUNEFRAMES_READY && waited < 120000) {
+          await new Promise(r => setTimeout(r, 200));
+          waited += 200;
+        }
+        if (!window.TUNEFRAMES_READY) throw new Error('TUNEFRAMES_READY timed out after 120s');
+      }
+    }
+
+    let bpm = 120, duration = '12s';
     const metaEl = document.getElementById('tuneframes');
     if (metaEl) {
+      // Support both JSON textContent and data-* attributes
       try {
-        const meta = JSON.parse(metaEl.textContent);
-        bpm = meta.bpm || 120;
-        duration = meta.duration || '4n';
+        const txt = metaEl.textContent.trim();
+        if (txt) {
+          const meta = JSON.parse(txt);
+          bpm = meta.bpm || 120;
+          duration = meta.duration || '12s';
+        }
       } catch(e) {}
+      if (metaEl.dataset.bpm) bpm = parseInt(metaEl.dataset.bpm, 10) || bpm;
+      if (metaEl.dataset.duration) duration = metaEl.dataset.duration || duration;
     }
 
     const durationSec = Math.max(Tone.Time(duration).toSeconds() + 0.5, 2);
     console.log('TuneFrames: rendering', durationSec, 's at BPM', bpm);
 
     const audioBuffer = await Tone.Offline(async () => {
+      // Fix: MetalSynth.triggerAttackRelease calls triggerAttack(computedTime, velocity)
+      // but triggerAttack(note, time, velocity) treats first arg as note and second as time,
+      // so toSeconds(velocity=undefined) = 0 for every trigger. Replace TAR to call
+      // _triggerEnvelopeAttack/_triggerEnvelopeRelease directly with the correct time.
+      // Also bumps same-time triggers by 0.1ms to prevent StateTimeline ordering errors.
+      if (typeof Tone !== 'undefined' && Tone.MetalSynth) {
+        Tone.MetalSynth.prototype.triggerAttackRelease = function(duration, time, velocity) {
+          const rawT = (time === undefined || time === null || +time <= 0) ? 0.05 : +time;
+          const vel = velocity !== undefined ? velocity : 1;
+          const dur = Tone.Time(duration).toSeconds();
+          let safeT = rawT;
+          try {
+            if (this._oscillators && this._oscillators[0] && this._oscillators[0]._state) {
+              const tl = this._oscillators[0]._state._timeline;
+              if (tl && tl.length > 0 && safeT <= tl[tl.length - 1].time) {
+                safeT = tl[tl.length - 1].time + 0.0001;
+              }
+            }
+          } catch(e) {}
+          this._triggerEnvelopeAttack(safeT, vel);
+          // Release envelope only; stopping oscillators adds StateTimeline stop events
+          // that block same-period re-triggers on rapid percussion patterns.
+          if (this.envelope && typeof this.envelope.triggerRelease === 'function') {
+            this.envelope.triggerRelease(safeT + dur);
+          }
+          return this;
+        };
+      }
+
       if (typeof main === 'function') await main();
+
+      // Auto-start Transport so Tone.Sequence / Tone.Part patterns play.
+      // Skills that already call Transport.start() inside main() are unaffected.
+      if (typeof Tone !== 'undefined' && Tone.Transport && Tone.Transport.state !== 'started') {
+        Tone.Transport.start(0);
+      }
     }, durationSec, 1, 44100, bpm);
 
     console.log('TuneFrames: buffer ready', audioBuffer.duration, audioBuffer.length);
@@ -76,10 +188,12 @@ const HELPER_SCRIPT = `
 })();
 `;
 
-async function render(compositionPath, outputPath, format = 'mp3') {
+async function render(compositionPath, outputPath, format = 'mp3', timeout = 60000) {
   const browser = await chromium.launch({ headless: true });
   const page = await browser.newPage();
 
+  page.setDefaultTimeout(timeout + 60000);
+
   page.on('pageerror', err => console.error('BROWSER ERR:', err.message));
   page.on('console', msg => console.log('BROWSER:', msg.type(), msg.text()));
 
@@ -93,15 +207,28 @@ async function render(compositionPath, outputPath, format = 'mp3') {
   await page.addInitScript({ content: HELPER_SCRIPT });
 
   await page.goto(`file://${path.resolve(compositionPath)}`, {
-    waitUntil: 'domcontentloaded', timeout: 30000
+    waitUntil: 'domcontentloaded', timeout
   });
 
   // Wait for Tone.js to actually be available
   await page.waitForFunction(() => typeof Tone !== 'undefined', { timeout: 15000 });
-  
+
+  // Apply global patches before any renderComposition runs.
+  // This covers skills that define their own renderComposition (e.g. audio-downtempo).
+  // Apply global patches before any renderComposition runs.
+  await page.evaluate(() => {
+    if (typeof window._patchToneWorklets === 'function') window._patchToneWorklets();
+  });
+
   // Also wait for our renderComposition to be defined
   await page.waitForFunction(() => typeof window.renderComposition === 'function', { timeout: 15000 });
 
+  // Check for TUNEFRAMES_READY signal (indicates Tone.Sampler / CDN sample usage)
+  const needsSampleWait = await page.evaluate(() => 'TUNEFRAMES_READY' in window);
+  if (needsSampleWait) {
+    console.log('Waiting for samples to load...');
+  }
+
   const wavPath = path.resolve(outputPath.replace(/\.[^.]+$/, '.wav'));
 
   console.log('Starting render...');