fix(ui): root persistent JavaScript callbacks; complete the C-ABI FFI layer (#8721)

Lands #8713, #8704 and #8717.

#8713 (closes #8701) fixes the systemic gap I filed while auditing #8699:
every perry-ui-* crate cached JS callbacks as raw NaN-boxed f64 in
thread-local side tables, and NO UI crate registered a root scanner. A
stored callback is a heap pointer held across collections -- unmarked, so
a live listener could be reclaimed, and unrewritten, so it could dangle
after an evacuating minor and surface cycles later as "value is not a
function".

It registers one mutable root scanner per UI crate and for the shared
dispatcher, and graduates all 474 census candidates: the frontier drops
628 -> 158 while audited holders rise 71 -> 280. The specific holder I
named in #8701, perry-ui-ios adaptive_layout LISTENERS, is now
scanner-covered; its sibling LAST_SNAPSHOT is correctly classified
not_a_gc_pointer (native viewport dimensions, no JS value).

The census got STRONGER, not weaker -- checked, because graduating 468
holders by relaxing the checker would look identical on the surface. Its
self-test goes from 89 planted declarations / 0 inventory entries checked
to 90 / 280. main's self-test validated none of the ledger; this one
validates all of it.

#8704 completes the bun:ffi / node:ffi C ABI. The raw-handle debt that
held it is resolved: bare reads are 913 against a baseline of 913, with
the baseline LOWERED from 918 -- a ratchet tightening, not a waiver.

#8717 renders Windows PdfView pages natively through Windows.Data.Pdf.

Two mechanical fixes on top: a not_a_gc_pointer verdict for #8717's
COMPLETED render table (keyed by a monotonic request id, holding only
owned PNG bytes or an error String), a changelog fragment for #8717, and
deletion of three ledger entries that go stale once #8704's scanner
widens call-graph coverage.

No version bump.

Co-authored-by: Ralph Küpper <ralph@skelpo.com>

Author: proggeramlug

Cargo.lock

@@ -0,0 +1,11 @@
+---
+category: Runtime
+title: Complete Bun and Node C-ABI FFI support
+---
+
+Perry now supports typed scalar C-ABI calls through `bun:ffi`, including stack
+arguments, pinned pointers, zero-copy native memory views, scalar reads, and
+rooted same-thread or threadsafe callbacks. A Node 26-compatible `node:ffi`
+adapter lets OpenTUI/Yoga and other native wrappers load their upstream shared
+libraries without source changes, and the real `bun-pty` shell roundtrip is
+covered end to end.

changelog.d/8704-complete-c-abi-ffi.md

@@ -0,0 +1,5 @@
+### Fixed
+
+Root persistent `perry/ui` JavaScript callbacks and state values across garbage
+collections on every native UI backend, including callbacks retained by native
+timer, hotkey, and focus-event closures.

changelog.d/8713-ui-callback-gc-roots.md

@@ -0,0 +1 @@
+Replaced the Windows `PdfView` STATIC-label placeholder and its text-scanned page count with a real `Windows.Data.Pdf` render path: the active page is rendered to PNG and painted in the Win32 control with GDI+, preserving aspect ratio and zoom. Navigation and zoom updates render on MTA workers with stale completions discarded, and widget state is released on destruction. Adds page-size and real WinRT decode/render coverage, plus Windows backend documentation.

changelog.d/8717-windows-pdfview-native-render.md

@@ -58,6 +58,7 @@ pub const NATIVE_MODULES: &[&str] = &[
     // #6562: Bun FFI (C-ABI). The `bun:` prefix is part of the specifier
     // (unlike `node:`, which is stripped) — `import { dlopen } from "bun:ffi"`.
     "bun:ffi",
+    "ffi",        // node:ffi (the node: prefix is normalized away)
     "bun:sqlite", // Bun facade over Perry's native SQLite engine
     "node-cron",  // cron-style scheduler (npm node-cron; aliases `cron`)
     "nodemailer", // SMTP email sending
@@ -243,6 +244,7 @@ pub const RUNTIME_ONLY_MODULES: &[&str] = &[
     "buffer",
     // #6562: bun:ffi is implemented entirely in perry-runtime.
     "bun:ffi",
+    "ffi",
     "assert",
     "assert/strict",
     "test",

crates/perry-api-manifest/src/entries.rs

@@ -206,9 +206,8 @@ pub(crate) const API_MANIFEST_PART_1: &[ApiEntry] = &[
     // bun:ffi (#6562). `FFIType` and `suffix` are
     // constants; symbol-table call stubs live on the object `dlopen`
     // returns, so the module surface itself is small. The later-stage
-    // exports (linkSymbols / CFunction / viewSource / read) are
-    // declared and throw a descriptive
-    // ERR_NOT_IMPLEMENTED at runtime.
+    // exports (linkSymbols / CFunction / viewSource / read) share the same
+    // scalar ABI and pinned-memory implementation.
     method("bun:ffi", "dlopen", false, None),
     method("bun:ffi", "ptr", false, None),
     method("bun:ffi", "CString", false, None),
@@ -217,18 +216,18 @@ pub(crate) const API_MANIFEST_PART_1: &[ApiEntry] = &[
     method("bun:ffi", "toArrayBuffer", false, None),
     method("bun:ffi", "toBuffer", false, None),
     method("bun:ffi", "JSCallback", false, None),
-    // Remaining surface: declared so feature-probes get a clear error rather
-    // than `undefined is not a function`, but NOT implemented yet — each
-    // throws at runtime. Marked `.stub_note` so the generated `.d.ts` /
-    // `reference.md` say so instead of reading as usable APIs (#6562).
-    method("bun:ffi", "CFunction", false, None)
-        .stub_note("stage 3 — not yet implemented, throws at runtime (#6562)"),
-    method("bun:ffi", "linkSymbols", false, None)
-        .stub_note("stage ≥2 — not yet implemented, throws at runtime (#6562)"),
-    method("bun:ffi", "viewSource", false, None)
-        .stub_note("stage ≥2 — not yet implemented, throws at runtime (#6562)"),
-    method("bun:ffi", "read", false, None)
-        .stub_note("stage ≥2 — not yet implemented, throws at runtime (#6562)"),
+    method("bun:ffi", "CFunction", false, None),
+    method("bun:ffi", "linkSymbols", false, None),
+    method("bun:ffi", "viewSource", false, None),
+    property("bun:ffi", "read"),
+    // node:ffi compatibility surface (Node 26), consumed by OpenTUI's Node
+    // adapter. Callback registration lives on the library returned by dlopen.
+    method("ffi", "dlopen", false, None),
+    method("ffi", "getRawPointer", false, None),
+    method("ffi", "toArrayBuffer", false, None),
+    method("ffi", "toBuffer", false, None),
+    method("ffi", "toString", false, None),
+    property("ffi", "suffix"),
     // bun:sqlite (#8510) shares node:sqlite's rusqlite handles while keeping
     // Bun's public constructor and statement vocabulary.
     class("bun:sqlite", "Database"),

crates/perry-api-manifest/src/entries/part_1.rs

@@ -93,10 +93,6 @@ fn stub_inventory_matches_known_clusters() {
         // event-loop refcount), mongodb.findOne (parsed document),
         // exponential-backoff options (honored, incl. retry predicate).
         ("#4917", 9),
-        // #6562 (bun:ffi) — the remaining FFI surface is declared so
-        // feature probes get a clear error, but throws at runtime until the
-        // later stages land: CFunction, linkSymbols, viewSource, read.
-        ("#6562", 4),
     ];
     let expected_map: BTreeMap<String, usize> =
         expected.iter().map(|(k, v)| (k.to_string(), *v)).collect();
@@ -123,8 +119,6 @@ fn stubs_only_appear_in_allowlisted_modules() {
         "exponential-backoff",
         "inspector",
         "repl",
-        // #6562: bun:ffi later-stage exports are declared-but-throwing stubs.
-        "bun:ffi",
     ];
     for e in iter_entries().filter(|e| e.stub) {
         assert!(

crates/perry-api-manifest/tests/stub_inventory.rs

@@ -20,7 +20,7 @@
 use libc::{c_char, c_float, c_int, c_uint, c_void};
 use std::cell::RefCell;
 use std::ffi::CString;
-use std::sync::Mutex;
+use std::sync::{Mutex, Once};
 
 use perry_ffi::copy_string_from_raw as str_from_header;
 
@@ -227,6 +227,8 @@ struct Fade {
     then_stop: bool,
 }
 
+static GC_SCANNER_REGISTERED: Once = Once::new();
+
 thread_local! {
     static ENGINE: RefCell<Option<MaBox<MA_ENGINE_SIZE>>> = RefCell::new(None);
     static SOUNDS: RefCell<Vec<Option<SoundEntry>>> = RefCell::new(Vec::new());
@@ -238,6 +240,32 @@ thread_local! {
     static PENDING_LOADED: RefCell<Vec<usize>> = RefCell::new(Vec::new());
 }
 
+fn ensure_gc_scanner_registered() {
+    GC_SCANNER_REGISTERED.call_once(|| {
+        perry_ffi::gc_register_mutable_root_scanner_named(
+            "perry-audio-miniaudio",
+            scan_miniaudio_gc_roots,
+        );
+    });
+}
+
+fn scan_miniaudio_gc_roots(visitor: &mut perry_ffi::GcRootVisitor<'_>) {
+    SOUNDS.with(|sounds| {
+        for sound in sounds.borrow_mut().iter_mut().flatten() {
+            if let Some(callback) = sound.on_loaded.as_mut() {
+                visitor.visit_nanbox_f64_slot(callback);
+            }
+        }
+    });
+    VOICES.with(|voices| {
+        for voice in voices.borrow_mut().iter_mut().flatten() {
+            if let Some(callback) = voice.on_ended.as_mut() {
+                visitor.visit_nanbox_f64_slot(callback);
+            }
+        }
+    });
+}
+
 /// Voice indices whose miniaudio end_callback fired on the audio thread.
 /// We can't touch thread-locals from there; main-thread `drain_*` pulls
 /// these into PENDING_ENDED on every hot-path entry point.
@@ -460,6 +488,7 @@ pub extern "C" fn perry_audio_unload(sound: f64) {
 
 #[no_mangle]
 pub extern "C" fn perry_audio_on_loaded(sound: f64, callback: f64) {
+    ensure_gc_scanner_registered();
     let idx = match classify(sound) {
         HandleKind::Sound(i) => i,
         _ => return,
@@ -1174,6 +1203,7 @@ pub extern "C" fn perry_audio_get_position(playback: f64) -> f64 {
 
 #[no_mangle]
 pub extern "C" fn perry_audio_on_ended(playback: f64, callback: f64) {
+    ensure_gc_scanner_registered();
     let idx = match classify(playback) {
         HandleKind::Playback(i) => i,
         _ => return,

crates/perry-audio-miniaudio/src/lib.rs

@@ -1166,6 +1166,9 @@ pub(super) fn compile_module_entry(
                     "0".to_string()
                 };
                 let has_stdlib = ctx.block().call(I32, "js_stdlib_has_active_handles", &[]);
+                let has_ffi_callbacks =
+                    ctx.block()
+                        .call(I32, "js_bun_ffi_has_active_threadsafe_callbacks", &[]);
                 // #591: TASK_QUEUE may carry a pending `.then` continuation
                 // that was queued by `js_run_stdlib_pump`'s resolution path
                 // in the SAME body iteration that already drained the inflight
@@ -1175,6 +1178,7 @@ pub(super) fn compile_module_entry(
                 let has_microtasks = ctx.block().call(I32, "js_microtasks_pending", &[]);
                 let any1 = ctx.block().or(I32, &has_timers, &has_callbacks);
                 let any2 = ctx.block().or(I32, &has_intervals, &has_stdlib);
+                let any2 = ctx.block().or(I32, &any2, &has_ffi_callbacks);
                 let any3 = ctx.block().or(I32, &any1, &any2);
                 let any4 = ctx.block().or(I32, &any3, &has_cron);
                 let any = ctx.block().or(I32, &any4, &has_microtasks);

crates/perry-codegen/src/codegen/entry.rs

@@ -222,9 +222,13 @@ pub(crate) fn lower(ctx: &mut FnCtx<'_>, expr: &Expr) -> Result<String> {
                     let has_callbacks = ctx.block().call(I32, "js_callback_timer_has_pending", &[]);
                     let has_intervals = ctx.block().call(I32, "js_interval_timer_has_pending", &[]);
                     let has_stdlib = ctx.block().call(I32, "js_stdlib_has_active_handles", &[]);
+                    let has_ffi_callbacks =
+                        ctx.block()
+                            .call(I32, "js_bun_ffi_has_active_threadsafe_callbacks", &[]);
                     let has_microtasks = ctx.block().call(I32, "js_microtasks_pending", &[]);
                     let any1 = ctx.block().or(I32, &has_timers, &has_callbacks);
                     let any2 = ctx.block().or(I32, &has_intervals, &has_stdlib);
+                    let any2 = ctx.block().or(I32, &any2, &has_ffi_callbacks);
                     let any3 = ctx.block().or(I32, &any1, &any2);
                     let any = ctx.block().or(I32, &any3, &has_microtasks);
                     let no_refed_work = ctx.block().icmp_eq(I32, &any, "0");