fix(doc-tests): empty // platforms: opts out of host run phase

The previous rule was: if a banner had no `platforms:` line at all,
default to all hosts. That collapsed the legitimate "opt out of the
host run phase" case (FFI imports only resolve under --target wasm /
--target web) into the same default-all branch, so wasm_snippets.ts
was being host-linked and failing on missing `bloom_*` externs.

- doc-tests/main.rs: track `platforms_seen` and only fall back to
  the default-all set when no directive was present at all. An
  explicit empty `// platforms:` now means "no host platforms".
- wasm_snippets.ts: switch to the new opt-out form and document why.

Cargo.lock follows v0.5.324 from 8190ec6.

Author: proggeramlug

Cargo.lock

@@ -415,13 +415,15 @@ fn read_banner(path: &Path) -> Result<Banner> {
     let text = std::fs::read_to_string(path)
         .with_context(|| format!("reading {}", path.display()))?;
     let mut b = Banner::default();
+    let mut platforms_seen = false;
     for line in text.lines().take(15) {
         let line = line.trim_start();
         if !line.starts_with("//") {
             break;
         }
         let body = line.trim_start_matches("//").trim();
         if let Some(rest) = body.strip_prefix("platforms:") {
+            platforms_seen = true;
             for item in rest.split(',') {
                 let t = item.trim();
                 if !t.is_empty() {
@@ -447,8 +449,13 @@ fn read_banner(path: &Path) -> Result<Banner> {
             }
         }
     }
-    // Default to "all hosts" if banner didn't specify.
-    if b.platforms.is_empty() {
+    // Default to "all hosts" only when no `platforms:` directive was given.
+    // An explicit empty `// platforms:` (no values) is the way an example
+    // opts out of the host run phase entirely — used by examples whose
+    // `declare function` FFI imports only resolve under `--target wasm` /
+    // `--target web`, where they lower to WASM imports instead of host
+    // linker externs.
+    if !platforms_seen {
         for p in ["macos", "linux", "windows"] {
             b.platforms.insert(p.to_string());
         }

crates/perry-doc-tests/src/main.rs

@@ -1,14 +1,18 @@
 // demonstrates: per-API wasm/web snippets shown in docs/src/platforms/wasm.md
 // docs: docs/src/platforms/wasm.md
-// platforms: macos, linux, windows
+// platforms:
+// targets: wasm, web
 // run: false
 
-// `run: false` because the snippets here either declare external FFI
-// functions whose host implementations live only in the browser bridge,
-// or call `fetch()` against a non-existent telemetry endpoint. The harness
-// still compiles + links the file on every PR, which catches API drift in
-// `declare function`, `fetch()`'s options shape, and `parallelMap` (whose
-// FFI lives in perry-runtime + perry-stdlib).
+// Empty `// platforms:` opts out of the host run phase. The `declare function`
+// FFI imports (`bloom_init_window`, `bloom_draw_rect`) lower to WASM imports
+// under `--target wasm` / `--target web`, but resolve through the host linker
+// on a native compile — and the host has no `bloom_*` symbols, so a native
+// link fails with `undefined reference`. The cross-compile phase still drives
+// `--target wasm` and `--target web` to catch API drift in `declare function`,
+// `fetch()`'s options shape, and `parallelMap` (whose FFI lives in
+// perry-runtime + perry-stdlib). `run: false` keeps the cross-compile artifact
+// from being executed.
 
 import { parallelMap } from "perry/thread"