mcpplibs · Sunrisepeak · Aug 5, 2026 · Aug 5, 2026 · Aug 5, 2026
diff --git a/.agents/docs/2026-08-05-add-eui-neo-0.5.5-plan.md b/.agents/docs/2026-08-05-add-eui-neo-0.5.5-plan.md
@@ -0,0 +1,121 @@
+# Design doc: bump `compat.eui-neo` to 0.5.5
+
+Date: 2026-08-05
+
+Follow-up to `.agents/docs/2026-07-29-add-eui-neo-plan.md` (which landed 0.5.3). Upstream
+released 0.5.4 and 0.5.5 as hotfixes; this bumps the index from 0.5.3 to 0.5.5 and — the
+non-trivial part — picks up the **Shadertoy subsystem** that 0.5.5 added to the core
+library.
+
+## Source and version
+
+| | |
+|---|---|
+| Upstream | `https://github.com/sudoevolve/EUI-NEO` |
+| Version | `0.5.5` (latest release, published 2024-08-02) |
+| Tarball | `archive/refs/tags/v0.5.5.tar.gz` |
+| sha256 | `cf0da91d7544fe406b704922137fd4d55ed080b3e647501e0ca5303abb00eb98` (computed twice, stable) |
+| Wrap dir | `EUI-NEO-0.5.5/` — absorbed by the standard `*/` glob prefix, no `install()` hook |
+| CN mirror | **pending** — no `mcpp-res` write access on this machine; see below |
+| License | Apache-2.0 (unchanged) |
+
+## Build recipe change: the Shadertoy subsystem is now mandatory (NOT optional)
+
+The descriptor's comment previously read "tracks upstream `CMakeLists.txt` (v0.5.3)". In
+0.5.5 the core library grew a Shadertoy subsystem, and it is **not** gated by any CMake
+option or macro:
+
+- `CORE_SOURCES` gains `core/render/shadertoy.cpp`, `shadertoy_json.cpp`,
+  `shadertoy_primitive.cpp` (unconditional).
+- The OpenGL backend list gains `core/render/opengl/opengl_shadertoy.cpp`.
+- `EUI_VULKAN_BACKEND_SOURCES` gains `core/render/vulkan/vulkan_shadertoy.cpp`.
+
+The reason it cannot be left out:
+
+- `core/render/render_backend.h` and `include/eui/types.h` both `#include
+  <core/render/shadertoy.h>` **unconditionally** (line 3 of each) and re-export the
+  `ShaderToy*` types (`using ShaderToyGraph = …`, etc.) with no `#ifdef` guard.
+- `render_backend.h` declares the `createShaderToy` / `renderShaderToy` virtuals (with
+  inline `Unsupported` defaults).
+- `core/render/opengl/opengl_backend.cpp` calls `releaseShaderToys()` unconditionally
+  (line 69) — dropping `opengl_shadertoy.cpp` is an undefined reference, not a silent
+  behavioural gap.
+
+So a 0.5.5 descriptor that kept the old 20-TU recipe would fail to link on the OpenGL
+path (the default) and never compile the Shadertoy interface the public headers promise.
+
+No new dependencies are introduced by the five files:
+
+| source | non-std includes | already a dep |
+|---|---|---|
+| `shadertoy.cpp` | — (std only) | — |
+| `shadertoy_json.cpp` | `"eui/json.h"` | `core/platform/json.cpp` is in the base set |
+| `shadertoy_primitive.cpp` | `shadertoy_primitive.h`, `primitive_geometry.h` | — (internal headers) |
+| `opengl_shadertoy.cpp` | `<glad/glad.h>` | `compat.glad` |
+| `vulkan_shadertoy.cpp` | `vulkan_shadertoy_shaders.h` | `compat.vulkan` (feature) |
+
+Everything else verified unchanged against 0.5.3: the 18 `CORE_SOURCES` paths the
+descriptor already named all still exist, the mcpp#233 `platform.o` collision stub
+(`core/platform/platform.cpp` → `mcpp_generated/eui_neo_platform_tu.cpp`) still applies,
+and every `3rd/` vendored dependency is at the same version the descriptor pins
+(freetype 2.13.3, glfw 3.4, libpng 1.6.43, zlib-1.3.1, yyjson-0.12.0; the single-file
+`stb_image.h` / `nanosvg*.h` remain at the `3rd/` root).
+
+## Descriptor changes (`pkgs/e/compat.eui-neo.lua`)
+
+1. `xpm.{linux,macosx,windows}` each gain a `["0.5.5"]` entry (0.5.3 retained).
+2. Base `sources` goes 20 → 24: `shadertoy.cpp`, `shadertoy_json.cpp`,
+   `shadertoy_primitive.cpp` (render layer), `opengl_shadertoy.cpp` (OpenGL group).
+3. `vulkan` feature gains `vulkan_shadertoy.cpp` (6 → 7 sources).
+4. Header comment updated to v0.5.5 + the Shadertoy note.
+
+## CN mirror: pending (fallback form used)
+
+`gtc` is not installed and `~/.config/gitcode-tool/config.json` does not exist on this
+machine, so the 0.5.5 mirror cannot be published from here. Per `docs/cn-mirror.md`'s
+no-write-access fallback, the 0.5.5 entry uses a **plain-string url** (GLOBAL upstream
+release); `check_mirror_urls.lua` exempts plain strings, so lint stays green and CN users
+fall back to upstream. The 0.5.3 entries keep their `{ GLOBAL, CN }` tables.
+
+Once `mcpp-res/eui-neo` has a `0.5.5` release (same tarball as GLOBAL for byte
+identical sha), flip the 0.5.5 `url` to `{ GLOBAL = …, CN =
+"https://gitcode.com/mcpp-res/eui-neo/releases/download/0.5.5/eui-neo-0.5.5.tar.gz" }`.
+sha256 does not change.
+
+## Test members
+
+All six `tests/examples/eui-neo*` members bumped their `compat.eui-neo` dep from `0.5.3`
+to `0.5.5` so the whole feature surface (markdown / vulkan / sdl2+network / app-main /
+window) exercises the new version. CI's selective-member logic already maps the
+descriptor edit to these members.
+
+## Fix caught by CI: char8_t is now a package-wide problem
+
+The first CI run (linux + macos, mcpp 2026.8.3.3) failed to build 0.5.5 with
+`no viable conversion from 'basic_string<char8_t>' to 'basic_string<char>'` in
+`core/platform/platform.cpp:616` (`resolveResourcePath()` returns
+`(error ? candidate : absolute).u8string()`) and `core/render/shadertoy_json.cpp`
+(lines 40, 56, 322). All are the `path::u8string()` → `std::string` conversion that
+`__cpp_char8_t` breaks.
+
+The 0.5.3 descriptor scoped `-fno-char8_t` to the **windows** profile because the only
+offending line sat inside `#if defined(_WIN32)`. 0.5.5's new Shadertoy subsystem and
+`resolveResourcePath()` are not Windows-gated, so the flag moved **package-wide** (base
+`cxxflags`, lines above) and was dropped from the windows block. Everything else stays at
+c++23.
+
+## Verification
+
+- `mcpp xpkg parse` (mcpp 2026.8.4.1, the local pin) → `parse OK`: versions 0.5.3+0.5.5
+  on all three platforms, sources 24, features 6.
+- The 0.5.5 sha256 was computed twice from the GLOBAL tarball and matches the entry in
+  the descriptor (`stat`: 13,339,545 bytes, full).
+- Local `mcpp test` on this Windows box could not get past `xlings install_packages`
+  (silent exit 1 after a complete download, reproduces for 0.5.3 too) — an
+  environment-level issue, not the descriptor: CI's 2026.8.3.3 installs 0.5.5 and all
+  deps fine and reaches the build step. The CI build errors above were the real signal,
+  and they are what this char8_t fix addresses.
+
+> NOTE: local mcpp is 2026.8.4.1 while CI pins 2026.8.3.3. Feature/parse behaviour is
+> unchanged across the two (nothing has touched the feature system since 0.0.109), but a
+> CI green is the authoritative signal.
diff --git a/pkgs/e/compat.eui-neo.lua b/pkgs/e/compat.eui-neo.lua
@@ -15,11 +15,16 @@
 -- genuinely vendored single-file headers live at its root (stb_image,
 -- nanosvg, nanosvgrast) and the sources include them as `"3rd/stb_image.h"`.
 --
--- The build recipe below tracks upstream `CMakeLists.txt` (v0.5.3): CORE_SOURCES
+-- The build recipe below tracks upstream `CMakeLists.txt` (v0.5.5): CORE_SOURCES
 -- plus the OpenGL backend and, for the glfw window backend, `ime_bridge.c`.
+-- 0.5.5 grew a Shadertoy subsystem: render_backend.h and include/eui/types.h now
+-- include core/render/shadertoy.h unconditionally, and opengl_backend.cpp calls
+-- releaseShaderToys(), so shadertoy.cpp / shadertoy_json.cpp / shadertoy_primitive.cpp
+-- and opengl_shadertoy.cpp are part of the lib, not optional (vulkan_shadertoy.cpp
+-- joins the `vulkan` feature the same way).
 --
 -- All `mcpp` paths are GLOBS relative to the verdir; the leading `*/` absorbs
--- the GitHub tarball's `EUI-NEO-0.5.3/` wrap layer.
+-- the GitHub tarball's `EUI-NEO-0.5.5/` wrap layer.
 package = {
     spec        = "1",
     namespace   = "compat",
@@ -36,20 +41,36 @@ package = {
                            CN     = "https://gitcode.com/mcpp-res/eui-neo/releases/download/0.5.3/eui-neo-0.5.3.tar.gz" },
                 sha256 = "6951ac330d0307c633bafe720b7888bf32785103eb16973adb4ee05ef06e64d1",
             },
+            -- CN mirror for 0.5.5 not published yet (no mcpp-res write access here);
+            -- plain-string url keeps lint green and lets CN users fall back to
+            -- upstream, per docs/cn-mirror.md. Flip to { GLOBAL, CN } once the
+            -- gitcode release exists — sha256 stays the same.
+            ["0.5.5"] = {
+                url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.5.tar.gz",
+                sha256 = "cf0da91d7544fe406b704922137fd4d55ed080b3e647501e0ca5303abb00eb98",
+            },
         },
         macosx = {
             ["0.5.3"] = {
                 url    = { GLOBAL = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.3.tar.gz",
                            CN     = "https://gitcode.com/mcpp-res/eui-neo/releases/download/0.5.3/eui-neo-0.5.3.tar.gz" },
                 sha256 = "6951ac330d0307c633bafe720b7888bf32785103eb16973adb4ee05ef06e64d1",
             },
+            ["0.5.5"] = {
+                url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.5.tar.gz",
+                sha256 = "cf0da91d7544fe406b704922137fd4d55ed080b3e647501e0ca5303abb00eb98",
+            },
         },
         windows = {
             ["0.5.3"] = {
                 url    = { GLOBAL = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.3.tar.gz",
                            CN     = "https://gitcode.com/mcpp-res/eui-neo/releases/download/0.5.3/eui-neo-0.5.3.tar.gz" },
                 sha256 = "6951ac330d0307c633bafe720b7888bf32785103eb16973adb4ee05ef06e64d1",
             },
+            ["0.5.5"] = {
+                url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.5.tar.gz",
+                sha256 = "cf0da91d7544fe406b704922137fd4d55ed080b3e647501e0ca5303abb00eb98",
+            },
         },
     },
 
@@ -120,6 +141,9 @@ package = {
             "*/core/render/image_source.cpp",
             "*/core/render/primitive.cpp",
             "*/core/render/render_backend.cpp",
+            "*/core/render/shadertoy.cpp",
+            "*/core/render/shadertoy_json.cpp",
+            "*/core/render/shadertoy_primitive.cpp",
             "*/core/render/stb_image_impl.cpp",
             "*/core/render/text.cpp",
             -- OpenGL backend and the GLFW IME bridge are UNCONDITIONAL sources.
@@ -128,6 +152,7 @@ package = {
             "*/core/render/opengl/opengl_backend.cpp",
             "*/core/render/opengl/opengl_image.cpp",
             "*/core/render/opengl/opengl_primitives.cpp",
+            "*/core/render/opengl/opengl_shadertoy.cpp",
             "*/core/render/opengl/opengl_text.cpp",
             "*/core/platform/ime_bridge.c",
             -- Window layer
@@ -222,7 +247,12 @@ package = {
         -- `#else` branch returning a null backend. Verified by symbol
         -- inspection, since it links and runs cleanly either way.
         cflags   = { "-include", "mcpp_eui_backends.h" },
-        cxxflags = { "-include", "mcpp_eui_backends.h" },
+        -- `-fno-char8_t` is package-wide since 0.5.5: the Windows-only char8_t
+        -- break of 0.5.3 (parseWindowsSelection) is no longer the only one —
+        -- resolveResourcePath() (platform.cpp:616) and the new Shadertoy TUs
+        -- return path::u8string() as std::string on EVERY platform. Root cause
+        -- is char8_t, not the standard level; everything else stays at c++23.
+        cxxflags = { "-include", "mcpp_eui_backends.h", "-fno-char8_t" },
 
         features = {
             ["vulkan"] = {
@@ -233,6 +263,7 @@ package = {
                     "*/core/render/vulkan/vulkan_image.cpp",
                     "*/core/render/vulkan/vulkan_polygon.cpp",
                     "*/core/render/vulkan/vulkan_primitives.cpp",
+                    "*/core/render/vulkan/vulkan_shadertoy.cpp",
                     "*/core/render/vulkan/vulkan_text.cpp",
                 },
                 deps = { ["compat.vulkan"] = "1.4.357.0" },
@@ -324,23 +355,14 @@ package = {
             -- this never came up before.
             cflags  = { "-DEUI_TRAY_WINAPI=1", "-DNOMINMAX", "-D_WIN32_WINNT=0x0A00" },
             -- Upstream builds at CMAKE_CXX_STANDARD 17; this index's floor is
-            -- c++23, and one Windows-only line does not survive the move:
-            -- `parseWindowsSelection()` in core/platform/platform.cpp pushes
-            -- `path::u8string()` into a std::vector<std::string>, and C++20
-            -- changed that return type to std::u8string.
-            --
-            -- The root cause is char8_t, not the standard level, so turn off
-            -- exactly that: every STL's <filesystem> selects the u8string()
-            -- return type on `__cpp_char8_t`, which -fno-char8_t undefines.
-            -- The rest of the package stays at c++23 on every platform.
-            --
-            -- Linux and macOS never see this — the code is inside
-            -- `#if defined(_WIN32)`. Worth fixing upstream (`wideToUtf8()`
-            -- already sits eight lines above and does the right thing); until
-            -- then this keeps us on a real upstream release tag rather than a
-            -- fork carrying the patch.
-            cxxflags = { "-DEUI_TRAY_WINAPI=1", "-DNOMINMAX", "-fno-char8_t",
-                         "-D_WIN32_WINNT=0x0A00" },
+            -- c++23. `-fno-char8_t` is applied PACKAGE-WIDE (base cxxflags)
+            -- since 0.5.5, not here: 0.5.3 only tripped on char8_t inside the
+            -- Windows-only `parseWindowsSelection()`, but 0.5.5's
+            -- resolveResourcePath() and the Shadertoy TUs return
+            -- path::u8string() as std::string on every platform. Worth fixing
+            -- upstream; until then this keeps us on a real upstream release
+            -- tag rather than a fork carrying the patch.
+            cxxflags = { "-DEUI_TRAY_WINAPI=1", "-DNOMINMAX", "-D_WIN32_WINNT=0x0A00" },
             -- Upstream lists winmm/urlmon/shell32/user32/imm32/pdh and stops
             -- there, because CMake's MSVC default `CMAKE_C_STANDARD_LIBRARIES`
             -- already drags in kernel32/user32/gdi32/shell32/ole32/comdlg32/…

diff --git a/tests/examples/eui-neo-app-main/mcpp.toml b/tests/examples/eui-neo-app-main/mcpp.toml
@@ -30,4 +30,4 @@ name = "eui-neo-app-main-tests"
 version = "0.1.0"
 
 [dependencies.compat]
-eui-neo = { version = "0.5.3", features = ["app-main"] }
+eui-neo = { version = "0.5.5", features = ["app-main"] }
diff --git a/tests/examples/eui-neo-markdown/mcpp.toml b/tests/examples/eui-neo-markdown/mcpp.toml
@@ -7,4 +7,4 @@ version = "0.1.0"
 # what switches components/markdown.h from its fallback to the real parser.
 
 [dependencies.compat]
-eui-neo = { version = "0.5.3", features = ["markdown"] }
+eui-neo = { version = "0.5.5", features = ["markdown"] }
diff --git a/tests/examples/eui-neo-sdl2/mcpp.toml b/tests/examples/eui-neo-sdl2/mcpp.toml
@@ -7,4 +7,4 @@ version = "0.1.0"
 # 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"] }
+eui-neo = { version = "0.5.5", features = ["sdl2", "network"] }
diff --git a/tests/examples/eui-neo-vulkan/mcpp.toml b/tests/examples/eui-neo-vulkan/mcpp.toml
@@ -6,7 +6,7 @@ version = "0.1.0"
 # package resolves the exclusive choice in its own preprocessor from the
 # MCPP_FEATURE_* flags. The window backend stays GLFW, unnamed.
 [dependencies.compat]
-eui-neo = { version = "0.5.3", features = ["vulkan"] }
+eui-neo = { version = "0.5.5", features = ["vulkan"] }
 
 [build]
 cxxflags = ["-DHAVE_EUI_VULKAN=1"]
diff --git a/tests/examples/eui-neo-window/mcpp.toml b/tests/examples/eui-neo-window/mcpp.toml
@@ -34,4 +34,4 @@ name = "eui-neo-window-tests"
 version = "0.1.0"
 
 [dependencies.compat]
-eui-neo = "0.5.3"
+eui-neo = "0.5.5"
diff --git a/tests/examples/eui-neo/mcpp.toml b/tests/examples/eui-neo/mcpp.toml
@@ -3,4 +3,4 @@ name = "eui-neo-tests"
 version = "0.1.0"
 
 [dependencies.compat]
-eui-neo = "0.5.3"
+eui-neo = "0.5.5"