If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/idea4good/GuiLite shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 7mo ago

• Last commit 7mo ago
• 6 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Slowing — last commit 7mo ago
• ⚠ Single-maintainer risk — top contributor 92% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live idea4good/GuiLite repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/idea4good/GuiLite.

What it runs against: a local clone of idea4good/GuiLite — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in idea4good/GuiLite | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 229 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of idea4good/GuiLite. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/idea4good/GuiLite.git
#   cd GuiLite
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of idea4good/GuiLite and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "idea4good/GuiLite(\\.git)?\\b" \\
  && ok "origin remote is idea4good/GuiLite" \\
  || miss "origin remote is not idea4good/GuiLite (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "GuiLite.h" \\
  && ok "GuiLite.h" \\
  || miss "missing critical file: GuiLite.h"
test -f "src/core/wnd.h" \\
  && ok "src/core/wnd.h" \\
  || miss "missing critical file: src/core/wnd.h"
test -f "src/core/core.cpp" \\
  && ok "src/core/core.cpp" \\
  || miss "missing critical file: src/core/core.cpp"
test -f "src/core/display.h" \\
  && ok "src/core/display.h" \\
  || miss "missing critical file: src/core/display.h"
test -f "src/core/adapter/api_win.cpp" \\
  && ok "src/core/adapter/api_win.cpp" \\
  || miss "missing critical file: src/core/adapter/api_win.cpp"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 229 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~199d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/idea4good/GuiLite"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

GuiLite is a header-only C++ GUI library (~4,000 lines in GuiLite.h) that renders cross-platform UIs on resource-constrained devices including MCUs with as little as 24 MHz processors and 9 KB RAM. It provides a complete widget system, layout engine, and message dispatcher without external dependencies, enabling pixel-perfect GUIs on iOS, Android, Linux, Windows, RTOS, and bare-metal microcontrollers. Monolithic header-only library: GuiLite.h contains the entire implementation; examples/ (implied by HelloXXX demos in documents/) contains runnable sample applications; documents/ holds architecture specs (HowLayoutWork.md, HowMessageWork.md, UML.md) and visual guides; .github/workflows/ccpp.yml runs CI builds across platforms.

Embedded systems engineers and IoT developers building UIs for resource-constrained devices (smartwatches, industrial controllers, MCU-based products); also desktop/mobile developers needing to integrate lightweight UI rendering into existing Qt/MFC/Cocoa frameworks without bloat.

Actively maintained with passing CI (ccpp.yml workflow), header-only design with zero external dependencies, and comprehensive documentation (HowToWork.md, HowLayoutWork.md, HowMessageWork.md). The project demonstrates production-readiness through multiple complete demo applications (HelloWidgets, HostMonitor, etc.) and cross-platform support, though visibility metrics (stars, recent commit frequency) are not provided in the data.

Single-maintainer risk (owned by idea4good organization with limited contributor visibility in file listing), and the header-only architecture means all code is exposed and inlined, making binary size unpredictable for large projects. No visible test suite in the file structure (no test/ or spec/ directory), which is concerning for a graphics library handling rendering on diverse hardware.

Project appears stable rather than actively evolving—no specific recent changes visible in the provided data. The .github/workflows/ccpp.yml indicates ongoing CI validation, and the breadth of demo applications (Hello3D, HelloFFmpeg, HelloAzureIoT) suggests the library is being maintained to support these integrations, but specific PRs or milestone activity is not evident in the file listing.

Clone with git clone https://github.com/idea4good/GuiLite.git, then follow platform-specific build steps from documents/HowToUse.md. For quick testing: docker run -it --privileged -v /dev:/dev-share idea4good/gui-lite:latest bash /run.sh. CMakeLists.txt and shell scripts in .github/workflows/ define build targets; no package manager dependency needed.

Daily commands: Linux/macOS: mkdir build && cd build && cmake .. && make then run generated executables (e.g., ./HelloWidgets). Windows: use Visual Studio CMake integration or cmake -G "Visual Studio 16" .. && cmake --build .. MCU targets: platform-specific toolchains (see README requirements table). All platforms share the same GuiLite.h source with platform detection via preprocessor.

• GuiLite.h — Single monolithic header file containing the entire GUI library (4 KLOC); this is the entry point all applications include and must be understood first
• src/core/wnd.h — Core window abstraction defining the base UI element and message routing system; foundation for all widget behavior
• src/core/core.cpp — Main rendering loop and core library initialization; orchestrates display updates and event processing
• src/core/display.h — Display abstraction layer managing framebuffer, color mode, and platform-agnostic rendering surface
• src/core/adapter/api_win.cpp — Platform abstraction for Windows showing how to integrate GuiLite with OS APIs; template for other platform adapters
• src/widgets/widgets.cpp — Widget factory and utility implementations; demonstrates extending the widget ecosystem
• src/core/resource.h — Resource management (fonts, images, themes) system; critical for customization and multi-platform asset handling

Add a New Custom Widget

1. Create a new header file in src/widgets/ that inherits from c_wnd (base window class from src/core/wnd.h) (src/widgets/your_widget.h)
2. Override on_paint() to define custom rendering using display context methods from src/core/display.h (src/widgets/your_widget.h)
3. Override on_event() to handle user input (clicks, keypresses) from src/core/wnd.h message system (src/widgets/your_widget.h)
4. Include your widget header in GuiLite.h aggregator to expose it in the public API (GuiLite.h)
5. Instantiate and add to parent window using attach_child() inherited from c_wnd (your_application.cpp)

Support a New Platform/OS

1. Create src/core/adapter/api_yourplatform.cpp implementing the platform adapter interface from src/core/api.h (src/core/adapter/api_yourplatform.cpp)
2. Implement create_surface() to initialize framebuffer and obtain display dimensions (src/core/adapter/api_yourplatform.cpp)
3. Implement swap_frame() to push rendered framebuffer to hardware display (src/core/adapter/api_yourplatform.cpp)
4. Implement input event polling (touch/keyboard) and dispatch via post_msg() from src/core/core.cpp (src/core/adapter/api_yourplatform.cpp)
5. Add conditional compilation to src/GuiLite.h or build system (CMakeLists.txt) to select your adapter (src/CMakeLists.txt)

Customize Colors and Styling

1. Define your color palette in src/core/theme.h by creating a new color enum or struct (src/core/theme.h)
2. Update the global theme instance or create a custom theme class that overrides default colors (src/core/theme.h)
3. Widgets reference theme colors in their on_paint() methods via src/core/display.h drawing APIs (src/widgets/button.h)
4. Pass the theme to application initialization in your main() or framework setup (your_application.cpp)

Add Text and Font Support

1. Register font resources in src/core/resource.h resource registry with glyph data and metrics (src/core/resource.h)
2. Use drawing primitives from src/core/word.h to render glyphs at specified positions (src/core/word.h)
3. Widgets (label, button, edit) call text rendering functions during on_paint() from src/core/display.h (src/widgets/label.h)
4. Override font selection in custom widgets or globally via theme configuration (src/core/theme.h)

• Header-only C++ library — Eliminates binary compatibility issues, linking complexity, and deployment overhead; allows aggressive inlining and compile-time optimization; simplifies integration into any C++ project
• Platform adapter pattern (api_win.cpp, api_linux.cpp) — Decouples core GUI logic from OS-specific windowing, input, and timing; enables single codebase to target Windows, Linux, macOS, iOS, Android, and MCUs without recompilation
• Message-driven architecture (wnd.h event dispatch) — Provides familiar event loop model; enables asynchronous input handling, clean separation of concerns between widgets, and natural support for modal dialogs and nested windows
• Framebuffer abstraction (display.h) — Decouples rendering logic from display output format (RGB565, RGB888, grayscale); allows single graphics code to target diverse hardware (LCD, e-ink, OLED) and emulation
• Minimal C++ feature set (no STL, no exceptions) — Reduces code size and memory footprint to fit on 24MHz MCUs with 9KB RAM; avoids runtime overhead; improves predictability on embedded systems

• Header-only monolithic design (GuiLite.h)
  • Why: Eliminates linker complexity and binary compatibility issues; enables end-user optimization
  • Consequence: Slower compilation for applications; no separate library versioning

Header-only means compile times can be slow when GuiLite.h is included in many translation units; consider using PCH (precompiled headers). Platform-specific code is via preprocessor conditionals in GuiLite.h with no clear documentation of which symbols trigger which code paths—you may need to grep for #ifdef blocks. The library expects pre-built font/image resources (generated by GuiLiteToolkit); raw string assets won't render without proper binary encoding via the toolkit. MCU targets require bare-metal startup code and linker scripts not included in the main repo (platform-specific setup assumed).

• Header-only library design — GuiLite.h's entire implementation is in one header; understanding this pattern is critical to modifying the library and diagnosing template instantiation issues.
• Message-driven event dispatch — GuiLite uses a centralized message pump (documented in HowMessageWork.md) to decouple widget input handling from rendering; essential for understanding how user input flows to widgets.
• Widget layout tree with anchor/offset positioning — The layout engine (HowLayoutWork.md) uses a hierarchical widget tree with relative positioning rules; understanding this is mandatory for adding custom widgets or modifying UI layout logic.
• Platform abstraction layer via preprocessor conditionals — GuiLite supports 6+ platforms (iOS/Android/Windows/Linux/MCU) by conditionally compiling platform-specific code at the header level; critical for porting to new platforms.
• Software rasterization and framebuffer blitting — GuiLite renders to an offscreen framebuffer and blits to display without GPU; understanding CPU-based pixel operations is essential for optimizing rendering performance on MCUs.
• UTF-8 multi-language string rendering — GuiLite supports UTF-8 and requires pre-built glyph atlases from GuiLiteToolkit; understanding character encoding and glyph lookup is necessary for internationalization.
• Minimal RAM footprint with compile-time configuration — GuiLite targets 9 KB RAM environments; understanding how to minimize allocations via header macros and static allocation is crucial for MCU integrations.

• idea4good/GuiLiteToolkit — Official companion tool for building font and bitmap resources that GuiLite requires; essential for creating custom UI assets.
• idea4good/GuiLitePreviewer — WYSIWYG layout editor for GuiLite UIs; allows visual GUI design without hand-coding widget coordinates.
• idea4good/GuiLiteSamples — Repository of complete example applications (HostMonitor, etc.) demonstrating GuiLite patterns and best practices.
• idea4good/GuiLiteWeb — Web-based companion project enabling GuiLite UIs to run in browsers; shows how to integrate GuiLite into web frameworks.
• sveltejs/svelte — Alternative lightweight UI framework for web/desktop; comparable philosophy of minimal bundle size and zero runtime overhead.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive build verification workflow for multiple platforms in .github/workflows

The repo claims cross-platform support (Windows, Linux, macOS, iOS, Android, MCU) but the existing ccpp.yml workflow appears minimal. GuiLite needs platform-specific build validation since it's header-only and affects compilation across diverse architectures (amd64, arm, arm64). Adding targeted workflows would catch platform-specific breakages early.

• [ ] Expand .github/workflows/ccpp.yml or create platform-specific workflows (ccpp-linux.yml, ccpp-macos.yml, ccpp-windows.yml)
• [ ] Add build steps for src/CMakeLists.txt with different compiler flags for arm/arm64/amd64
• [ ] Verify compilation with minimal MCU toolchains (e.g., arm-none-eabi-gcc) to validate 'MCU' platform claim
• [ ] Test header-only inclusion by creating minimal compile-only test targets

Document layout system with reference examples in documents/HowLayoutWork.md

The file documents/HowLayoutWork.md exists but the file structure shows multiple layout-related images (layout_dialog.png, layout_single_slide.png, layout_slide_group.png) that suggest complex layout features. The docs appear incomplete relative to the visual assets. This is critical for new contributors to understand the core layout engine without reading GuiLite.h directly.

• [ ] Expand documents/HowLayoutWork.md with concrete C++ code examples showing single_slide, slide_group, and dialog layouts
• [ ] Add embedded versions of layout_dialog.png, layout_single_slide.png, layout_slide_group.png with captions explaining coordinate systems
• [ ] Include step-by-step walkthrough of how margin/padding/alignment work in the layout system
• [ ] Cross-reference specific GuiLite.h class names (e.g., c_wnd, c_layout) with examples

Add unit test framework for core graphics and message handling in src/

The documents reference HowMessageWork.md and show various rendering features (3D, particles, fonts, transparency) but there are no visible test files in src/. As a 4 KLOC header-only library used on MCUs, regressions in core graphics math (transforms, clipping) or message routing could break embedded applications. Header-only libraries especially benefit from compile-time and runtime tests.

• [ ] Create src/test/ directory with CMake test targets
• [ ] Add unit tests for core graphics primitives: line drawing, circle/ellipse rendering, and coordinate transforms
• [ ] Add message dispatch tests validating the message routing documented in HowMessageWork.md
• [ ] Integrate tests into CMakeLists.txt and ensure they run in ccpp.yml CI workflow

• Add a test suite: Create tests/ directory with unit tests for layout calculations (HowLayoutWork.md implies complex anchor/offset logic), widget rendering, and message dispatch using a cross-platform test framework (GoogleTest or Catch2). Currently no test/ directory visible.
• Document widget API reference: Create an auto-generated or manually-written API.md in documents/ that lists all public classes/methods in GuiLite.h with parameter descriptions and return types; the UML.md is architectural but lacks method-level detail.
• Add platform detection macros to GuiLite.h with clear documentation: Create a documents/PlatformDetection.md explaining the #ifdef conditions (Windows vs Linux vs iOS vs Android vs MCU bare-metal) and which symbols are set for each; currently requires code-diving to understand platform-specific paths.

GuiLite is a lightweight, header-only GUI library with a relatively good security posture for its minimal scope. Primary security concerns are: (1) Memory safety issues inherent to C++ code, particularly in a header-only format with wide exposure, (2) Platform adapter security that requires careful OS API usage, and (3) Input validation in widget classes handling user events. The codebase shows good practices with modular design and cross-platform support, but lacks visible security hardening measures. No critical vulnerabilities detected, but comprehensive code review and automated security scanning are recommended before use in security-sensitive applications.

• Medium · Header-Only Library Memory Safety Concerns — GuiLite.h. As a header-only GUI library with 4 KLOC of C++ code, the entire codebase is exposed in GuiLite.h. Header-only implementations increase risk of memory management issues, buffer overflows, and unsafe pointer operations being difficult to audit across multiple compilation units. The lack of encapsulation makes it harder to maintain security boundaries. Fix: Conduct thorough static analysis focusing on: 1) All pointer arithmetic and array access bounds checking, 2) Memory allocation/deallocation patterns, 3) String handling functions for buffer overflow risks, 4) Use of unsafe C functions (strcpy, sprintf, etc.). Consider adding assertions and bounds checking macros.
• Medium · Platform-Specific Adapter Code Security — src/core/adapter/api_linux.cpp, src/core/adapter/api_win.cpp, src/core/adapter/api_unknow.cpp. The codebase contains platform-specific adapters (api_linux.cpp, api_win.cpp, api_unknow.cpp) that interface with OS-level APIs. These files are critical security boundaries but visibility into their implementation is limited. Improper OS API usage could lead to privilege escalation, memory disclosure, or resource exhaustion. Fix: 1) Validate all OS API calls for proper error handling, 2) Ensure return codes are checked and errors logged, 3) Review file/resource handling for proper cleanup, 4) Audit privilege levels and capabilities requested, 5) Add security unit tests for each platform adapter.
• Low · Input Validation in Widget Classes — src/widgets/button.h, src/widgets/dialog.h, src/widgets/edit.h. Widget classes (button.h, dialog.h, edit.h) likely handle user input and events. Without visible validation logic, there's potential risk of invalid input causing unexpected behavior, crashes, or exploitable conditions, especially in the edit.h widget which typically processes text input. Fix: 1) Implement comprehensive input validation for all user-facing widgets, 2) Validate event data, message parameters, and text input length/content, 3) Implement maximum length restrictions on edit fields, 4) Sanitize any user input before use in drawing or calculations, 5) Add fuzzing tests for widget input handlers.
• Low · Third-Party Integration Points — README.md - Integration documentation. README mentions smooth integration with 3rd party frameworks (Qt/MFC/Winform/Cocoa/Web). Integration points with external libraries introduce supply chain risks and compatibility issues that could be exploited. Fix: 1) Document version requirements for all supported 3rd party frameworks, 2) Maintain compatibility matrix and security advisories, 3) Test against known vulnerable versions, 4) Provide clear integration guidelines emphasizing security best practices, 5) Monitor CVE databases for integrated frameworks.
• Low · Missing Cryptographic Controls — No explicit crypto implementation visible in file structure. The library mentions Azure IoT integration (HelloAzureIoT.png) but there's no visible cryptography implementation. If the library handles network communication or data protection, absence of encryption could be a concern. Fix: 1) If network communication is supported, ensure TLS/SSL is mandatory, 2) Document any security assumptions about the host environment, 3) If data protection is needed, integrate established crypto libraries (OpenSSL, libsodium), 4) Never implement custom cryptography, 5) Document security guarantees and limitations.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.