native

Imported from wischner/native (AGENTS.md). Install upstream with npx skills add wischner/native. Copyright stays with the author.

AGENTS.md

The working project brief for contributors and coding agents, and the map of every maintained Markdown document in this repository. It describes how the library is structured, how builds must be handled, what quality bar is expected, and which documents a code change obliges you to refresh.

Read this first

Every code change must leave the affected documents refreshed in the same commit. Documentation in this project describes the code as it exists now — not a roadmap, not a wish list. A commit that changes behavior and leaves the matching chapter, standard, note, or matrix stale is an incomplete commit. See Refresh obligations for the concrete mapping.

The two normative standards outrank everything else:

Part 1 — Project rules

Project intent

• native is a modern C++ UI library.
• The public surface must feel like pure C++, not like a wrapper around native APIs.
• Platform-specific and toolkit-specific code must stay behind the public interface.
• The library should remain small, readable, educational, and easy to reason about.

Architecture

The library implementation is organized into three layers:

1. Core C++ layer

   • Located in lib/native/
   • Shared across all targets
   • Contains portable logic such as geometry, events, windows, app flow, and graphics abstractions

2. Platform layer

   • Located in lib/native/platforms/
   • Handles operating-system-specific integration
   • Examples: Windows, Linux, Haiku, macOS

3. Toolkit layer

   • Located in lib/native/toolkits/
   • Used when a platform needs a separate windowing or rendering backend
   • Examples on Linux: x11, sdl2, openmotif

The src/ directory contains the vision application. It is a consumer of the public library API and must not contain private library implementation. Tests live in tests/, and developer automation in scripts/.

Library-owned path manipulation, traversal, metadata, and file publication use the C++20 std::filesystem library; file contents use standard C++ streams. Do not add direct POSIX or C filesystem calls, shell command construction, or OS-specific helpers for work covered by those facilities. Public values that identify filesystem entries use std::filesystem::path; filename patterns, extensions, and labels remain text. Descriptor, process, signal, and terminal operations use POSIX interfaces. Native UI, standard-panel, system-icon, and known-folder APIs remain isolated and allowed in their platform or toolkit layer where the C++ standard library has no equivalent.

Public interface rules

• The public API is exposed through include/native.h.
• include/native.h must remain pure C++.
• Do not expose native OS handles, toolkit types, or platform headers in the public API.
• User-facing classes must not contain platform-specific implementation details.
• Prefer clear, modern, lowercase API naming consistent with the current codebase.

Native state and bindings

• Every created wnd owns one opaque internal peer. Per-window backend state, including graphics caches, is stored by that peer and never in the public class definition.
• Use native::bindings only where a native callback or resource identifier must recover its library object. Keep those callback-facing bindings in toolkit or platform globals.* files inside the relevant namespace.
• Object-to-state compatibility names use the stateless internal detail::peer_bindings; do not add another process-wide bidirectional map for a new window/control state type.

Build system rules

• The build system entry point is CMakeLists.txt.
• CMake toolchain files live in scripts/cmake/.
• Developer automation lives in purpose-specific directories under scripts/, such as scripts/linux/, scripts/windows/, and scripts/macos/remote/.
• Do not add a new top-level Makefile for normal project orchestration.
• Builds use the Docker-backed CMake targets. macOS is the documented exception: use scripts/macos/remote/build.sh for CMake/AppleClang with the Apple SDK on the configured remote Mac; validate shared C++ with GCC/Docker first. Do not substitute an ad hoc host build.
• The purpose of Docker is to make backend builds reproducible and independent of host package drift.

Docker targets

The top-level CMake project provides:

• docker-x11
• docker-gemix
• docker-gemix-gemd (same GEMix image, serialized libgem transport)
• docker-sdl2
• docker-openmotif
• docker-openlook
• docker-wmaker
• docker-win
• docker-haiku

These targets use the following Docker images:

• X11: wischner/gcc-x86_64-linux-x11
• GEMix: wischner/gcc-x86_64-gemix:latest
• SDL2: wischner/gcc-x86_64-linux-sdl
• OpenMotif: wischner/gcc-x86_64-linux-motif
• OPEN LOOK: wischner/gcc-x86_64-linux-openlook
• Window Maker: wischner/gcc-x86_64-linux-window-maker
• Windows MinGW-w64: wischner/gcc-x86_64-windows-mingw-w64
• Haiku cross toolchain: wischner/gcc-x86_64-haiku

Both GEMix build targets use the published wischner/gcc-x86_64-gemix:latest image, which already contains the GEM v1.0.0 SDK built from commit 0df463d9ff4b4cbbdd0612ce700c9e11e5e33661: headers and Rasta-backend libraries in /usr/local with gemix-* pkg-config files, plus gemd, resgen, the GEM resources, and the recorded revision in /opt/gemix/share/metadata/gem.version. Docker pulls the image on first use; no local SDK image build and no sibling GEM checkout is needed.

The expected workflow is:

cmake -S . -B build/cmake
cmake --build build/cmake --target docker-gemix
cmake --build build/cmake --target docker-gemix-gemd
cmake --build build/cmake --target docker-x11
cmake --build build/cmake --target docker-sdl2
cmake --build build/cmake --target docker-openmotif
cmake --build build/cmake --target docker-openlook
cmake --build build/cmake --target docker-wmaker
cmake --build build/cmake --target docker-win
cmake --build build/cmake --target docker-haiku

docker-amiga-check is a separate runtime qualification target, not a library backend. It uses the pinned wischner/gcc-m68k-amiga image recorded in CMake, scripts/cmake/toolchain-amiga.cmake and build/amiga-toolchain/. Both C++20 threading and filesystem checks currently fail; no Amiga Vision binary or F5 launch configuration exists. The VS Code task exposes the same diagnostic.

Build directories

• build/cmake/ is the host-side CMake control tree.
• build/linux-x11/ is the Docker-produced X11 build tree.
• build/linux-gemix/ is the Docker-produced GEMix build tree.
• build/linux-gemix-gemd/ is the separate libgem/gemd GEMix build tree.
• build/linux-sdl2/ is the Docker-produced SDL2 build tree.
• build/linux-openmotif/ is the Docker-produced OpenMotif build tree.
• build/linux-openlook/ is the Docker-produced OPEN LOOK build tree.
• build/linux-wmaker/ is the Docker-produced Window Maker build tree.
• build/windows-mingw-w64/ is the Docker-produced Windows MinGW-w64 build tree.
• build/haiku/ is the Docker-produced Haiku build tree.

Do not collapse multiple platform or toolkit builds into the same CMake build directory.

Linux backend rules

X11 backend

• Files under lib/native/toolkits/x11/ are for Xlib, Xt, and Athena code.
• Use Athena widgets for standard controls and menus instead of emulating their painting and input behavior with custom Xlib windows.
• Do not include Motif headers in the X11 backend.
• If a file only needs Xlib/Xutil/XRandR types, include only the matching X11 headers.
• The Docker X11 image must provide Xt and Athena, and must compile the X11 backend without OpenMotif installed.
• The X11 F5 profile runs Docker GDB through scripts/linux/x11/run-twm.sh in a dedicated monochrome Xephyr/TWM display, never directly on the host desktop. The session's tools come from the X11 image, and it is scaled to the host Xft.dpi. Keep GDB/MI stdout clean and other backend profiles independent.

OPEN LOOK backend

• Build with docker-openlook. F5 and standalone execution use the wischner/gcc-x86_64-linux-openlook:latest image and its openlook-xephyr helper, which supplies Xephyr and olwm. No Tribblix VM is required.
• Keep GDB/MI stdout clean and use scripts/linux/docker-debug.sh for F5, or scripts/linux/toolkit-session-run.sh openlook for standalone runs.

SDL2 backend

• Files under lib/native/toolkits/sdl2/ are for SDL2 code only.
• SDL2_ttf is optional.
• If SDL2_ttf is not found, text drawing must degrade gracefully instead of breaking the build.
• SDL2 paint flow must render at frame boundaries, not present once per primitive.
• Avoid repaint backlogs and laggy input paths; invalidation should be efficient.
• Default SDL2 windows should open in a reachable on-screen position.

OpenMotif backend

• Files under lib/native/toolkits/openmotif/ are for Motif/Xt integration only.
• Keep Motif and Xt types out of include/native.h.
• Use widget or resource colors when available, so Motif environments such as CDE can provide the default look.
• If resource lookup fails, fall back to explicit defaults:
  • paper = white
  • ink = black
• Keep the X11/Athena backend independent from Motif headers and libraries.

Windows backend rules

• Files under lib/native/platforms/windows/ are for Win32 integration only.
• Windows F5 runs vision.exe natively in the Windows VM through the scripts/windows/vm/ deployment and interactive-desktop debug scripts, not Wine. The Docker MinGW build remains the build source.
• Keep Win32 handle types and message-loop details out of include/native.h.
• Mouse press/release/move/wheel events must map to the same native semantics used by Linux backends.
• painter behavior must match Linux stable backends:
  • press starts stroke
  • move extends stroke
  • release ends stroke
  • wheel clears strokes

Haiku backend rules

• Files under lib/native/platforms/haiku/ are for Haiku API integration only.

• Keep BApplication, BWindow, and BView usage behind the platform layer.

• Mouse press/release/move/wheel and paint invalidation flow must match Linux stable backends.

• painter behavior must match Linux stable backends:

  • press starts stroke
  • move extends stroke
  • release ends stroke
  • wheel clears strokes

• Optional Haiku GLSL uses dynamically loaded Mesa OSMesa, with native views unchanged. The verified Mesa 22.0.5 runtime uses GALLIUM_DRIVER=softpipe; its llvmpipe JIT is rejected before drawing. Keep driver selection in test, debug and deployment environments, never mutate it inside the library.

• Haiku image context nesting owns its predecessor state and leaves in binding order. Foreign Mesa bindings are rejected unchanged before activation.

Vision program

• vision is the single program built by the repository.
• Its source lives in src/ and it links against native through the public API.
• VS Code launch configurations should point to vision for each active backend.
• Educational programs belong in docs/manuals/PROGRAMMING-NATIVE.md and its chapter files, not in a separate examples source tree.

Quality bar

• Prefer small, explicit, maintainable code over clever code.
• Match the style and architecture already present in the project.
• Fix root causes, not just symptoms.
• Keep toolkit and platform code isolated to their own directories.
• Do not let backend-specific hacks leak into the public API.
• When adding fallback behavior, make it explicit and predictable.

Part 2 — Documentation map

Top level

Standards — docs/standards/

Normative. Short, rule-shaped, and authoritative when a book chapter and a standard appear to disagree.

The Book of Native — docs/manuals/book-of-native/

Explains how the library is built and why. It is the detailed companion to the architectural standards: most chapters name the Architecture section they expand. Index: docs/manuals/BOOK-OF-NATIVE.md — current scope, runtime-tested backend list, and the maintained chapter table of contents.

Architecture Sections 10 (Fonts) and 15 (Classic trees) now have matching internal pattern chapters. The application-side references remain Drawing primitives and collection/disclosure controls.

Programming Native — docs/manuals/programming-native/

Teaches how to write applications against the library. Complete runnable programs and focused snippets; this is where educational example code lives instead of a separate examples source tree. Index: docs/manuals/PROGRAMMING-NATIVE.md — how a native program is organized, the 20-chapter table of contents, and build instructions.

| 20-IMAGE-SHADERS.md | Shader-view lifecycle, source ownership, typed parameters, portable expression authoring/package format, fitting, animation, fallback and mouse acceptance. |

Notes — docs/notes/

Exceptional material only: remote builds, unusual host requirements, open issues, and TODO inventories. Standard local and Docker build instructions do not belong here — they belong in the book. Index: docs/notes/README.md, which states what qualifies.

Other

Part 3 — Documentation obligations

Refresh obligations

Documentation must be refreshed in the same commit as the code change that invalidates it. Use this table to find what a change touches.

Every new control, and every existing control added to another backend, must record its N, H, C, or E kind in CUSTOM.md in the same commit. Every C entry must also have a concrete justification in the reviewed-proposals table; an unexplained custom implementation is a defect.

Documentation conventions

• Keep docs aligned with the actual build flow.
• Markdown file names use uppercase words separated by hyphens with a lowercase .md suffix, for example BACKEND-OPEN-ISSUES.md. Conventional single-word names such as README.md remain valid.
• BOOK-OF-NATIVE.md and docs/manuals/book-of-native/ describe how the current code works; they are not a roadmap. No speculative features, no future plans, no "coming soon".
• If a feature is not implemented, leave it out until the code exists.
• Prefer backend-agnostic explanations in the book when the same pattern is shared.
• Use docs/notes/ only for exceptional cases such as remote builds or unusual host requirements. Do not keep normal Docker build instructions there.
• Do not maintain generated API docs; docs/api stays absent until that work is intentionally started.
• Adding a new note also means adding its line to docs/notes/README.md; adding a chapter also means adding it to its manual's table of contents — and adding either means adding a row to the documentation map above.

High-quality contributor prompts

Use prompts like these when asking an agent or contributor to work on the codebase. They are intentionally specific and should be preferred over vague requests.

Build and infrastructure

• "Update the top-level CMake workflow so Linux X11 and SDL2 builds run through the Docker-backed targets, and keep VS Code debug tasks aligned with the same paths."
• "Refactor the Linux build output layout so toolkit-specific builds live under build/linux-* without breaking the Docker CMake targets or debugger launch paths."

General feature work

• "Implement the feature inside the correct layer: core logic in lib/native/, OS integration in lib/native/platforms/, toolkit behavior in lib/native/toolkits/, and keep the public headers in include/ pure C++."
• "When changing build or backend behavior, update the code, docs, and VS Code launch/build integration together."

Vision's terminal acceptance mode keeps its attributed shader/font assets under src/assets/retro-terminal/. Copy the complete directory beside the deployed binary; its asset README records upstream revision, licenses and port limits.