more work on desktoplib

2026-09-07 14:36:45 -06:00
parent 5d47f08354
commit bdade6bc27
3 changed files with 197 additions and 4 deletions
@@ -0,0 +1,59 @@
+# AGENTS.md
+
+## Project
+
+**desktoplib** — Cross-platform C++20 library for terminal UIs, process management, and serial (USB) communication. Namespace: `ckitty`.
+
+## Build
+
+```bash
+make -f makelib.mak    # Build static library (out/libdesktoplib.a)
+make                   # Build test executable (out/out.exe)
+make -f makelib.mak remake  # Clean and rebuild library
+```
+
+Compiler: `g++` with `-std=c++20` (developed with MSYS2/UCRT64 on Windows). Test build defines `DESKTOPLIB_TEST` and links `src/desktoplib/main.cpp`.
+
+## Conventions
+
+- Headers use `#pragma once`
+- Source lives under `src/desktoplib/<module>/`
+- OS abstraction: `os/common.hpp` declares interface; `os/unix.cpp` and `os/windows.cpp` implement platform-specific behavior
+- Terminal methods chain via `Terminal&` return
+- ANSI escape sequences are encapsulated in `color`, `backg`, `style`, `pos`, `move`, `key`
+- `Terminal` has friend access to `color`/`backg`/`style` private constructors
+- UI elements inherit from `ckitty::terminal::UI` and implement `render(Terminal&)`
+
+## Module Layout
+
+```
+src/desktoplib/
+├── main.cpp              # Test harness (compiled when DESKTOPLIB_TEST is defined)
+├── os/
+│   ├── common.hpp        # Cross-platform terminal OS interface
+│   ├── unix.cpp          # POSIX implementations
+│   └── windows.cpp       # Windows implementations
+├── terminal/
+│   ├── Terminal.hpp/cpp  # Core terminal output/input engine
+│   ├── UI.hpp            # Abstract UI base class
+│   └── ui/
+│       ├── Box.hpp/cpp   # Bordered box widget
+│       ├── InnerScroll.hpp/cpp  # Scrollbar widget
+│       ├── MenuMap.hpp   # 2D navigation grid
+│       └── Content.hpp   # Virtual content renderer base
+└── proc/
+    ├── Process.hpp       # Stub: planned process abstraction
+    └── Process.cpp
+```
+
+## Current State
+
+- **Terminal**: functional (ANSI colors, RGB/HSL, cursor positioning, input, UI widgets)
+- **Process**: stub only — `class Process {};`
+- **Serial**: not yet started
+
+## Notes
+
+- Do not add comments unless explicitly requested
+- Follow existing naming: module directories are lowercase, classes are PascalCase, methods/variables are camelCase
+- When extending OS abstraction, update `common.hpp` first, then both `unix.cpp` and `windows.cpp`