# 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`