@@ -186,6 +186,11 @@ translation unit actually references:
 
 The last row is the one that catches a `default`-based regression.
 
+> Superseded in part by `.agents/docs/2026-07-30-eui-neo-window-and-app-main-members.md`:
+> every member above is headless, so the backends were verified by symbol reference
+> rather than by rendering. `eui-neo-window` and `eui-neo-app-main` now assert
+> `rectDraws`/`textDraws` from a real frame under `MCPP_RUN_WINDOW=1`.
+
 ## Features
 
 | feature | gates | default |
@@ -203,6 +208,12 @@ the library, for the same reason it is opt-in here: a consumer with its own `mai
 not be handed a second one. A real EUI application enables it and supplies only
 `app::dslAppConfig()` and `app::compose()`.
 
+> Sharpened later: mcpp links a dependency's objects *eagerly*, so `glfw_app_main.o` is
+> always in the link rather than only when `main` is undefined. An `app-main` project may
+> therefore contain no `main()` of its own **at all** — including every `mcpp test` TU.
+> `tests/examples/eui-neo-app-main` is built around that constraint; see
+> `.agents/docs/2026-07-30-eui-neo-window-and-app-main-members.md`.
+
 **`markdown`** is the more interesting one. `components/markdown.h` is header-only and
 compiles one of *two* definitions of `detail::parseMarkdownBlocks` depending on
 `EUI_HAS_MD4C` — the md4c parser, or a fallback that wraps the entire source in one
 
@@ -0,0 +1,152 @@
+# Design doc: window + app-main test members for compat.eui-neo
+
+Date: 2026-07-30
+
+Follows `.agents/docs/2026-07-29-add-eui-neo-plan.md`, which landed `compat.eui-neo`
+0.5.3 with four workspace members (`eui-neo`, `eui-neo-markdown`, `eui-neo-vulkan`,
+`eui-neo-sdl2`).
+
+## Gap
+
+All four existing members are **headless by construction**. They assert on
+`eui::json::Document`, `core::platform::` frame flags, `components::detail::`
+markdown blocks and — structurally, via `nm` — which backend the dispatch TUs
+reference. None of them:
+
+* creates a window,
+* initialises the OpenGL render backend,
+* enters a render loop, or
+* renders text (the freetype path).
+
+Two consequences:
+
+1. `compat.eui-neo` shipped an `app-main` feature that **nothing built**. Upstream's
+   `core/app/glfw_app_main.cpp` is 584 lines of platform code and was compiled by
+   zero members on zero platforms.
+2. A consumer that drives EUI itself — `core::window::createWindow()` +
+   `core::render::createRenderBackend()` + `app::update`/`app::render` — was never
+   exercised, so it was unknown whether that surface is even reachable through the
+   descriptor's `include_dirs`.
+
+This adds one member per entry-point shape. They are the two shapes an EUI
+application can have, and they are mutually exclusive per project (features resolve
+per consuming project).
+
+## Members
+
+| member | `app-main` | entry point | new coverage |
+|---|---|---|---|
+| `eui-neo-window` | off | hand-written `main()` in the test TU | `core::window`, OpenGL backend, `ScopedRenderBackend`, paced loop, freetype text |
+| `eui-neo-app-main` | **on** | upstream `glfw_app_main.cpp` | the feature's source compiles; `main` really comes from the package |
+
+Both are `[target.'cfg(linux)']`-gated, matching `imgui-window`, `gui-stack` and the
+rest of the X11/GLFW stack in this index. Off-Linux they declare no dependencies and
+the test TU compiles to `int main() { return 0; }`.
+
+Both declare `compat.glfw` **directly** rather than leaning on the transitive edge:
+each calls GLFW itself (`glfwPollEvents`/`glfwWindowShouldClose` in one,
+`glfwSetWindowShouldClose` in the other), because EUI's `core::window` facade
+exposes no event-pump entry point.
+
+## Why the run is opt-in
+
+A window needs a display; CI runners have none. Same answer as `imgui-window`:
+build + link is the headless test, and `MCPP_RUN_WINDOW=1` opts into the real run.
+
+```
+$ mcpp test -p tests/examples/eui-neo-window            # headless CI
+compat.eui-neo[own main]: linked; window run is opt-in (MCPP_RUN_WINDOW=1)
+
+$ MCPP_RUN_WINDOW=1 mcpp test -p tests/examples/eui-neo-window
+compat.eui-neo[own main]: ok (60 frames in 0.98s, 120 rect / 120 text draws)
+```
+
+`eui-neo-app-main` cannot put that gate in `main()` — it does not have one. It goes in
+a **namespace-scope constructor**, which runs before the package's `main()`:
+
+```cpp
+struct WindowRunGate { WindowRunGate() { if (!getenv("MCPP_RUN_WINDOW")) exit(0); } };
+const WindowRunGate g_gate;
+```
+
+Both runs are bounded by a 60-frame budget so the opt-in path terminates on its own
+instead of waiting for a human to close the window.
+
+## Why `app-main` cannot carry tests — and what that pins
+
+mcpp links a dependency's objects **eagerly**, not as lazily-selected archive members.
+`glfw_app_main.o` is therefore always in the link, not only when `main` is still
+undefined. Verified by adding a `main()` to an `app-main` project:
+
+```
+ld: obj/glfw_app_main.o: in function `main':
+    core/app/glfw_app_main.cpp:398: multiple definition of `main';
+    obj/probe.o: first defined here
+```
+
+So an `app-main` project may not contain **any** TU of its own that defines `main` —
+including every `mcpp test` TU. `eui-neo-app-main` is built around that: no `main()`,
+per `tests/examples/catch2-main`. This makes the member a two-sided assertion:
+
+* if `app-main` stops contributing its source → `undefined reference to 'main'` here;
+* if `app-main` stops being opt-in → `multiple definition of 'main'` in *every other*
+  member.
+
+The descriptor comment on the feature is updated to say this; the previous wording
+("a consumer that has its own main() must not get a second one") describes the intent
+but understates the consequence.
+
+## A green test is not a rendered frame
+
+Per the `eui-neo` plan's "the library really is built" section: a frame counter only
+proves `app::update()` ran. `app::update()` reaches `compose()` and the `.onFrame()`
+hook without touching the render backend at all, so a member counting frames would
+pass against a null backend — which is exactly the failure mode the first revision of
+this descriptor shipped (`createRenderBackend()` returning null behind a green CI).
+
+Both members therefore assert on `core::render::lastRenderFrameStats()` and require
+`rectDraws > 0` **and** `textDraws > 0` over the frame budget. `textDraws` is split out
+from `rectDraws` on purpose: text is the only path that needs freetype plus a usable
+system font, and "no font at any of upstream's Linux fallback paths" is a different
+failure from "dead backend".
+
+## Loop mechanics worth recording
+
+Two non-obvious things the loop in `eui-neo-window` has to get right, both discovered
+by running it:
+
+* **Pacing is mandatory.** `OpenGLRenderBackend::initialize()` calls
+  `glfwSwapInterval(0)`, so `present()` never blocks on vsync. An unpaced loop ran at
+  ~8300 fps and pinned a core; the member paces off `DslAppConfig::fpsValue`.
+* **`onFrame` fires twice per rendered frame.** `app::update()` runs the runtime a
+  second time with `deltaSeconds == 0` to settle the re-compose that `onFrame` itself
+  requested (`dsl_app_impl.h`, the `composeRequested()` branch). Counting every
+  invocation reports 2x the real frame rate — gate on the delta.
+
+Neither is a descriptor bug; both are upstream behaviour a consumer must know, and
+neither was discoverable from the headless members.
+
+## Verification
+
+Local, mcpp **0.0.109** (matching `validate.yml` `env.MCPP_VERSION`), linux-x86_64,
+gcc 16.1.0, X11 display with NVIDIA GL 4.6.
+
+```
+                              headless        MCPP_RUN_WINDOW=1
+eui-neo-window                ok (0.08s)      ok (60 frames, 120 rect / 120 text draws)
+eui-neo-app-main              ok (0.07s)      ok (60 frames, 118 rect / 118 text draws)
+eui-neo            (existing) ok
+eui-neo-markdown   (existing) ok
+```
+
+`mcpp xpkg parse`, `check_mirror_urls.lua`, `check_package_name.lua` and
+`check_cross_package_refs.lua` all pass on the touched descriptor. The descriptor
+change is comment-only.
+
+## Not done
+
+* `app-main-sdl2` stays uncovered. It is the same shape against `compat.sdl2`, and
+  covering it means a fifth window member for one `sources` line; worth doing if the
+  SDL2 window backend gains real users.
+* macOS/Windows only get the build+link half, same as `imgui-window`. The opt-in run
+  has been exercised on linux-x86_64 only.
@@ -20,9 +20,11 @@ members = [
     "tests/examples/curl",
     "tests/examples/eigen",
     "tests/examples/eui-neo",
+    "tests/examples/eui-neo-app-main",
     "tests/examples/eui-neo-markdown",
     "tests/examples/eui-neo-sdl2",
     "tests/examples/eui-neo-vulkan",
+    "tests/examples/eui-neo-window",
     "tests/examples/ffmpeg",
     "tests/examples/ffmpeg-module",
     "tests/examples/fmtlib.fmt",
 
@@ -259,6 +259,21 @@ package = {
             -- `compat.gtest`'s `main` feature is: a consumer that has its own
             -- main() must not get a second one. A real EUI application enables
             -- this and supplies only app::dslAppConfig() + app::compose().
+            --
+            -- Sharper than "must not get a second one": mcpp links a
+            -- dependency's objects EAGERLY, not as lazily-selected archive
+            -- members, so `glfw_app_main.o` is always in the link rather than
+            -- only when `main` is still undefined. Enabling this feature is
+            -- therefore incompatible with ANY translation unit of the consumer
+            -- that defines main() — including every `mcpp test` TU, which means
+            -- an app-main project cannot carry its own tests/. Verified: adding
+            -- one yields `multiple definition of 'main'` from
+            -- glfw_app_main.cpp:398. tests/examples/eui-neo-app-main is
+            -- structured around that constraint (no main() at all, and its
+            -- opt-in window run is gated in a namespace-scope constructor
+            -- because there is no main() of ours to gate it in);
+            -- tests/examples/eui-neo-window is the same UI with the feature OFF
+            -- and a hand-written loop.
             ["app-main"] = { sources = { "*/core/app/glfw_app_main.cpp" } },
             -- Same gate for the SDL2 window backend. Upstream picks between the
             -- two by EUI_APP_MAIN_SOURCE; here the consumer picks by name, and
 
@@ -0,0 +1,27 @@
+# compat.eui-neo, `app-main` FEATURE path: the package supplies `int main()`
+# (upstream core/app/glfw_app_main.cpp) and this project deliberately defines
+# none. If the feature stops contributing that source, this member fails to link
+# with `undefined reference to 'main'` — the same assertion shape as
+# tests/examples/catch2-main.
+#
+# This cannot share a project with tests/examples/eui-neo: features are resolved
+# per consuming project, and — because mcpp links a dependency's objects
+# EAGERLY rather than as lazily-selected archive members — a project that
+# enables `app-main` may not contain any translation unit of its own that
+# defines main(). See the note in pkgs/e/compat.eui-neo.lua.
+#
+# Linux-only (cfg): the whole X11/GLFW/GL stack is linux-gated across this
+# index, matching tests/examples/imgui-window. Off-Linux the member has no
+# dependencies and the test TU compiles to a no-op.
+#
+# compat.glfw is a DIRECT dependency because the test TU calls
+# glfwSetWindowShouldClose() itself to bound the opt-in window run.
+#
+# The `compat` index redirect is inherited from the workspace root.
+[package]
+name = "eui-neo-app-main-tests"
+version = "0.1.0"
+
+[target.'cfg(linux)'.dependencies.compat]
+eui-neo = { version = "0.5.3", features = ["app-main"] }
+glfw = "3.4"