doc-tests: wasm_snippets.ts banner should constrain to // targets: wasm — currently fails to link on every native target #219

Context

docs/examples/platforms/wasm_snippets.ts declares // platforms: macos, linux, windows and // run: false, then forward-declares two FFI functions whose host implementations live only in the browser bridge:

declare function bloom_init_window(w: number, h: number, title: number, fs: number): void
declare function bloom_draw_rect(x: number, y: number, w: number, h: number, ...): void

The example exists to illustrate how declare function lowers to WASM imports under --target wasm / --target web. But the doc-tests harness compiles every example with the native backend by default, which routes the declares through the host linker — and the host has no bloom_* symbols, so the link step fails with:

/usr/bin/ld: perry_llvm_*.ll:(.text+0x24): undefined reference to `bloom_init_window'
/usr/bin/ld: perry_llvm_*.ll:(.text+0x51): undefined reference to `bloom_draw_rect'

This affects all 3 platforms' doc-tests gates (macOS, GTK4, Windows). The current GTK4 gate is only red because of this + #216 + #217 + #218; once those land, this one needs the banner fix to take the gate green.

The example author left a comment acknowledging the pattern:

// Reference the declares so the codegen emits import lines into the WASM
// (otherwise the linker would dead-strip them on the native target).
function exerciseFfi(): void {
    bloom_init_window(800, 600, 0, 0)
    bloom_draw_rect(0, 0, 100, 100, 1.0, 0.0, 0.0, 1.0)
}

— which only makes sense on the wasm target. The author appears to have intended the example to be wasm-only but the banner enabled all-platforms.

Fix

Change the banner from // platforms: macos, linux, windows to // targets: wasm (or // platforms: empty + // targets: wasm, web). With targets pinned, the doc-tests harness will only attempt the wasm/web compile path, where declare function lowers to a WASM import statement instead of an ELF/Mach-O extern reference. The link step disappears entirely on those targets.

Verify by inspecting docs/examples/platforms/wasm.md (the doc page this example is {{#include}}'d into) — confirm the doc page already presents this as wasm-specific content.

Acceptance

• docs/examples/platforms/wasm_snippets.ts banner constrains to wasm/web targets (whichever shape the doc-tests harness already supports — // targets: is the most likely directive).
• All 3 doc-tests gates (macOS, GTK4, Windows) stop failing on this file. Confirm with a cargo run --release -p perry-doc-tests local sweep.
• The example still compiles cleanly under --target wasm and --target web. Verify by spot-checking the emitted .wasm for an import "ffi" "bloom_init_window" entry.

Pointers

• Failing example: docs/examples/platforms/wasm_snippets.ts
• Doc page that includes it: docs/src/platforms/wasm.md
• Banner parser (for valid directive shapes): crates/perry-doc-tests/src/main.rs::read_banner (~line 390)
• Cross-compile validator (for understanding which target combinations are buildable): crates/perry-doc-tests/src/main.rs::target_buildable_reason

Related

• doc-tests harness: pass --app-bundle-id (and other widget-cross-compile flags) so home-screen widget targets become exercisable #194 (closed v0.5.305 — banner/harness machinery these directives live in)
• GTK4: perry_ui_open_folder_dialog not wired — blocks docs/examples/ui/dialogs/snippets.ts on Linux CI #216 / GTK4: 4 widget overlay/reorder FFIs not wired — blocks docs/examples/ui/layout/snippets.ts on Linux CI #217 / GTK4: SplitView FFIs (splitview_create, splitview_add_child) not wired — co-blocks docs/examples/ui/layout/snippets.ts on Linux CI #218 (sibling GTK4 doc-tests blockers — the gtk4 gate stays red until all four land)

Estimated size

Tiny — banner-line edit. The harness either already supports // targets:-only banners (no platform list needed) or needs a small parser-side allowance for that shape.