feat(linux): first-class Linux backend + Perry 0.5.x string FFI fixes

Linux backend port:
- Port 25 missing render/post-FX/profiler/screenshot/impulse FFI from
  the macOS backend so libbloom_linux.a covers the surface bloom/core's
  TS layer calls into. Without these, perry compile fails to link any
  game on Linux with undefined-reference errors for bloom_take_screenshot,
  bloom_set_render_scale/upscale_mode/cas_strength/auto_resolution,
  bloom_set_dof/ssgi/fog/vignette/film_grain/sun_shafts/chromatic_aberration,
  bloom_set_taa_enabled/auto_exposure/manual_exposure/env_intensity,
  bloom_set_env_clear_from_hdr, bloom_get_physical_width/height,
  bloom_get_render_scale, bloom_splat_impulse, bloom_profiler_overlay_text,
  bloom_profiler_frame_history. EngineState already exposed the underlying
  renderer methods; the wrappers are platform-agnostic.
- Add native/linux/bundle-jolt.sh: merges cmake-built libbloom_jolt.a +
  libJolt.a into libbloom_linux_bundled.a so perry's single-staticlib
  link picks up the JPH:: symbols. Output to a separate filename so
  cargo's hardlink-based caching doesn't revert the merge on the next
  cargo build.
- package.json linux target: lib -> libbloom_linux_bundled.a,
  libs:["stdc++"]. Add `image` dep for HDR env loading.

Perry 0.5.x string-FFI fixes (affects all platforms):
- Add bloom_shared::string_header::alloc_perry_string with the new
  20-byte StringHeader layout (utf16_len, byte_len, capacity, refcount,
  flags). Old engine code wrote a 12-byte 0.4.x layout; perry's 0.5.x
  runtime reads 8 bytes into the payload, returning strings with a
  garbage prefix and trailing read-past-end.
- Replace all hand-rolled 12-byte allocations in linux + macos
  (bloom_read_file, bloom_get_clipboard_text, bloom_open_file_dialog,
  bloom_save_file_dialog, bloom_profiler_overlay_text,
  bloom_profiler_frame_history) with the helper.
- Return alloc_perry_string("") instead of std::ptr::null() on miss in
  bloom_read_file / clipboard / dialog paths. Perry NaN-boxes a null
  string-typed return as a string at address 0; subsequent .length /
  .charCodeAt segfault. Empty-string return makes `data.length === 0`
  the correct miss check (matches what the jump game's discoverLevels
  already assumes).
- package.json: declare bloom_read_file, bloom_get_clipboard_text,
  bloom_open_file_dialog, bloom_save_file_dialog as returns:"string"
  so perry codegen NaN-boxes the pointer as a string instead of
  sitofp'ing it to a number (which made `data.length` return 0 and
  `data.charCodeAt(i)` print decimal digits of the pointer value).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Ralph Kuepper

native/linux/Cargo.lock

@@ -13,6 +13,7 @@ jolt = ["bloom-shared/jolt"]
 
 [dependencies]
 bloom-shared = { path = "../shared", default-features = false, features = ["mp3"] }
+image = { version = "0.25", default-features = false, features = ["hdr"] }
 raw-window-handle = "0.6"
 wgpu = "29"
 libc = "0.2"

native/linux/Cargo.toml

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Merge libbloom_jolt.a + libJolt.a (built by bloom-shared/build.rs via cmake)
+# into libbloom_linux.a. Perry's link step only sees the single staticlib
+# named in package.json's perry.nativeLibrary.targets.linux.lib, so the
+# C++ Jolt symbols would otherwise be unresolved.
+set -euo pipefail
+
+cd "$(dirname "$0")"
+TARGET_DIR="target/release"
+SRC_LIB="$TARGET_DIR/libbloom_linux.a"
+# Output to a separate filename so cargo's hardlink caching doesn't revert
+# our merge on the next `cargo build` (cargo restores the cached copy of
+# libbloom_linux.a via hardlink). Perry's package.json points at this name.
+OUT_LIB="$TARGET_DIR/libbloom_linux_bundled.a"
+
+if [[ ! -f "$SRC_LIB" ]]; then
+  echo "bundle-jolt: $SRC_LIB not found — run 'cargo build --release' first" >&2
+  exit 1
+fi
+MAIN_LIB="$SRC_LIB"
+
+JOLT_SHIM=$(find "$TARGET_DIR/build" -name libbloom_jolt.a -path "*/out/lib/*" | head -1)
+JOLT_LIB=$(find "$TARGET_DIR/build"  -name libJolt.a       -path "*/out/lib/*" | head -1)
+
+if [[ -z "$JOLT_SHIM" || -z "$JOLT_LIB" ]]; then
+  echo "bundle-jolt: could not locate libbloom_jolt.a / libJolt.a under $TARGET_DIR/build" >&2
+  exit 1
+fi
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+# Extract each archive into its own subdir so identical object names
+# (e.g. bloom_jolt.cpp.o) from different archives don't overwrite each
+# other, then rename with a per-archive prefix before merging.
+extract() {
+  local archive="$1" prefix="$2"
+  local subdir="$WORK/$prefix"
+  mkdir -p "$subdir"
+  ( cd "$subdir" && ar x "$archive" )
+  for f in "$subdir"/*.o; do
+    mv "$f" "$WORK/${prefix}_$(basename "$f")"
+  done
+  rmdir "$subdir"
+}
+
+extract "$(realpath "$MAIN_LIB")"  bloom
+extract "$(realpath "$JOLT_SHIM")" jshim
+extract "$(realpath "$JOLT_LIB")"  jolt
+
+# Build the merged staticlib. Output to OUT_LIB so cargo doesn't clobber it
+# via its hardlink cache.
+rm -f "$OUT_LIB"
+ar crs "$OUT_LIB" "$WORK"/*.o
+
+echo "bundle-jolt: merged $(ls "$WORK"/*.o | wc -l) object files into $OUT_LIB"

native/linux/bundle-jolt.sh

@@ -1,6 +1,6 @@
 use bloom_shared::engine::EngineState;
 use bloom_shared::renderer::Renderer;
-use bloom_shared::string_header::str_from_header;
+use bloom_shared::string_header::{str_from_header, alloc_perry_string};
 use bloom_shared::audio::{parse_wav, parse_ogg, parse_mp3};
 
 use std::sync::OnceLock;
@@ -1401,13 +1401,13 @@ pub extern "C" fn bloom_set_cursor_shape(shape: f64) {
 #[no_mangle]
 pub extern "C" fn bloom_set_clipboard_text(_text_ptr: *const u8) {}
 #[no_mangle]
-pub extern "C" fn bloom_get_clipboard_text() -> *const u8 { std::ptr::null() }
+pub extern "C" fn bloom_get_clipboard_text() -> *const u8 { alloc_perry_string("") }
 
 // E5b: File dialogs (stub on this platform)
 #[no_mangle]
-pub extern "C" fn bloom_open_file_dialog(_filter_ptr: *const u8, _title_ptr: *const u8) -> *const u8 { std::ptr::null() }
+pub extern "C" fn bloom_open_file_dialog(_filter_ptr: *const u8, _title_ptr: *const u8) -> *const u8 { alloc_perry_string("") }
 #[no_mangle]
-pub extern "C" fn bloom_save_file_dialog(_default_name_ptr: *const u8, _title_ptr: *const u8) -> *const u8 { std::ptr::null() }
+pub extern "C" fn bloom_save_file_dialog(_default_name_ptr: *const u8, _title_ptr: *const u8) -> *const u8 { alloc_perry_string("") }
 
 // Model bounds accessors. Return the axis-aligned bounding box of a loaded
 // model in model-local coordinates. Editors use these to size gizmos, auto-
@@ -1456,24 +1456,14 @@ pub extern "C" fn bloom_file_exists(path_ptr: *const u8) -> f64 {
 #[no_mangle]
 pub extern "C" fn bloom_read_file(path_ptr: *const u8) -> *const u8 {
     let path = str_from_header(path_ptr);
+    // Always return a valid Perry string. A null pointer would NaN-box into a
+    // string-typed JS value pointing at address 0; subsequent `.length` /
+    // `.charCodeAt` reads dereference the bogus StringHeader and segfault.
+    // Callers detect "missing file" via `data.length === 0` (e.g. the
+    // jump game's discoverLevels probe across level1..level10 / custom_*).
     match std::fs::read_to_string(path) {
-        Ok(contents) => {
-            // Return Perry-format string: StringHeader (length u32 + capacity u32 + refcount u32) followed by UTF-8 data
-            let bytes = contents.as_bytes();
-            let len = bytes.len();
-            let total = 12 + len; // 12 bytes header (3 × u32) + data
-            let layout = std::alloc::Layout::from_size_align(total, 4).unwrap();
-            unsafe {
-                let ptr = std::alloc::alloc(layout);
-                if ptr.is_null() { return std::ptr::null(); }
-                *(ptr as *mut u32) = len as u32;           // length
-                *(ptr.add(4) as *mut u32) = len as u32;    // capacity
-                *(ptr.add(8) as *mut u32) = 1;             // refcount (unique)
-                std::ptr::copy_nonoverlapping(bytes.as_ptr(), ptr.add(12), len);
-                ptr
-            }
-        }
-        Err(_) => std::ptr::null(),
+        Ok(contents) => alloc_perry_string(&contents),
+        Err(_)       => alloc_perry_string(""),
     }
 }
 
@@ -2200,6 +2190,197 @@ pub extern "C" fn bloom_set_sss_enabled(on: f64) {
     engine().renderer.set_sss_enabled(on != 0.0);
 }
 
+// ============================================================
+// Render scale / upscale / DRS / post-FX / screenshots / impulse
+// Ports of the macOS FFI surface so the bloom/core TS layer links
+// cleanly on Linux. EngineState in bloom-shared already exposes the
+// underlying renderer methods, so these wrappers are platform-agnostic.
+// ============================================================
+
+#[no_mangle]
+pub extern "C" fn bloom_take_screenshot(path_ptr: *const u8) {
+    let path = str_from_header(path_ptr).to_string();
+    let eng = engine();
+    eng.renderer.screenshot_requested = true;
+    eng.renderer.pending_screenshot_path = Some(path);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_env_clear_from_hdr(path_ptr: *const u8) {
+    use image::ImageDecoder;
+    let path = str_from_header(path_ptr).to_string();
+    let file = match std::fs::File::open(&path) {
+        Ok(f) => f,
+        Err(_) => return,
+    };
+    let decoder = match image::codecs::hdr::HdrDecoder::new(std::io::BufReader::new(file)) {
+        Ok(d) => d,
+        Err(_) => return,
+    };
+    let (w, h) = decoder.dimensions();
+    let byte_len = (w as usize) * (h as usize) * 3 * 4;
+    let mut buf = vec![0u8; byte_len];
+    if decoder.read_image(&mut buf).is_err() {
+        return;
+    }
+    let rgb_f32: Vec<f32> = buf
+        .chunks_exact(4)
+        .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
+        .collect();
+    engine().renderer.load_env_from_hdr(w, h, &rgb_f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_fog(r: f64, g: f64, b: f64, density: f64, height_ref: f64, height_falloff: f64) {
+    let r_ = engine();
+    r_.renderer.set_fog_color(r as f32, g as f32, b as f32);
+    r_.renderer.set_fog_density(density as f32);
+    r_.renderer.set_fog_height_falloff(height_ref as f32, height_falloff as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_chromatic_aberration(strength: f64) {
+    engine().renderer.set_chromatic_aberration(strength as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_vignette(strength: f64, softness: f64) {
+    engine().renderer.set_vignette(strength as f32, softness as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_film_grain(strength: f64) {
+    engine().renderer.set_film_grain(strength as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_sun_shafts(strength: f64, decay: f64, r: f64, g: f64, b: f64) {
+    let eng = engine();
+    eng.renderer.set_sun_shaft_strength(strength as f32);
+    eng.renderer.set_sun_shaft_decay(decay as f32);
+    eng.renderer.set_sun_shaft_color(r as f32, g as f32, b as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_auto_exposure(on: f64) {
+    engine().renderer.set_auto_exposure(on != 0.0);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_taa_enabled(on: f64) {
+    engine().renderer.set_taa_enabled(on != 0.0);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_render_scale(scale: f64) {
+    engine().renderer.set_render_scale(scale as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_get_render_scale() -> f64 {
+    engine().renderer.render_scale() as f64
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_upscale_mode(mode: f64) {
+    engine().renderer.set_upscale_mode(mode as u32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_cas_strength(strength: f64) {
+    engine().renderer.set_cas_strength(strength as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_get_physical_width() -> f64 {
+    engine().renderer.physical_width() as f64
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_get_physical_height() -> f64 {
+    engine().renderer.physical_height() as f64
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_auto_resolution(target_hz: f64, enabled: f64) {
+    let eng = engine();
+    if enabled != 0.0 {
+        let current = eng.renderer.render_scale();
+        eng.drs.enable(target_hz as f32, current);
+    } else {
+        eng.drs.disable();
+    }
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_manual_exposure(value: f64) {
+    engine().renderer.set_manual_exposure(value as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_env_intensity(intensity: f64) {
+    engine().renderer.set_env_intensity(intensity as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_ssgi_enabled(enabled: f64) {
+    engine().renderer.set_ssgi_enabled(enabled != 0.0);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_ssgi_intensity(intensity: f64) {
+    engine().renderer.set_ssgi_intensity(intensity as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_ssgi_radius(radius: f64) {
+    engine().renderer.set_ssgi_radius(radius as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_set_dof(enabled: f64, focus_distance: f64, aperture: f64) {
+    let r = &mut engine().renderer;
+    r.set_dof_enabled(enabled != 0.0);
+    r.set_dof_focus_distance(focus_distance as f32);
+    r.set_dof_aperture(aperture as f32);
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_splat_impulse(x: f64, z: f64, radius: f64, strength: f64) {
+    engine().renderer.impulse_field.submit_splat(
+        x as f32, z as f32, radius as f32, strength as f32,
+    );
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_profiler_frame_history() -> *const u8 {
+    let hist = engine().profiler.frame_history();
+    let mut s = String::with_capacity(hist.len() * 24);
+    for (cpu, gpu) in &hist {
+        s.push_str(&format!("{:.2}|{:.2}\n", cpu, gpu));
+    }
+    alloc_perry_string(&s)
+}
+
+#[no_mangle]
+pub extern "C" fn bloom_profiler_overlay_text() -> *const u8 {
+    let snap = engine().profiler.snapshot();
+    let mut s = String::with_capacity(snap.len() * 48);
+    for (label, cpu, gpu) in &snap {
+        s.push_str(label);
+        s.push('|');
+        s.push_str(&format!("{:.2}", cpu));
+        s.push('|');
+        match gpu {
+            Some(g) => s.push_str(&format!("{:.2}", g)),
+            None    => s.push_str("-1"),
+        }
+        s.push('\n');
+    }
+    alloc_perry_string(&s)
+}
+
+
 // ============================================================
 // Profiler — CPU phase timings (always available) + GPU timestamps
 // (when the adapter supports TIMESTAMP_QUERY). Disabled by default.