mcpplibs · Sunrisepeak · Sep 26, 2026 · Sep 26, 2026
diff --git a/.agents/docs/2026-09-26-bump-eui-neo-0.6.0-plan.md b/.agents/docs/2026-09-26-bump-eui-neo-0.6.0-plan.md
@@ -0,0 +1,83 @@
+# Design doc: bump `compat.eui-neo` to 0.6.0
+
+Date: 2026-09-26
+
+Follow-up to `.agents/docs/2026-09-04-bump-eui-neo-0.5.9-plan.md` and commit `1cf5768` (0.5.9),
+plus the index-side re-release `0.5.9.1` (vulkan loader re-pin). Upstream released 0.6.0;
+this bumps the index from 0.5.9.1 to 0.6.0.
+
+## Source and version
+
+| | |
+|---|---|
+| Upstream | `https://github.com/sudoevolve/EUI-NEO` |
+| Version | `0.6.0` (latest release) |
+| Tarball | `archive/refs/tags/v0.6.0.tar.gz` |
+| sha256 | `11d0725bcc6f16abbbea6052b58c6949008cf78ceaa1645002ba1b3abf9772a1` (derived from the tag tarball) |
+| Wrap dir | `EUI-NEO-0.6.0/` — absorbed by the existing `install()` hook (`normalise_layout`) |
+| CN mirror | **pending** — no `mcpp-res` write access on this machine; plain-string url fallback per SOP |
+| License | Apache-2.0 (unchanged) |
+
+## What changed upstream (0.5.9 → 0.6.0)
+
+- `CORE_SOURCES` gains exactly one TU: `core/audio/audio.cpp` — a streaming audio `Player`
+  behind the new `include/eui/audio.h` (`eui::audio`, surfaced through the umbrella header).
+- The TU vendors **miniaudio 0.11.21** as a single header at `3rd/miniaudio.h` and carries
+  `#define MINIAUDIO_IMPLEMENTATION` itself; no other TU in the lib touches it. Upstream adds
+  `${EUI_MINIAUDIO_DIR}` (= `3rd/`) as a **PRIVATE** include dir because audio.cpp includes it
+  by bare name `"miniaudio.h"`.
+- Upstream link additions for miniaudio: `${CMAKE_DL_LIBS} m` PUBLIC on Linux;
+  `CoreAudio + AudioToolbox + CoreFoundation` frameworks on macOS; nothing on Windows (the
+  WASAPI backend binds its APIs at runtime).
+- `core/audio/audio.h` is a pimpl header (only `<memory>`, `<string>`) — consumers never need
+  the `3rd/` search path.
+- Everything else is app- or CMake-level: `EUI_ENABLE_MODULES` default, an INTERFACE
+  `EUI_DEBUG_BUILD=1` tied to CMake Debug config, new example targets (`promo`, `vcd_viewer`),
+  probe test properties. `tray_bridge.c` differs from 0.5.9 only in comment language + EOF
+  newline (verified by diff). `3rd/` dependency pins, features, and flags carry over unchanged.
+- `-fno-char8_t` remains required.
+
+## Descriptor changes (`pkgs/e/compat.eui-neo.lua`)
+
+- `xpm.<linux|macosx|windows>["0.6.0"]`: plain-string GLOBAL url (no CN mirror), sha256 above.
+- `sources += */core/audio/audio.cpp`.
+- `*/3rd` added to the platform-level `include_dirs` + `private_include_dirs` pair on all
+  three legs (linux: extended beside the glib path) — the miniaudio bare include, package-side
+  only. ⚠️ A BASE-level `private_include_dirs` was tried first and is **inert**: measured, not
+  assumed — audio.cpp's dependency scan failed with `'miniaudio.h' file not found` while every
+  base-level `include_dirs` entry took effect normally. The platform-level pair is the shape
+  the glib leg already established from emitted `compile_commands.json` (the -I lands on the
+  package's own TUs and not on consumers'). Publishing `*/3rd` would expose bare
+  `stb_image.h`/`nanosvg.h`/`miniaudio.h` and shadowed vendored copies of index packages in
+  every consumer TU.
+- linux `ldflags += -lm`; macosx `ldflags += -framework CoreAudio -framework AudioToolbox
+  -framework CoreFoundation`; windows unchanged.
+- Header comment: recipe now tracks `CMakeLists.txt` v0.6.0; `3rd/` note counts miniaudio as
+  the fourth vendored single-file header; new 0.6.0 paragraph.
+
+## Test members
+
+All seven `tests/examples/eui-neo*` members bumped to `0.6.0` (the vulkan member moves from
+`0.5.9.1`; the rest from `0.5.9`). No test source changes: the 0.6.0 surface this workspace
+exercises (backends, app-mains, tray, markdown, network) is unchanged; the audio Player is
+new API that no member reaches yet.
+
+## Verification
+
+Locally, mcpp 2026.9.26.2 (upgraded for this run — the index floor moved to 2026.9.18.3),
+Linux x86_64:
+
+- Index lint: `check_mirror_urls`, `check_platform_version_parity`, `check_duplicate_versions`,
+  `check_package_name`, `check_cross_package_refs` — all clean on the descriptor.
+- First revision used a BASE-level `private_include_dirs = { "*/3rd" }`; audio.cpp's dependency
+  scan failed (`'miniaudio.h' file not found`) — the finding recorded in the descriptor. The
+  platform-level pair replaced it.
+- All seven members `mcpp test` green: eui-neo (headless), eui-neo-window, eui-neo-app-main,
+  eui-neo-markdown, eui-neo-sdl2 (sdl2+network), eui-neo-vulkan, eui-neo-tray.
+- Interface check on the emitted `compile_commands.json`: the package's `core/audio/audio.cpp`
+  TU carries `-I …/eui-neo-0.6.0/3rd`; the member's consumer TU carries neither the 3rd path
+  nor the glib path — private pairing behaves the same as the glib leg.
+
+Windows/macOS legs rest on CI: the descriptor changes there are additive (source list + the
+same private include pair + frameworks), and upstream's own CMake pins the same link model
+(nothing extra on Windows; three frameworks on macOS).
diff --git a/pkgs/e/compat.eui-neo.lua b/pkgs/e/compat.eui-neo.lua
@@ -11,11 +11,13 @@
 -- libpng, zlib, glad, tray, yyjson, md4c). NONE of those are built here: each
 -- one already exists in this index as its own `compat.*` package at the same
 -- upstream version, and building them once for the whole ecosystem is the
--- point of having them. `3rd/` is still on the include path because three
+-- point of having them. `3rd/` is still on the include path because four
 -- genuinely vendored single-file headers live at its root (stb_image,
--- nanosvg, nanosvgrast) and the sources include them as `"3rd/stb_image.h"`.
+-- nanosvg, nanosvgrast, and since 0.6.0 miniaudio) and the sources include
+-- them as `"3rd/stb_image.h"` — except miniaudio, which audio.cpp includes
+-- BARE; see the 0.6.0 note below.
 --
--- The build recipe below tracks upstream `CMakeLists.txt` (v0.5.9): CORE_SOURCES
+-- The build recipe below tracks upstream `CMakeLists.txt` (v0.6.0): 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
@@ -56,8 +58,30 @@
 -- via global properties. 3rd/, dependencies, features, and flags carry over
 -- unchanged.
 --
+-- 0.6.0: CORE_SOURCES gains one TU — `core/audio/audio.cpp`, a streaming
+-- audio Player behind the new `include/eui/audio.h`. Its only third-party
+-- need is miniaudio 0.11.21, vendored as the single header `3rd/miniaudio.h`
+-- (same category as stb_image/nanosvg — genuinely vendored, not mirrored as
+-- an index package), and the TU carries `#define MINIAUDIO_IMPLEMENTATION`
+-- itself, so NOTHING else in the lib touches it. Two things follow:
+--   * audio.cpp includes it as a BARE `"miniaudio.h"` (upstream adds
+--     `EUI_MINIAUDIO_DIR` = `3rd/` as a PRIVATE include dir), so `*/3rd` must
+--     be on this package's include path — see private_include_dirs below.
+--     PUBLISHED headers stay clean: `core/audio/audio.h` hides miniaudio
+--     behind a pimpl, so consumers must not inherit the raw `3rd/` path
+--     (it would expose bare stb_image.h/nanosvg.h and shadow real index
+--     packages for every consumer TU).
+--   * miniaudio links something on every platform (upstream: `${CMAKE_DL_LIBS}
+--     m` PUBLIC on Linux, CoreAudio+AudioToolbox+CoreFoundation on macOS,
+--     nothing on Windows — the WASAPI backend is dlopen-bound at runtime).
+-- Everything else this release moves is app- or CMake-level: the
+-- EUI_ENABLE_MODULES default, an INTERFACE `EUI_DEBUG_BUILD=1` tied to the
+-- Debug CONFIG, promo/vcd_viewer example targets, and Chinese re-commenting
+-- of tray_bridge.c (diff vs 0.5.9: comments + EOF newline only). `3rd/`,
+-- deps and the backend/app-main source lists are unchanged.
+--
 -- All `mcpp` paths are GLOBS relative to the verdir; the leading `*/` absorbs
--- the GitHub tarball's `EUI-NEO-0.5.9/` wrap layer.
+-- the GitHub tarball's `EUI-NEO-0.6.0/` wrap layer.
 package = {
     spec        = "1",
     namespace   = "compat",
@@ -155,6 +179,14 @@ package = {
                 url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.9.tar.gz",
                 sha256 = "370d1da706d94bbbb144fa1634e1d9796a8a1ffd58b696fbb801296aef15703d",
             },
+            -- 0.6.0 has no CN mirror yet (never published to mcpp-res), so it
+            -- is a plain-string GLOBAL url — check_mirror_urls.lua exempts
+            -- plain strings, and the maintainer flips it to { GLOBAL, CN }
+            -- when the mirror lands.
+            ["0.6.0"] = {
+                url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.6.0.tar.gz",
+                sha256 = "11d0725bcc6f16abbbea6052b58c6949008cf78ceaa1645002ba1b3abf9772a1",
+            },
         },
         macosx = {
             ["0.5.3"] = {
@@ -197,6 +229,11 @@ package = {
                 url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.9.tar.gz",
                 sha256 = "370d1da706d94bbbb144fa1634e1d9796a8a1ffd58b696fbb801296aef15703d",
             },
+            -- 0.6.0: see the linux block — plain-string GLOBAL, no CN mirror.
+            ["0.6.0"] = {
+                url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.6.0.tar.gz",
+                sha256 = "11d0725bcc6f16abbbea6052b58c6949008cf78ceaa1645002ba1b3abf9772a1",
+            },
         },
         windows = {
             ["0.5.3"] = {
@@ -239,6 +276,11 @@ package = {
                 url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.5.9.tar.gz",
                 sha256 = "370d1da706d94bbbb144fa1634e1d9796a8a1ffd58b696fbb801296aef15703d",
             },
+            -- 0.6.0: see the linux block — plain-string GLOBAL, no CN mirror.
+            ["0.6.0"] = {
+                url    = "https://github.com/sudoevolve/EUI-NEO/archive/refs/tags/v0.6.0.tar.gz",
+                sha256 = "11d0725bcc6f16abbbea6052b58c6949008cf78ceaa1645002ba1b3abf9772a1",
+            },
         },
     },
 
@@ -250,6 +292,21 @@ package = {
         -- `*/include` carries the umbrella `eui_neo.h` and `eui/*.h`; `*` is the
         -- verdir root, which is what makes the `"components/…"`, `"core/…"` and
         -- `"3rd/stb_image.h"` quoted includes resolve. Upstream marks both PUBLIC.
+        -- `*/3rd` is added to the PRIVATE include set of every platform block
+        -- below (0.6.0: audio.cpp includes the vendored `3rd/miniaudio.h` by
+        -- BARE name — see the header comment). Not here: a BASE-level
+        -- `private_include_dirs` is inert — measured, not assumed. The first
+        -- revision of this 0.6.0 change carried it and audio.cpp's dependency
+        -- scan failed with `'miniaudio.h' file not found` while every base
+        -- `include_dirs` entry took effect normally. The proven shape is the
+        -- glib pair below: `include_dirs` + `private_include_dirs` in the
+        -- PLATFORM block, which yields the -I on this package's own TUs and
+        -- NOT on consumers' (verified in emitted compile_commands), matching
+        -- upstream's `target_include_directories(eui_neo PRIVATE …)`.
+        -- Publishing `*/3rd` would hand every consumer a search path holding
+        -- bare stb_image.h/nanosvg.h/miniaudio.h and shadowed copies of the
+        -- index packages vendored under 3rd/; `core/audio/audio.h` is a pimpl
+        -- header that never mentions miniaudio, so nothing needs it publicly.
         include_dirs = { "*/include", "*", "mcpp_generated" },
 
         -- mcpp#233/#240: every package in a link emits its objects into ONE
@@ -332,6 +389,11 @@ package = {
             -- its own TU (upstream CORE_SOURCES). GLFW branch rides on ime_bridge.h
             -- (ime_bridge.c, already compiled) + glfw; SDL2 branch needs only SDL.
             "*/core/window/window_input_backend.cpp",
+            -- 0.6.0: streaming audio via the vendored single-header miniaudio
+            -- (MINIAUDIO_IMPLEMENTATION lives in this TU). Needs `*/3rd` on the
+            -- include path — see private_include_dirs — and per-platform link
+            -- additions — see the platform blocks.
+            "*/core/audio/audio.cpp",
         },
 
         targets = { ["eui-neo"] = { kind = "lib" } },
@@ -538,6 +600,12 @@ package = {
             -- 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" },
+            -- 0.6.0: audio.cpp's bare `#include "miniaudio.h"` — the same
+            -- platform-level pair the linux leg proves (see the note above
+            -- the base include_dirs). No link addition is needed on Windows:
+            -- miniaudio's WASAPI backend binds its APIs at runtime.
+            include_dirs         = { "*/3rd" },
+            private_include_dirs = { "*/3rd" },
             -- 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/…
@@ -570,7 +638,17 @@ package = {
             -- bridge files; the AppKit tray path is Cocoa-native and never
             -- includes tray.h.
             cflags   = { "-DEUI_TRAY_APPKIT=1" },
-            ldflags  = { "-framework", "Cocoa", "-lobjc" },
+            -- 0.6.0: audio.cpp's bare `#include "miniaudio.h"` — the same
+            -- platform-level pair the linux leg proves. See the note above
+            -- the base include_dirs for why BASE-level private_include_dirs
+            -- does not work.
+            include_dirs         = { "*/3rd" },
+            private_include_dirs = { "*/3rd" },
+            -- 0.6.0: the three audio frameworks upstream links PUBLIC for
+            -- miniaudio's CoreAudio backend.
+            ldflags  = { "-framework", "Cocoa", "-lobjc",
+                         "-framework", "CoreAudio", "-framework", "AudioToolbox",
+                         "-framework", "CoreFoundation" },
             flags = {
                 { glob = "*/core/platform/native_bridge.c", cflags = { "-x", "objective-c" } },
                 { glob = "*/core/platform/tray_bridge.c",   cflags = { "-x", "objective-c" } },
@@ -631,16 +709,22 @@ package = {
             -- Where install() put glib. PRIVATE: `<gio/gio.h>` is included by
             -- tray_bridge.c and by nothing this package publishes, so a
             -- consumer must not inherit a glib header search path.
-            include_dirs         = { "mcpp_generated/glib/include/glib-2.0" },
-            private_include_dirs = { "mcpp_generated/glib/include/glib-2.0" },
+            -- `*/3rd` joins for 0.6.0 (audio.cpp's bare `"miniaudio.h"` — see
+            -- the note above the base include_dirs): package-side only, same
+            -- proven pairing as the glib path.
+            include_dirs         = { "mcpp_generated/glib/include/glib-2.0", "*/3rd" },
+            private_include_dirs = { "mcpp_generated/glib/include/glib-2.0", "*/3rd" },
             -- ⚠️ THE EXPLICIT `-L` IS NOT REDUNDANT WITH `runtime.library_dirs`
             -- BELOW. That key becomes `-Wl,-rpath` only — it tells the LOADER
             -- where to look, not the LINKER. lld happens to search rpath and
             -- would hide this; GNU ld does not, and `-lglib-2.0` then falls
             -- through to whatever the host has (or to nothing).
             --
-            -- `-ldl` is glad's CMAKE_DL_LIBS.
-            ldflags = { "-lpthread", "-ldl",
+            -- `-ldl` is glad's CMAKE_DL_LIBS; `-lm` joins for 0.6.0, where
+            -- upstream adds `${CMAKE_DL_LIBS} m` PUBLIC for miniaudio's ALSA
+            -- backend. (Linking libm is not staging it — the forbidden list
+            -- below is about payload RUNPATH contents.)
+            ldflags = { "-lpthread", "-ldl", "-lm",
                         "-Lmcpp_generated/glib/lib",
                         "-lgio-2.0", "-lgobject-2.0", "-lglib-2.0" },
             runtime = {

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.9", features = ["app-main"] }
+eui-neo = { version = "0.6.0", 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.9", features = ["markdown"] }
+eui-neo = { version = "0.6.0", 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.9", features = ["sdl2", "network"] }
+eui-neo = { version = "0.6.0", features = ["sdl2", "network"] }
diff --git a/tests/examples/eui-neo-tray/mcpp.toml b/tests/examples/eui-neo-tray/mcpp.toml
@@ -25,4 +25,4 @@ name = "eui-neo-tray-tests"
 version = "0.1.0"
 
 [dependencies.compat]
-eui-neo = "0.5.9"
+eui-neo = "0.6.0"
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.9.1", features = ["vulkan"] }
+eui-neo = { version = "0.6.0", 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.9"
+eui-neo = "0.6.0"
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.9"
+eui-neo = "0.6.0"