xbintsc 0.5.45 → 0.5.52

package/runtime/ext_gui/layout_inline.cpp

@@ -15,6 +15,10 @@ void Layouter::flattenInline(LayoutBox *box, float contentWidth,
                              std::vector<InlineItem> &out) const {
   const XtStyle &style = *box->style;
   if (box->is_text) {
+    if (style.writing_mode != WritingMode::HorizontalTB) {
+      flattenVerticalText(box, out);
+      return;
+    }
     float height = lineHeightOf(style);
     float ascent = ascentOf(style);
     const std::string &text = box->text;
@@ -45,7 +49,8 @@ void Layouter::flattenInline(LayoutBox *box, float contentWidth,
     }
     return;
   }
-  if (box->display == Display::InlineBlock) {
+  if (box->display == Display::InlineBlock || style.inline_level ||
+      style.writing_mode != WritingMode::HorizontalTB) {
     float available = contentWidth;
     float intrinsic = preferredContentWidth(box, available);
     setContainingBlock(box, containingBlockAncestor(box));
@@ -56,6 +61,13 @@ void Layouter::flattenInline(LayoutBox *box, float contentWidth,
     item.atomic = true;
     item.width = box->margin_left + box->width + box->margin_right;
     item.height = box->margin_top + box->height + box->margin_bottom;
+    float shift = 0.0f;
+    if (!isAuto(style.vertical_align)) {
+      shift = px(style.vertical_align, available, style.font_size, 0.0f);
+    }
+    /* A positive `vertical-align` raises the atomic box above the baseline;
+     * the line box keeps its own ascent so the shift is purely visual. */
+    item.shift = shift;
     item.ascent = item.height;
     out.push_back(std::move(item));
     return;
@@ -68,6 +80,13 @@ void Layouter::flattenInline(LayoutBox *box, float contentWidth,
 }
 
 void Layouter::computeInlineGeometry(LayoutBox *box) const {
+  /* An atomic inline box already has geometry from its own formatting context;
+   * replacing it with the union of its descendants would shrink an inline-grid
+   * to its text (and an inline-block to its content). */
+  if (!box->is_text && box->style != nullptr &&
+      (box->display == Display::InlineBlock || box->style->inline_level)) {
+    return;
+  }
   if (box->is_text) {
     if (box->fragments.empty()) return;
     float minx = kHuge, miny = kHuge, maxx = -kHuge, maxy = -kHuge;
@@ -119,6 +138,11 @@ float Layouter::layoutInlineRun(LayoutBox *container, const std::vector<LayoutBo
   if (items.empty()) return 0;
 
   const XtStyle &containerStyle = *container->style;
+  if (containerStyle.writing_mode != WritingMode::HorizontalTB) {
+    float height = layoutVerticalRun(container, items, contentWidth, y);
+    for (LayoutBox *box : run) computeInlineGeometry(box);
+    return height;
+  }
   float cursorY = y;
   std::vector<InlineItem *> line;
   float lineWidth = 0;
@@ -159,7 +183,7 @@ float Layouter::layoutInlineRun(LayoutBox *container, const std::vector<LayoutBo
          * `layoutBlock`, so it must not be moved back onto the line. */
         if (!isAbsoluteChild(item->box)) {
           float dx = x + item->box->margin_left - item->box->x;
-          float dy = cursorY + item->box->margin_top - item->box->y;
+          float dy = cursorY + item->box->margin_top - item->box->y - item->shift;
           translate(item->box, dx, dy);
           /* `position: relative` on an inline-block shifts it after line
            * placement, so the line box keeps the space it reserved. */

package/runtime/ext_gui/layout_vertical.cpp

@@ -0,0 +1,196 @@
+/*
+ * xbintsc GUI engine — vertical writing mode (`writing-mode: vertical-rl|-lr`).
+ *
+ * This is a focused text layout: characters are placed one per column step,
+ * CJK glyphs upright and other scripts rotated 90° at paint time. It covers the
+ * decorative vertical labels a page uses; mixed block/inline content in a
+ * vertical container still falls back to horizontal layout (documented).
+ */
+
+#include "layout_flow_internal.h"
+
+namespace xtgui {
+namespace layout_flow_detail {
+
+namespace {
+
+/** Decode one UTF-8 codepoint at `index`, advancing it. */
+uint32_t nextCodePoint(const std::string &text, size_t *index) {
+  unsigned char first = (unsigned char)text[*index];
+  uint32_t value = first;
+  size_t length = 1;
+  if ((first & 0x80u) == 0) {
+    value = first;
+  } else if ((first & 0xe0u) == 0xc0u) {
+    value = first & 0x1fu;
+    length = 2;
+  } else if ((first & 0xf0u) == 0xe0u) {
+    value = first & 0x0fu;
+    length = 3;
+  } else {
+    value = first & 0x07u;
+    length = 4;
+  }
+  for (size_t i = 1; i < length && *index + i < text.size(); i++) {
+    value = (value << 6) | ((unsigned char)text[*index + i] & 0x3fu);
+  }
+  *index += length;
+  return value;
+}
+
+/** CJK, kana, Hangul and fullwidth forms are kept upright in vertical text. */
+bool isUprightCodePoint(uint32_t value) {
+  if (value >= 0x1100 && value <= 0x11ff) return true;
+  if (value >= 0x2e80 && value <= 0xa4cf) return true;
+  if (value >= 0xac00 && value <= 0xd7af) return true;
+  if (value >= 0xf900 && value <= 0xfaff) return true;
+  if (value >= 0xfe30 && value <= 0xfe4f) return true;
+  if (value >= 0xff00 && value <= 0xffef) return true;
+  if (value >= 0x20000) return true;
+  return false;
+}
+
+/** The column's top-left x for the first column (right edge for `vertical-rl`). */
+float firstColumnX(const LayoutBox *container, const XtStyle &style, float contentWidth,
+                   float columnWidth) {
+  if (style.writing_mode == WritingMode::VerticalLR) return container->content_x;
+  float x = container->content_x + contentWidth - columnWidth;
+  if (x < container->content_x) x = container->content_x;
+  return x;
+}
+
+}  // namespace
+
+void Layouter::flattenVerticalText(LayoutBox *box, std::vector<InlineItem> &out) const {
+  const XtStyle &style = *box->style;
+  const float columnWidth = lineHeightOf(style);
+  const std::string &text = box->text;
+  size_t index = 0;
+  while (index < text.size()) {
+    size_t start = index;
+    uint32_t code = nextCodePoint(text, &index);
+    if (code == '\n') {
+      InlineItem br;
+      br.box = box;
+      br.style = &style;
+      br.force_break = true;
+      br.vertical = true;
+      out.push_back(std::move(br));
+      continue;
+    }
+    InlineItem item;
+    item.box = box;
+    item.style = &style;
+    item.text = text.substr(start, index - start);
+    item.is_space = code == ' ' || code == '\t';
+    item.vertical = true;
+    item.upright = isUprightCodePoint(code);
+    item.width = columnWidth;
+    item.height = textWidth(item.text, style);
+    item.ascent = item.height;
+    out.push_back(std::move(item));
+  }
+}
+
+float Layouter::layoutVerticalRun(LayoutBox *container, const std::vector<InlineItem> &items,
+                                  float contentWidth, float y) const {
+  const XtStyle &style = *container->style;
+  const float columnWidth = lineHeightOf(style);
+  const bool rightToLeft = style.writing_mode != WritingMode::VerticalLR;
+  float limit = -1.0f;
+  if (!isAuto(style.height)) limit = px(style.height, container->content_height, style.font_size, -1.0f);
+
+  float columnX = firstColumnX(container, style, contentWidth, columnWidth);
+  float cursorY = y;
+  float startY = y;
+  float minX = columnX;
+  float maxX = columnX + columnWidth;
+  float maxY = y;
+  bool atColumnStart = true;
+
+  auto newColumn = [&]() {
+    columnX += rightToLeft ? -columnWidth : columnWidth;
+    cursorY = startY;
+    atColumnStart = true;
+    if (columnX < minX) minX = columnX;
+    if (columnX + columnWidth > maxX) maxX = columnX + columnWidth;
+  };
+
+  for (const InlineItem &item : items) {
+    if (item.force_break) {
+      newColumn();
+      continue;
+    }
+    if (item.is_space && atColumnStart) continue;
+    if (limit >= 0.0f && !atColumnStart && cursorY + item.height > startY + limit) newColumn();
+    item.box->fragments.push_back(
+        {columnX, cursorY, columnWidth, item.height, item.text, true, item.upright});
+    cursorY += item.height;
+    atColumnStart = false;
+    if (cursorY > maxY) maxY = cursorY;
+    if (item.width > 0.0f) {
+      float right = columnX + columnWidth;
+      if (right > maxX) maxX = right;
+    }
+  }
+  (void)minX;
+  (void)maxX;
+  return maxY - startY;
+}
+
+float Layouter::layoutVerticalTextBox(LayoutBox *box, float x, float y, float width) const {
+  const XtStyle &style = *box->style;
+  const float columnWidth = lineHeightOf(style);
+  const bool rightToLeft = style.writing_mode != WritingMode::VerticalLR;
+  float limit = -1.0f;
+  if (!isAuto(style.height)) limit = px(style.height, -1.0f, style.font_size, -1.0f);
+
+  float columnX = rightToLeft ? x + width - columnWidth : x;
+  if (rightToLeft && columnX < x) columnX = x;
+  float cursorY = y;
+  float startY = y;
+  float minX = columnX;
+  float maxX = columnX + columnWidth;
+  float maxY = y;
+  bool atColumnStart = true;
+
+  size_t index = 0;
+  const std::string &text = box->text;
+  while (index < text.size()) {
+    size_t start = index;
+    uint32_t code = nextCodePoint(text, &index);
+    if (code == '\n') {
+      columnX += rightToLeft ? -columnWidth : columnWidth;
+      cursorY = startY;
+      atColumnStart = true;
+      continue;
+    }
+    std::string glyph = text.substr(start, index - start);
+    float advance = textWidth(glyph, style);
+    if (limit >= 0.0f && !atColumnStart && cursorY + advance > startY + limit) {
+      columnX += rightToLeft ? -columnWidth : columnWidth;
+      cursorY = startY;
+      atColumnStart = true;
+    }
+    if (code == ' ' && atColumnStart) continue;
+    box->fragments.push_back(
+        {columnX, cursorY, columnWidth, advance, glyph, true, isUprightCodePoint(code)});
+    cursorY += advance;
+    atColumnStart = false;
+    if (cursorY > maxY) maxY = cursorY;
+  }
+
+  box->x = minX;
+  box->y = startY;
+  box->width = maxX - minX;
+  box->height = maxY - startY;
+  box->content_x = box->x;
+  box->content_y = box->y;
+  box->content_width = box->width;
+  box->content_height = box->height;
+  box->baseline = box->height;
+  return box->height;
+}
+
+}  // namespace layout_flow_detail
+}  // namespace xtgui

package/runtime/ext_gui/media.cpp

@@ -33,7 +33,9 @@ namespace xtgui {
 std::unique_ptr<MediaPlayer> MediaPlayer::open(const std::string& path, std::string* error,
                                                std::unique_ptr<AudioSink> audio) {
   if (g_api == nullptr || g_api->open == nullptr) {
-    if (error) *error = "media support requires the 'media' extension (pass --ext media)";
+    if (error) {
+      *error = "media support was not linked; rebuild with '--feature media' (or make the media use visible to the compiler)";
+    }
     return nullptr;
   }
   char message[kErrorSize] = {0};
@@ -59,7 +61,7 @@ bool xt_media_decode_audio(const uint8_t* data, size_t size, DecodedAudio* out,
                            std::string* error) {
   if (g_api == nullptr || g_api->decode_audio == nullptr) {
     if (error) {
-      *error = "cannot decode this audio format; enable the 'media' extension (pass --ext media)";
+      *error = "cannot decode this audio format; rebuild with '--feature media' (the FFmpeg backend was not linked)";
     }
     return false;
   }

package/runtime/ext_gui/media.h

@@ -7,8 +7,8 @@
  * The engine owns the DOM integration (one `MediaPlayer` per element, owned by
  * the window) and the renderer uploads decoded frames as GPU textures. The
  * decoder itself is optional: `MediaPlayer::open` dispatches through the table
- * the `media` extension installs at startup (see `media_api.h`). A program built
- * with `--ext gui` alone therefore links without FFmpeg and reports an `error`
+ * the `media` link feature installs at startup (see `media_api.h`). A program
+ * that does not use media therefore links without FFmpeg and reports an `error`
  * event when a media element is opened.
  *
  * A `MediaPlayer` owns one demux/decode pipeline for a single source file. It
@@ -25,7 +25,7 @@
  * engine already runs a frame loop, so there is no separate media thread and no
  * interaction with the garbage collector.
  *
- * The FFmpeg headers stay inside the media extension's `media.cpp`; this header
+ * The FFmpeg headers stay inside the media feature's `media.cpp`; this header
  * only exposes value types so the rest of the engine (and `gui_engine.h`) can
  * hold a player without pulling in libav*.
  */

package/runtime/ext_gui/media_api.h

@@ -6,16 +6,17 @@
  *
  * 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
+ * optional `media` link feature (`runtime/ext_media/`, linked as
  * `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
- * directly (it is a `runtimeSources()` entry of the media extension), and a
+ * only when the compiler selects the feature (it is the feature's
+ * `runtimeSources()` entry), and a
  * constructor calls `xt_media_install` with its function table. The GUI's
- * dispatch layer (`media.cpp`) starts with a null table, so a program built
- * with `--ext gui` alone still links and simply reports that media support was
- * not enabled.
+ * dispatch layer (`media.cpp`) starts with a null table, so a program that does
+ * not use media still links and simply reports that media support was
+ * not linked.
  *
  * `audio_sink` is an opaque `xtgui::AudioSink*` owned by the caller until the
  * open call; the backend takes ownership whether the open succeeds or not.
@@ -72,7 +73,7 @@ void xt_media_install(const XtMediaApi *api);
 
 /** Decoder backend entry points, implemented by `runtime/ext_media/media.cpp`
  * (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. */
+ * linker extract the archive member when the `media` feature is selected. */
 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);

package/runtime/ext_gui/paint.cpp

@@ -9,6 +9,7 @@
 #include "paint.h"
 
 #include <algorithm>
+#include <cmath>
 #include <cstddef>
 #include <cstdio>
 #include <utility>
@@ -46,6 +47,7 @@ FontSpec specOf(const XtStyle &style) {
   spec.pixel_size = style.font_size;
   spec.weight = style.font_weight;
   spec.italic = style.font_style == FontStyle::Italic;
+  spec.letter_spacing = style.letter_spacing.unit == Unit::Px ? style.letter_spacing.value : 0.0f;
   return spec;
 }
 
@@ -145,11 +147,34 @@ void addTextRuns(const LayoutBox *box, const XtStyle &style, DisplayList &out,
   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);
+  constexpr float kQuarterTurn = 1.57079632679f;
   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);
+    if (!fragment.vertical) {
+      paint_detail::addTextRun(out, fragment.x, fragment.y + ascent, fragment.width,
+                               fragment.height, fragment.text, spec, base, box->world, clip, style,
+                               chain, viewportWidth, viewportHeight);
+      continue;
+    }
+    if (fragment.upright) {
+      /* CJK-style upright glyph centred in its column cell. */
+      float glyphWidth = fragment.height;
+      float x = fragment.x + (fragment.width - glyphWidth) / 2.0f;
+      float baseline = fragment.y + (fragment.height - style.font_size) / 2.0f + ascent;
+      paint_detail::addTextRun(out, x, baseline, glyphWidth, fragment.width, fragment.text, spec,
+                               base, box->world, clip, style, chain, viewportWidth, viewportHeight);
+      continue;
+    }
+    /* Rotate the horizontal run 90° clockwise about its column's top edge. */
+    float pivotX = fragment.x + ascent;
+    float pivotY = fragment.y;
+    Matrix2D turn = Matrix2D::translate(pivotX, pivotY)
+                        .multiply(Matrix2D::rotate(kQuarterTurn))
+                        .multiply(Matrix2D::translate(-pivotX, -pivotY));
+    Matrix2D transform = box->world.multiply(turn);
+    paint_detail::addTextRun(out, pivotX, pivotY + ascent, fragment.height, fragment.width,
+                             fragment.text, spec, base, transform, clip, style, chain,
+                             viewportWidth, viewportHeight);
   }
 }
 
@@ -191,6 +216,13 @@ void paintBoxInner(const LayoutBox *box, DisplayList &out, const PaintClip &clip
       /* Drop shadows sit behind the box's own background but above earlier
        * siblings. */
       paint_detail::addBoxDropShadows(out, *box, *style, chain, own);
+      /* A backdrop filter samples everything painted before this box, so it is
+       * emitted before any of the box's own shapes. */
+      paint_detail::addBackdropFilter(out, *box, *style, own, viewportWidth, viewportHeight);
+      /* CSS `box-shadow` outsets paint behind the background too; inset ones
+       * paint above it. */
+      paint_detail::addBoxShadows(out, *box, *style, chain, own, false, viewportWidth,
+                                  viewportHeight);
       paint_detail::paintBackgrounds(out, *box, *style, chain, own, viewportWidth,
                                      viewportHeight);
       const Matrix2D &matrix = box->world;
@@ -210,6 +242,9 @@ void paintBoxInner(const LayoutBox *box, DisplayList &out, const PaintClip &clip
         paint_detail::addRectFiltered(out, box->x + box->width - right, box->y + top, right,
                                       inner_height, 0.0f, bc, own, matrix, chain);
       }
+      paint_detail::addBoxShadows(out, *box, *style, chain, own, true, viewportWidth,
+                                  viewportHeight);
+      paint_detail::addOutline(out, *box, *style, chain, own, viewportWidth, viewportHeight);
       if (box->is_canvas && box->canvas_id != 0 && box->content_width > 0.0f &&
           box->content_height > 0.0f) {
         PaintImage image;
@@ -361,6 +396,15 @@ std::string DisplayList::dump() const {
       text += prefix + "end-layer\n";
       continue;
     }
+    if (op.kind == PaintKind::Backdrop) {
+      const PaintBackdrop &backdrop = backdrops[op.index];
+      std::snprintf(buffer, sizeof(buffer),
+                    "backdrop x=%.1f y=%.1f w=%.1f h=%.1f r=%.1f blur=%.1f", backdrop.x,
+                    backdrop.y, backdrop.width, backdrop.height, backdrop.radius,
+                    backdrop.blur);
+      text += prefix + buffer + "\n";
+      continue;
+    }
     std::string suffix;
     if (op.kind == PaintKind::Rect) {
       suffix = transformSuffix(rects[op.index].transform);
@@ -382,12 +426,22 @@ std::string DisplayList::dump() const {
       suffix = transformSuffix(image.transform);
       if (image.gradient != nullptr) {
         const PaintGradient &gradient = *image.gradient;
-        std::snprintf(buffer, sizeof(buffer),
-                      "image x=%.1f y=%.1f w=%.1f h=%.1f gradient=%s center=%.1f,%.1f "
-                      "radius=%.1f,%.1f stops=",
-                      image.x, image.y, image.width, image.height,
-                      gradient.repeating ? "repeating-radial" : "radial", gradient.center_x,
-                      gradient.center_y, gradient.radius_x, gradient.radius_y);
+        const bool linear = gradient.kind == PaintGradient::Kind::Linear;
+        const char *kind = linear ? (gradient.repeating ? "repeating-linear" : "linear")
+                                  : (gradient.repeating ? "repeating-radial" : "radial");
+        if (linear) {
+          std::snprintf(buffer, sizeof(buffer),
+                        "image x=%.1f y=%.1f w=%.1f h=%.1f gradient=%s start=%.1f,%.1f "
+                        "dir=%.4f,%.4f length=%.1f stops=",
+                        image.x, image.y, image.width, image.height, kind, gradient.start_x,
+                        gradient.start_y, gradient.dir_x, gradient.dir_y, gradient.length);
+        } else {
+          std::snprintf(buffer, sizeof(buffer),
+                        "image x=%.1f y=%.1f w=%.1f h=%.1f gradient=%s center=%.1f,%.1f "
+                        "radius=%.1f,%.1f stops=",
+                        image.x, image.y, image.width, image.height, kind, gradient.center_x,
+                        gradient.center_y, gradient.radius_x, gradient.radius_y);
+        }
         text += prefix + buffer;
         for (size_t stop = 0; stop < gradient.stops.size(); stop++) {
           std::snprintf(buffer, sizeof(buffer), "%s%s@%.4f", stop == 0 ? "" : ",",
@@ -395,6 +449,10 @@ std::string DisplayList::dump() const {
                         gradient.stops[stop].offset);
           text += buffer;
         }
+      } else if (image.bitmap != nullptr) {
+        std::snprintf(buffer, sizeof(buffer),
+                      "image x=%.1f y=%.1f w=%.1f h=%.1f bitmap=%s", image.x, image.y,
+                      image.width, image.height, image.bitmap->key.c_str());
       } else if (image.media_id != 0) {
         std::snprintf(buffer, sizeof(buffer), "image x=%.1f y=%.1f w=%.1f h=%.1f media=%llu",
                       image.x, image.y, image.width, image.height,

package/runtime/ext_gui/paint.h

@@ -32,22 +32,35 @@ struct GradientStop {
   Color color;
 };
 
-/** A radial `background-image` layer resolved by the paint pass: the renderer
+/** A `background-image` gradient layer resolved by the paint pass: the renderer
  * rasterises it into one RGBA texture and draws that as a single image quad.
  *
  * Nesting translucent bands instead composites every band's alpha once per band
  * — each band covers the whole interior — so a vignette whose stops fade to
  * `transparent` turns into an opaque disc that hides the scene behind it.
- * Resolving the ramp per pixel composites it exactly once. */
+ * Resolving the ramp per pixel composites it exactly once, and it is the only
+ * way to draw a stop narrower than a band: a walk of solid rectangles either
+ * swallows a 1px divider line (it falls between two samples) or widens it into
+ * a block the width of a band. */
 struct PaintGradient {
+  enum class Kind { Radial, Linear };
+  Kind kind = Kind::Radial;
   std::vector<GradientStop> stops;
+  /* radial: the ending shape, box-local logical pixels. */
   /** Centre in box-local logical pixels; the drawn quad spans the whole box. */
   float center_x = 0.0f;
   float center_y = 0.0f;
   float radius_x = 0.0f;
   float radius_y = 0.0f;
-  /** `repeating-radial-gradient()`: the stop pattern restarts every `period`
-   * (the last stop's offset) instead of clamping at the outer ellipse. */
+  /* linear: `t` grows along the gradient line from `start_*` in the direction
+   * `(dir_x, dir_y)` over `length`; both box-local logical pixels. */
+  float start_x = 0.0f;
+  float start_y = 0.0f;
+  float dir_x = 1.0f;
+  float dir_y = 0.0f;
+  float length = 0.0f;
+  /** `repeating-*`: the stop pattern restarts every `period` (the last stop's
+   * offset) instead of clamping at the last stop. */
   bool repeating = false;
   float period = 1.0f;
   /** Identity of the ramp (stops and geometry) for the renderer's texture cache. */
@@ -81,6 +94,22 @@ struct PaintText {
   bool shadow = false;
 };
 
+/** A CPU-rasterised RGBA bitmap carried by a display-list image op. Shadows are
+ * painted as one pre-blurred texture rather than a stack of offset copies: a
+ * separable Gaussian on the mask is the CSS blur, and the shader only has to
+ * composite one quad. `scale` is bitmap pixels per logical pixel. */
+struct PaintBitmap {
+  int width = 0;
+  int height = 0;
+  float scale = 1.0f;
+  /** Logical offset of the bitmap's top-left from the shape's origin (a text
+   * run's start/baseline, or a box's top-left). */
+  float origin_x = 0.0f;
+  float origin_y = 0.0f;
+  std::string key;
+  std::vector<unsigned char> pixels;
+};
+
 /** An image to draw, scaled into the given rectangle (viewport-relative).
  * A non-zero `media_id` names a live `<video>` frame owned by the media
  * subsystem; a non-zero `canvas_id` names a live `<canvas>` bitmap owned by the
@@ -101,9 +130,13 @@ struct PaintImage {
   /** 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};
-  /** A `background-image` radial gradient: the renderer rasterises it into the
-   * quad instead of loading `src`/`svg`. Its stops already carry the colour
-   * functions of the filter chain; `tint` still carries brightness/opacity. */
+  /** A CPU-rasterised shadow mask (white RGB, coverage in alpha) drawn with
+   * `tint` as its colour. */
+  std::shared_ptr<const PaintBitmap> bitmap;
+  /** A `background-image` gradient (linear or radial): the renderer rasterises
+   * it into the quad instead of loading `src`/`svg`. Its stops already carry the
+   * colour functions of the filter chain; `tint` still carries
+   * brightness/opacity. */
   std::shared_ptr<const PaintGradient> gradient;
 };
 
@@ -136,7 +169,7 @@ struct PaintClip {
   int paths[2] = {-1, -1};
 };
 
-enum class PaintKind { Rect, Text, Image, LayerBegin, LayerEnd };
+enum class PaintKind { Rect, Text, Image, LayerBegin, LayerEnd, Backdrop };
 
 /** One `mix-blend-mode` compositing group. The ops between its `LayerBegin`
  * and `LayerEnd` markers are rendered to an offscreen texture and composited
@@ -145,6 +178,23 @@ struct PaintLayer {
   MixBlendMode blend = MixBlendMode::Normal;
 };
 
+/** One `backdrop-filter` application: the renderer snapshots the scene painted
+ * so far, applies the Gaussian blur / colour matrix to it, and composites the
+ * result back only inside the element's rounded border box. */
+struct PaintBackdrop {
+  float x = 0;
+  float y = 0;
+  float width = 0;
+  float height = 0;
+  float radius = 0;
+  /** Standard deviation of the Gaussian in logical pixels (0 = no blur). */
+  float blur = 0;
+  /** Combined colour filter, row-major 3x3 plus a per-channel offset. */
+  float color[9] = {1, 0, 0, 0, 1, 0, 0, 0, 1};
+  float offset[3] = {0, 0, 0};
+  float alpha = 1;
+};
+
 /** One entry in painter order: which kind of shape, its index in the matching
  * payload vector, and the clip in effect. */
 struct PaintOp {
@@ -164,6 +214,8 @@ struct DisplayList {
   std::vector<ClipPathGeometry> clip_paths;
   /** `mix-blend-mode` groups referenced by `LayerBegin` ops. */
   std::vector<PaintLayer> layers;
+  /** `backdrop-filter` regions referenced by `Backdrop` ops. */
+  std::vector<PaintBackdrop> backdrops;
 
   void clear() {
     rects.clear();
@@ -172,6 +224,7 @@ struct DisplayList {
     ops.clear();
     clip_paths.clear();
     layers.clear();
+    backdrops.clear();
   }
   bool empty() const { return rects.empty() && texts.empty() && images.empty(); }
   /** Human-readable dump, one shape per line, in painter order (diagnostics/tests). */