@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/libraries/blitz-ui/native-osr/src/lib.rs

@@ -11,17 +11,18 @@
 //! buffer) or `dd_osr_frame_into` (copy into a host-bound SharedArrayBuffer —
 //! the zero-copy path used by the html-ui worker channel).
 
+use std::collections::HashSet;
 use std::os::raw::c_int;
 use std::panic::{catch_unwind, AssertUnwindSafe};
 use std::str::FromStr;
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::sync::Arc;
+use std::sync::{Arc, Mutex, OnceLock};
 use std::time::Instant;
 
 use anyrender::ImageRenderer;
 use anyrender_vello_cpu::VelloCpuImageRenderer;
 use atomic_refcell::AtomicRefCell;
-use blitz_dom::{Document, DocumentConfig, EventDriver, FontContext};
+use blitz_dom::{BaseDocument, Document, DocumentConfig, EventDriver, FontContext};
 use blitz_html::HtmlDocument;
 use blitz_paint::paint_scene;
 use blitz_traits::events::{
@@ -92,6 +93,35 @@ impl ShellProvider for FlagShell {
     fn request_redraw(&self) {
         self.flag.store(true, Ordering::Relaxed);
     }
+
+    #[cfg(not(target_os = "android"))]
+    fn get_clipboard_text(&self) -> Result<String, blitz_traits::shell::ClipboardError> {
+        clipboard()
+            .and_then(|mut cb| cb.get_text().ok())
+            .ok_or(blitz_traits::shell::ClipboardError)
+    }
+
+    #[cfg(not(target_os = "android"))]
+    fn set_clipboard_text(&self, text: String) -> Result<(), blitz_traits::shell::ClipboardError> {
+        clipboard()
+            .and_then(|mut cb| cb.set_text(text).ok())
+            .ok_or(blitz_traits::shell::ClipboardError)
+    }
+}
+
+/// Long-lived process clipboard. On X11 the clipboard owner must keep serving
+/// selection requests while it owns the selection, so a fresh `Clipboard` per
+/// call is wrong: its `Drop` hands contents to the clipboard manager and
+/// destroys the server window, which races requesters and can leave stale or
+/// empty contents. Klipper already snapshots content on ownership changes, so
+/// keeping the context alive for the process is the normal-app pattern.
+#[cfg(not(target_os = "android"))]
+fn clipboard() -> Option<std::sync::MutexGuard<'static, arboard::Clipboard>> {
+    static CB: std::sync::OnceLock<Option<std::sync::Mutex<arboard::Clipboard>>> =
+        std::sync::OnceLock::new();
+    CB.get_or_init(|| arboard::Clipboard::new().ok().map(std::sync::Mutex::new))
+        .as_ref()
+        .and_then(|m| m.lock().ok())
 }
 
 fn build_doc(
@@ -167,6 +197,67 @@ pub struct OsrDoc {
     pub(crate) rect_buf: [f64; 4],
     /// Owned node-id list written by dd_osr_query_all.
     pub(crate) query_buf: Vec<u64>,
+    /// Serialization flag — set for the duration of each FFI call. The ABI
+    /// exposes a raw `*mut OsrDoc`, so nothing prevents a host from calling
+    /// the same doc from two threads at once (which would alias `&mut` and
+    /// corrupt the DOM instantly). Callers that arrive while busy get -1.
+    busy: AtomicBool,
+}
+
+// ── Handle registry + per-doc call serialization ──
+//
+// Every handle handed out by dd_osr_init is registered here and removed by
+// dd_osr_destroy *before* the Box is freed, so FFI entry points can tell a
+// live handle from a stale/garbage pointer without dereferencing it. The
+// `busy` flag is then swapped under the registry lock so the
+// contains-check → claim sequence is atomic against destroy: after a doc
+// leaves the registry no thread can newly enter it, and destroy only frees
+// the Box once it owns `busy` (no in-flight call).
+static DOCS: OnceLock<Mutex<HashSet<usize>>> = OnceLock::new();
+
+fn docs() -> Option<&'static Mutex<HashSet<usize>>> {
+    // Mutex poisoning turns into a permanent OSR outage if a call ever panics
+    // while holding it — treat a poisoned/lock failure as "unknown handle".
+    DOCS.get_or_init(|| Mutex::new(HashSet::new())).into()
+}
+
+/// RAII claim on a live doc — releases `busy` on drop (including unwind).
+pub(crate) struct DocGuard {
+    doc: *mut OsrDoc,
+}
+
+impl DocGuard {
+    /// Safety: registry membership keeps the Box alive (destroy removes the
+    /// handle before freeing) and `busy` guarantees exclusive access.
+    pub(crate) fn get(&mut self) -> &mut OsrDoc {
+        unsafe { &mut *self.doc }
+    }
+}
+
+impl Drop for DocGuard {
+    fn drop(&mut self) {
+        unsafe { (*self.doc).busy.store(false, Ordering::Release) };
+    }
+}
+
+/// Validate `handle` against the live-doc registry and claim exclusive
+/// access to it. Returns None for null/stale handles or a doc already
+/// inside an FFI call.
+pub(crate) fn doc_enter(handle: *mut OsrDoc) -> Option<DocGuard> {
+    if handle.is_null() {
+        return None;
+    }
+    let key = handle as usize;
+    let reg = docs()?.lock().ok()?;
+    if !reg.contains(&key) {
+        return None;
+    }
+    // SAFETY: still under the registry lock — the doc cannot be freed here.
+    let d = unsafe { &*handle };
+    if d.busy.swap(true, Ordering::Acquire) {
+        return None;
+    }
+    Some(DocGuard { doc: handle })
 }
 
 /// O(1) "did anything change" check: Blitz propagates a damaged_descendants
@@ -269,6 +360,13 @@ pub extern "C" fn dd_osr_init(
     html_len: usize,
 ) -> *mut OsrDoc {
     ffi(std::ptr::null_mut(), || {
+        static LOG_INIT: std::sync::Once = std::sync::Once::new();
+        LOG_INIT.call_once(|| {
+            let _ = env_logger::Builder::from_env(
+                env_logger::Env::default().default_filter_or("off"),
+            )
+            .try_init();
+        });
         let Some(html) = (unsafe { read_str(html_ptr, html_len) }) else {
             return std::ptr::null_mut();
         };
@@ -294,8 +392,20 @@ pub extern "C" fn dd_osr_init(
             out_buf: Vec::new(),
             rect_buf: [0.0; 4],
             query_buf: Vec::new(),
+            busy: AtomicBool::new(false),
         };
-        Box::into_raw(Box::new(doc))
+        let handle = Box::into_raw(Box::new(doc));
+        match docs().and_then(|m| m.lock().ok()) {
+            Some(mut reg) => {
+                reg.insert(handle as usize);
+                handle
+            }
+            // Registry unavailable — don't hand out an untracked handle.
+            None => {
+                drop(unsafe { Box::from_raw(handle) });
+                std::ptr::null_mut()
+            }
+        }
     })
 }
 
@@ -305,9 +415,10 @@ pub extern "C" fn dd_osr_init(
 #[no_mangle]
 pub extern "C" fn dd_osr_set_html(handle: *mut OsrDoc, html_ptr: *const u8, html_len: usize) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let Some(html) = (unsafe { read_str(html_ptr, html_len) }) else {
             return -2;
         };
@@ -323,6 +434,39 @@ pub extern "C" fn dd_osr_set_html(handle: *mut OsrDoc, html_ptr: *const u8, html
     })
 }
 
+/// taffy's `round_layout` snaps each border side to whole layout units via
+/// `round(c + w) - round(c)`, so a sub-unit border side (a 1px border at
+/// zoom 1.25 computes as 0.8px) can round to 0 depending on the node's
+/// cumulative position. A zero side makes blitz-paint's corner-split math
+/// divide by zero and emit NaN border paths — the adjacent edges (e.g. the
+/// left border) then paint nothing. Restore any side taffy collapsed that
+/// layout says is nonzero.
+fn restore_collapsed_borders(doc: &mut BaseDocument) {
+    let root = doc.root_element().id;
+    doc.iter_subtree_mut(root, |id, doc| {
+        let Some(node) = doc.get_node_mut(id) else {
+            return;
+        };
+        let Some(ld) = node.try_layout_data_mut() else {
+            return;
+        };
+        let ub = ld.unrounded_layout.border;
+        let fb = &mut ld.final_layout.border;
+        if fb.left == 0.0 && ub.left > 0.0 {
+            fb.left = ub.left;
+        }
+        if fb.right == 0.0 && ub.right > 0.0 {
+            fb.right = ub.right;
+        }
+        if fb.top == 0.0 && ub.top > 0.0 {
+            fb.top = ub.top;
+        }
+        if fb.bottom == 0.0 && ub.bottom > 0.0 {
+            fb.bottom = ub.bottom;
+        }
+    });
+}
+
 /// Resolve + rasterize + diff when dirty. Returns Some(rect) when the pixel
 /// buffer changed (rect = pixel-space dirty region), None when clean or
 /// identical. Writes per-call timings into d.stats.
@@ -334,6 +478,7 @@ fn raster_if_dirty(d: &mut OsrDoc) -> Option<[u32; 4]> {
     let t0 = Instant::now();
     let mut inner = d.doc.inner_mut();
     inner.resolve(0.0);
+    restore_collapsed_borders(&mut inner);
     let (w, h) = inner.viewport().window_size;
     let scale = inner.viewport().scale_f64();
     if inner.has_pending_critical_resources() {
@@ -389,9 +534,10 @@ fn raster_if_dirty(d: &mut OsrDoc) -> Option<[u32; 4]> {
 #[no_mangle]
 pub extern "C" fn dd_osr_frame(handle: *mut OsrDoc) -> *const u8 {
     ffi(std::ptr::null(), || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return std::ptr::null();
         };
+        let d = g.get();
         if raster_if_dirty(d).is_none() {
             return std::ptr::null();
         }
@@ -409,9 +555,10 @@ fn needed_buf_len(d: &OsrDoc) -> usize {
 #[no_mangle]
 pub extern "C" fn dd_osr_buf_needed(handle: *mut OsrDoc) -> usize {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         needed_buf_len(d)
     })
 }
@@ -422,9 +569,10 @@ pub extern "C" fn dd_osr_buf_needed(handle: *mut OsrDoc) -> usize {
 #[no_mangle]
 pub extern "C" fn dd_osr_bind_frame_buf(handle: *mut OsrDoc, ptr: *mut u8, len: usize) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         if ptr.is_null() || len < needed_buf_len(d) {
             return -2;
         }
@@ -475,9 +623,10 @@ fn write_bound_frame(d: &mut OsrDoc, rect: [u32; 4]) -> c_int {
 #[no_mangle]
 pub extern "C" fn dd_osr_frame_into(handle: *mut OsrDoc) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let Some(buf) = d.frame_buf.as_ref() else {
             return -3;
         };
@@ -499,9 +648,10 @@ pub extern "C" fn dd_osr_frame_into(handle: *mut OsrDoc) -> c_int {
 #[no_mangle]
 pub extern "C" fn dd_osr_refresh_into(handle: *mut OsrDoc) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let Some(buf) = d.frame_buf.as_ref() else {
             return -3;
         };
@@ -523,9 +673,10 @@ pub extern "C" fn dd_osr_refresh_into(handle: *mut OsrDoc) -> c_int {
 #[no_mangle]
 pub extern "C" fn dd_osr_last_stats(handle: *mut OsrDoc) -> *const f64 {
     ffi(std::ptr::null(), || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return std::ptr::null();
         };
+        let d = g.get();
         d.stats.as_ptr()
     })
 }
@@ -535,9 +686,10 @@ pub extern "C" fn dd_osr_last_stats(handle: *mut OsrDoc) -> *const f64 {
 #[no_mangle]
 pub extern "C" fn dd_osr_pixels_len(handle: *mut OsrDoc) -> usize {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         d.pixels.len()
     })
 }
@@ -546,9 +698,10 @@ pub extern "C" fn dd_osr_pixels_len(handle: *mut OsrDoc) -> usize {
 #[no_mangle]
 pub extern "C" fn dd_osr_resize(handle: *mut OsrDoc, width: f64, height: f64, scale: f64) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let w = width.max(1.0) as u32;
         let h = height.max(1.0) as u32;
         {
@@ -618,9 +771,10 @@ pub extern "C" fn dd_osr_pointer(
     mods: u32,
 ) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         d.pointer_pos = (x, y);
         let mut event = make_pointer_event(d, x, y, dom_button(button));
         event.mods = kbt_modifiers(mods);
@@ -631,7 +785,10 @@ pub extern "C" fn dd_osr_pointer(
                 UiEvent::PointerDown(event)
             }
             2 => {
-                d.buttons ^= event.button.into();
+                // Release clears the bit — XOR would toggle it back on for a
+                // button-up that never had a matching down (double-up races,
+                // focus-loss sequences), leaving a phantom pressed state.
+                d.buttons &= !MouseEventButtons::from(event.button);
                 event.buttons = d.buttons;
                 UiEvent::PointerUp(event)
             }
@@ -643,7 +800,9 @@ pub extern "C" fn dd_osr_pointer(
     })
 }
 
-/// Wheel event at the last pointer position. Deltas are in pixels.
+/// Wheel event at the last pointer position. Deltas are in pixels using
+/// Blitz/winit semantics (+y = scroll up); the JS wrapper negates DOM
+/// WheelEvent deltas before crossing the FFI.
 #[no_mangle]
 pub extern "C" fn dd_osr_wheel(
     handle: *mut OsrDoc,
@@ -654,9 +813,10 @@ pub extern "C" fn dd_osr_wheel(
     mods: u32,
 ) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let event = BlitzWheelEvent {
             delta: BlitzWheelDelta::Pixels(delta_x, delta_y),
             coords: pointer_coords(d, x, y),
@@ -686,9 +846,10 @@ pub extern "C" fn dd_osr_key(
     mods: u32,
 ) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let key_s = unsafe { read_str(key_ptr, key_len) }.unwrap_or("Unidentified");
         let code_s = unsafe { read_str(code_ptr, code_len) }.unwrap_or("");
         let key = Key::from_str(key_s).unwrap_or(Key::Unidentified);
@@ -724,9 +885,10 @@ pub extern "C" fn dd_osr_key(
 #[no_mangle]
 pub extern "C" fn dd_osr_hit_test(handle: *mut OsrDoc, x: f64, y: f64) -> c_int {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         let doc = d.doc.inner();
         let scale = doc.viewport().scale_f64();
         let lx = (x / scale) as f32;
@@ -747,9 +909,10 @@ pub extern "C" fn dd_osr_hit_test(handle: *mut OsrDoc, x: f64, y: f64) -> c_int
 #[no_mangle]
 pub extern "C" fn dd_osr_frame_rect(handle: *mut OsrDoc) -> u64 {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         let [x, y, w, h] = d.dirty_rect;
         ((x as u64) << 48) | ((y as u64) << 32) | ((w as u64) << 16) | h as u64
     })
@@ -761,9 +924,10 @@ pub extern "C" fn dd_osr_frame_rect(handle: *mut OsrDoc) -> u64 {
 #[no_mangle]
 pub extern "C" fn dd_osr_pending(handle: *mut OsrDoc) -> c_int {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         fold_redraw(d);
         if d.dirty || d.doc.inner().is_animating() {
             1
@@ -778,9 +942,10 @@ pub extern "C" fn dd_osr_pending(handle: *mut OsrDoc) -> c_int {
 #[no_mangle]
 pub extern "C" fn dd_osr_poll_events(handle: *mut OsrDoc) -> *const u8 {
     ffi(std::ptr::null(), || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return std::ptr::null();
         };
+        let d = g.get();
         let mut q = d.events.borrow_mut();
         if q.is_empty() {
             return std::ptr::null();
@@ -804,9 +969,10 @@ pub extern "C" fn dd_osr_poll_events(handle: *mut OsrDoc) -> *const u8 {
 #[no_mangle]
 pub extern "C" fn dd_osr_events_len(handle: *mut OsrDoc) -> usize {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         d.events_buf.len()
     })
 }
@@ -840,6 +1006,31 @@ pub extern "C" fn dd_osr_destroy(handle: *mut OsrDoc) -> c_int {
         if handle.is_null() {
             return -1;
         }
+        let key = handle as usize;
+        let Some(reg_mutex) = docs() else { return -1 };
+        let mut reg = match reg_mutex.lock() {
+            Ok(r) => r,
+            Err(_) => return -1,
+        };
+        if !reg.contains(&key) {
+            return -1; // stale or double destroy — never touch the memory
+        }
+        // Claim the doc while still holding the registry lock: a thread that
+        // passed doc_enter earlier is either holding busy (we spin for it —
+        // FFI calls are µs-scale) or can no longer get in.
+        let d = unsafe { &*handle };
+        let mut spins = 0u32;
+        while d.busy.swap(true, Ordering::Acquire) {
+            spins += 1;
+            if spins > 100_000 {
+                // A caller is stuck inside the doc — refuse to free live
+                // memory. -2 = "busy"; the host may retry.
+                return -2;
+            }
+            std::hint::spin_loop();
+        }
+        reg.remove(&key);
+        drop(reg);
         drop(unsafe { Box::from_raw(handle) });
         0
     })

package/libraries/blitz-ui/native-osr/src/mutate.rs

@@ -10,7 +10,7 @@ use blitz_dom::{
     ns,
 };
 
-use crate::{OsrDoc, ffi, read_str};
+use crate::{OsrDoc, doc_enter, ffi, read_str};
 
 fn attr_qname(name: &str) -> QualName {
     QualName::new(None, ns!(), LocalName::from(name))
@@ -33,9 +33,10 @@ fn with_node_mutator(
     }
     let id = node_id(node);
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         if d.doc.inner().get_node(id).is_none() {
             return -1; // stale/missing node — no-op
         }
@@ -53,9 +54,10 @@ fn with_node_mutator(
 #[no_mangle]
 pub extern "C" fn dd_osr_query(handle: *mut OsrDoc, sel_ptr: *const u8, sel_len: usize) -> u64 {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         let Some(sel) = (unsafe { read_str(sel_ptr, sel_len) }) else {
             return 0;
         };
@@ -167,6 +169,52 @@ pub extern "C" fn dd_osr_set_inner_html(
     })
 }
 
+/// Parse an HTML fragment and append it as the node's last children —
+/// `innerHTML +=` semantics. Unlike set_inner_html the existing children
+/// survive, so streaming views (the devtools console) can append rows
+/// without reparsing the whole list. Requires the HtmlProvider set in
+/// build_doc — same parser path as set_inner_html.
+#[no_mangle]
+pub extern "C" fn dd_osr_append_html(
+    handle: *mut OsrDoc,
+    node: u64,
+    html_ptr: *const u8,
+    html_len: usize,
+) -> c_int {
+    with_node_mutator(handle, node, |m, id| {
+        let Some(html) = (unsafe { read_str(html_ptr, html_len) }) else {
+            return -1;
+        };
+        let provider = m.doc.html_parser_provider.clone();
+        provider.parse_inner_html(m, id, html);
+        0
+    })
+}
+
+/// Drop all but the last `keep` children of `node` — lets a streaming view
+/// bound the DOM size without an innerHTML rebuild.
+#[no_mangle]
+pub extern "C" fn dd_osr_trim_children(
+    handle: *mut OsrDoc,
+    node: u64,
+    keep: u64,
+) -> c_int {
+    with_node_mutator(handle, node, |m, id| {
+        let kids: Vec<NodeId> = {
+            let Some(n) = m.doc.get_node(id) else {
+                return -1;
+            };
+            n.children.iter().copied().collect()
+        };
+        let keep = keep as usize;
+        let drop_n = kids.len().saturating_sub(keep);
+        for cid in kids.into_iter().take(drop_n) {
+            m.remove_and_drop_node(cid);
+        }
+        0
+    })
+}
+
 /// Get an attribute's value (or input's current text for <input>/<textarea>)
 /// into the doc's out-buffer. Read `dd_osr_out_len` for the byte length.
 /// NULL when the node/attr is absent.
@@ -178,9 +226,10 @@ pub extern "C" fn dd_osr_get_attr(
     name_len: usize,
 ) -> *const u8 {
     ffi(std::ptr::null(), || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return std::ptr::null();
         };
+        let d = g.get();
         let Some(name) = (unsafe { read_str(name_ptr, name_len) }) else {
             return std::ptr::null();
         };
@@ -213,9 +262,10 @@ pub extern "C" fn dd_osr_get_attr(
 #[no_mangle]
 pub extern "C" fn dd_osr_node_rect(handle: *mut OsrDoc, node: u64) -> *const f64 {
     ffi(std::ptr::null(), || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return std::ptr::null();
         };
+        let d = g.get();
         if node == 0 {
             return std::ptr::null();
         }
@@ -237,9 +287,10 @@ pub extern "C" fn dd_osr_node_rect(handle: *mut OsrDoc, node: u64) -> *const f64
 #[no_mangle]
 pub extern "C" fn dd_osr_out_len(handle: *mut OsrDoc) -> usize {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         d.out_buf.len()
     })
 }
@@ -248,9 +299,10 @@ pub extern "C" fn dd_osr_out_len(handle: *mut OsrDoc) -> usize {
 #[no_mangle]
 pub extern "C" fn dd_osr_focus(handle: *mut OsrDoc, node: u64) -> c_int {
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let mut doc = d.doc.inner_mut();
         if node == 0 {
             doc.clear_focus();
@@ -277,9 +329,10 @@ pub extern "C" fn dd_osr_query_all(
     sel_len: usize,
 ) -> *const u64 {
     ffi(std::ptr::null(), || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return std::ptr::null();
         };
+        let d = g.get();
         let Some(sel) = (unsafe { read_str(sel_ptr, sel_len) }) else {
             return std::ptr::null();
         };
@@ -296,13 +349,50 @@ pub extern "C" fn dd_osr_query_all(
 #[no_mangle]
 pub extern "C" fn dd_osr_query_all_len(handle: *mut OsrDoc) -> usize {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         d.query_buf.len()
     })
 }
 
+/// Scroll a specific node (a scroll container) to absolute (x, y) offsets.
+/// Unlike scroll_into_view — which at this Blitz rev only scrolls the root
+/// viewport — this reaches nested scrollports; offsets clamp to the node's
+/// scroll range, so y=1e9 pins a log view to its bottom.
+///   behavior: 0 = instant, 1 = smooth
+#[no_mangle]
+pub extern "C" fn dd_osr_scroll_to(
+    handle: *mut OsrDoc,
+    node: u64,
+    x: f64,
+    y: f64,
+    behavior: c_int,
+) -> c_int {
+    ffi(-1, || {
+        let Some(mut g) = doc_enter(handle) else {
+            return -1;
+        };
+        let d = g.get();
+        let id = node_id(node);
+        {
+            let doc = d.doc.inner();
+            if node == 0 || doc.get_node(id).is_none() {
+                return -1;
+            }
+        }
+        d.doc.inner_mut().scroll_to(
+            id,
+            x,
+            y,
+            if behavior == 1 { ScrollBehavior::Smooth } else { ScrollBehavior::Instant },
+        );
+        d.dirty = true;
+        0
+    })
+}
+
 /// Scroll the viewport so that `node` is visible.
 ///   behavior: 0 = instant, 1 = smooth
 ///   v_align/h_align: 0 = start, 1 = center, 2 = end, 3 = nearest
@@ -323,9 +413,10 @@ pub extern "C" fn dd_osr_scroll_into_view(
         }
     }
     ffi(-1, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return -1;
         };
+        let d = g.get();
         let id = node_id(node);
         {
             let doc = d.doc.inner();
@@ -354,9 +445,10 @@ pub extern "C" fn dd_osr_closest(
     sel_len: usize,
 ) -> u64 {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_mut() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
+        let d = g.get();
         let Some(sel) = (unsafe { read_str(sel_ptr, sel_len) }) else {
             return 0;
         };
@@ -373,13 +465,16 @@ pub extern "C" fn dd_osr_closest(
 #[no_mangle]
 pub extern "C" fn dd_osr_focused_node(handle: *mut OsrDoc) -> u64 {
     ffi(0, || {
-        let Some(d) = (unsafe { handle.as_ref() }) else {
+        let Some(mut g) = doc_enter(handle) else {
             return 0;
         };
-        d.doc
+        let d = g.get();
+        let focused = d
+            .doc
             .inner()
             .get_focussed_node_id()
             .map(|id| id.as_u64())
-            .unwrap_or(0)
+            .unwrap_or(0);
+        focused
     })
 }