fix(pangocairo): 闸门改成 layout 自己的度量,而不是字体族数

`families > 0` 看着够用,其实不够,花了两轮 CI 才看清。同一个 CI runner 报告
四个字体族,然后把同一个 layout 量成 80x858545(一个进程)和 80x346398(另一
个)—— 在 100px surface 上都是荒谬的高度,因为那里的「四个字体族」是 fontconfig
有条目而背后没有可用字体。字形落到 surface 之外,墨迹数变成任意的:两个逐字节
相同绘制代码的孪生测试,一个 0 一个 116。

上一轮的修法(ink > 0 而不是 > 100)是必要但不充分的,底层原因相同:两者都在
**推断**机器的适用性,而不是**检验**它。

闸门现在是 w > 0 && h > 0 && h <= 100,不满足时运行会说出来 —— 「这条检查被跳
过了」和「文字画出来了」不能长得一样。两个测试现在都打印 layout 尺寸和字体族数,
于是孪生测试可以互相对照。

tarball 重切:sha256 → b470a658…,CN 容器 tag → 1.56.1-4。

Author: Sunrisepeak

.agents/docs/2026-08-30-graphics-stack-coverage-design.md

@@ -2100,11 +2100,23 @@ freedesktop.cairo  字形落下去的那张 surface
 
 **空白图片意味着其中之一没干活。**
 
-⭐ **而断言是 `ink > 0`,刻意不是一个调出来的数。** 早先写的是 `> 100`:在我这台
-有 184 个字体族的机器上得到 216 像素、**通过**;在只有 4 个字体族的 CI runner 上
-得到 72 像素、**失败** —— 因为几乎没有字体时「世界」渲染成豆腐块,墨迹更薄。
-那个阈值是**对机器的断言**,不是对这次构建的断言。和 gnome.gio 的 xdgmime 检查
-刻意不断言具体 MIME 是同一条理由。
+### ⭐ 这条断言错了两次才对
+
+**第一次:`drawn > 100`。** 在我这台 184 个字体族的机器上得到 216 像素、通过;
+在只有 4 个字体族的 CI runner 上得到 72、失败。**按开发机字体调出来的阈值是对
+机器的断言。** 改成 `> 0`。
+
+**第二次:用 `families > 0` 当闸门。** 也不够,而且花了两轮 CI 才看清。同一个
+runner 报告**四个字体族**,然后把同一个 layout 量成 `80x858545`(一个进程)和
+`80x346398`(另一个)—— 在 100px 的 surface 上都是荒谬的高度,因为那里的「四个
+字体族」是 fontconfig 有**条目**而背后没有可用字体。字形于是落到 surface 之外,
+墨迹数变成任意的:**两个逐字节相同绘制代码的孪生测试,一个 0 一个 116。**
+
+所以闸门现在是 **layout 自己的度量**(`w > 0 && h > 0 && h <= 100`)——
+**显式检验这台机器能不能渲染**,而不是从字体族数去推断。不满足时运行**会说出来**,
+因为「这条检查被跳过了」和「文字画出来了」不能长得一样。
+
+和 gnome.gio 的 xdgmime 检查刻意不断言具体 MIME 是同一条理由。
 
 ⚠️ 而且它**诚实地降级**:`freedesktop.fontconfig` 故意把运行期路径编译成空,
 所以没有 `FONTCONFIG_FILE` 的 runner 合法地找到零个字体族 —— 那就没有东西可画、

pkgs/p/gnome.pango.lua

@@ -84,14 +84,14 @@ package = {
             ["1.56.1"] = {
                 url = {
                     GLOBAL = "https://github.com/mcpplibs/pango/archive/refs/tags/1.56.1.tar.gz",
-                    -- ⚠️ The container tag is `1.56.1-3`, not `1.56.1`. gitcode
+                    -- ⚠️ The container tag is `1.56.1-4`, not `1.56.1`. gitcode
                     -- refuses to REPLACE an asset of the same name in an
                     -- existing release, so each corrected tarball needs a new
                     -- container tag while the PACKAGE version stays upstream's.
                     -- Verified byte-identical to the GLOBAL tag archive.
-                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1-3/pango-1.56.1.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1-4/pango-1.56.1.tar.gz",
                 },
-                sha256 = "d520087d521729124c43bf4b86ae90f4049f23f580e10cd6b1b186873b3d4ab0",
+                sha256 = "b470a658e05ef0e14d779bc852371ce52dd11efa76d10782347be40f1d63476b",
             },
         },
     },

pkgs/p/gnome.pangocairo.lua

@@ -90,14 +90,14 @@ package = {
             ["1.56.1"] = {
                 url = {
                     GLOBAL = "https://github.com/mcpplibs/pango/archive/refs/tags/1.56.1.tar.gz",
-                    -- ⚠️ The container tag is `1.56.1-3`, not `1.56.1`. gitcode
+                    -- ⚠️ The container tag is `1.56.1-4`, not `1.56.1`. gitcode
                     -- refuses to REPLACE an asset of the same name in an
                     -- existing release, so each corrected tarball needs a new
                     -- container tag while the PACKAGE version stays upstream's.
                     -- Verified byte-identical to the GLOBAL tag archive.
-                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1-3/pango-1.56.1.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1-4/pango-1.56.1.tar.gz",
                 },
-                sha256 = "d520087d521729124c43bf4b86ae90f4049f23f580e10cd6b1b186873b3d4ab0",
+                sha256 = "b470a658e05ef0e14d779bc852371ce52dd11efa76d10782347be40f1d63476b",
             },
         },
     },

pkgs/p/gnome.pangoft2.lua

@@ -68,14 +68,14 @@ package = {
             ["1.56.1"] = {
                 url = {
                     GLOBAL = "https://github.com/mcpplibs/pango/archive/refs/tags/1.56.1.tar.gz",
-                    -- ⚠️ The container tag is `1.56.1-3`, not `1.56.1`. gitcode
+                    -- ⚠️ The container tag is `1.56.1-4`, not `1.56.1`. gitcode
                     -- refuses to REPLACE an asset of the same name in an
                     -- existing release, so each corrected tarball needs a new
                     -- container tag while the PACKAGE version stays upstream's.
                     -- Verified byte-identical to the GLOBAL tag archive.
-                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1-3/pango-1.56.1.tar.gz",
+                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1-4/pango-1.56.1.tar.gz",
                 },
-                sha256 = "d520087d521729124c43bf4b86ae90f4049f23f580e10cd6b1b186873b3d4ab0",
+                sha256 = "b470a658e05ef0e14d779bc852371ce52dd11efa76d10782347be40f1d63476b",
             },
         },
     },

tests/examples/pangocairo/tests/module.cpp

@@ -60,7 +60,21 @@ int main()
     pango_layout_get_pixel_size(layout, &w, &h);
     g_print("   layout pixel size: %dx%d\n", w, h);
 
+    // ⚠️ THE SURFACE IS CHECKED, and its format is PRINTED. The first version
+    // of this test only counted pixels, so when it reported 0 on a runner
+    // where the header-route twin reported 116 there was nothing to go on:
+    // "0 pixels" is a symptom shared by "nothing was drawn", "the surface is
+    // in an error state" and "the pixel loop is reading the wrong bytes".
     cairo_surface_t *surf = cairo_image_surface_create(CAIRO_FORMAT_ARGB32, 400, 100);
+    g_print("   surface status=%d format=%d (CAIRO_FORMAT_ARGB32=%d)\n",
+            (int) cairo_surface_status(surf),
+            (int) cairo_image_surface_get_format(surf),
+            (int) CAIRO_FORMAT_ARGB32);
+    check(cairo_surface_status(surf) == CAIRO_STATUS_SUCCESS,
+          "the ARGB32 surface was created without error");
+    check(cairo_image_surface_get_format(surf) == CAIRO_FORMAT_ARGB32,
+          "…and the format it reports is the one that was asked for");
+
     cairo_t *cr = cairo_create(surf);
     cairo_set_source_rgb(cr, 0, 0, 0);
     cairo_move_to(cr, 10, 10);
@@ -69,6 +83,7 @@ int main()
 
     cairo_surface_flush(surf);
     const unsigned char *d = cairo_image_surface_get_data(surf);
+    check(d != nullptr, "the surface has readable pixel data");
     const int stride = cairo_image_surface_get_stride(surf);
     long drawn = 0;
     for (int y = 0; d && y < 100; ++y)

tests/examples/pangocairo/tests/pangocairo.cpp

@@ -127,24 +127,31 @@ int main()
     const long drawn = ink(surf);
     std::printf("   non-transparent pixels: %ld\n", drawn);
 
-    if (families > 0) {
+    // ⚠️ THE GUARD IS THE LAYOUT'S OWN METRICS, NOT THE FAMILY COUNT.
+    //
+    // `families > 0` looked like enough and is not. A CI runner reported FOUR
+    // families and measured this layout at 80x858545 — a nonsense height on a
+    // 100px surface, because "four families" there means fontconfig has
+    // entries but no usable font behind them. The glyphs then land off the
+    // surface and the ink count is arbitrary: 0 in one process and 116 in
+    // another, from byte-identical drawing code.
+    //
+    // An earlier version also asserted `drawn > 100`, which passed here (216
+    // pixels, 184 families) and failed there (72) — a threshold calibrated to
+    // the developer's font set is an assertion about the MACHINE. Ink is ink.
+    const bool usable = families > 0 && w > 0 && h > 0 && h <= 100;
+    if (usable) {
         // ⭐ THE WHOLE LINE, IN ONE ASSERTION.
-        check(w > 0 && h > 0, "the layout measured a non-empty box");
-        // ⚠️ `> 0`, NOT `> 100`. An earlier version used 100 and PASSED here
-        // (216 pixels, 184 font families) while FAILING on a CI runner with
-        // four families and 72 — because with almost no fonts "世界" renders
-        // as tofu boxes and the ink is thinner. The threshold was calibrated
-        // to the developer's font set, which makes it an assertion about the
-        // MACHINE rather than about this build. Ink is ink: any positive count
-        // proves all seven packages put pixels down.
         check(drawn > 0,
               "pango_cairo_show_layout put ink on the surface — seven packages");
     } else {
-        // Not a pass. The runner has no fonts, so the only real check could
-        // not run, and saying so is the point.
-        std::printf("   ⚠️  0 font families: this runner has no fonts, so the\n"
-                    "       rendering assertion was NOT run. That is a property\n"
-                    "       of the machine, not of this build.\n");
+        // Not a pass. The machine cannot render, so the only real check could
+        // not run, and saying so is the point: "it was skipped" and "it worked"
+        // must not look alike.
+        std::printf("   \342\232\240  no usable font (families=%d, layout %dx%d on a\n"
+                    "       100px surface): the rendering assertion was NOT run.\n"
+                    "       That is a property of this machine, not this build.\n",
+                    families, w, h);
         check(drawn >= 0, "the surface is readable (rendering check skipped)");
     }