feat: add compat.eui-neo 0.5.3 with selectable render and window backends

EUI-NEO as a Form B compat package: the core TUs compiled into one lib, public
headers exposed via include_dirs, so consumers write `#include <eui_neo.h>`.
The C++23 module surface is out of scope — upstream ships no module interface
units.

Depends on #134 for compat.vulkan, compat.sdl2 and compat.curl; the `vulkan`,
`sdl2` and `network` features resolve against them.

Sourced from upstream's v0.5.3 release tag with a real sha256, mirrored to
gitcode mcpp-res. Upstream vendors freetype/glfw/libpng/zlib/glad/tray/yyjson/
md4c under 3rd/; none are built here — each is already in this index at the
same version, which is what the six packages from #131 were for.

Backend selection is the interesting part. Upstream compiles exactly one render
backend and one window backend, dispatching on
`#if OPENGL ... #elif VULKAN` and `#if SDL2` / else-GLFW, so defining both
halves of either pair silently picks the first and ignores the caller —
invisible in CI, since neither backend runs headless. mcpp features are
additive with no `default-features = false` (mcpp#242), and all three obvious
encodings fail silently: a `default` feature carrying defines/sources/deps is
inert, `default = { implies = ... }` is the opposite and always applies, and a
package-level define cannot be unset by a feature. Verified with probes on both
0.0.109 and 2026.7.29.1 — a version bump does not change it. What works is
resolving the choice in the preprocessor from the -DMCPP_FEATURE_<NAME> flags
mcpp already passes, via a force-included header; that also means naming an
unrelated feature no longer drops the backends.

Doing so exposed a second problem: mcpp routes `cflags` to C translation units
and `cxxflags` to C++ ones. The first revision of this descriptor carried
`cflags = { "-DEUI_RENDER_BACKEND_OPENGL=1" }` and nothing else, so
render_backend.cpp never saw it — the package built, linked, passed its tests,
and had no render backend at all.

Four members cover the matrix: default (opengl+glfw), markdown, vulkan, and
sdl2+network. Backend selection is verified structurally rather than by
trusting a green test — render_backend.o and window_backend.o are checked for
which backend they actually reference, including for the member that names only
an unrelated feature.

Verified cold on all three platforms with mcpp 0.0.109. compat.vulkan has no
windows build, so the vulkan member gates with [target.'cfg(...)'] and asserts
the default OpenGL configuration there instead.

Design: .agents/docs/2026-07-29-add-eui-neo-plan.md

Co-authored-by: SPeak Agent <248744407+speak-agent@users.noreply.github.com>

Author: 2 people

.agents/docs/2026-07-29-add-eui-neo-plan.md

@@ -38,6 +38,8 @@ mcpp self config --mirror CN   # 切换至国内镜像,默认使用 GLOBAL 上
 | 运行时 loader compat(纯源码,绕开上游 codegen/asm) | [`compat.vulkan`](pkgs/c/compat.vulkan.lua)(Khronos loader:`loader/generated/` 已签入,汇编路径经 `UNKNOWN_FUNCTIONS_SUPPORTED` 降级为纯 C,故无需 CMake/Python/汇编器;windows 延后)· [`compat.vulkan-headers`](pkgs/c/compat.vulkan-headers.lua) |
 | 全源码直编 + 生成 config(仅缺口平台) | [`compat.curl`](pkgs/c/compat.curl.lua)(win32 用上游签入 config,unix 生成) · [`compat.sdl2`](pkgs/c/compat.sdl2.lua)(win/mac 用上游签入 config,linux 生成 + 手工开 X11) |
 | 补索引空缺的头文件包 | [`compat.glx-headers`](pkgs/c/compat.glx-headers.lua)(libglvnd 的 `GL/glx.h`,Khronos registry 不含,SDL 的 X11 后端必需) |
+| C++ 应用框架 compat(依赖复用索引内既有包) | [`compat.eui-neo`](pkgs/e/compat.eui-neo.lua)(上游 `3rd/` 自带 8 个 vendored 依赖,此处一个不编,全部改指索引内同版本 `compat.*`) |
+| 互斥后端(同包多后端二选一) | [`compat.eui-neo`](pkgs/e/compat.eui-neo.lua) 的 `opengl`/`vulkan` 与 `glfw`/`sdl2`。**`default` feature 在 mcpp 上不可用**(带 `defines/sources/deps` 完全不生效;带 `implies` 反而恒生效),可行解是用 `-DMCPP_FEATURE_<NAME>` 在强制包含头里做前置判定。另注意 `cflags` 只作用于 C TU,C++ 需 `cxxflags` |
 | 恒开的 interface define | [`compat.curl`](pkgs/c/compat.curl.lua) 的 `CURL_STATICLIB`:`cflags` 恒开但包私有,feature `defines` 可达消费端但需点名 —— `default = { implies = … }` 无条件生效,恰好两者兼得 |
 | 单包多 major(形态随版本切换) | [`compat.catch2`](pkgs/c/compat.catch2.lua)(3.x 编 `src/catch2/` 出静态库;2.x 走 `single_include/` header-only) |
 | 外部构建系统(`install()` 从源码构建) | [`compat.openblas`](pkgs/c/compat.openblas.lua)(Make) · [`compat.openssl`](pkgs/c/compat.openssl.lua)(Perl Configure + Make,静态 libssl/libcrypto) |

README.md

@@ -19,6 +19,10 @@ members = [
     "tests/examples/core",
     "tests/examples/curl",
     "tests/examples/eigen",
+    "tests/examples/eui-neo",
+    "tests/examples/eui-neo-markdown",
+    "tests/examples/eui-neo-sdl2",
+    "tests/examples/eui-neo-vulkan",
     "tests/examples/ffmpeg",
     "tests/examples/ffmpeg-module",
     "tests/examples/fmtlib.fmt",

mcpp.toml

@@ -0,0 +1,10 @@
+[package]
+name = "eui-neo-markdown-tests"
+version = "0.1.0"
+
+# Long-form declaration so the `markdown` feature is requested. It pulls
+# compat.md4c and publishes EUI_HAS_MD4C=1 as an interface define, which is
+# what switches components/markdown.h from its fallback to the real parser.
+
+[dependencies.compat]
+eui-neo = { version = "0.5.3", features = ["markdown"] }

pkgs/e/compat.eui-neo.lua

@@ -0,0 +1,55 @@
+// POSITIVE verification for compat.eui-neo's `markdown` feature.
+//
+// components/markdown.h is header-only and compiles one of two definitions of
+// detail::parseMarkdownBlocks depending on EUI_HAS_MD4C. That makes it a clean
+// probe for something the descriptor cannot otherwise prove: the feature's
+// `defines` really do reach the CONSUMER's translation unit, not just the
+// package's own. Without propagation this member would link md4c and still
+// silently get the fallback parser.
+//
+// tests/examples/eui-neo asserts the negative side — same header, feature off,
+// degenerate single-Paragraph result.
+#include <eui_neo.h>
+import std;
+
+namespace app {
+
+const DslAppConfig& dslAppConfig() {
+    static const DslAppConfig config = DslAppConfig{}.title("markdown feature test");
+    return config;
+}
+
+void compose(eui::Ui&, const eui::Screen&) {}
+
+} // namespace app
+
+int main() {
+#if !defined(EUI_HAS_MD4C)
+    std::println("EUI_HAS_MD4C not defined — the feature's interface define did not propagate");
+    return 1;
+#else
+    namespace md = components::detail;
+
+    const auto blocks = md::parseMarkdownBlocks("# Heading\n\nBody text.\n");
+
+    // The real parser splits heading from paragraph; the fallback returns one
+    // Paragraph holding the raw source.
+    if (blocks.size() < 2) {
+        std::println("expected >= 2 blocks from the md4c parser, got {}", blocks.size());
+        return 2;
+    }
+    if (blocks[0].kind != md::MarkdownBlockKind::Heading || blocks[0].headingLevel != 1) {
+        std::println("expected an h1 first block, got kind={} level={}",
+                     static_cast<int>(blocks[0].kind), blocks[0].headingLevel);
+        return 3;
+    }
+    if (md::plainText(blocks[0].runs) != "Heading") {
+        std::println("unexpected heading text: '{}'", md::plainText(blocks[0].runs));
+        return 4;
+    }
+
+    std::println("compat.eui-neo[markdown]: ok ({} blocks, h1 = '{}')",
+                 blocks.size(), md::plainText(blocks[0].runs));
+    return 0;
+#endif
+}

tests/examples/eui-neo-markdown/mcpp.toml

@@ -0,0 +1,10 @@
+[package]
+name = "eui-neo-sdl2-tests"
+version = "0.1.0"
+
+# Covers the two remaining alternates in one member: the SDL2 window backend
+# replacing GLFW, and `network` turning core/platform/network.cpp from stubs
+# into a real libcurl-backed implementation. The render backend stays OpenGL,
+# unnamed — naming a feature no longer costs you the defaults.
+[dependencies.compat]
+eui-neo = { version = "0.5.3", features = ["sdl2", "network"] }

tests/examples/eui-neo-markdown/tests/markdown.cpp

@@ -0,0 +1,91 @@
+// Verify compat.eui-neo's `sdl2` window backend and `network` feature.
+//
+// Both are asserted at COMPILE time first, because both fail silently at
+// runtime otherwise: a window backend that did not switch just uses GLFW, and
+// `network` that did not switch leaves core/platform/network.cpp compiled as
+// stubs that return failure. Neither shows up without a display or a network.
+#include <eui_neo.h>
+// SDL_MAIN_HANDLED before <SDL.h>: on Windows SDL_main.h does
+// `#define main SDL_main` and expects the real entry point to come from
+// SDL2main (src/main/windows/SDL_windows_main.c). This package does not ship
+// that — a library consumer should not be handed an entry point — so the test
+// takes SDL's documented alternative and keeps its own main, pairing it with
+// SDL_SetMainReady() below. Without this the link fails with
+// "LNK1561: entry point must be defined".
+#define SDL_MAIN_HANDLED
+#include <SDL.h>
+#include <curl/curl.h>
+import std;
+
+#if !defined(EUI_WINDOW_BACKEND_SDL2)
+#error "sdl2 feature requested but EUI_WINDOW_BACKEND_SDL2 is not defined"
+#endif
+#if !defined(EUI_HAS_CURL)
+#error "network feature requested but EUI_HAS_CURL is not defined"
+#endif
+
+namespace app {
+
+const DslAppConfig& dslAppConfig() {
+    static const DslAppConfig config = DslAppConfig{}.title("sdl2 + network test");
+    return config;
+}
+
+void compose(eui::Ui&, const eui::Screen&) {}
+
+} // namespace app
+
+int main() {
+    // SDL's dummy driver is a real driver, so unlike the GL/Vulkan backends
+    // this actually runs: init, create, query, tear down.
+    SDL_SetMainReady();
+    SDL_SetHint(SDL_HINT_VIDEODRIVER, "dummy");
+    if (SDL_Init(SDL_INIT_VIDEO) != 0) {
+        std::println("SDL_Init failed: {}", SDL_GetError());
+        return 1;
+    }
+    SDL_Window* window = SDL_CreateWindow("eui-neo", SDL_WINDOWPOS_UNDEFINED,
+                                          SDL_WINDOWPOS_UNDEFINED, 200, 100,
+                                          SDL_WINDOW_HIDDEN);
+    if (window == nullptr) {
+        std::println("SDL_CreateWindow failed: {}", SDL_GetError());
+        SDL_Quit();
+        return 2;
+    }
+    const char* driver = SDL_GetCurrentVideoDriver();
+    SDL_DestroyWindow(window);
+    SDL_Quit();
+
+    // libcurl came in through the feature's dependency, and it has TLS — the
+    // thing EUI-NEO's downloader needs and the thing a misconfigured curl
+    // silently lacks. No connection is made.
+    if (curl_global_init(CURL_GLOBAL_DEFAULT) != CURLE_OK) {
+        std::println("curl_global_init failed");
+        return 3;
+    }
+    const curl_version_info_data* curlInfo = curl_version_info(CURLVERSION_NOW);
+    const bool haveTls = curlInfo != nullptr &&
+                         (curlInfo->features & CURL_VERSION_SSL) != 0 &&
+                         curlInfo->ssl_version != nullptr;
+    curl_global_cleanup();
+    if (!haveTls) {
+        std::println("libcurl reached us without TLS");
+        return 4;
+    }
+
+    // Still eui-neo underneath — a headless facade from the base source set.
+    eui::json::Document doc;
+    if (!doc.parse(R"({"window": "sdl2"})")) {
+        std::println("parse failed: {}", doc.error().message);
+        return 5;
+    }
+    std::string windowBackend;
+    if (!doc.stringAt("/window", windowBackend) || windowBackend != "sdl2") {
+        std::println("unexpected /window: '{}'", windowBackend);
+        return 6;
+    }
+
+    std::println("compat.eui-neo[sdl2,network]: ok (SDL driver={}, curl {} ssl={})",
+                 driver, curlInfo->version, curlInfo->ssl_version);
+    return 0;
+}

tests/examples/eui-neo-sdl2/mcpp.toml

@@ -0,0 +1,26 @@
+# `vulkan` REPLACES the default OpenGL backend rather than adding to it: the
+# package resolves the exclusive choice in its own preprocessor from the
+# MCPP_FEATURE_* flags. The window backend stays GLFW, unnamed.
+#
+# linux + macOS only, because compat.vulkan is — see the note at the top of
+# pkgs/c/compat.vulkan.lua. On windows this member falls back to the default
+# (OpenGL) build so the member still exercises something, and tests/backend.cpp
+# adapts via HAVE_EUI_VULKAN.
+[package]
+name = "eui-neo-vulkan-tests"
+version = "0.1.0"
+
+[target.'cfg(linux)'.dependencies.compat]
+eui-neo = { version = "0.5.3", features = ["vulkan"] }
+
+[target.'cfg(linux)'.build]
+cxxflags = ["-DHAVE_EUI_VULKAN=1"]
+
+[target.'cfg(macos)'.dependencies.compat]
+eui-neo = { version = "0.5.3", features = ["vulkan"] }
+
+[target.'cfg(macos)'.build]
+cxxflags = ["-DHAVE_EUI_VULKAN=1"]
+
+[target.'cfg(windows)'.dependencies.compat]
+eui-neo = "0.5.3"

tests/examples/eui-neo-sdl2/tests/backends.cpp

@@ -0,0 +1,90 @@
+// Verify compat.eui-neo's `vulkan` feature actually swaps the render backend.
+//
+// Two things have to hold, and only one of them is about Vulkan:
+//
+//  1. The backend define really flipped. EUI_RENDER_BACKEND_VULKAN must be
+//     visible here and EUI_RENDER_BACKEND_OPENGL must NOT — if `default` had
+//     leaked through alongside the explicit feature, both would be set and
+//     core/render/render_backend.cpp would have silently compiled the OpenGL
+//     path (its dispatch is `#if OPENGL … #elif VULKAN`, so OpenGL wins).
+//     That failure is invisible at runtime without a GPU, so it is asserted at
+//     COMPILE time below.
+//
+//  2. The Vulkan translation units are linked. compat.vulkan's loader entry
+//     points must resolve from a consumer that reached them through eui-neo's
+//     feature-scoped dependency, not through a direct one.
+//
+// Everything else about the Vulkan backend needs a device, a surface and a
+// window, none of which exist on a CI runner — see the design doc.
+//
+// HAVE_EUI_VULKAN is set by THIS project's own [target.'cfg(...)'.build]
+// cxxflags: compat.vulkan has no windows build, so on windows the member takes
+// the default OpenGL configuration instead and asserts THAT.
+#include <eui_neo.h>
+#if defined(HAVE_EUI_VULKAN)
+#include <vulkan/vulkan.h>
+#endif
+import std;
+
+#if defined(HAVE_EUI_VULKAN)
+#  if !defined(EUI_RENDER_BACKEND_VULKAN)
+#    error "vulkan feature requested but EUI_RENDER_BACKEND_VULKAN is not defined"
+#  endif
+#  if defined(EUI_RENDER_BACKEND_OPENGL)
+#    error "EUI_RENDER_BACKEND_OPENGL leaked in alongside the vulkan feature"
+#  endif
+#else
+// The default (OpenGL) build publishes NO interface define — the package
+// resolves it in its own preprocessor, which the consumer never sees. So the
+// only thing assertable from here is the absence of the vulkan one.
+#  if defined(EUI_RENDER_BACKEND_VULKAN)
+#    error "EUI_RENDER_BACKEND_VULKAN present without the vulkan feature"
+#  endif
+#endif
+
+namespace app {
+
+const DslAppConfig& dslAppConfig() {
+    static const DslAppConfig config = DslAppConfig{}.title("vulkan backend test");
+    return config;
+}
+
+void compose(eui::Ui&, const eui::Screen&) {}
+
+} // namespace app
+
+int main() {
+    // The loader answers this without any ICD, so it is safe on a driverless
+    // runner while still proving compat.vulkan came along with the feature.
+#if defined(HAVE_EUI_VULKAN)
+    std::uint32_t apiVersion = 0;
+    if (vkEnumerateInstanceVersion(&apiVersion) != VK_SUCCESS) {
+        std::println("vkEnumerateInstanceVersion failed");
+        return 1;
+    }
+#endif
+
+    // Still the eui-neo library underneath: assert on a headless facade that
+    // lives in core/platform/json.cpp, so a build that dropped the base
+    // sources while chasing the feature fails here.
+    eui::json::Document doc;
+    if (!doc.parse(R"({"backend": "vulkan"})")) {
+        std::println("parse failed: {}", doc.error().message);
+        return 2;
+    }
+    std::string backend;
+    if (!doc.stringAt("/backend", backend) || backend != "vulkan") {
+        std::println("unexpected /backend: '{}'", backend);
+        return 3;
+    }
+
+#if defined(HAVE_EUI_VULKAN)
+    std::println("compat.eui-neo[vulkan]: ok (backend={}, loader api {}.{}.{})",
+                 backend, VK_VERSION_MAJOR(apiVersion), VK_VERSION_MINOR(apiVersion),
+                 VK_VERSION_PATCH(apiVersion));
+#else
+    std::println("compat.eui-neo[vulkan]: skipped, default opengl build asserted instead (parsed {})",
+                 backend);
+#endif
+    return 0;
+}