xbintsc 0.3.49 → 0.3.65

package/runtime/ext_gui/layout_flex.cpp

@@ -19,9 +19,12 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
                  containerStyle.flex_direction == FlexDirection::ColumnReverse;
   float gap = px(containerStyle.gap, contentWidth, containerStyle.font_size, 0.0f);
 
+  /* An absolutely positioned child is out of flow: it takes no part in the flex
+   * algorithm and is placed against the container's padding box instead. */
   std::vector<LayoutBox *> items;
   for (const std::unique_ptr<LayoutBox> &child : container->children) {
-    if (child->display != Display::None) items.push_back(child.get());
+    if (child->display == Display::None || isAbsoluteChild(child.get())) continue;
+    items.push_back(child.get());
   }
   if (items.empty()) return 0;
   size_t count = items.size();
@@ -71,6 +74,7 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
     for (size_t i = 0; i < count; i++) {
       float contentW = mainSizes[i] - horizontalEdges(items[i]);
       if (contentW < 0) contentW = 0;
+      setContainingBlock(items[i], containingBlockAncestor(items[i]));
       layoutBlock(items[i], container->content_x, container->content_y, contentWidth,
                   definiteHeight, contentW);
       cross[i] = verticalEdges(items[i]) + items[i]->height;
@@ -98,8 +102,8 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
     for (size_t k = 0; k < count; k++) {
       size_t i = reverse ? (count - 1 - k) : k;
       float crossOffset = crossOffsetFor(containerStyle.align_items, crossSize, cross[i]);
-      float dx = cursor - items[i]->x;
-      float dy = container->content_y + crossOffset - items[i]->y;
+      float dx = cursor + items[i]->margin_left - items[i]->x;
+      float dy = container->content_y + crossOffset + items[i]->margin_top - items[i]->y;
       translate(items[i], dx, dy);
       cursor += mainSizes[i] + between;
     }
@@ -111,6 +115,7 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
   std::vector<float> outer(count, 0.0f);
   float sumBase = 0;
   for (size_t i = 0; i < count; i++) {
+    setContainingBlock(items[i], containingBlockAncestor(items[i]));
     layoutBlock(items[i], container->content_x, container->content_y, contentWidth, definiteHeight);
     outer[i] = verticalEdges(items[i]) + items[i]->height;
     sumBase += outer[i];
@@ -142,8 +147,11 @@ float Layouter::layoutFlex(LayoutBox *container, float contentWidth, float defin
   float cursor = container->content_y + offset;
   for (size_t k = 0; k < count; k++) {
     size_t i = reverse ? (count - 1 - k) : k;
-    float dx = container->content_x - items[i]->x;
-    float dy = cursor - items[i]->y;
+    float dx = container->content_x + items[i]->margin_left - items[i]->x;
+    /* Margins keep the item's outer box on the main axis, exactly like block
+     * flow — a negative `margin-top` pulls the item up instead of being
+     * silently dropped. */
+    float dy = cursor + items[i]->margin_top - items[i]->y;
     translate(items[i], dx, dy);
     cursor += mainSizes[i] + between;
   }

package/runtime/ext_gui/layout_flow.cpp

@@ -48,6 +48,8 @@ float Layouter::preferredContentWidth(const LayoutBox *box, float available) con
   float best = 0;
   for (const std::unique_ptr<LayoutBox> &child : box->children) {
     if (child->display == Display::None) continue;
+    /* Out-of-flow children do not contribute to the parent's intrinsic width. */
+    if (isAbsoluteChild(child.get())) continue;
     if (child->is_text) {
       best = std::max(best, textWidth(child->text, *child->style));
     } else {
@@ -91,18 +93,107 @@ void Layouter::resolveEdges(LayoutBox *box, float containingWidth) const {
   }
 }
 
+bool Layouter::establishesContainingBlock(const LayoutBox *box) {
+  return box->style != nullptr && box->style->position != Position::Static;
+}
+
+const LayoutBox *Layouter::containingBlockAncestor(const LayoutBox *box) const {
+  /* Absolute boxes resolve against the padding box of the nearest ancestor with
+   * `position != static`; when there is none, the caller falls back to the
+   * initial containing block (the viewport). */
+  for (const LayoutBox *ancestor = box; ancestor != nullptr; ancestor = ancestor->parent) {
+    if (establishesContainingBlock(ancestor)) return ancestor;
+  }
+  return nullptr;
+}
+
+void Layouter::setContainingBlock(LayoutBox *box, const LayoutBox *ancestor) const {
+  if (ancestor != nullptr) {
+    /* The padding box of the ancestor. Its height is only known once the
+     * ancestor's own layout has finished, which is why `publishContainingBlock`
+     * is called again at the end of `layoutBlock` for the box that owns it. */
+    box->cb_x = ancestor->content_x - ancestor->padding_left;
+    box->cb_y = ancestor->content_y - ancestor->padding_top;
+    box->cb_width = ancestor->padding_left + ancestor->content_width + ancestor->padding_right;
+    box->cb_height = ancestor->padding_top + ancestor->content_height + ancestor->padding_bottom;
+    return;
+  }
+  /* No positioned ancestor: the initial containing block is the viewport. */
+  box->cb_x = 0;
+  box->cb_y = 0;
+  box->cb_width = vw;
+  box->cb_height = vh;
+}
+
+void Layouter::publishContainingBlock(LayoutBox *box) const {
+  if (!establishesContainingBlock(box)) return;
+  for (const std::unique_ptr<LayoutBox> &child : box->children) setContainingBlock(child.get(), box);
+}
+
+void Layouter::applyPosition(LayoutBox *box) const {
+  if (box->style == nullptr) return;
+  const XtStyle &style = *box->style;
+  if (style.position == Position::Static) return;
+  float em = style.font_size;
+
+  if (style.position == Position::Relative) {
+    /* Relative positioning offsets the box (and its subtree) without changing
+     * the space it occupies in the flow. */
+    float dx = 0;
+    float dy = 0;
+    if (!isAuto(style.left)) dx = px(style.left, box->cb_width, em);
+    else if (!isAuto(style.right)) dx = -px(style.right, box->cb_width, em);
+    if (!isAuto(style.top)) dy = px(style.top, box->cb_height, em);
+    else if (!isAuto(style.bottom)) dy = -px(style.bottom, box->cb_height, em);
+    if (dx != 0 || dy != 0) translate(box, dx, dy);
+    return;
+  }
+
+  /* Absolute (and fixed, which resolves against the viewport): the static
+   * position stands in for every `auto` inset. */
+  float x = box->x;
+  float y = box->y;
+  if (!isAuto(style.left)) x = box->cb_x + px(style.left, box->cb_width, em) + box->margin_left;
+  else if (!isAuto(style.right)) {
+    x = box->cb_x + box->cb_width - px(style.right, box->cb_width, em) - box->margin_right - box->width;
+  }
+  if (!isAuto(style.top)) y = box->cb_y + px(style.top, box->cb_height, em) + box->margin_top;
+  else if (!isAuto(style.bottom)) {
+    y = box->cb_y + box->cb_height - px(style.bottom, box->cb_height, em) - box->margin_bottom - box->height;
+  }
+  translate(box, x - box->x, y - box->y);
+}
+
 float Layouter::layoutBlock(LayoutBox *box, float x, float y, float availableWidth,
                             float availableHeight, float forcedContentWidth,
-                            float forcedContentHeight) const {
+                            float forcedContentHeight, bool inFlow) const {
   const XtStyle &style = *box->style;
   float em = style.font_size;
   resolveEdges(box, availableWidth);
 
   float contentWidth;
+  bool outOfFlow = style.position == Position::Absolute || style.position == Position::Fixed;
   if (forcedContentWidth >= 0) {
     contentWidth = forcedContentWidth;
   } else if (isAuto(style.width)) {
-    contentWidth = availableWidth - horizontalEdges(box);
+    if (outOfFlow && !isAuto(style.left) && !isAuto(style.right)) {
+      /* Both horizontal insets are set, so `auto` fills the space between them
+       * (the padding box of the containing block). */
+      contentWidth = box->cb_width - horizontalEdges(box) - px(style.left, box->cb_width, em) -
+                     px(style.right, box->cb_width, em);
+      if (contentWidth < 0) contentWidth = 0;
+    } else if (outOfFlow) {
+      /* An out-of-flow box does not fill its containing block: an `auto` width
+       * is shrink-to-fit — its preferred width, capped by the space available
+       * (the containing block's width, not the parent's content box, because an
+       * absolute box is laid out against the former). */
+      float available = box->cb_width - horizontalEdges(box);
+      float preferred = preferredContentWidth(box, availableWidth);
+      contentWidth = preferred < available ? preferred : available;
+      if (contentWidth < 0) contentWidth = 0;
+    } else {
+      contentWidth = availableWidth - horizontalEdges(box);
+    }
   } else {
     contentWidth = px(style.width, availableWidth, em);
   }
@@ -142,9 +233,32 @@ float Layouter::layoutBlock(LayoutBox *box, float x, float y, float availableWid
   box->height =
       box->border_top + box->padding_top + contentHeight + box->padding_bottom + box->border_bottom;
   box->baseline = box->height;
+  /* Now that this box has its final size, its padding box is the containing
+   * block its own children resolve against — and only now can an out-of-flow
+   * child be placed with `bottom`/`right`. */
+  publishContainingBlock(box);
+  layoutAbsoluteChildren(box, contentWidth, availableHeight);
+  applyPosition(box);
+  /* An absolutely positioned box consumes no space in its parent's flow. */
+  if (!inFlow) return 0;
   return box->margin_top + box->height + box->margin_bottom;
 }
 
+bool Layouter::isAbsoluteChild(const LayoutBox *box) {
+  return box->style != nullptr && (box->style->position == Position::Absolute ||
+                                   box->style->position == Position::Fixed);
+}
+
+void Layouter::layoutAbsoluteChildren(LayoutBox *block, float contentWidth,
+                                      float availableHeight) const {
+  for (const std::unique_ptr<LayoutBox> &child : block->children) {
+    if (child->display == Display::None || !isAbsoluteChild(child.get())) continue;
+    setContainingBlock(child.get(), block);
+    layoutBlock(child.get(), block->content_x, block->content_y, contentWidth, availableHeight, -1,
+                -1, false);
+  }
+}
+
 float Layouter::layoutChildren(LayoutBox *block, float contentWidth, float availableHeight,
                                float definiteHeight) const {
   if (block->style->display == Display::Flex)
@@ -155,14 +269,30 @@ float Layouter::layoutChildren(LayoutBox *block, float contentWidth, float avail
   std::vector<LayoutBox *> inlineRun;
   auto flush = [&]() {
     if (inlineRun.empty()) return;
-    y += layoutInlineRun(block, inlineRun, contentWidth, y);
+    /* Source whitespace between block boxes collapses away (HTML's model), so a
+     * run that carries no visible content produces no line at all. */
+    bool visible = false;
+    for (LayoutBox *box : inlineRun) {
+      if (!isCollapsibleText(box)) {
+        visible = true;
+        break;
+      }
+    }
+    if (visible) y += layoutInlineRun(block, inlineRun, contentWidth, y);
     inlineRun.clear();
   };
   for (const std::unique_ptr<LayoutBox> &child : block->children) {
     Display display = child->display;
     if (display == Display::None) continue;
-    if (display == Display::Block || display == Display::ListItem || display == Display::Flex) {
+    if (isAbsoluteChild(child.get())) {
+      /* Out of flow: `layoutAbsoluteChildren` places it once this block knows
+       * its own size. */
+      continue;
+    }
+    if (display == Display::Block || display == Display::ListItem || display == Display::Flex ||
+        child->style == nullptr) {
       flush();
+      setContainingBlock(child.get(), containingBlockAncestor(block));
       y += layoutBlock(child.get(), block->content_x, y, contentWidth, availableHeight);
     } else {
       inlineRun.push_back(child.get());

package/runtime/ext_gui/layout_flow_internal.h

@@ -62,6 +62,17 @@ inline bool isAuto(const Length &length) {
   return length.unit == Unit::Auto || length.unit == Unit::Invalid || length.unit == Unit::None;
 }
 
+/** True for a text node that holds nothing but HTML source whitespace. HTML
+ * collapses those away between block-level boxes, which is what keeps a
+ * document's indentation from becoming part of the page (the browser model). */
+inline bool isCollapsibleText(const LayoutBox *box) {
+  if (!box->is_text) return false;
+  for (char c : box->text) {
+    if (c != ' ' && c != '\t' && c != '\n' && c != '\r') return false;
+  }
+  return true;
+}
+
 /* Per-character advance as a fraction of the font size is no longer needed
  * here: text metrics come from the shaping stack (see `text.h`). */
 
@@ -117,14 +128,42 @@ struct Layouter {
 
   void resolveEdges(LayoutBox *box, float containingWidth) const;
 
-  /** Lay out `box` at (x, y) and return its outer height (margins included). */
+  /** Lay out `box` at (x, y) and return its outer height (margins included).
+   * `inFlow` is false for an absolutely positioned child: it is still laid out,
+   * but the caller ignores the returned height (it is out of flow). */
   float layoutBlock(LayoutBox *box, float x, float y, float availableWidth, float availableHeight,
-                    float forcedContentWidth = -1, float forcedContentHeight = -1) const;
+                    float forcedContentWidth = -1, float forcedContentHeight = -1,
+                    bool inFlow = true) const;
 
   /** Lay out the children of `block`; returns the used content height. */
   float layoutChildren(LayoutBox *block, float contentWidth, float availableHeight,
                        float definiteHeight) const;
 
+  /** Lay out the absolutely positioned children of `block`. Called once the
+   * block has its final size, because those children resolve `bottom`/`right`
+   * against its padding box. */
+  void layoutAbsoluteChildren(LayoutBox *block, float contentWidth, float availableHeight) const;
+
+  /** True when `box` establishes a containing block for absolute descendants. */
+  static bool establishesContainingBlock(const LayoutBox *box);
+
+  /** True for an out-of-flow child (`position: absolute` or `fixed`). */
+  static bool isAbsoluteChild(const LayoutBox *box);
+
+  /** Nearest ancestor (or `box` itself) that is a containing block, else null. */
+  const LayoutBox *containingBlockAncestor(const LayoutBox *box) const;
+
+  /** Re-publish the containing block of `box`'s children once `box` has its own
+   * final size (an absolute child resolves `bottom`/`right` against it). */
+  void publishContainingBlock(LayoutBox *box) const;
+
+  /** Publish `box`'s padding box as the containing block for absolute
+   * descendants of the nearest positioned ancestor (null means the viewport). */
+  void setContainingBlock(LayoutBox *box, const LayoutBox *ancestor) const;
+
+  /** Resolve the static/relative/absolute offsets of an already laid-out box. */
+  void applyPosition(LayoutBox *box) const;
+
   void flattenInline(LayoutBox *box, float contentWidth, std::vector<InlineItem> &out) const;
 
   void computeInlineGeometry(LayoutBox *box) const;

package/runtime/ext_gui/layout_inline.cpp

@@ -48,6 +48,7 @@ void Layouter::flattenInline(LayoutBox *box, float contentWidth,
   if (box->display == Display::InlineBlock) {
     float available = contentWidth;
     float intrinsic = preferredContentWidth(box, available);
+    setContainingBlock(box, containingBlockAncestor(box));
     layoutBlock(box, 0, 0, available, -1, intrinsic);
     InlineItem item;
     item.box = box;
@@ -163,9 +164,16 @@ float Layouter::layoutInlineRun(LayoutBox *container, const std::vector<LayoutBo
     }
     for (InlineItem *item : current) {
       if (item->atomic) {
-        float dx = x + item->box->margin_left - item->box->x;
-        float dy = cursorY + item->box->margin_top - item->box->y;
-        translate(item->box, dx, dy);
+        /* An out-of-flow item was already placed against its containing block by
+         * `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;
+          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. */
+          applyPosition(item->box);
+        }
       } else {
         item->box->fragments.push_back({x, cursorY, item->width, height, item->text});
       }

package/runtime/ext_gui/paint.cpp

@@ -67,6 +67,12 @@ void paintBox(const LayoutBox *box, DisplayList &out) {
   if (box == nullptr) return;
   const XtStyle *style = box->style;
 
+  /* A fully transparent box paints nothing — not itself, and not its subtree.
+   * `opacity` is otherwise unsupported: a shape carries its colour's alpha only,
+   * so a partly transparent box (an `opacity` transition mid-flight, say) is
+   * still painted opaque. */
+  if (style != nullptr && style->opacity <= 0.0f) return;
+
   if (style != nullptr && box->display != Display::None) {
     if (box->is_text) {
       addTextRuns(box, *style, out);

package/runtime/ext_gui/script.cpp

@@ -15,8 +15,11 @@
 #include <unordered_map>
 #include <vector>
 
-/** Script id -> AOT-compiled function value. Lives for the whole process (the
- * runtime arena never reclaims, so storing `xt_value`s is safe). */
+/** Script id -> AOT-compiled function value. Lives for the whole process. The
+ * runtime collector is a mark-sweep over the heap, so these values are only
+ * safe while a root provider keeps them reachable — `xt_gui_script_gc_scan`
+ * below does that (without it a collection frees everything the script
+ * captured and the first frame after it crashes). */
 static std::unordered_map<std::string, xt_value> &script_registry() {
   static std::unordered_map<std::string, xt_value> registry;
   return registry;
@@ -31,9 +34,16 @@ extern "C" xt_value xt_register_script(int32_t argc, xt_value *argv) {
       script_registry()[std::string(id)] = fn;
     }
   }
+  /* Registration is idempotent; do it on first use so a program that never
+   * opens a window still keeps its scripts alive across a collection. */
+  xt_gc_register_root_provider(xt_gui_script_gc_scan);
   return XT_UNDEFINED;
 }
 
+void xt_gui_script_gc_scan(void) {
+  for (const auto &entry : script_registry()) xt_gc_mark_value(entry.second);
+}
+
 /** Collect `data-xt-id` markers from `<script>` elements, in document order. */
 static void collect_script_ids(const xtgui::Node *node, std::vector<std::string> &ids) {
   if (node == nullptr) return;

package/runtime/ext_gui/text.cpp

@@ -46,10 +46,21 @@ namespace {
 const char *const kSansCandidates[] = {
     /* Explicit override wins (also checked per family class below). */
     nullptr,
+    /* Fonts with CJK coverage come first: the default face is a single face, so
+     * it has to be able to render Chinese/Japanese/Korean text as well as
+     * Latin (see "Implemented text" in doc/gui.md). */
+    "C:\\Windows\\Fonts\\msyh.ttc",      /* Microsoft YaHei (Win 8.1+) */
+    "C:\\Windows\\Fonts\\msyh.ttf",      /* Microsoft YaHei (Win 7) */
+    "C:\\Windows\\Fonts\\Deng.ttf",      /* DengXian */
+    "C:\\Windows\\Fonts\\simsun.ttc",    /* SimSun */
+    "/System/Library/Fonts/PingFang.ttc",
+    "/System/Library/Fonts/STHeiti Light.ttc",
     "/System/Library/Fonts/Helvetica.ttc",
     "/System/Library/Fonts/Supplemental/Arial.ttf",
     "/System/Library/Fonts/Supplemental/Verdana.ttf",
     "/Library/Fonts/Arial.ttf",
+    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
+    "/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
     "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
     "/usr/share/fonts/truetype/liberation/LiberationSans-Regular.ttf",
     "/usr/share/fonts/TTF/DejaVuSans.ttf",
@@ -60,10 +71,13 @@ const char *const kSansCandidates[] = {
 
 const char *const kMonoCandidates[] = {
     nullptr,
+    "C:\\Windows\\Fonts\\msyh.ttc",      /* CJK-capable fallback (see above) */
+    "/System/Library/Fonts/PingFang.ttc",
     "/System/Library/Fonts/Menlo.ttc",
     "/System/Library/Fonts/Supplemental/Courier New.ttf",
     "/System/Library/Fonts/Courier.ttc",
     "/Library/Fonts/Courier New.ttf",
+    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
     "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
     "/usr/share/fonts/truetype/liberation/LiberationMono-Regular.ttf",
     "/usr/share/fonts/TTF/DejaVuSansMono.ttf",

package/runtime/ext_gui/window.cpp

@@ -283,6 +283,28 @@ static xt_value win_is_open(xt_value self, xt_value env, int32_t argc, xt_value
   return (win != NULL && win->open) ? XT_TRUE : XT_FALSE;
 }
 
+/** Web 'window.closed': true once the window has been closed. The browser
+ * spelling of 'isOpen()', so a document can stop its frame loop with
+ * 'if (window.closed) return;' in every host. */
+static xt_value win_closed_get(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
+  (void)env;
+  (void)argc;
+  (void)argv;
+  XtGuiWindow *win = xt_gui_window_from_this(self);
+  return (win != NULL && win->open) ? XT_FALSE : XT_TRUE;
+}
+
+/** `/driver`: which SDL_GPU backend the device is running (`"vulkan"`,
+ * `"direct3d12"`, `"metal"`, …). The engine asks SDL for the best available
+ * one, so this is how a program (or a test) confirms the path in use. */
+static xt_value win_driver(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
+  (void)self;
+  (void)env;
+  (void)argc;
+  (void)argv;
+  return xt_string_from_cstr(xt_gui_driver());
+}
+
 /** `requestAnimationFrame(fn)` -> id. The callback runs once on the next frame
  * with the frame timestamp (ms) as its only argument. */
 static xt_value win_request_animation_frame(xt_value self, xt_value env, int32_t argc,
@@ -355,6 +377,22 @@ static xt_value win_off(xt_value self, xt_value env, int32_t argc, xt_value *arg
   return self;
 }
 
+/** Web spelling of 'on': 'window.addEventListener(type, fn, options?)'. The
+ * optional 'options' argument ('capture'/'once') is accepted and ignored —
+ * window-level delivery has no capture phase — so a document written against
+ * the browser API compiles and behaves the same here. */
+static xt_value win_add_event_listener(xt_value self, xt_value env, int32_t argc, xt_value *argv) {
+  win_on(self, env, argc, argv);
+  return XT_UNDEFINED;
+}
+
+/** Web spelling of 'off': 'window.removeEventListener(type, fn, options?)'. */
+static xt_value win_remove_event_listener(xt_value self, xt_value env, int32_t argc,
+                                          xt_value *argv) {
+  win_off(self, env, argc, argv);
+  return XT_UNDEFINED;
+}
+
 /* -- input diagnostics ---------------------------------------------------- */
 
 static double xt_gui_number_or(xt_value value, double fallback) {
@@ -455,10 +493,16 @@ xt_value xt_gui_window_proto(void) {
   define_method(proto, "fontMetrics", (void *)win_font_metrics);
   define_method(proto, "close", (void *)win_close);
   define_method(proto, "isOpen", (void *)win_is_open);
+  define_getter(proto, "closed", (void *)win_closed_get);
+  define_method(proto, "driver", (void *)win_driver);
   define_method(proto, "requestAnimationFrame", (void *)win_request_animation_frame);
   define_method(proto, "cancelAnimationFrame", (void *)win_cancel_animation_frame);
   define_method(proto, "on", (void *)win_on);
   define_method(proto, "off", (void *)win_off);
+  /* Web spellings, so a document written against the browser API runs
+   * unchanged under the engine. */
+  define_method(proto, "addEventListener", (void *)win_add_event_listener);
+  define_method(proto, "removeEventListener", (void *)win_remove_event_listener);
   define_method(proto, "hitTest", (void *)win_hit_test);
   define_method(proto, "sendEvent", (void *)win_send_event);
   g_window_proto = proto;

package/runtime/rt.h

@@ -371,6 +371,16 @@ size_t xt_heap_allocations(void);
  */
 void xt_gc_add_root(xt_value *slot);
 void xt_gc_add_root_range(xt_value *base, size_t count);
+/**
+ * Register a provider that marks a subsystem's live set when the values are
+ * not reachable through value slots (the event loop's timers, a promise
+ * microtask queue, an extension that caches values in its own containers).
+ * Providers run during every collection and registration is idempotent.
+ */
+void xt_gc_register_root_provider(void (*provider)(void));
+/** Mark `value` (and everything reachable from it) as live. Root providers use
+ * this; the collector also marks explicitly registered slots and the C stack. */
+void xt_gc_mark_value(xt_value value);
 
 #ifdef __cplusplus
 }

package/runtime/xt_io/console.inc

@@ -38,6 +38,11 @@ xt_value xt_console_assert(int32_t argc, xt_value *argv) {
 static char *xt_console_labels[XT_CONSOLE_MAX_LABELS];
 static long xt_console_counts[XT_CONSOLE_MAX_LABELS];
 static clock_t xt_console_timers[XT_CONSOLE_MAX_LABELS];
+/* A running timer is tracked by its own flag: clock() legitimately returns 0
+   (notably on Windows, where its resolution is one millisecond and a process
+   started less than a millisecond ago reports 0), so the timestamp itself
+   cannot serve as the "no timer running" sentinel. */
+static unsigned char xt_console_timer_active[XT_CONSOLE_MAX_LABELS];
 static int xt_console_label_count = 0;
 static int xt_console_depth = 0;
 
@@ -51,6 +56,7 @@ static int xt_console_find_label(const char *label) {
   memcpy(xt_console_labels[index], label, strlen(label) + 1);
   xt_console_counts[index] = 0;
   xt_console_timers[index] = 0;
+  xt_console_timer_active[index] = 0;
   return index;
 }
 
@@ -96,14 +102,17 @@ xt_value xt_console_table(int32_t argc, xt_value *argv) {
 xt_value xt_console_time(int32_t argc, xt_value *argv) {
   const char *label = xt_console_label(argc, argv);
   int index = xt_console_find_label(label ? label : "default");
-  if (index >= 0) xt_console_timers[index] = clock();
+  if (index >= 0) {
+    xt_console_timers[index] = clock();
+    xt_console_timer_active[index] = 1;
+  }
   return XT_UNDEFINED;
 }
 
 xt_value xt_console_time_log(int32_t argc, xt_value *argv) {
   const char *label = xt_console_label(argc, argv);
   int index = xt_console_find_label(label ? label : "default");
-  if (index >= 0 && xt_console_timers[index] != 0) {
+  if (index >= 0 && xt_console_timer_active[index]) {
     double ms = (double)(clock() - xt_console_timers[index]) * 1000.0 / CLOCKS_PER_SEC;
     printf("%s: %.3fms\n", xt_console_labels[index], ms);
   }
@@ -114,6 +123,9 @@ xt_value xt_console_time_end(int32_t argc, xt_value *argv) {
   xt_console_time_log(argc, argv);
   const char *label = xt_console_label(argc, argv);
   int index = xt_console_find_label(label ? label : "default");
-  if (index >= 0) xt_console_timers[index] = 0;
+  if (index >= 0) {
+    xt_console_timers[index] = 0;
+    xt_console_timer_active[index] = 0;
+  }
   return XT_UNDEFINED;
 }

package/src/driver/compiler.ts

@@ -23,6 +23,7 @@ import { findRuntimeLibrary } from "./runtime-lib.js";
 import { resolveToolchain } from "./toolchain-provider.js";
 import { ensureIconObject, readIcon, EMPTY_ICON, IconError, type IconInfo } from "./icon.js";
 import { ensureWindowsIconResource, resolveResourceCompiler } from "./win-icon.js";
+import { ensureWindowsEntryObject } from "./win-entry.js";
 import { bundlePathFor, packageMacApp } from "./mac-bundle.js";
 import type { AppConfig } from "./config.js";
 import {
@@ -295,6 +296,18 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     toolchain.env,
   );
 
+  /* On Windows a GUI program links as a **Windows-subsystem** executable, so
+   * launching it does not flash a console window. That subsystem's C runtime
+   * wants `WinMain`, so a tiny shim object bridges it to the runtime's `main`.
+   * `app.console: true` keeps the console subsystem instead (useful while
+   * debugging, because stdout and stderr only exist there). Other platforms
+   * have no equivalent. */
+  const windowsSubsystem = process.platform === "win32" && registry.has("gui") && app.console !== true;
+  const consoleSubsystem = windowsSubsystem ? ["-Wl,/SUBSYSTEM:WINDOWS"] : [];
+  const entryObject = windowsSubsystem
+    ? ensureWindowsEntryObject(runner, clang, cacheDir, toolchain.env)
+    : undefined;
+
   const iconObjects: string[] = [];
   // The GUI extension references the icon symbols unconditionally, so a GUI
   // program gets an (empty) icon object even with no icon configured.
@@ -320,12 +333,24 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   link(runner, {
     clang,
-    objectPaths: [objectPath, ...runtimeObjects, ...extensionObjects, ...nativeObjects, ...iconObjects],
+    objectPaths: [
+      objectPath,
+      ...runtimeObjects,
+      ...extensionObjects,
+      ...nativeObjects,
+      ...(entryObject !== undefined ? [entryObject] : []),
+      ...iconObjects,
+    ],
     outputPath,
     linkerFlags: [
       ...toolchain.linkerArgs,
       ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm"]),
       ...registry.linkerFlags(),
+      /* A GUI program is a Windows-subsystem executable: no console window is
+       * created when it is launched. Console output (stdout/stderr) is lost in
+       * that subsystem, so a program that wants to report things opts back in
+       * with `app.console: true`. */
+      ...consoleSubsystem,
     ],
     optimize,
     env: toolchain.env,

package/src/driver/config.ts

@@ -24,6 +24,13 @@ export interface AppConfig {
   /** macOS only: produce a `<name>.app` bundle. */
   readonly bundle?: boolean;
   readonly bundleId?: string;
+  /**
+   * Windows only: link as a console-subsystem executable instead of the default
+   * Windows subsystem. A GUI program defaults to the Windows subsystem so that
+   * launching it does not open a console window — which also means stdout and
+   * stderr go nowhere, so set this while debugging a GUI program.
+   */
+  readonly console?: boolean;
 }
 
 /** The on-disk schema of `xbintsc.config.json`. Every field is optional. */