xbintsc 0.5.23 → 0.5.32

package/runtime/ext_gui/css_selector.cpp

@@ -72,6 +72,13 @@ class SelectorParser {
         }
         std::string name = xt_css_lower(readIdent(text, index));
         if (name.empty()) return false;
+        /* `::before`/`::after` are generated-content elements, not states. The
+         * single-colon spellings (`:before`) are the legacy equivalent. */
+        if (pseudoElement || name == "before" || name == "after") {
+          compound->pseudo_element = name;
+          any = true;
+          continue;
+        }
         if (!pseudoElement && *index < text.size() && text[*index] == '(') {
           int depth = 0;
           size_t start = *index;
@@ -192,6 +199,8 @@ class SelectorParser {
       if (!compound.id.empty()) ids++;
       classes += computeCompoundSpecificity(compound);
       if (!compound.tag.empty()) types++;
+      /* A pseudo-element counts like a type selector (CSS specificity). */
+      if (!compound.pseudo_element.empty()) types++;
     }
     return (ids << 20) | (classes << 10) | types;
   }

package/runtime/ext_gui/css_sheet.cpp

@@ -1,5 +1,9 @@
 /*
  * xbintsc GUI engine — CSS declaration and stylesheet parsing.
+ *
+ * At-rules are no longer all skipped: `@media` blocks are parsed recursively
+ * and each rule keeps its (possibly nested) query, which the cascade evaluates
+ * against the viewport. Every other at-rule is ignored with its block.
  */
 
 #include "css_internal.h"
@@ -41,6 +45,42 @@ size_t findTopLevel(const std::string &text, char needle, size_t from) {
   return std::string::npos;
 }
 
+/** The `}` matching the `{` at `open`, respecting strings and nested blocks. */
+size_t findBlockEnd(const std::string &text, size_t open) {
+  int depth = 0;
+  char quote = 0;
+  for (size_t i = open; i < text.size(); i++) {
+    char c = text[i];
+    if (quote != 0) {
+      if (c == quote) quote = 0;
+      continue;
+    }
+    if (c == '"' || c == '\'') quote = c;
+    else if (c == '{') depth++;
+    else if (c == '}') {
+      depth--;
+      if (depth == 0) return i;
+    }
+  }
+  return std::string::npos;
+}
+
+/** Join a nested `@media` prelude: distribute `inner` over an outer comma list. */
+std::string combineMedia(const std::string &outer, const std::string &inner) {
+  if (outer.empty()) return inner;
+  if (inner.empty()) return outer;
+  std::vector<std::string> outerParts = xt_css_split_commas(outer);
+  std::vector<std::string> innerParts = xt_css_split_commas(inner);
+  std::string combined;
+  for (const std::string &o : outerParts) {
+    for (const std::string &i : innerParts) {
+      if (!combined.empty()) combined += ", ";
+      combined += o + " and " + i;
+    }
+  }
+  return combined;
+}
+
 std::string stripImportant(std::string value, bool *important) {
   size_t pos = value.rfind('!');
   if (pos == std::string::npos) return value;
@@ -52,6 +92,54 @@ std::string stripImportant(std::string value, bool *important) {
   return value;
 }
 
+/** Parse one rule list, carrying the enclosing `@media` prelude. */
+void parseRules(const std::string &text, const std::string &media, int *order,
+                StyleSheet *sheet) {
+  size_t index = 0;
+  while (index < text.size()) {
+    while (index < text.size() && xt_is_css_space(text[index])) index++;
+    if (index >= text.size()) break;
+
+    if (text[index] == '@') {
+      size_t nameStart = index + 1;
+      size_t nameEnd = nameStart;
+      while (nameEnd < text.size() &&
+             (std::isalnum((unsigned char)text[nameEnd]) || text[nameEnd] == '-'))
+        nameEnd++;
+      std::string name = xt_css_lower(text.substr(nameStart, nameEnd - nameStart));
+      size_t brace = text.find('{', nameEnd);
+      size_t semi = text.find(';', nameEnd);
+      if (brace != std::string::npos && (semi == std::string::npos || brace < semi)) {
+        size_t close = findBlockEnd(text, brace);
+        if (close == std::string::npos) break;
+        if (name == "media") {
+          std::string query = xt_css_trim(text.substr(nameEnd, brace - nameEnd));
+          std::string nested = combineMedia(media, query);
+          parseRules(text.substr(brace + 1, close - brace - 1), nested, order, sheet);
+        }
+        /* Other block at-rules (`@supports`, `@keyframes`, `@font-face`, …) are
+         * not part of the engine's subset: ignore the whole block. */
+        index = close + 1;
+      } else {
+        index = (semi == std::string::npos) ? text.size() : semi + 1;
+      }
+      continue;
+    }
+
+    size_t brace = text.find('{', index);
+    if (brace == std::string::npos) break;
+    size_t close = findBlockEnd(text, brace);
+    if (close == std::string::npos) break;
+    Rule rule;
+    rule.selectors = xt_css_parse_selector_list(text.substr(index, brace - index));
+    rule.declarations = xt_css_parse_declarations(text.substr(brace + 1, close - brace - 1));
+    rule.order = (*order)++;
+    rule.media = media;
+    if (!rule.selectors.empty() && !rule.declarations.empty()) sheet->rules.push_back(std::move(rule));
+    index = close + 1;
+  }
+}
+
 }  // namespace
 
 std::vector<Declaration> xt_css_parse_declarations(const std::string &text) {
@@ -77,52 +165,8 @@ std::vector<Declaration> xt_css_parse_declarations(const std::string &text) {
 StyleSheet xt_css_parse_stylesheet(const std::string &text) {
   StyleSheet sheet;
   std::string clean = stripComments(text);
-  size_t index = 0;
   int order = 0;
-  while (index < clean.size()) {
-    while (index < clean.size() && xt_is_css_space(clean[index])) index++;
-    if (index >= clean.size()) break;
-    if (clean[index] == '@') {
-      size_t brace = clean.find('{', index);
-      size_t semi = clean.find(';', index);
-      if (brace != std::string::npos && (semi == std::string::npos || brace < semi)) {
-        int depth = 0;
-        size_t i = brace;
-        for (; i < clean.size(); i++) {
-          if (clean[i] == '{') depth++;
-          else if (clean[i] == '}') {
-            depth--;
-            if (depth == 0) break;
-          }
-        }
-        index = (i < clean.size()) ? i + 1 : clean.size();
-      } else {
-        index = (semi == std::string::npos) ? clean.size() : semi + 1;
-      }
-      continue;
-    }
-    size_t brace = clean.find('{', index);
-    if (brace == std::string::npos) break;
-    int depth = 0;
-    size_t close = std::string::npos;
-    for (size_t i = brace; i < clean.size(); i++) {
-      if (clean[i] == '{') depth++;
-      else if (clean[i] == '}') {
-        depth--;
-        if (depth == 0) {
-          close = i;
-          break;
-        }
-      }
-    }
-    if (close == std::string::npos) break;
-    Rule rule;
-    rule.selectors = xt_css_parse_selector_list(clean.substr(index, brace - index));
-    rule.declarations = xt_css_parse_declarations(clean.substr(brace + 1, close - brace - 1));
-    rule.order = order++;
-    if (!rule.selectors.empty() && !rule.declarations.empty()) sheet.rules.push_back(std::move(rule));
-    index = close + 1;
-  }
+  parseRules(clean, "", &order, &sheet);
   return sheet;
 }
 

package/runtime/ext_gui/document.cpp

@@ -47,7 +47,7 @@ void XtDocument::restyle(float viewportWidth, float viewportHeight) {
     MatchState state;
     state.hover = hover_;
     state.focus = focus_;
-    xt_style_compute(root_.get(), sheet_, styles_, viewportWidth, viewportHeight, state);
+    xt_style_compute(root_.get(), sheet_, styles_, viewportWidth, viewportHeight, state, &pseudos_);
     startTransitions();
     updateDisplay();
   }
@@ -124,6 +124,9 @@ void XtDocument::startTransitions() {
   for (auto &entry : styles_) {
     const Node *node = entry.first;
     const XtStyle &target = entry.second;
+    /* Generated boxes are rebuilt on every restyle; a transition keyed by one
+     * would address a node that no longer exists. */
+    if (node->is_pseudo) continue;
     if (target.transitions.empty()) continue;
     auto prev_it = display_.find(node);
     if (prev_it == display_.end()) continue;

package/runtime/ext_gui/document.h

@@ -118,6 +118,8 @@ class XtDocument {
   std::unique_ptr<Node> root_;
   /** Detached nodes (created or removed) stay alive here so handles remain valid. */
   std::unordered_map<const Node *, std::unique_ptr<Node>> detached_;
+  /** Synthetic `::before`/`::after` nodes for the current style generation. */
+  PseudoNodeSet pseudos_;
   bool dirty_ = false;
   StyleSheet sheet_;
   std::unordered_map<const Node *, XtStyle> styles_;   // target (cascade)

package/runtime/ext_gui/dom.h

@@ -18,6 +18,9 @@ namespace xtgui {
 
 enum class NodeType { Document, Element, Text };
 
+/** Which generated-content box a synthetic pseudo-element node represents. */
+enum class PseudoElement { None, Before, After };
+
 struct Attr {
   std::string name;
   std::string value;
@@ -32,6 +35,19 @@ struct Node {
   Node *parent = nullptr;
   std::vector<std::unique_ptr<Node>> children;
 
+  /* -- generated content (`::before` / `::after`) -------------------------
+   * A pseudo-element is a synthetic node owned by the document's per-restyle
+   * arena, not by the DOM tree: it is never in `children`, so traversal,
+   * queries, serialization and `elementIndex()` do not see it. `pseudo_origin`
+   * is the element the selector matched and whose computed style it inherits.
+   * `pseudo_before`/`pseudo_after` are transient pointers set by the cascade
+   * for the layout pass (the arena is rebuilt on every restyle). */
+  bool is_pseudo = false;
+  PseudoElement pseudo = PseudoElement::None;
+  const Node *pseudo_origin = nullptr;
+  Node *pseudo_before = nullptr;
+  Node *pseudo_after = nullptr;
+
   Node() = default;
   explicit Node(NodeType nodeType) : type(nodeType) {}
 

package/runtime/ext_gui/dom_api.cpp

@@ -52,11 +52,39 @@ XtGuiWindow *resolve_window(xt_value self) {
   return xt_gui_window_from_this(xt_object_get_cstr(self, "__xt_gui_win"));
 }
 
+/** Bind a pending handle to the node its key now finds: copy the slot
+ * bookkeeping of the canonical handle, then drop the pending marker so later
+ * resolutions take the normal path. */
+static xtgui::Node *bind_pending(XtGuiWindow *win, xt_value self, xtgui::Node *node) {
+  xt_value canonical = xt_gui_node_handle(win, node);
+  if (!XT_IS_OBJECT(canonical)) return nullptr;
+  xt_object_set(self, xt_string_from_cstr("__xt_gui_node"),
+                xt_object_get_cstr(canonical, "__xt_gui_node"));
+  xt_object_set(self, xt_string_from_cstr("__xt_gui_slot_gen"),
+                xt_object_get_cstr(canonical, "__xt_gui_slot_gen"));
+  xt_object_set(self, xt_string_from_cstr("__xt_gui_gen"),
+                xt_object_get_cstr(canonical, "__xt_gui_gen"));
+  xt_object_set(self, xt_string_from_cstr("__xt_gui_pending"), XT_UNDEFINED);
+  xt_gui_canvas_bind_pending(win, node, self);
+  return node;
+}
+
 /** Resolve a node handle to its node, or NULL when it is stale/foreign. */
 xtgui::Node *resolve_node(xt_value self, XtGuiWindow **winOut) {
   XtGuiWindow *win = resolve_window(self);
   if (winOut != nullptr) *winOut = win;
   if (win == nullptr || win->document == nullptr) return nullptr;
+  /* A pending handle names its node indirectly so that a module which queried
+   * `#id` before `loadHTML` ran still works: look the key up now and bind. */
+  xt_value pending = xt_object_get_cstr(self, "__xt_gui_pending");
+  if (XT_IS_NUMBER(pending)) {
+    std::string key = to_string_value(xt_object_get_cstr(self, "__xt_gui_pending_key"));
+    xtgui::Node *node = (int)xt_to_number(pending) == domapi::pending_by_id
+                            ? domapi::document_find_by_id(win, key)
+                            : domapi::document_query_selector(win, key);
+    if (node == nullptr) return nullptr;
+    return bind_pending(win, self, node);
+  }
   xt_value gen = xt_object_get_cstr(self, "__xt_gui_gen");
   if (!XT_IS_NUMBER(gen) || xt_to_number(gen) != win->doc_generation) return nullptr;
   if (value_truthy(xt_object_get_cstr(self, "__xt_gui_doc"))) {
@@ -121,6 +149,15 @@ void set_class_name(XtGuiWindow *win, xtgui::Node *node, const std::string &valu
   }
 }
 
+xt_value pending_handle(XtGuiWindow *win, int kind, const std::string &key) {
+  xt_value handle = xt_object_new_with_proto(node_proto());
+  if (win != nullptr) xt_object_set(handle, xt_string_from_cstr("__xt_gui_win"), win->object);
+  xt_object_set(handle, xt_string_from_cstr("__xt_gui_pending"), xt_number((double)kind));
+  xt_object_set(handle, xt_string_from_cstr("__xt_gui_pending_key"),
+                xt_string_from_cstr(key.c_str()));
+  return handle;
+}
+
 }  // namespace domapi
 
 xt_value xt_gui_node_handle(XtGuiWindow *win, const xtgui::Node *node) {

package/runtime/ext_gui/dom_api_canvas.cpp

@@ -58,8 +58,23 @@ METHOD(node_get_context) {
   std::string mode = string_arg(argc, argv, 0);
   XtGuiWindow *win = nullptr;
   xtgui::Node *node = resolve_node(self, &win);
-  if (node == nullptr || !node->isElement() || !node->isTag("canvas")) return XT_NULL;
+  if (mode == "webgl" || mode == "experimental-webgl" || mode == "webgl2") {
+    const bool webgl2 = mode == "webgl2";
+    if (node == nullptr) return XT_NULL;
+    if (!node->isElement() || !node->isTag("canvas")) return XT_NULL;
+    if (xt_gui_canvas_find(win, node) != nullptr) return XT_NULL;  // already a 2D canvas
+    xt_value cached = xt_object_get_cstr(self, "__xt_gui_gl");
+    if (XT_IS_OBJECT(cached)) {
+      const bool cached_webgl2 = value_truthy(xt_object_get_cstr(cached, "__xt_gl_webgl2"));
+      return cached_webgl2 == webgl2 ? cached : XT_NULL;
+    }
+    xtgui::WebGLContext *context = xt_gui_webgl_get(win, node, webgl2);
+    return webgl_context_handle(self, context);
+  }
   if (mode != "2d") return XT_NULL;
+  if (node == nullptr) return xt_canvas_pending_context(self, win);
+  if (!node->isElement() || !node->isTag("canvas")) return XT_NULL;
+  if (xt_gui_webgl_find(win, node) != nullptr) return XT_NULL;  // already a WebGL canvas
   xtgui::Canvas2D *canvas = xt_gui_canvas_get(win, node);
   if (canvas == nullptr) return XT_NULL;
   xt_value cached = xt_object_get_cstr(self, "__xt_gui_ctx");
@@ -72,84 +87,6 @@ METHOD(node_get_context) {
   return ctx;
 }
 
-METHOD(node_width_get) {
-  (void)env;
-  (void)argc;
-  (void)argv;
-  XtGuiWindow *win = nullptr;
-  xtgui::Node *node = resolve_node(self, &win);
-  if (node == nullptr || !node->isElement()) return xt_number(0);
-  if (node->isTag("canvas")) {
-    xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node);
-    if (canvas != nullptr) return xt_number(canvas->width());
-  }
-  const std::string *attr = node->attr("width");
-  float value = 0.0f;
-  if (attr != nullptr && xtgui::xt_css_parse_number(*attr, &value)) return xt_number(value);
-  return xt_number(0);
-}
-
-METHOD(node_width_set) {
-  (void)env;
-  XtGuiWindow *win = nullptr;
-  xtgui::Node *node = resolve_node(self, &win);
-  if (node == nullptr || !node->isElement()) return XT_UNDEFINED;
-  double value = number_arg(argc, argv, 0, 0.0);
-  if (node->isTag("canvas")) {
-    xtgui::Canvas2D *canvas = xt_gui_canvas_get(win, node);
-    if (canvas != nullptr) {
-      canvas->resize((int)value, canvas->height());
-      if (win != nullptr && win->document != nullptr) {
-        win->document->setCanvasInfo(node, (float)canvas->width(), (float)canvas->height(),
-                                     canvas->id());
-      }
-    }
-    return XT_UNDEFINED;
-  }
-  set_attribute(win, node, "width", std::to_string((long long)value));
-  return XT_UNDEFINED;
-}
-
-METHOD(node_height_get) {
-  (void)env;
-  (void)argc;
-  (void)argv;
-  XtGuiWindow *win = nullptr;
-  xtgui::Node *node = resolve_node(self, &win);
-  if (node == nullptr || !node->isElement()) return xt_number(0);
-  if (node->isTag("canvas")) {
-    xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node);
-    if (canvas != nullptr) return xt_number(canvas->height());
-  }
-  const std::string *attr = node->attr("height");
-  float value = 0.0f;
-  if (attr != nullptr && xtgui::xt_css_parse_number(*attr, &value)) return xt_number(value);
-  return xt_number(0);
-}
-
-METHOD(node_height_set) {
-  (void)env;
-  XtGuiWindow *win = nullptr;
-  xtgui::Node *node = resolve_node(self, &win);
-  if (node == nullptr || !node->isElement()) return XT_UNDEFINED;
-  double value = number_arg(argc, argv, 0, 0.0);
-  if (node->isTag("canvas")) {
-    xtgui::Canvas2D *canvas = xt_gui_canvas_get(win, node);
-    if (canvas != nullptr) {
-      canvas->resize(canvas->width(), (int)value);
-      if (win != nullptr && win->document != nullptr) {
-        win->document->setCanvasInfo(node, (float)canvas->width(), (float)canvas->height(),
-                                     canvas->id());
-      }
-    }
-    return XT_UNDEFINED;
-  }
-  set_attribute(win, node, "height", std::to_string((long long)value));
-  return XT_UNDEFINED;
-}
-
-/* -- state / style getters and setters ------------------------------------ */
-
 METHOD(canvas_get_canvas) {
   (void)env;
   (void)argc;
@@ -579,4 +516,4 @@ METHOD(canvas_get_image_data) {
 
 }  // namespace domapi
 
-#undef METHOD
+#undef METHOD

package/runtime/ext_gui/dom_api_canvas_extra.cpp

@@ -227,6 +227,135 @@ METHOD(canvas_get_transform) {
   return result;
 }
 
+METHOD(node_width_get) {
+  (void)env;
+  (void)argc;
+  (void)argv;
+  XtGuiWindow *win = nullptr;
+  xtgui::Node *node = resolve_node(self, &win);
+  if (node == nullptr || !node->isElement()) return xt_number(0);
+  if (node->isTag("canvas")) {
+    if (xtgui::WebGLContext *webgl = xt_gui_webgl_find(win, node)) {
+      return xt_number(webgl->width());
+    }
+    xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node);
+    if (canvas != nullptr) return xt_number(canvas->width());
+  }
+  const std::string *attr = node->attr("width");
+  float value = 0.0f;
+  if (attr != nullptr && xtgui::xt_css_parse_number(*attr, &value)) return xt_number(value);
+  /* A canvas with no context still reports the CSS default bitmap size. */
+  return xt_number(node->isTag("canvas") ? 300 : 0);
+}
+
+METHOD(node_width_set) {
+  (void)env;
+  XtGuiWindow *win = nullptr;
+  xtgui::Node *node = resolve_node(self, &win);
+  if (node == nullptr || !node->isElement()) return XT_UNDEFINED;
+  double value = canvas_number_arg(argc, argv, 0, 0.0);
+  if (node->isTag("canvas")) {
+    if (xtgui::WebGLContext *webgl = xt_gui_webgl_find(win, node)) {
+      webgl->resize((int)value, webgl->height());
+      /* A resize replaces the colour texture; the page has to re-upload the
+       * image op even when the box size did not change. */
+      mark_dirty(win);
+      if (win != nullptr && win->document != nullptr) {
+        win->document->setCanvasInfo(node, (float)webgl->width(), (float)webgl->height(),
+                                     webgl->id());
+      }
+      return XT_UNDEFINED;
+    }
+    xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node);
+    if (canvas != nullptr) {
+      canvas->resize((int)value, canvas->height());
+      if (win != nullptr && win->document != nullptr) {
+        win->document->setCanvasInfo(node, (float)canvas->width(), (float)canvas->height(),
+                                     canvas->id());
+      }
+      return XT_UNDEFINED;
+    }
+    /* No context yet: update the attribute so a later getContext uses it. */
+    int height = 150;
+    const std::string *height_attr = node->attr("height");
+    float parsed = 0.0f;
+    if (height_attr != nullptr && xtgui::xt_css_parse_number(*height_attr, &parsed)) {
+      height = (int)(parsed + 0.5f);
+    }
+    set_attribute(win, node, "width", std::to_string((long long)value));
+    if (win != nullptr && win->document != nullptr) {
+      win->document->setCanvasInfo(node, (float)value, (float)height, 0);
+    }
+    return XT_UNDEFINED;
+  }
+  set_attribute(win, node, "width", std::to_string((long long)value));
+  return XT_UNDEFINED;
+}
+
+METHOD(node_height_get) {
+  (void)env;
+  (void)argc;
+  (void)argv;
+  XtGuiWindow *win = nullptr;
+  xtgui::Node *node = resolve_node(self, &win);
+  if (node == nullptr || !node->isElement()) return xt_number(0);
+  if (node->isTag("canvas")) {
+    if (xtgui::WebGLContext *webgl = xt_gui_webgl_find(win, node)) {
+      return xt_number(webgl->height());
+    }
+    xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node);
+    if (canvas != nullptr) return xt_number(canvas->height());
+  }
+  const std::string *attr = node->attr("height");
+  float value = 0.0f;
+  if (attr != nullptr && xtgui::xt_css_parse_number(*attr, &value)) return xt_number(value);
+  return xt_number(node->isTag("canvas") ? 150 : 0);
+}
+
+METHOD(node_height_set) {
+  (void)env;
+  XtGuiWindow *win = nullptr;
+  xtgui::Node *node = resolve_node(self, &win);
+  if (node == nullptr || !node->isElement()) return XT_UNDEFINED;
+  double value = canvas_number_arg(argc, argv, 0, 0.0);
+  if (node->isTag("canvas")) {
+    if (xtgui::WebGLContext *webgl = xt_gui_webgl_find(win, node)) {
+      webgl->resize(webgl->width(), (int)value);
+      mark_dirty(win);
+      if (win != nullptr && win->document != nullptr) {
+        win->document->setCanvasInfo(node, (float)webgl->width(), (float)webgl->height(),
+                                     webgl->id());
+      }
+      return XT_UNDEFINED;
+    }
+    xtgui::Canvas2D *canvas = xt_gui_canvas_find(win, node);
+    if (canvas != nullptr) {
+      canvas->resize(canvas->width(), (int)value);
+      if (win != nullptr && win->document != nullptr) {
+        win->document->setCanvasInfo(node, (float)canvas->width(), (float)canvas->height(),
+                                     canvas->id());
+      }
+      return XT_UNDEFINED;
+    }
+    int width = 300;
+    const std::string *width_attr = node->attr("width");
+    float parsed = 0.0f;
+    if (width_attr != nullptr && xtgui::xt_css_parse_number(*width_attr, &parsed)) {
+      width = (int)(parsed + 0.5f);
+    }
+    set_attribute(win, node, "height", std::to_string((long long)value));
+    if (win != nullptr && win->document != nullptr) {
+      win->document->setCanvasInfo(node, (float)width, (float)value, 0);
+    }
+    return XT_UNDEFINED;
+  }
+  set_attribute(win, node, "height", std::to_string((long long)value));
+  return XT_UNDEFINED;
+}
+
+/* -- state / style getters and setters ------------------------------------ */
+
+
 }  // namespace domapi
 
-#undef METHOD
+#undef METHOD

package/runtime/ext_gui/dom_api_canvas_pending.cpp

@@ -0,0 +1,41 @@
+/*
+ * xbintsc GUI engine — 2D contexts for pending canvas handles.
+ *
+ * The gui extension hands out element handles before `loadHTML`; a module may
+ * call `getContext("2d")` in that window. Keep the bridge here so
+ * `dom_api_canvas.cpp` stays focused (and under the per-file line budget).
+ */
+#include <memory>
+#include <string>
+
+#include "canvas.h"
+#include "dom_api_internal.h"
+#include "gui_engine.h"
+
+namespace {
+
+bool is_pending_canvas(xt_value self) {
+  xt_value pending = xt_object_get_cstr(self, "__xt_gui_pending");
+  return XT_IS_NUMBER(pending);
+}
+
+}  // namespace
+
+namespace domapi {
+
+xt_value xt_canvas_pending_context(xt_value self, XtGuiWindow *win) {
+  if (!is_pending_canvas(self) || win == nullptr) return XT_NULL;
+  xt_value cached = xt_object_get_cstr(self, "__xt_gui_ctx");
+  if (XT_IS_OBJECT(cached)) return cached;
+  auto created = std::make_unique<xtgui::Canvas2D>(300, 150);
+  xtgui::Canvas2D *raw = created.get();
+  win->pending_canvases[raw->id()] = std::move(created);
+  xt_value ctx = xt_object_new_with_proto(canvas_proto());
+  xt_object_set(ctx, xt_string_from_cstr("__xt_gui_canvas"), xt_number((double)raw->id()));
+  xt_object_set(ctx, xt_string_from_cstr("__xt_gui_node"), self);
+  xt_object_set(self, xt_string_from_cstr("__xt_gui_ctx"), ctx);
+  xt_object_set(self, xt_string_from_cstr("__xt_gui_pending_canvas"), xt_number((double)raw->id()));
+  return ctx;
+}
+
+}  // namespace domapi