@@ -1,6 +1,6 @@
 # mcpp 图形栈:从「能跑通」到「能开发」的覆盖面设计
 
-Date: 2026-08-30 · 前置:[`2026-08-30-gbm-cross-repo-closed-loop-plan.md`](2026-08-30-gbm-cross-repo-closed-loop-plan.md) §19/§20 · **状态:已实现并闭环验证(v1.8,§11 总账 / §14 fork 规范 / §18 八角度复核 / §19 合成器闸门与 GObject 栈,含沙箱实测 · §20 gio 与一次被推翻的判断 · §21 namespace 是契约:四个成员补上 import)**
+Date: 2026-08-30 · 前置:[`2026-08-30-gbm-cross-repo-closed-loop-plan.md`](2026-08-30-gbm-cross-repo-closed-loop-plan.md) §19/§20 · **状态:已实现并闭环验证(v1.9,§11 总账 / §14 fork 规范 / §18 八角度复核 / §19 合成器闸门与 GObject 栈,含沙箱实测 · §20 gio 与一次被推翻的判断 · §21 namespace 是契约 · §22 pango:文本排版接上了)**
 
 ## 0. 这份文档解决什么
 
@@ -2047,3 +2047,112 @@ error: use of undeclared identifier 'G_UNICODE_OTHER_LETTER'
 
 CI 加了导出数下限(glib ≥1900、gio ≥2400)、pango 那三个符号按名断言、一个
 枚举量、以及转出链。**塌陷是静默的,所以必须有东西去数。**
+
+---
+
+## 22. pango:文本排版那条线接上了(2026-08-31)
+
+§19.7 说 pango 被 gio 挡住。gio 到位(§20),闸门就开了。
+
+### 22.1 三个成员,和 fork 的判据
+
+| 成员 | 是什么 | 模块导出 |
+|---|---|---|
+| `gnome.pango` | 分项、bidi、断行、markup | 851 |
+| `gnome.pangoft2` | fontconfig 选文件,FreeType 出字形 | 88 |
+| `gnome.pangocairo` | cairo 后端 —— `pango_cairo_show_layout` | 284 |
+
+判据仍是**生成器,不是行数**。pango 有三个,本 fork 再加一个:
+
+```
+configure_file         pango-features.h.meson -> pango-features.h
+configure_file         (没有输入模板)          -> config.h
+gobject/glib-mkenums   pango_headers          -> pango-enum-types.{h,c}   27 个
+(fork 自己的)          gen_module()           -> 三个 .cppm
+```
+
+⚠️ **`config.h` 是特殊的一个**:上游写的是
+`configure_file(output: 'config.h', configuration: pango_conf)`,**没有
+`input:`** —— meson 按 key 逐条发 `#define`,树里根本没有可替换的模板。所以这个
+文件必须**写出来**,里面每个值都是本包做的**决定**。其中两个是算术而非选择:
+
+```
+PANGO_BINARY_AGE    = minor * 100 + micro      # 5601
+PANGO_INTERFACE_AGE = minor 为奇数 ? 0 : micro  # 1
+```
+
+`pango_version_check()` 读第一个,所以写错不会构建失败,而是让一次**正确的版本
+比较给出错误答案**。测试两个方向都断言了。
+
+### 22.2 ⭐ 唯一一个产出像素的测试
+
+`pangocairo` 把 `"Hello 世界"` 画到 ARGB32 surface 上,数非透明像素:**1,492**。
+走到那一步要七个包:
+
+```
+gnome.pango        分项、bidi、断行
+gnome.pangoft2     fontconfig 选文件,FreeType 光栅化
+gnome.gio          PangoFontMap 是 GListModel
+compat.harfbuzz    整形
+compat.fribidi     bidi 算法
+freedesktop.cairo  字形落下去的那张 surface
+```
+
+**空白图片意味着其中之一没干活。**
+
+⚠️ 而且它**诚实地降级**:`freedesktop.fontconfig` 故意把运行期路径编译成空,
+所以没有 `FONTCONFIG_FILE` 的 runner 合法地找到零个字体族 —— 那就没有东西可画、
+也没有东西可断言。**那种情况被报告出来,而不是被静默略过**,因为「0 个字体族,
+所以唯一的真检查没跑」和「文字画出来了」不能长得一样。
+
+### 22.3 ⚠️ 本 fork 踩到的一次静默降级
+
+`HAVE_CAIRO_FREETYPE` 被一次编辑失误从 config.h 里弄丢了。**什么都没有构建失败。**
+`pangocairo-fontmap.c` 只是**一个后端都没注册**,程序在运行期死于
+
+```
+Pango-CRITICAL: Unknown $PANGOCAIRO_BACKEND value.
+  Available backends are:            <- 空列表
+```
+
+随后段错误。测试现在读 font map 的**字体类型**并要求 `CAIRO_FONT_TYPE_FT` ——
+这条断言会当场抓住它。同一类:**"能编译" 对配置宏没有任何证明力。**
+
+### 22.4 ⚠️ `freedesktop.cairo` 的模块自己就不够用(待办)
+
+1.18.2 实测:导出 470 个名字、**零个枚举量**(没有 `CAIRO_FORMAT_ARGB32`、
+没有 `CAIRO_FONT_TYPE_FT`)、**没有 `cairo_t`**。
+
+索引自己的 cairo 示例没发现,因为它**同时**写了 `#include <cairo.h>` 和
+`import freedesktop.cairo;` —— 头文件补上了模块缺的那半。**这意味着
+`import freedesktop.cairo;` 从来没有被单独检验过。**
+
+pangocairo 不能混用两条路(pangocairo.h 经 glib 到 `<stdio.h>`,混用会让
+`struct _IO_FILE` 变成两个实体),所以 `gnome.pangocairo` 自己扫 `cairo.h`。
+从两个模块导出同一个实体是无害的(是同一批 global-module 实体),所以这是**追加**
+而不是冲突。**cairo 的包装体修好后那行可以去掉。**
+
+同类的漏名坑见 §21.4;`freedesktop.cairo` 是同一个生成器家族里还没修的一个。
+
+### 22.5 依赖形态:点名 pangocairo 一个就够
+
+`gnome.pango` 和 `gnome.pangoft2` 是 `gnome.pangocairo` 的 workspace **path**
+依赖,`gnome.gio` 又是 `gnome.pango` 的。消费者再点名任何一个都会得到
+
+```
+error: dependency 'gnome.gobject' is requested as both a version dep
+       (by 'pango') and a path dep (by 'gnome.gio@2.82.5'). Pick one.
+```
+
+这条错误就是本 fork 第一次构建时学到的。
+
+### 22.6 结果
+
+| | |
+|---|---|
+| fork CI | 三个 job 全绿(两条工具链 + `upstream/` 未改) |
+| 测试 | 六个:三个成员 × 两条消费路线 |
+| 索引 | 三个示例,gcc 16.1 与 llvm 22.1 双绿 |
+| 端到端 | 1,492 个像素 |
+
+**文本排版那条线接上了。**
@@ -108,6 +108,9 @@ members = [
     "tests/examples/gobject",
     "tests/examples/gmodule",
     "tests/examples/gio",
+    "tests/examples/pango",
+    "tests/examples/pangoft2",
+    "tests/examples/pangocairo",
     "tests/examples/libgbm",
     "tests/examples/libpng",
     "tests/examples/libwebp",
 
@@ -0,0 +1,97 @@
+-- gnome.pango — international text layout.
+--
+-- Itemisation, the bidirectional algorithm, line breaking, markup and layout.
+-- It knows about scripts and fonts and NOTHING about rasterising: that is
+-- `gnome.pangoft2`, and drawing is `gnome.pangocairo`. Upstream ships them as
+-- three shared libraries and this index follows that split, because it is what
+-- a consumer links.
+--
+-- ─────────────────────────────────────────────────────────────────────────
+-- ⭐ THIS IS THE PACKAGE THAT WAS BLOCKED ON gio
+--
+-- `PangoFontMap` declares
+--
+--     G_IMPLEMENT_INTERFACE (G_TYPE_LIST_MODEL, pango_font_map_list_model_init)
+--
+-- so the type cannot even REGISTER without gio's interface. The index recorded
+-- that gap for a while under a reason that turned out to be wrong — see
+-- `gnome.gio` for what the reason was and why it did not follow.--
+-- ─────────────────────────────────────────────────────────────────────────
+-- ⭐ TWO WAYS TO CONSUME IT, AND YOU PICK ONE
+--
+--     import gnome.pango;
+--     #include <pango/pango.h>
+--
+-- The namespace is the contract in this index: `compat.xxx` means headers, an
+-- owner namespace means the package exposes `import`. This module exports
+-- 851 names and re-exports `gnome.gio`, because pango.h
+-- includes glib-object.h and a consumer cannot name gio itself — it is a
+-- workspace path dependency.
+--
+-- ⚠️ THE TWO ROUTES DO NOT COMPOSE. A TU that does both reaches <stdio.h>
+-- twice — once through the module's global fragment, once directly — and the
+-- same `struct _IO_FILE` becomes two entities. Which route to take is decided
+-- by macros, which a module cannot carry: code using `PANGO_TYPE_*` or
+-- `G_OBJECT` takes the header route, code using the function API imports and
+-- includes nothing. Each member ships a test for each route.
+--
+-- ─────────────────────────────────────────────────────────────────────────
+-- WHY A FORK: GENERATORS, NOT LINE COUNT
+--
+-- The criterion that made cairo (104k lines) a plain descriptor and
+-- libdisplay-info (2k) a fork. Pango has three, and the fork adds a fourth:
+--
+--     configure_file         pango-features.h.meson -> pango-features.h
+--     configure_file         (NO input template)    -> config.h
+--     gobject/glib-mkenums   pango_headers          -> pango-enum-types.{h,c}
+--     (the fork's own)       gen_module()           -> the .cppm wrapper
+--
+-- ⚠️ config.h is the odd one: upstream writes
+-- `configure_file(output: 'config.h', configuration: pango_conf)` with NO
+-- `input:`, so meson emits a `#define` per key and there is nothing in the
+-- tree to substitute into. The file is WRITTEN, and every value in it is a
+-- decision. Two are arithmetic — `PANGO_BINARY_AGE = minor*100 + micro` and
+-- `PANGO_INTERFACE_AGE = minor odd ? 0 : micro` — and `pango_version_check()`
+-- reads the first, so a wrong value makes a correct version comparison answer
+-- wrongly AT RUN TIME rather than failing to build.
+--
+-- https://github.com/mcpplibs/pango
+--
+-- ─────────────────────────────────────────────────────────────────────────
+-- LINUX ONLY. The generated config.h fixes the visibility attribute and the
+-- font backend, and pangoxft (the X11 backend) is deliberately not built —
+-- Xft is not in this index and a Wayland stack does not want it.
+--
+-- ⚠️ NAME gio ALONE if you also want it. glib, gobject and gmodule are
+-- workspace PATH dependencies of `gnome.gio`, and mcpp rejects a package
+-- requested both ways:
+--
+--     error: dependency 'gnome.gobject' is requested as both a version dep
+--            (by 'pango') and a path dep (by 'gnome.gio@2.82.5'). Pick one.
+--
+-- That error is how this fork learned it, on the first build.
+package = {
+    spec        = "1",
+    namespace   = "gnome",
+    name        = "pango",
+    description = "Pango 1.56.1 — international text layout: itemisation, shaping, bidi and line breaking",
+    licenses    = {"LGPL-2.1-or-later"},
+    repo        = "https://github.com/mcpplibs/pango",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["1.56.1"] = {
+                url = {
+                    GLOBAL = "https://github.com/mcpplibs/pango/archive/refs/tags/1.56.1.tar.gz",
+                    -- Verified byte-identical to the GLOBAL tag archive, not
+                    -- merely "same version": the asset IS that archive.
+                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1/pango-1.56.1.tar.gz",
+                },
+                sha256 = "52b32cd2b30326459950ad9a6ecb24ab4909dbe3f631a2657e3973d78015ed01",
+            },
+        },
+    },
+
+    mcpp = "*/mcpp/pango/mcpp.toml",
+}
@@ -0,0 +1,103 @@
+-- gnome.pangocairo — the cairo backend, and the usual entry point.
+--
+-- Almost every consumer reaches pango through this member:
+-- `pango_cairo_create_layout(cr)` then `pango_cairo_show_layout(cr, layout)`
+-- is the whole API most programs need.
+--
+-- ⚠️ IT DEPENDS ON pangoft2, NOT JUST cairo. Upstream compiles
+-- `pangocairo-fcfont.c` and `pangocairo-fcfontmap.c` whenever the freetype
+-- backend is enabled (meson.build:489) — they are what let a cairo surface
+-- draw a fontconfig-selected font, which on Linux is every font.
+--
+-- ─────────────────────────────────────────────────────────────────────────
+-- ⚠️ A SILENT DEGRADATION WORTH KNOWING ABOUT
+--
+-- `HAVE_CAIRO_FREETYPE` was dropped from config.h once by an editing slip.
+-- NOTHING FAILED TO BUILD. `pangocairo-fontmap.c` simply registered no
+-- backends, and the program died at run time with
+--
+--     Pango-CRITICAL: Unknown $PANGOCAIRO_BACKEND value.
+--       Available backends are:          <- an empty list
+--
+-- then segfaulted. The fork's test now reads the font map's FONT TYPE and
+-- requires `CAIRO_FONT_TYPE_FT`, which catches it immediately.
+--
+-- ⚠️ AND freedesktop.cairo's MODULE IS NOT SUFFICIENT ON ITS OWN. Measured on
+-- 1.18.2: 470 names, ZERO enumerators (no `CAIRO_FORMAT_ARGB32`, no
+-- `CAIRO_FONT_TYPE_FT`) and no `cairo_t`. The index's own cairo example does
+-- not notice, because it writes BOTH `#include <cairo.h>` and
+-- `import freedesktop.cairo;`. pangocairo cannot mix the routes, so its module
+-- scans cairo.h itself; that can go when cairo's wrapper is fixed.--
+-- ─────────────────────────────────────────────────────────────────────────
+-- ⭐ TWO WAYS TO CONSUME IT, AND YOU PICK ONE
+--
+--     import gnome.pangocairo;
+--     #include <pango/pangocairo.h>
+--
+-- The namespace is the contract in this index: `compat.xxx` means headers, an
+-- owner namespace means the package exposes `import`. This module exports
+-- 284 names and re-exports `gnome.pango`,
+-- `gnome.pangoft2` and `freedesktop.cairo`.
+--
+-- ⚠️ THE TWO ROUTES DO NOT COMPOSE. A TU that does both reaches <stdio.h>
+-- twice — once through the module's global fragment, once directly — and the
+-- same `struct _IO_FILE` becomes two entities. Which route to take is decided
+-- by macros, which a module cannot carry: code using `PANGO_TYPE_*` or
+-- `G_OBJECT` takes the header route, code using the function API imports and
+-- includes nothing. Each member ships a test for each route.
+--
+-- ─────────────────────────────────────────────────────────────────────────
+-- WHY A FORK: GENERATORS, NOT LINE COUNT
+--
+-- The criterion that made cairo (104k lines) a plain descriptor and
+-- libdisplay-info (2k) a fork. Pango has three, and the fork adds a fourth:
+--
+--     configure_file         pango-features.h.meson -> pango-features.h
+--     configure_file         (NO input template)    -> config.h
+--     gobject/glib-mkenums   pango_headers          -> pango-enum-types.{h,c}
+--     (the fork's own)       gen_module()           -> the .cppm wrapper
+--
+-- ⚠️ config.h is the odd one: upstream writes
+-- `configure_file(output: 'config.h', configuration: pango_conf)` with NO
+-- `input:`, so meson emits a `#define` per key and there is nothing in the
+-- tree to substitute into. The file is WRITTEN, and every value in it is a
+-- decision. Two are arithmetic — `PANGO_BINARY_AGE = minor*100 + micro` and
+-- `PANGO_INTERFACE_AGE = minor odd ? 0 : micro` — and `pango_version_check()`
+-- reads the first, so a wrong value makes a correct version comparison answer
+-- wrongly AT RUN TIME rather than failing to build.
+--
+-- https://github.com/mcpplibs/pango
+--
+-- ─────────────────────────────────────────────────────────────────────────
+-- LINUX ONLY. The generated config.h fixes the visibility attribute and the
+-- font backend, and pangoxft (the X11 backend) is deliberately not built —
+-- Xft is not in this index and a Wayland stack does not want it.
+--
+-- ⚠️ `gnome.pango` and `gnome.pangoft2` are workspace PATH dependencies of
+-- this package, so a consumer must NOT name them as well. Naming
+-- `gnome.pangocairo` alone gets the whole stack.
+package = {
+    spec        = "1",
+    namespace   = "gnome",
+    name        = "pangocairo",
+    description = "PangoCairo 1.56.1 — pango's cairo rendering backend, the usual entry point",
+    licenses    = {"LGPL-2.1-or-later"},
+    repo        = "https://github.com/mcpplibs/pango",
+    type        = "package",
+
+    xpm = {
+        linux = {
+            ["1.56.1"] = {
+                url = {
+                    GLOBAL = "https://github.com/mcpplibs/pango/archive/refs/tags/1.56.1.tar.gz",
+                    -- Verified byte-identical to the GLOBAL tag archive, not
+                    -- merely "same version": the asset IS that archive.
+                    CN     = "https://gitcode.com/mcpp-res/pango/releases/download/1.56.1/pango-1.56.1.tar.gz",
+                },
+                sha256 = "52b32cd2b30326459950ad9a6ecb24ab4909dbe3f631a2657e3973d78015ed01",
+            },
+        },
+    },
+
+    mcpp = "*/mcpp/pangocairo/mcpp.toml",
+}