feat: add CSS selector queries and expose container state

Author: franzos

CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.2.2] - 2026-02-19
+
+### Added
+- CSS selector queries on elements via `select_one()` and `css_escape_ident()`
+- Pending image tracking: `take_pending_images()` collects URLs discovered during layout
+- Anchor click and cursor state now exposed via `take_anchor_click()` and `cursor()`
+
 ## [0.2.1] - 2026-02-18
 
 ### Added

Cargo.lock

@@ -102,3 +102,11 @@ let prepared = prepare_email_html(raw_bytes, Some(&cid_resolver), None);
 ```
 
 `EMAIL_MASTER_CSS` provides an email user-agent stylesheet (body reset, responsive images, table normalization, MSO workarounds).
+
+## Tips
+
+A few things worth knowing when integrating `PixbufContainer` into a GUI:
+
+- **Image loading is your job.** During layout, litehtml discovers `<img>` URLs and queues them. Call `take_pending_images()` to drain the queue, fetch the data yourself, then feed it back via `load_image_data()`. Stage multiple images before re-rendering to avoid one rebuild per image.
+- **Pixel data is premultiplied.** `container.pixels()` returns premultiplied RGBA. If your framework expects straight alpha (e.g. iced's `image::Handle::from_rgba`), you'll need to unpremultiply first.
+- **Anchor clicks and cursor state are pull-based.** After mouse events, call `take_anchor_click()` to check if a link was clicked and `cursor()` to read the current CSS cursor value. Discard anchor clicks during active text selections to avoid accidental navigation.

README.md

@@ -1,6 +1,6 @@
 [package]
 name = "litehtml-sys"
-version = "0.2.0"
+version = "0.2.2"
 edition = "2021"
 license = "MIT AND BSD-3-Clause AND Apache-2.0"
 authors = ["Franz Geffke <mail@gofranz.com>"]

litehtml-sys/Cargo.toml

@@ -1177,6 +1177,15 @@ float lh_element_get_font_size(lh_element_t* el)
     return elem->css().get_font_size();
 }
 
+lh_element_t* lh_element_select_one(lh_element_t* el, const char* selector)
+{
+    if (!el || !selector) return nullptr;
+    auto* elem = reinterpret_cast<litehtml::element*>(el);
+    auto found = elem->select_one(selector);
+    if (!found) return nullptr;
+    return reinterpret_cast<lh_element_t*>(found.get());
+}
+
 void lh_element_get_placement(lh_element_t* el, lh_position_t* pos)
 {
     if (!el || !pos) return;

litehtml-sys/csrc/litehtml_c.cpp

@@ -381,6 +381,10 @@ void lh_element_get_inline_box_at(lh_element_t* el, int index, lh_position_t* po
 typedef void (*lh_inline_box_callback)(const lh_position_t* pos, void* ctx);
 void lh_element_get_inline_boxes(lh_element_t* el, lh_inline_box_callback cb, void* ctx);
 
+/* Find the first descendant matching a CSS selector (e.g. "#id", "[name=foo]").
+   Returns NULL if no match or if el/selector is NULL. */
+lh_element_t* lh_element_select_one(lh_element_t* el, const char* selector);
+
 /* Get the computed text-align value (0=left, 1=right, 2=center, 3=justify). */
 int lh_element_get_text_align(lh_element_t* el);
 

litehtml-sys/csrc/litehtml_c.h

@@ -1,6 +1,6 @@
 [package]
 name = "litehtml"
-version = "0.2.1"
+version = "0.2.2"
 edition = "2021"
 license = "MIT"
 authors = ["Franz Geffke <mail@gofranz.com>"]

litehtml/Cargo.toml

@@ -1657,6 +1657,53 @@ static CONTAINER_VTABLE: sys::lh_container_vtable_t = sys::lh_container_vtable_t
 // Document
 // ---------------------------------------------------------------------------
 
+/// Escape CSS meta-characters in an identifier for use in selectors.
+///
+/// Without escaping, `select_one("#foo.bar")` is parsed as "id=foo AND class=bar".
+/// With escaping, `select_one(&format!("#{}", css_escape_ident("foo.bar")))` correctly
+/// matches an element with `id="foo.bar"`.
+pub fn css_escape_ident(s: &str) -> String {
+    let mut out = String::with_capacity(s.len() + 8);
+    for (i, c) in s.chars().enumerate() {
+        if matches!(
+            c,
+            '.' | ':'
+                | '['
+                | ']'
+                | '('
+                | ')'
+                | '#'
+                | '>'
+                | '+'
+                | '~'
+                | ','
+                | ' '
+                | '{'
+                | '}'
+                | '!'
+                | '"'
+                | '\''
+                | '\\'
+                | '/'
+                | '='
+                | '^'
+                | '$'
+                | '*'
+                | '|'
+                | '%'
+                | '&'
+                | '@'
+        ) {
+            out.push('\\');
+        }
+        if i == 0 && c.is_ascii_digit() {
+            out.push('\\');
+        }
+        out.push(c);
+    }
+    out
+}
+
 /// Opaque handle to a litehtml element. Borrows from the parent [`Document`].
 pub struct Element<'a> {
     ptr: *mut sys::lh_element_t,
@@ -1710,6 +1757,23 @@ impl<'a> Element<'a> {
         unsafe { sys::lh_element_get_font_size(self.ptr) }
     }
 
+    /// Find the first descendant matching a CSS selector.
+    ///
+    /// Useful for locating elements by ID (`"#myid"`) or attribute
+    /// (`"[name=anchor]"`). Returns `None` if no match is found.
+    pub fn select_one(&self, selector: &str) -> Option<Element<'a>> {
+        let c_sel = CString::new(selector).ok()?;
+        let ptr = unsafe { sys::lh_element_select_one(self.ptr, c_sel.as_ptr()) };
+        if ptr.is_null() {
+            None
+        } else {
+            Some(Element {
+                ptr,
+                _phantom: PhantomData,
+            })
+        }
+    }
+
     /// Absolute pixel bounding box after layout.
     pub fn placement(&self) -> Position {
         let mut pos = sys::lh_position_t {

litehtml/src/lib.rs

@@ -46,11 +46,17 @@ pub struct PixbufContainer {
     cached_clip_mask: Option<tiny_skia::Mask>,
     clip_mask_dirty: bool,
     images: HashMap<String, tiny_skia::Pixmap>,
+    pending_images: Vec<(String, bool)>,
+    /// URLs that have already been handed off for fetching. Prevents the same
+    /// URL from being re-added to `pending_images` across document rebuilds.
+    requested_images: std::collections::HashSet<String>,
     viewport: Position,
     base_url: String,
     caption: String,
     scale_factor: f32,
     ignore_overflow_clips: bool,
+    last_anchor_click: Option<String>,
+    current_cursor: String,
 }
 
 impl PixbufContainer {
@@ -82,6 +88,8 @@ impl PixbufContainer {
             cached_clip_mask: None,
             clip_mask_dirty: false,
             images: HashMap::new(),
+            pending_images: Vec::new(),
+            requested_images: std::collections::HashSet::new(),
             viewport: Position {
                 x: 0.0,
                 y: 0.0,
@@ -92,6 +100,8 @@ impl PixbufContainer {
             caption: String::new(),
             scale_factor,
             ignore_overflow_clips: false,
+            last_anchor_click: None,
+            current_cursor: String::new(),
         }
     }
 
@@ -170,6 +180,33 @@ impl PixbufContainer {
         self.ignore_overflow_clips = ignore;
     }
 
+    /// Take the last anchor click URL, if any.
+    ///
+    /// Returns `Some(url)` when `on_anchor_click` was triggered by litehtml
+    /// (via `Document::on_lbutton_up`), clearing the stored value.
+    pub fn take_anchor_click(&mut self) -> Option<String> {
+        self.last_anchor_click.take()
+    }
+
+    /// Drain and return image URLs discovered during layout that haven't been
+    /// loaded yet. The consumer is responsible for fetching the data and calling
+    /// `load_image_data` with the result.
+    pub fn take_pending_images(&mut self) -> Vec<(String, bool)> {
+        std::mem::take(&mut self.pending_images)
+    }
+
+    /// Clear all pending/requested image tracking. Call on navigation so
+    /// the new page's images are discovered fresh.
+    pub fn clear_pending_images(&mut self) {
+        self.pending_images.clear();
+        self.requested_images.clear();
+    }
+
+    /// Get the current CSS cursor value set by litehtml (e.g. `"pointer"`, `"default"`).
+    pub fn cursor(&self) -> &str {
+        &self.current_cursor
+    }
+
     /// Resize the pixmap, clearing all existing content.
     pub fn resize(&mut self, width: u32, height: u32) {
         self.resize_with_scale(width, height, self.scale_factor);
@@ -739,8 +776,13 @@ impl DocumentContainer for PixbufContainer {
                         width: 1.0,
                         ..Stroke::default()
                     };
-                    self.pixmap
-                        .stroke_path(&path, &paint, &stroke, transform, self.cached_clip_mask.as_ref());
+                    self.pixmap.stroke_path(
+                        &path,
+                        &paint,
+                        &stroke,
+                        transform,
+                        self.cached_clip_mask.as_ref(),
+                    );
                 }
             }
             2 => {
@@ -756,8 +798,12 @@ impl DocumentContainer for PixbufContainer {
         }
     }
 
-    fn load_image(&mut self, _src: &str, _baseurl: &str, _redraw_on_ready: bool) {
-        // Image loading is handled externally via `load_image_data`.
+    fn load_image(&mut self, src: &str, _baseurl: &str, redraw_on_ready: bool) {
+        if src.is_empty() || self.images.contains_key(src) || self.requested_images.contains(src) {
+            return;
+        }
+        self.requested_images.insert(src.to_string());
+        self.pending_images.push((src.to_string(), redraw_on_ready));
     }
 
     fn get_image_size(&self, src: &str, _baseurl: &str) -> Size {
@@ -807,14 +853,22 @@ impl DocumentContainer for PixbufContainer {
                     intersect_masks(&mut m, existing);
                 }
                 self.pixmap.draw_pixmap(
-                    dst_x, dst_y, img.as_ref(), &img_paint,
-                    Transform::identity(), Some(&m),
+                    dst_x,
+                    dst_y,
+                    img.as_ref(),
+                    &img_paint,
+                    Transform::identity(),
+                    Some(&m),
                 );
             }
         } else {
             self.pixmap.draw_pixmap(
-                dst_x, dst_y, img.as_ref(), &img_paint,
-                Transform::identity(), self.cached_clip_mask.as_ref(),
+                dst_x,
+                dst_y,
+                img.as_ref(),
+                &img_paint,
+                Transform::identity(),
+                self.cached_clip_mask.as_ref(),
             );
         }
     }
@@ -832,8 +886,13 @@ impl DocumentContainer for PixbufContainer {
         if let Some(path) =
             build_rounded_rect_path(border.x, border.y, border.width, border.height, &radii)
         {
-            self.pixmap
-                .fill_path(&path, &paint, FillRule::Winding, transform, self.cached_clip_mask.as_ref());
+            self.pixmap.fill_path(
+                &path,
+                &paint,
+                FillRule::Winding,
+                transform,
+                self.cached_clip_mask.as_ref(),
+            );
         }
     }
 
@@ -878,8 +937,13 @@ impl DocumentContainer for PixbufContainer {
             if let Some(path) =
                 build_rounded_rect_path(border.x, border.y, border.width, border.height, &radii)
             {
-                self.pixmap
-                    .fill_path(&path, &paint, FillRule::Winding, transform, self.cached_clip_mask.as_ref());
+                self.pixmap.fill_path(
+                    &path,
+                    &paint,
+                    FillRule::Winding,
+                    transform,
+                    self.cached_clip_mask.as_ref(),
+                );
             }
         }
     }
@@ -930,8 +994,13 @@ impl DocumentContainer for PixbufContainer {
             if let Some(path) =
                 build_rounded_rect_path(border.x, border.y, border.width, border.height, &radii)
             {
-                self.pixmap
-                    .fill_path(&path, &paint, FillRule::Winding, transform, self.cached_clip_mask.as_ref());
+                self.pixmap.fill_path(
+                    &path,
+                    &paint,
+                    FillRule::Winding,
+                    transform,
+                    self.cached_clip_mask.as_ref(),
+                );
             }
         }
     }
@@ -1016,9 +1085,13 @@ impl DocumentContainer for PixbufContainer {
         self.base_url = base_url.to_string();
     }
 
-    fn on_anchor_click(&mut self, _url: &str) {}
+    fn on_anchor_click(&mut self, url: &str) {
+        self.last_anchor_click = Some(url.to_string());
+    }
 
-    fn set_cursor(&mut self, _cursor: &str) {}
+    fn set_cursor(&mut self, cursor: &str) {
+        self.current_cursor = cursor.to_string();
+    }
 
     fn set_clip(&mut self, pos: Position, radius: BorderRadiuses) {
         if self.ignore_overflow_clips {
@@ -1100,13 +1173,13 @@ fn blend_pixel(
     }
 
     // Apply clip mask
+    let pixel_offset = y as usize * width as usize + x as usize;
     let effective_a = if let Some(mask) = mask {
-        let mask_idx = (y * width + x) as usize;
         let mask_data = mask.data();
-        if mask_idx >= mask_data.len() {
+        if pixel_offset >= mask_data.len() {
             return;
         }
-        let mask_val = mask_data[mask_idx];
+        let mask_val = mask_data[pixel_offset];
         if mask_val == 0 {
             return;
         }
@@ -1119,7 +1192,7 @@ fn blend_pixel(
         return;
     }
 
-    let idx = ((y * width + x) * 4) as usize;
+    let idx = pixel_offset * 4;
     if idx + 3 >= data.len() {
         return;
     }