AMYboard Web: ?play=1 deep links auto-write sketch to simulator (#1092)

Marketing-page sketch links now carry play=1, so the linked sketch starts
playing as soon as the visitor clicks "Click anywhere to start" — no need
to know about "Write to Simulator". Plain shared links (no play=1) keep
the load-only review-first behavior, and the flag is ignored in control
mode so nothing is ever auto-written to real hardware.

Also fixes a pre-existing tab=code deep-link bug where the 300ms
re-select of sketch.py reloaded the FS default into the editor,
clobbering the world sketch that had just been loaded.

Adds the two missing example sketches to the marketing grid:
drum_machine (Gamma9001) and filter_audio_in.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: bwhitman

tulip/amyboardweb/static/index.html

@@ -658,83 +658,91 @@ <h2 class="section-title">Hear it in action</h2>
     <h2 class="section-title">What it can do</h2>
     <p style="font-size:1.2rem; font-weight:500; margin-bottom:2rem; opacity:0.85;">Try out some examples on <a href="/editor/" style="color:#FFDD00; text-decoration:underline; text-underline-offset:3px;">AMYboard online</a>, and send them to your AMYboard in seconds!</p>
     <div class="can-do-grid">
-      <a href="/editor/?mode=simulate&env=acid_generator&user=shorepine&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=acid_generator&user=shorepine&play=1&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Generative Acid patch (303 + 808)</span>
         <span class="can-do-desc">We set up a TB303 and 808 and play a generative pattern. Twiddle the knobs!!</span>
       </a>
-      <a href="/editor/?mode=simulate&env=woodpiano&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=drum_machine&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+        <span class="can-do-title">Gamma9001 drum machine</span>
+        <span class="can-do-desc">Three drum channels at once: a main kit rotating through all six Gamma9001 banks, TR-909 hats, and a tabla/shaker percussion layer.</span>
+      </a>
+      <a href="/editor/?mode=simulate&env=woodpiano&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">A custom 4-op FM synth</span>
         <span class="can-do-desc">We set up a custom ALGO patch in Python modeled after the infamous WOOD PIANO preset.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=methodical_mid&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=methodical_mid&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Play a MIDI file</span>
         <span class="can-do-desc">We load a MIDI file from disk and play it with a synth patch.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=spacey&user=shorepine&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=spacey&user=shorepine&play=1&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">A spacey synth patch</span>
         <span class="can-do-desc">Global effects (echo, reverb) on top of a slow envelope over PWM.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=cvfilter&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=cvfilter&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Control your filters with CV input</span>
         <span class="can-do-desc">We use the AMY CtrlCoef EXT0 to have CV input modulate the filter frequency.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=audiopassthru&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=filter_audio_in&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+        <span class="can-do-title">Filter live audio with CV</span>
+        <span class="can-do-desc">Runs live audio in through a low-pass filter, with the cutoff frequency controlled by CV1.</span>
+      </a>
+      <a href="/editor/?mode=simulate&env=audiopassthru&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Convert between SPDIF and analog audio</span>
         <span class="can-do-desc">Set up AMY to pass AUDIO_IN to AUDIO_OUT so that S/PDIF outputs over analog line-out, and vice versa.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=midi2cv&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=midi2cv&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">MIDI controller to CV</span>
         <span class="can-do-desc">We set up a callback to get MIDI controller data and output scaled CV values.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=dx7filt&user=shorepine&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=dx7filt&user=shorepine&play=1&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">DX7 setup with filter and reverb</span>
         <span class="can-do-desc">Try setting the MIDI CC for VCF freq!</span>
       </a>
-      <a href="/editor/?mode=simulate&env=arp&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=arp&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Arpeggiator</span>
         <span class="can-do-desc">Uses MIDI input callbacks and the AMY sequencer to set up an arpeggiator</span>
       </a>
-      <a href="/editor/?mode=simulate&env=audiopassthru&user=shorepine&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=audiopassthru&user=shorepine&play=1&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Echo / reverb on live audio</span>
         <span class="can-do-desc">Shows how to use AUDIO_IN to add effects on live audio. Turn on "allow audio input" on the web and move the effects!</span>
       </a>
-      <a href="/editor/?mode=simulate&env=chords&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=chords&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Chord computer</span>
         <span class="can-do-desc">Plays chords based on a root note.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=wavfile&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=wavfile&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Load a wav file into a sampler</span>
         <span class="can-do-desc">Loads a WAVE file from disk (can also be SD card) and plays it back as a sampler.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=xanadu&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=xanadu&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Xanadu</span>
         <span class="can-do-desc">Joseph Kung's "Xanadu" for Csound, ported to AMY commands in code.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=wavetable&user=shorepine&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=wavetable&user=shorepine&play=1&tab=patch" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Wavetable patch</span>
         <span class="can-do-desc">Uses our WAVETABLE oscillator type to play wavetable synthesis.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=preset_selector&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=preset_selector&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Preset Selector</span>
         <span class="can-do-desc">Sets up the rotary encoder to cycle through all 257 AMYboard presets.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=piano&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=piano&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Additive-synthesis piano</span>
         <span class="can-do-desc">Uses the AMY dpwe piano patch, fully synthesized from partial analysis.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=house_generator&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=house_generator&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Generative House</span>
         <span class="can-do-desc">A generative house track with 808 drums, Wood Piano bassline, and piano chords over evolving progressions.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=universal_hair&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=universal_hair&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Evolving Chords</span>
         <span class="can-do-desc">Lush evolving chord progressions with layered synths and generative voice leading.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=sampler&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=sampler&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Live MIDI sampler</span>
         <span class="can-do-desc">Hold a MIDI key to record up to 5s of audio in, then play it back pitched to the keyboard on synth 1.</span>
       </a>
-      <a href="/editor/?mode=simulate&env=sineclock&user=shorepine&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
+      <a href="/editor/?mode=simulate&env=sineclock&user=shorepine&play=1&tab=code" class="can-do-item" style="text-decoration:none; color:#fff;">
         <span class="can-do-title">Sineclock</span>
         <span class="can-do-desc">Douglas Repetto's sineclock — chimes the time of day with stacked sine waves.</span>
       </a>

tulip/amyboardweb/static/spss.js

@@ -11,6 +11,12 @@ var amyboard_started = false;
 // read later in start_audio() after check_url_env_params() has mutated the URL.
 // Keeps the default run_sketch() path from racing the deferred world-load.
 var _url_env_pending = false;
+// Deep-link autoplay (?play=1, used by the marketing page's sketch links):
+// once BOTH the deep-link sketch has loaded and audio has started, auto-write
+// it to the simulator so it plays without pressing "Write to Simulator".
+// Simulate mode only — never auto-writes to real hardware.
+var _url_env_autoplay = false;
+var _url_env_loaded = false;
 var amy_yield_synth_commands = null;
 var amy_dump_state_to_string_c = null;
 
@@ -3785,6 +3791,7 @@ async function import_amyboard_world_file(index) {
 
 // Load an AMYboard World environment by username and environment name.
 // Called from URL params: /editor/?env=woodpiano&user=bwhitman
+// Returns true if the sketch was fetched and loaded into the editor.
 async function load_world_environment_by_name(username, envName) {
     try {
         var params = new URLSearchParams();
@@ -3795,7 +3802,7 @@ async function load_world_environment_by_name(username, envName) {
         var data = await response.json();
         if (!data || !Array.isArray(data.items) || !data.items.length) {
             show_alert("Sketch '" + envName + "' by " + username + " not found.");
-            return;
+            return false;
         }
         // Match by filename stem (e.g. "spacey" matches "spacey.py" or legacy "spacey.tar")
         var item = null;
@@ -3809,7 +3816,7 @@ async function load_world_environment_by_name(username, envName) {
         }
         if (!item) {
             show_alert("Sketch '" + envName + "' by " + username + " not found.");
-            return;
+            return false;
         }
         var filename = normalize_world_filename(item.filename);
         var packageName = filename.replace(/\.(py|tar)$/, "");
@@ -3836,8 +3843,10 @@ async function load_world_environment_by_name(username, envName) {
         if (codeTabBtn && window.bootstrap) {
             try { new window.bootstrap.Tab(codeTabBtn).show(); } catch (e) {}
         }
+        return true;
     } catch (e) {
         show_alert("Failed to load sketch '" + envName + "' by " + username + ".");
+        return false;
     }
 }
 
@@ -3872,20 +3881,26 @@ function check_url_env_params() {
     var user = params.get("user");
     var tab = params.get("tab"); // "code" or "patch"
     if (env && user) {
+        // ?play=1 (marketing-page links): auto-write the sketch to the
+        // simulator once it loads and audio starts. Simulate mode only.
+        _url_env_autoplay = params.get("play") === "1" && amyboard_mode !== 'control';
         // Show immediate loading toast
         show_world_toast_loading(env);
         // Delay slightly to let micropython init complete
         setTimeout(async function() {
-            await load_world_environment_by_name(user, env);
+            _url_env_loaded = !!(await load_world_environment_by_name(user, env));
+            maybe_autoplay_url_env();
             // Switch to requested tab after environment loads
             if (tab === "code") {
                 var codeTab = document.getElementById("environment-tab");
                 if (codeTab) {
                     new bootstrap.Tab(codeTab).show();
-                    // Re-select sketch.py and refresh CodeMirror after tab is visible
+                    // Re-select sketch.py and refresh CodeMirror after tab is visible.
+                    // loadEditor must be false: true would re-read FS sketch.py into
+                    // the editor, clobbering the world sketch we just loaded above.
                     setTimeout(async function() {
                         if (list_environment_files().indexOf("sketch.py") !== -1) {
-                            await select_environment_file("sketch.py", true);
+                            await select_environment_file("sketch.py", false);
                         }
                         if (editor) {
                             editor.refresh();
@@ -3902,6 +3917,21 @@ function check_url_env_params() {
     }
 }
 
+// Deep-link autoplay: fires the same write_sketch_to_amyboard() the "Write to
+// Simulator" button does, once BOTH the deep-link sketch load and start_audio()
+// have completed. Either can finish first, so both call sites invoke this.
+async function maybe_autoplay_url_env() {
+    if (!_url_env_autoplay || !_url_env_loaded || !audio_started) return;
+    if (amyboard_mode === 'control') return;
+    _url_env_autoplay = false;  // one-shot
+    try {
+        await write_sketch_to_amyboard();
+        console.log('deep-link autoplay: sketch written to simulator');
+    } catch (e) {
+        console.warn('deep-link autoplay failed:', e);
+    }
+}
+
 // Remembered admin token for reserved usernames (e.g. "shorepine"). Stored in
 // a cookie only after a successful upload so a bad token never gets cached.
 var _ADMIN_TOKEN_COOKIE = "amyboard_world_admin_token";
@@ -6078,6 +6108,9 @@ except Exception as _e:
     // Sync UI knobs from the AMY state that run_sketch just applied.
     try { await sync_channel_knobs_from_synth_to_ui(window.current_synth || 1); } catch (e) {}
   }
+  // Deep-link ?play=1: if the sketch already loaded, write it to the simulator
+  // now that audio is running (the load-side call fires when audio wins the race).
+  await maybe_autoplay_url_env();
 }
 
 // ---- wire_code_parser.js ----