xbintsc 0.5.31 → 0.5.36

package/runtime/ext_gui/media_api.h

@@ -7,7 +7,7 @@
  * The engine knows how to model `<video>`/`<audio>` elements and how to draw
  * their frames, but it deliberately contains no decoder: FFmpeg lives in the
  * separate `media` compile extension (`runtime/ext_media/`, linked as
- * `media.a`). Keeping the boundary C-only means the backend can be a prebuilt
+ * `media.a`, or `media.lib` with the MSVC ABI on Windows). Keeping the boundary C-only means the backend can be a prebuilt
  * C++ archive that is compiled independently of the engine.
  *
  * Registration is push-based: the backend's bridge translation unit is linked
@@ -40,10 +40,30 @@ typedef XtMediaPlayerHandle (*XtMediaByIdFn)(uint64_t id);
 /** Tear down every decoder and process-wide media state. */
 typedef void (*XtMediaShutdownFn)(void);
 
+/** Interleaved float PCM returned by the memory decoder.
+ *
+ * `samples` is allocated by the backend and must be released with the table's
+ * `free_audio` entry point (both archives use the same static CRT). */
+typedef struct XtMediaAudioBuffer {
+  int channels;
+  int sample_rate;
+  int frames;
+  float *samples;
+} XtMediaAudioBuffer;
+
+/** Decode an in-memory audio file (`decodeAudioData`). Returns 1 on success and
+ * fills `out`; on failure returns 0 and copies a message into `error`. */
+typedef int (*XtMediaDecodeAudioFn)(const unsigned char *data, size_t size,
+                                    XtMediaAudioBuffer *out, char *error, size_t error_size);
+/** Release the `samples` a successful `decode_audio` allocated. */
+typedef void (*XtMediaFreeAudioFn)(void *samples);
+
 typedef struct XtMediaApi {
   XtMediaOpenFn open;
   XtMediaByIdFn by_id;
   XtMediaShutdownFn shutdown;
+  XtMediaDecodeAudioFn decode_audio;
+  XtMediaFreeAudioFn free_audio;
 } XtMediaApi;
 
 /** Install a decoder table. Implemented by the GUI engine; called once by the
@@ -51,12 +71,15 @@ typedef struct XtMediaApi {
 void xt_media_install(const XtMediaApi *api);
 
 /** Decoder backend entry points, implemented by `runtime/ext_media/media.cpp`
- * (inside `media.a`). The bridge references them, which is what makes the
+ * (inside `media.a`/`media.lib`). The bridge references them, which is what makes the
  * linker extract the archive member when the media extension is enabled. */
 XtMediaPlayerHandle xt_media_backend_open(const char *path, char *error,
                                           size_t error_size, void *audio_sink);
 XtMediaPlayerHandle xt_media_backend_by_id(uint64_t id);
 void xt_media_backend_shutdown(void);
+int xt_media_backend_decode_audio(const unsigned char *data, size_t size,
+                                  XtMediaAudioBuffer *out, char *error, size_t error_size);
+void xt_media_backend_free_audio(void *samples);
 
 #ifdef __cplusplus
 }

package/runtime/ext_gui/media_query.cpp

@@ -0,0 +1,211 @@
+/*
+ * xbintsc GUI engine — `@media` query evaluation.
+ *
+ * The CSS parser keeps each rule's raw media prelude and this unit decides
+ * whether it applies to the current viewport. The subset mirrors what a desktop
+ * window can answer: width/height ranges, orientation, hover/pointer class and
+ * the two accessibility preferences. Unknown features evaluate to false, which
+ * is what a browser does (and keeps e.g. `@media print` blocks inert).
+ */
+#include "css_internal.h"
+
+#include <cmath>
+#include <string>
+#include <vector>
+
+namespace xtgui {
+
+namespace {
+
+std::string lowerTrim(const std::string &text) { return xt_css_lower(xt_css_trim(text)); }
+
+/** Split `text` on the word `and` at nesting depth zero. */
+std::vector<std::string> splitAnd(const std::string &text) {
+  std::vector<std::string> parts;
+  std::string current;
+  int depth = 0;
+  for (size_t i = 0; i < text.size();) {
+    char c = text[i];
+    if (c == '(') depth++;
+    else if (c == ')') depth--;
+    bool atWord = (c == 'a' || c == 'A') && i + 3 <= text.size() &&
+                  xt_css_lower(text.substr(i, 3)) == "and" &&
+                  (i == 0 || xt_is_css_space(text[i - 1])) &&
+                  (i + 3 == text.size() || xt_is_css_space(text[i + 3]));
+    if (atWord && depth == 0) {
+      std::string part = xt_css_trim(current);
+      if (!part.empty()) parts.push_back(part);
+      current.clear();
+      i += 3;
+      continue;
+    }
+    current.push_back(c);
+    i++;
+  }
+  std::string part = xt_css_trim(current);
+  if (!part.empty()) parts.push_back(part);
+  return parts;
+}
+
+/** Resolve a media-feature length. `rem`/`em` assume the 16px initial font. */
+bool mediaLength(const std::string &raw, float vw, float vh, float *out) {
+  Length length = xt_css_parse_length(raw);
+  switch (length.unit) {
+    case Unit::Px:
+    case Unit::Number:
+      *out = length.value;
+      return true;
+    case Unit::Em:
+    case Unit::Rem:
+      *out = length.value * 16.0f;
+      return true;
+    case Unit::Vw:
+      *out = vw * length.value / 100.0f;
+      return true;
+    case Unit::Vh:
+      *out = vh * length.value / 100.0f;
+      return true;
+    default:
+      return false;
+  }
+}
+
+/** Compare `actual` with a feature value, honouring a min-/max- prefix. */
+bool compareLength(const std::string &name, const std::string &rawValue, float actual, float vw,
+                   float vh) {
+  float value = 0.0f;
+  if (!mediaLength(rawValue, vw, vh, &value)) return false;
+  const bool min = name.rfind("min-", 0) == 0;
+  const bool max = name.rfind("max-", 0) == 0;
+  if (min) return actual >= value;
+  if (max) return actual <= value;
+  return std::fabs(actual - value) < 0.01f;
+}
+
+bool splitFeature(const std::string &inner, std::string *name, std::string *value) {
+  int depth = 0;
+  for (size_t i = 0; i < inner.size(); i++) {
+    char c = inner[i];
+    if (c == '(') depth++;
+    else if (c == ')') depth--;
+    else if (c == ':' && depth == 0) {
+      *name = lowerTrim(inner.substr(0, i));
+      *value = lowerTrim(inner.substr(i + 1));
+      return true;
+    }
+  }
+  return false;
+}
+
+/** `(width >= 600px)` / `(600px <= width)` range syntax. */
+bool evaluateRange(const std::string &inner, float vw, float vh, bool *matched) {
+  static const char *const ops[] = {">=", "<=", ">", "<", "="};
+  for (const char *op : ops) {
+    size_t pos = inner.find(op);
+    if (pos == std::string::npos) continue;
+    std::string left = lowerTrim(inner.substr(0, pos));
+    std::string right = lowerTrim(inner.substr(pos + std::string(op).size()));
+    std::string opText(op);
+    /* `600px < width` means width > 600px: flip the comparison. */
+    bool flipped = left != "width" && left != "height";
+    std::string feature = flipped ? right : left;
+    std::string valueText = flipped ? left : right;
+    float actual = 0.0f;
+    if (feature == "width") actual = vw;
+    else if (feature == "height") actual = vh;
+    else return false;
+    float value = 0.0f;
+    if (!mediaLength(valueText, vw, vh, &value)) return false;
+    if (flipped) {
+      if (opText == ">") opText = "<";
+      else if (opText == "<") opText = ">";
+      else if (opText == ">=") opText = "<=";
+      else if (opText == "<=") opText = ">=";
+    }
+    if (opText == ">=") *matched = actual >= value;
+    else if (opText == "<=") *matched = actual <= value;
+    else if (opText == ">") *matched = actual > value;
+    else if (opText == "<") *matched = actual < value;
+    else *matched = std::fabs(actual - value) < 0.01f;
+    return true;
+  }
+  return false;
+}
+
+bool evaluateFeature(const std::string &inner, float vw, float vh) {
+  bool rangeMatched = false;
+  if (evaluateRange(inner, vw, vh, &rangeMatched)) return rangeMatched;
+
+  std::string name;
+  std::string value;
+  if (!splitFeature(inner, &name, &value)) return false;
+  if (name.empty() || value.empty()) return false;
+
+  if (name == "width" || name == "min-width" || name == "max-width") {
+    return compareLength(name, value, vw, vw, vh);
+  }
+  if (name == "height" || name == "min-height" || name == "max-height") {
+    return compareLength(name, value, vh, vw, vh);
+  }
+  if (name == "orientation") {
+    if (value == "landscape") return vw >= vh;
+    if (value == "portrait") return vh > vw;
+    return false;
+  }
+  if (name == "hover" || name == "any-hover") return value == "hover";
+  if (name == "pointer" || name == "any-pointer") return value == "fine";
+  if (name == "prefers-color-scheme") return value == "light";
+  if (name == "prefers-reduced-motion") return value == "no-preference";
+  if (name == "prefers-contrast") return value == "no-preference";
+  if (name == "scripting") return value == "enabled";
+  if (name == "display-mode") return value == "browser";
+  return false;
+}
+
+}  // namespace
+
+bool xt_css_media_matches(const std::string &query, float viewport_width, float viewport_height) {
+  std::string text = lowerTrim(query);
+  if (text.empty()) return true;
+
+  bool any = false;
+  for (const std::string &rawQuery : xt_css_split_commas(text)) {
+    std::string part = lowerTrim(rawQuery);
+    bool negate = false;
+    if (part.rfind("not ", 0) == 0) {
+      negate = true;
+      part = xt_css_trim(part.substr(4));
+    } else if (part.rfind("only ", 0) == 0) {
+      part = xt_css_trim(part.substr(5));
+    }
+    bool matched = true;
+    bool first = true;
+    for (const std::string &segment : splitAnd(part)) {
+      std::string token = xt_css_trim(segment);
+      if (token.empty()) continue;
+      if (first && token[0] != '(') {
+        /* Media type: a desktop window is `screen`, never `print`. */
+        if (token == "all" || token == "screen") {
+          matched = true;
+        } else {
+          matched = false;
+        }
+      } else {
+        std::string inner = token;
+        if (inner.front() == '(' && inner.back() == ')') {
+          inner = xt_css_trim(inner.substr(1, inner.size() - 2));
+        }
+        if (!evaluateFeature(inner, viewport_width, viewport_height)) matched = false;
+      }
+      first = false;
+    }
+    if (negate) matched = !matched;
+    if (matched) {
+      any = true;
+      break;
+    }
+  }
+  return any;
+}
+
+}  // namespace xtgui

package/runtime/ext_gui/paint.cpp

@@ -1,5 +1,9 @@
 /*
  * xbintsc GUI engine — display list construction.
+ *
+ * The tree walk lives here. Background layers are in `paint_background.cpp`,
+ * filter/shadow approximations in `paint_effects.cpp` and `clip-path`
+ * triangulation in `paint_clip.cpp`.
  */
 
 #include "paint.h"
@@ -8,6 +12,7 @@
 #include <cstdio>
 #include <utility>
 
+#include "paint_internal.h"
 #include "style.h"
 
 namespace xtgui {
@@ -43,50 +48,14 @@ FontSpec specOf(const XtStyle &style) {
   return spec;
 }
 
-void addRect(DisplayList &out, float x, float y, float width, float height, float radius,
-             const Color &color, const PaintClip &clip, const Matrix2D &transform) {
-  if (width <= 0.0f || height <= 0.0f || color.a <= 0.0f) return;
-  PaintRect rect;
-  rect.x = x;
-  rect.y = y;
-  rect.width = width;
-  rect.height = height;
-  rect.radius = radius;
-  rect.color = color;
-  rect.transform = transform;
-  out.rects.push_back(rect);
-  out.ops.push_back(PaintOp{PaintKind::Rect, (uint32_t)(out.rects.size() - 1), clip});
-}
-
-void addTextRuns(const LayoutBox *box, const XtStyle &style, DisplayList &out,
-                 const PaintClip &clip) {
-  if (box->fragments.empty() || style.color.a <= 0.0f) return;
-  FontSpec spec = specOf(style);
-  float ascent = 0;
-  xt_text_metrics(spec, &ascent, nullptr, nullptr);
-  if (ascent <= 0.0f) ascent = style.font_size * 0.8f;
-  for (const TextFragment &fragment : box->fragments) {
-    if (fragment.text.empty()) continue;
-    PaintText run;
-    run.x = fragment.x;
-    run.baseline = fragment.y + ascent;
-    run.width = fragment.width;
-    run.height = fragment.height;
-    run.color = style.color;
-    run.text = fragment.text;
-    run.font = spec;
-    run.transform = box->world;
-    out.texts.push_back(std::move(run));
-    out.ops.push_back(PaintOp{PaintKind::Text, (uint32_t)(out.texts.size() - 1), clip});
-  }
-}
-
-void addImage(const PaintImage &image, DisplayList &out, const PaintClip &clip) {
-  out.images.push_back(image);
-  out.ops.push_back(PaintOp{PaintKind::Image, (uint32_t)(out.images.size() - 1), clip});
+int zIndexOf(const LayoutBox *box) {
+  if (box->style == nullptr || !box->style->has_z_index) return 0;
+  return box->style->z_index;
 }
 
-void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip);
+void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip,
+              const paint_detail::FilterChain &parentChain, float viewportWidth,
+              float viewportHeight);
 
 /** The clip a box imposes on its content: its padding box, intersected with the
  * clip already in effect. Only `overflow: hidden/scroll/auto` clips. A
@@ -106,23 +75,32 @@ PaintClip clipForChildren(const LayoutBox *box, const PaintClip &parent) {
     width = bounds.width;
     height = bounds.height;
   }
-  if (!parent.active) return PaintClip{true, x, y, width, height};
+  PaintClip result = parent;
+  result.active = true;
+  if (!parent.active) {
+    result.x = x;
+    result.y = y;
+    result.width = width;
+    result.height = height;
+    return result;
+  }
   float x0 = std::max(x, parent.x);
   float y0 = std::max(y, parent.y);
   float x1 = std::min(x + width, parent.x + parent.width);
   float y1 = std::min(y + height, parent.y + parent.height);
-  return PaintClip{true, x0, y0, std::max(0.0f, x1 - x0), std::max(0.0f, y1 - y0)};
-}
-
-int zIndexOf(const LayoutBox *box) {
-  if (box->style == nullptr || !box->style->has_z_index) return 0;
-  return box->style->z_index;
+  result.x = x0;
+  result.y = y0;
+  result.width = std::max(0.0f, x1 - x0);
+  result.height = std::max(0.0f, y1 - y0);
+  return result;
 }
 
 /** Paint `box`'s children following z-index: negative z first (ascending), then
  * auto/zero in document order, then positive z (ascending), so higher stacks
  * paint last. */
-void paintChildren(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
+void paintChildren(const LayoutBox *box, DisplayList &out, const PaintClip &clip,
+                   const paint_detail::FilterChain &chain, float viewportWidth,
+                   float viewportHeight) {
   std::vector<const LayoutBox *> children;
   for (const std::unique_ptr<LayoutBox> &child : box->children) {
     if (child->display == Display::None || child->style == nullptr) continue;
@@ -131,41 +109,78 @@ void paintChildren(const LayoutBox *box, DisplayList &out, const PaintClip &clip
   std::stable_sort(children.begin(), children.end(), [](const LayoutBox *a, const LayoutBox *b) {
     return zIndexOf(a) < zIndexOf(b);
   });
-  for (const LayoutBox *child : children) paintBox(child, out, clip);
+  for (const LayoutBox *child : children)
+    paintBox(child, out, clip, chain, viewportWidth, viewportHeight);
 }
 
-void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
+void addTextRuns(const LayoutBox *box, const XtStyle &style, DisplayList &out,
+                 const PaintClip &clip, const paint_detail::FilterChain &chain,
+                 float viewportWidth, float viewportHeight) {
+  if (box->fragments.empty() || style.color.a <= 0.0f) return;
+  FontSpec spec = specOf(style);
+  float ascent = 0;
+  xt_text_metrics(spec, &ascent, nullptr, nullptr);
+  if (ascent <= 0.0f) ascent = style.font_size * 0.8f;
+  Color base = paint_detail::filterColor(chain, style.color);
+  for (const TextFragment &fragment : box->fragments) {
+    if (fragment.text.empty()) continue;
+    paint_detail::addTextRun(out, fragment.x, fragment.y + ascent, fragment.width,
+                             fragment.height, fragment.text, spec, base, box->world, clip, style,
+                             chain, viewportWidth, viewportHeight);
+  }
+}
+
+void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip,
+              const paint_detail::FilterChain &parentChain, float viewportWidth,
+              float viewportHeight) {
   if (box == nullptr) return;
   const XtStyle *style = box->style;
 
-  /* A fully transparent box paints nothing — not itself, and not its subtree. */
-  if (style != nullptr && style->opacity <= 0.0f) return;
+  /* A fully transparent or hidden box paints nothing — not itself, and not its
+   * subtree. */
+  if (style != nullptr && (style->opacity <= 0.0f || !style->visible)) return;
+
+  /* A text box points at its parent element's style; its filters were already
+   * folded into `parentChain`, so applying them again would double them. */
+  paint_detail::FilterChain chain = parentChain;
+  if (style != nullptr && !box->is_text && !style->filters.empty()) {
+    chain = paint_detail::extendFilter(parentChain, style->filters, *style, viewportWidth,
+                                       viewportHeight);
+  }
+
+  PaintClip own = clip;
+  if (style != nullptr && box->display != Display::None && !box->is_text) {
+    if (style->clip_path.type != ClipPathSpec::Type::None) {
+      int index = paint_detail::addClipPathForBox(out, *box, *style, viewportWidth, viewportHeight);
+      own = paint_detail::addClipPath(own, index);
+    }
+  }
 
   if (style != nullptr && box->display != Display::None) {
     if (box->is_text) {
-      addTextRuns(box, *style, out, clip);
+      addTextRuns(box, *style, out, own, chain, viewportWidth, viewportHeight);
     } else {
-      /* Background first, then the border ring, then replaced content. Children
-       * are clipped by this box's padding box when it establishes one. Every
-       * shape carries the box's `transform` matrix for the renderer. */
+      /* Drop shadows sit behind the box's own background but above earlier
+       * siblings. */
+      paint_detail::addBoxDropShadows(out, *box, *style, chain, own);
+      paint_detail::paintBackgrounds(out, *box, *style, chain, own, viewportWidth,
+                                     viewportHeight);
       const Matrix2D &matrix = box->world;
-      if (style->has_background) {
-        addRect(out, box->x, box->y, box->width, box->height, style->border_radius,
-                style->background, clip, matrix);
-      }
       if (style->border_style != BorderStyle::None && style->has_border_color) {
-        const Color bc = style->border_color;
+        const Color bc = paint_detail::filterColor(chain, style->border_color);
         float top = box->border_top;
         float right = box->border_right;
         float bottom = box->border_bottom;
         float left = box->border_left;
         float inner_height = box->height - top - bottom;
-        addRect(out, box->x, box->y, box->width, top, 0.0f, bc, clip, matrix);
-        addRect(out, box->x, box->y + box->height - bottom, box->width, bottom, 0.0f, bc, clip,
-                matrix);
-        addRect(out, box->x, box->y + top, left, inner_height, 0.0f, bc, clip, matrix);
-        addRect(out, box->x + box->width - right, box->y + top, right, inner_height, 0.0f, bc,
-                clip, matrix);
+        paint_detail::addRectFiltered(out, box->x, box->y, box->width, top, 0.0f, bc, own,
+                                      matrix, chain);
+        paint_detail::addRectFiltered(out, box->x, box->y + box->height - bottom, box->width,
+                                      bottom, 0.0f, bc, own, matrix, chain);
+        paint_detail::addRectFiltered(out, box->x, box->y + top, left, inner_height, 0.0f, bc,
+                                      own, matrix, chain);
+        paint_detail::addRectFiltered(out, box->x + box->width - right, box->y + top, right,
+                                      inner_height, 0.0f, bc, own, matrix, chain);
       }
       if (box->is_canvas && box->canvas_id != 0 && box->content_width > 0.0f &&
           box->content_height > 0.0f) {
@@ -176,7 +191,7 @@ void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
         image.height = box->content_height;
         image.canvas_id = box->canvas_id;
         image.transform = matrix;
-        addImage(image, out, clip);
+        paint_detail::addImage(out, image, own, chain);
       } else if (box->is_media && box->media_id != 0 && box->content_width > 0.0f &&
                  box->content_height > 0.0f) {
         PaintImage image;
@@ -186,7 +201,7 @@ void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
         image.height = box->content_height;
         image.media_id = box->media_id;
         image.transform = matrix;
-        addImage(image, out, clip);
+        paint_detail::addImage(out, image, own, chain);
       } else if (box->is_inline_svg && !box->svg_markup.empty() && box->content_width > 0.0f &&
                  box->content_height > 0.0f) {
         PaintImage image;
@@ -196,7 +211,7 @@ void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
         image.height = box->content_height;
         image.svg = box->svg_markup;
         image.transform = matrix;
-        addImage(image, out, clip);
+        paint_detail::addImage(out, image, own, chain);
       } else if (box->is_image && !box->image_src.empty() && box->content_width > 0.0f &&
                  box->content_height > 0.0f) {
         PaintImage image;
@@ -206,24 +221,34 @@ void paintBox(const LayoutBox *box, DisplayList &out, const PaintClip &clip) {
         image.height = box->content_height;
         image.src = box->image_src;
         image.transform = matrix;
-        addImage(image, out, clip);
+        paint_detail::addImage(out, image, own, chain);
       }
     }
   }
 
-  paintChildren(box, out, clipForChildren(box, clip));
+  /* Drop shadows belong to the box that declared them: its silhouette has
+   * already been emitted, so descendants must not repeat it. */
+  paint_detail::FilterChain childChain = chain;
+  childChain.shadows.clear();
+  paintChildren(box, out, clipForChildren(box, own), childChain, viewportWidth, viewportHeight);
 }
 
 }  // namespace
 
-void xt_paint_build(const LayoutBox *root, DisplayList &out) {
+void xt_paint_build(const LayoutBox *root, DisplayList &out, float viewportWidth,
+                    float viewportHeight) {
   PaintClip none;
-  paintBox(root, out, none);
+  paint_detail::FilterChain chain;
+  if (root != nullptr && viewportWidth <= 0.0f) {
+    viewportWidth = root->cb_width;
+    viewportHeight = root->cb_height;
+  }
+  paintBox(root, out, none, chain, viewportWidth, viewportHeight);
 }
 
 std::string DisplayList::dump() const {
   std::string text;
-  char buffer[288];
+  char buffer[320];
   for (const PaintOp &op : ops) {
     std::string prefix;
     if (op.clip.active) {
@@ -231,6 +256,14 @@ std::string DisplayList::dump() const {
                     op.clip.width, op.clip.height);
       prefix = buffer;
     }
+    if (op.clip.path_count > 0) {
+      prefix += "clip-path=";
+      for (int i = 0; i < op.clip.path_count; i++) {
+        if (i > 0) prefix += ",";
+        prefix += std::to_string(op.clip.paths[i]);
+      }
+      prefix += " ";
+    }
     std::string suffix;
     if (op.kind == PaintKind::Rect) {
       suffix = transformSuffix(rects[op.index].transform);
@@ -246,6 +279,7 @@ std::string DisplayList::dump() const {
                     "text x=%.1f baseline=%.1f size=%.1f color=%s \"%s\"", run.x, run.baseline,
                     run.font.pixel_size, formatColor(run.color).c_str(), run.text.c_str());
       text += prefix + buffer;
+      if (run.shadow) text += " shadow=1";
     } else {
       const PaintImage &image = images[op.index];
       suffix = transformSuffix(image.transform);

package/runtime/ext_gui/paint.h

@@ -46,6 +46,9 @@ struct PaintText {
   std::string text;
   FontSpec font;
   Matrix2D transform;
+  /** Set on a `text-shadow` copy (diagnostics only; the renderer draws it like
+   * any other glyph run). */
+  bool shadow = false;
 };
 
 /** An image to draw, scaled into the given rectangle (viewport-relative).
@@ -65,17 +68,38 @@ struct PaintImage {
   uint64_t media_id = 0;
   uint64_t canvas_id = 0;
   Matrix2D transform;
+  /** Modulating colour for the image shader (white normally; a filter's
+   * multiplicative effect may tint it). */
+  Color tint{1.0f, 1.0f, 1.0f, 1.0f};
+};
+
+/** One triangle of a clip path in device-space logical pixels. The paint pass
+ * triangulates (possibly concave) polygons once so the renderer can clip
+ * convex shape/glyph quads by a simple half-plane test per triangle. */
+struct ClipTriangle {
+  float x[3] = {0, 0, 0};
+  float y[3] = {0, 0, 0};
+};
+
+/** A resolved `clip-path` polygon plus its triangulation. */
+struct ClipPathGeometry {
+  std::vector<float> points;  // x, y pairs (diagnostics)
+  std::vector<ClipTriangle> triangles;
 };
 
 /** The clip rectangle in effect for a painted shape (device-space logical
  * pixels — a transformed subtree contributes the bounding box of its clip).
- * `width <= 0` means "no clip". */
+ * `width <= 0` means "no clip". `paths` index `DisplayList::clip_paths`; at most
+ * two nested `clip-path` shapes are kept (CSS would intersect every ancestor;
+ * deeper nesting is rare and the outermost two are the ones a UI uses). */
 struct PaintClip {
   bool active = false;
   float x = 0;
   float y = 0;
   float width = 0;
   float height = 0;
+  int path_count = 0;
+  int paths[2] = {-1, -1};
 };
 
 enum class PaintKind { Rect, Text, Image };
@@ -95,20 +119,26 @@ struct DisplayList {
   /** Shapes in painter order (backgrounds/borders first, then children, then
    * stacked siblings), each with the clip rectangle that bounds it. */
   std::vector<PaintOp> ops;
+  /** Device-space clip-path polygons shared by an element's ops. */
+  std::vector<ClipPathGeometry> clip_paths;
 
   void clear() {
     rects.clear();
     texts.clear();
     images.clear();
     ops.clear();
+    clip_paths.clear();
   }
   bool empty() const { return rects.empty() && texts.empty() && images.empty(); }
   /** Human-readable dump, one shape per line, in painter order (diagnostics/tests). */
   std::string dump() const;
 };
 
-/** Build the display list for a laid-out tree and append it to `out`. */
-void xt_paint_build(const LayoutBox *root, DisplayList &out);
+/** Build the display list for a laid-out tree and append it to `out`. The
+ * viewport size resolves `vw`/`vh` units inside `clip-path` and shadows; pass 0
+ * to take it from the root box's containing block. */
+void xt_paint_build(const LayoutBox *root, DisplayList &out, float viewportWidth = 0.0f,
+                    float viewportHeight = 0.0f);
 
 }  // namespace xtgui