feat: absorb backends, ecs adapters, and gui plugins from labelle-cli

[apotema]

Summary

Implements the assembler side of #5 (and labelle-toolkit/labelle-cli#147). All runtime content that the assembler wires into generated build.zig files — the five backends, the three ECS adapters, and the five GUI plugins — now lives in this repo instead of labelle-cli.

Paired with labelle-toolkit/labelle-cli#??? (feat/eject-backends) which removes the same content from there.

What moved

• backends/: raylib, sokol, bgfx, sdl, wgpu (5 backends)
• ecs/: zig-ecs, zflecs, mr-ecs (3 adapters)
• gui/: clay, raylib-imgui, simple-raylib, simple-sokol, sokol-imgui (5 plugins)

Cache layout change

Introduces a new cache slot ~/.labelle/packages/assembler/<version>/ alongside the existing cli/<version>/ slot. During the staged migration, resolveBundledPackage falls back from the assembler slot to the cli slot so each stage could land independently. The final stage (#8) removes the dead cli-slot machinery entirely since nothing bundled lives there anymore.

The resolver takes both cli_version and assembler_version so local: path overrides can point each slot at a different sibling repo during dev.

Commits (staged for review)

1. feat: absorb raylib backend — Stage 1 plumbing + first backend
2. feat: absorb sokol backend — Stage 2
3. refactor: silence assembler-slot probe — suppresses spurious warnings during migration
4. feat: absorb bgfx backend — Stage 3
5. feat: absorb sdl backend — Stage 4
6. feat: absorb wgpu backend — Stage 5 (last backend)
7. refactor: drop dead backend fallback — Stage 6 cleanup
8. feat: absorb ecs adapters — Stage 7
9. feat: absorb gui plugins + drop dead cli cache slot — Stage 8 (final)

Test plan

• zig build test passes on this branch
• cd ecs/zig-ecs && zig build test passes (CI step added)
• End-to-end: generate examples/{raylib,sokol,bgfx,wgpu} in labelle-cli with LABELLE_ASSEMBLER pointing at this branch's binary, verify .labelle/deps/labelle-*/src/gfx.zig inodes trace back to backends/ in this repo
• CI green on the remote

Closes #5.

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

[cursor]

PR Summary

Medium Risk
Large, mostly additive drop of multiple backend implementations and build templates plus new third-party deps; risk is mainly build/link portability regressions (SDL/bgfx native linking, shader binaries, and audio mixer edge cases).

Overview
Moves backend runtime content into this repo by adding new Zig packages for bgfx, raylib, SDL2, and sokol, each exposing gfx/input/audio/window modules and re-exporting any native artifacts needed for consumers to link.

Adds substantial new backend implementations and demo/example projects (notably a full bgfx renderer with embedded shaders and a software audio mixer, plus an SDL2 backend with SDL_mixer audio, texture management, and embedded font text rendering), along with backend-specific templates/*.txt used for generated desktop/WASM entrypoints.

Updates CI to run the additional ecs/zig-ecs adapter test suite (cd ecs/zig-ecs && zig build test).

^{Reviewed by Cursor Bugbot for commit aa69c1b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[gemini-code-assist]

Code Review

This pull request introduces significant updates to the backend and ECS adapter infrastructure, including the addition of new backends (bgfx, raylib, sdl, sokol, wgpu) and ECS adapters (mr-ecs, zig-ecs). The changes also include a migration from CLI-bundled packages to an assembler-based cache system. My review identified several critical issues: hardcoded paths in the SDL build file, platform-specific window handle logic in the bgfx backend, memory leaks in the sokol audio backend, inefficient view implementation in the zig-ecs adapter, and potential integer overflow vulnerabilities in the wgpu audio WAV parser.

[gemini-code-assist]

The include and library paths for SDL2 are hardcoded to a specific macOS Homebrew location (/opt/homebrew/...). This will cause build failures on Linux, Windows, Intel-based Macs (which use /usr/local), or any system where Homebrew is installed in a non-standard location. Consider using b.dependency to manage SDL2 or at least providing a way to override these paths via build options.

[gemini-code-assist]

The native window handle is hardcoded to use glfw.getCocoaWindow(win), which is specific to macOS. This will prevent the code from compiling or running correctly on Windows or Linux. You should use a conditional check based on builtin.target.os.tag to retrieve the appropriate native handle for the target platform.

    init.platformData.nwh = switch (builtin.target.os.tag) {
        .macos => glfw.getCocoaWindow(win),
        .windows => glfw.getWin32Window(win),
        .linux => glfw.getX11Window(win),
        else => null,
    };

[gemini-code-assist]

This line causes a memory leak. By setting the sound slot to null without freeing the underlying samples buffer, the reference to the allocated memory is lost. The deinit function (lines 81-86) only iterates over non-null slots, so it will not be able to reclaim this memory later. Even if a race condition exists with the audio thread, you must track these allocations (e.g., in a 'pending free' list) to ensure they are eventually deallocated. The same issue exists in unloadMusic at line 437.

[gemini-code-assist]

The view implementation is extremely inefficient for a game engine. It performs a full O(N) scan of all entities and allocates a new ArrayList (materialized as a slice) every time it is called. In a typical ECS usage pattern, views are created every frame, leading to significant performance degradation and memory pressure. This should be refactored to wrap the underlying zig-ecs view iterators directly, avoiding allocations and leveraging the ECS's optimized query structures.

[gemini-code-assist]

Potential integer overflow and out-of-bounds logic in the WAV chunk parser. If a corrupted WAV file provides a very large chunk_size, the addition chunk_data_start + chunk_size can overflow usize (especially on 32-bit platforms). This could lead to an infinite loop or incorrect memory access in subsequent iterations. Validate that the chunk fits within the bytes_read bounds before advancing pos.

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 530c2c4. Configure here.}

[cursor]

bgfx window hardcodes macOS-only native window handle

High Severity

glfw.getCocoaWindow(win) is unconditionally called to obtain the native window handle, but this function only exists on macOS. On Linux or Windows, a different GLFW function is needed (e.g., getX11Window, getWin32Window). The builtin import on line 3 is present but unused, suggesting platform-conditional logic was intended but never implemented. This makes the entire bgfx backend unusable on non-macOS platforms.

 

^{Reviewed by Cursor Bugbot for commit 530c2c4. Configure here.}

[cursor]

Raylib audio never recycles freed sound/music slots

Medium Severity

Unlike the bgfx and SDL audio backends which both implement findFreeSoundSlot()/findFreeMusicSlot() to scan for previously-freed null slots, the raylib loadSound and loadMusic only ever increment next_sound_id/next_music_id. After repeated load/unload cycles, IDs will be exhausted even though freed slots exist, causing all subsequent loads to return 0.

Additional Locations (1)

• backends/raylib/src/audio.zig#L68-L77

 

^{Reviewed by Cursor Bugbot for commit 530c2c4. Configure here.}

[cursor]

SDL build hardcodes macOS Homebrew library paths

Medium Severity

The SDL include and library paths are hardcoded to /opt/homebrew/include and /opt/homebrew/lib, which are specific to Apple Silicon macOS with Homebrew. This breaks builds on Linux, Windows, and even Intel Macs where Homebrew installs to /usr/local. These paths are baked into the module definitions and propagated to all consumers of the SDL backend.

 

^{Reviewed by Cursor Bugbot for commit 530c2c4. Configure here.}

[Copilot]

Pull request overview

This PR completes the migration of assembler-wired runtime content (backends, ECS adapters, GUI plugins) into labelle-assembler, and updates cache resolution to use a new ~/.labelle/packages/assembler/<version>/ slot (with transitional version-key handling via assembler_version).

Changes:

• Reworked cache APIs from CLI-bundled packages to assembler-bundled packages (resolveAssemblerPackage / resolveBundledPackage, populateAssemblerCache, fetchAssemblerPackages).
• Updated generator/linker code paths to resolve bundled runtime content from the assembler cache slot.
• Added the migrated backend/ECS/GUI package sources (plus examples) and expanded CI to run zig-ecs adapter tests.

Reviewed changes

Copilot reviewed 84 out of 87 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/root.zig	Re-exports updated cache APIs and resolves backend templates via bundled-package resolver.
src/deps_linker.zig	Links backend/ECS deps using resolveBundledPackage instead of CLI cache.
src/cache.zig	Introduces assembler cache slot resolution, population, and fetching; updates cache validation.
src/build_files.zig	Uses bundled-package resolver for backend/ECS path generation in fallback zon generation.
gui/sokol-imgui/src/adapter.zig	Adds sokol Dear ImGui GUI adapter module.
gui/sokol-imgui/build.zig.zon	Declares sokol-imgui GUI plugin package metadata/deps.
gui/sokol-imgui/build.zig	Builds sokol-imgui module and re-exports sokol backend modules/artifact.
gui/simple-sokol/src/adapter.zig	Adds simple immediate-mode GUI backend for sokol.
gui/simple-sokol/build.zig.zon	Declares simple-sokol GUI plugin package metadata/deps.
gui/simple-sokol/build.zig	Builds simple-sokol GUI module.
gui/simple-raylib/src/adapter.zig	Adds simple immediate-mode GUI backend for raylib.
gui/simple-raylib/build.zig.zon	Declares simple-raylib GUI plugin package metadata/deps.
gui/simple-raylib/build.zig	Builds simple-raylib GUI module.
gui/raylib-imgui/src/adapter.zig	Adds raylib Dear ImGui GUI adapter module.
gui/raylib-imgui/build.zig.zon	Declares raylib-imgui GUI plugin package metadata/deps.
gui/raylib-imgui/build.zig	Builds rlImGui bridge C++ static lib + GUI module; re-exports raylib backend modules/artifact.
gui/clay/src/adapter.zig	Adds Clay GUI adapter module.
gui/clay/build.zig.zon	Declares clay GUI plugin package metadata/deps.
gui/clay/build.zig	Builds clay GUI module.
ecs/zig-ecs/test/adapter_test.zig	Adds zig-ecs adapter tests.
ecs/zig-ecs/src/adapter.zig	Adds zig-ecs adapter implementation for engine ECS contract.
ecs/zig-ecs/build.zig.zon	Declares zig-ecs adapter package metadata/deps.
ecs/zig-ecs/build.zig	Builds zig-ecs adapter module and test step.
ecs/zflecs/src/adapter.zig	Adds zflecs adapter implementation.
ecs/zflecs/build.zig.zon	Declares zflecs adapter package metadata/deps.
ecs/zflecs/build.zig	Builds zflecs adapter module.
ecs/mr-ecs/src/adapter.zig	Adds mr-ecs adapter implementation.
ecs/mr-ecs/build.zig.zon	Declares mr-ecs adapter package metadata/deps.
ecs/mr-ecs/build.zig	Builds mr-ecs adapter module.
backends/wgpu/templates/desktop.txt	Adds wgpu backend lifecycle template.
backends/wgpu/src/window.zig	Adds wgpu window module skeleton (GLFW-based).
backends/wgpu/src/input.zig	Adds wgpu input module (GLFW-based).
backends/wgpu/src/audio.zig	Adds wgpu audio module (software WAV mixer).
backends/wgpu/example/build.zig.zon	Adds wgpu backend demo package metadata.
backends/wgpu/example/build.zig	Adds wgpu backend demo build script.
backends/wgpu/build.zig.zon	Declares wgpu backend package metadata/deps.
backends/wgpu/build.zig	Builds wgpu backend modules and re-exports native artifacts.
backends/sokol/templates/mobile.txt	Adds sokol mobile lifecycle template.
backends/sokol/templates/desktop.txt	Adds sokol desktop lifecycle template.
backends/sokol/src/window.zig	Adds sokol window module.
backends/sokol/src/stb_image_impl.c	Adds stb_image implementation for sokol gfx.
backends/sokol/src/input.zig	Adds sokol input module.
backends/sokol/src/audio.zig	Adds sokol audio module (saudio mixer).
backends/sokol/example/build.zig.zon	Adds sokol backend demo package metadata.
backends/sokol/example/build.zig	Adds sokol backend demo build script.
backends/sokol/example/assets/characters_frames.zon	Adds sokol demo sprite atlas frame data.
backends/sokol/example/assets/characters_animations.zon	Adds sokol demo animation data.
backends/sokol/build.zig.zon	Declares sokol backend package metadata/deps.
backends/sokol/build.zig	Builds sokol backend modules and re-exports native artifact + emscripten helpers.
backends/sdl/templates/desktop.txt	Adds SDL backend lifecycle template.
backends/sdl/src/window.zig	Adds SDL window module.
backends/sdl/src/sdl.zig	Adds shared SDL2 @cImport module.
backends/sdl/src/input.zig	Adds SDL input module.
backends/sdl/src/audio.zig	Adds SDL audio module (SDL_mixer).
backends/sdl/example/build.zig.zon	Adds SDL backend demo package metadata.
backends/sdl/example/build.zig	Adds SDL backend demo build script.
backends/sdl/build.zig.zon	Declares SDL backend package metadata.
backends/sdl/build.zig	Builds SDL backend modules and shared SDL import module.
backends/raylib/templates/wasm.txt	Adds raylib WASM lifecycle template.
backends/raylib/templates/desktop.txt	Adds raylib desktop lifecycle template.
backends/raylib/src/window.zig	Adds raylib window module.
backends/raylib/src/input.zig	Adds raylib input module.
backends/raylib/src/gfx.zig	Adds raylib gfx module.
backends/raylib/src/audio.zig	Adds raylib audio module.
backends/raylib/build.zig.zon	Declares raylib backend package metadata/deps.
backends/raylib/build.zig	Builds raylib backend modules and re-exports native artifact + emsdk helpers.
backends/bgfx/templates/desktop.txt	Adds bgfx backend lifecycle template.
backends/bgfx/src/window.zig	Adds bgfx window module (GLFW + bgfx).
backends/bgfx/src/input.zig	Adds bgfx input module (GLFW-based).
backends/bgfx/src/audio.zig	Adds bgfx audio module (software WAV mixer).
backends/bgfx/example/main.zig	Adds bgfx backend demo program.
backends/bgfx/example/build.zig.zon	Adds bgfx backend demo package metadata.
backends/bgfx/example/build.zig	Adds bgfx backend demo build script.
backends/bgfx/build.zig.zon	Declares bgfx backend package metadata/deps.
backends/bgfx/build.zig	Builds bgfx backend modules and re-exports native artifacts.
.github/workflows/ci.yml	Adds CI step to run zig-ecs adapter tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

validateCache checks the assembler-bundled cache slot using cfg.labelle_version only. When cfg.assembler_version is set to a different version, this will report the wrong cache state (and can block generation even though resolveBundledPackage will look under assembler_version). Consider using (cfg.assembler_version orelse cfg.labelle_version) for the assembler cache check and for the missing-package message.