@geastack/core 0.1.23

package/include/event.h

@@ -0,0 +1,32 @@
+#pragma once
+
+namespace gea::framework::events {
+
+enum class EventType {
+	Touch,
+	Frame,
+	Timeout,
+	SettingsToggle,
+};
+
+enum class TouchPhase {
+	Down = 1,
+	Move = 2,
+	Up = 3,
+};
+
+struct Event {
+	EventType type = EventType::Frame;
+	TouchPhase touchPhase = TouchPhase::Down;
+	bool touching = false;
+	int data = 0;
+	int x = 0;
+	int y = 0;
+	// Multi-touch pointer index. 0 = primary pointer (full gesture: scroll,
+	// click, focus, keyboard). >=1 = additional simultaneous fingers, which fire
+	// per-node touch/pointer/press events only (e.g. holding a move button while
+	// tapping jump). Single-touch sources (ESP32 panel, mouse) always use 0.
+	int pointerId = 0;
+};
+
+}  // namespace gea::framework::events

package/include/events.h

@@ -0,0 +1,116 @@
+#pragma once
+
+#include "event.h"
+
+#include <cstdint>
+#include <functional>
+
+namespace gea::framework::events {
+
+enum class PointerEventType {
+	TouchStart,
+	TouchMove,
+	TouchEnd,
+	Click,
+	Input,
+	KeyDown,
+	Rotary
+};
+
+enum class EventPhase {
+	None = 0,
+	Capturing = 1,
+	AtTarget = 2,
+	Bubbling = 3
+};
+
+class EventTarget {
+public:
+	explicit EventTarget(int nodeId = -1) : nodeId_(nodeId) {}
+
+	int id() const { return nodeId_; }
+	bool valid() const { return nodeId_ >= 0; }
+	const char *getAttribute(const char *name) const;
+	const char *dataset(const char *name) const;
+	int pressId() const;
+	int pressValue() const;
+
+private:
+	int nodeId_;
+};
+
+struct TouchPoint {
+	int identifier = 1;
+	EventTarget target{};
+	int screenX = 0;
+	int screenY = 0;
+	int clientX = 0;
+	int clientY = 0;
+	int pageX = 0;
+	int pageY = 0;
+};
+
+struct PointerEvent {
+	PointerEventType type;
+	EventTarget target{};
+	EventTarget currentTarget{};
+	int targetId = -1;
+	int currentTargetId = -1;
+	int pointerId = 0;
+	int x = 0;
+	int y = 0;
+	int clientX = 0;
+	int clientY = 0;
+	int pageX = 0;
+	int pageY = 0;
+	int screenX = 0;
+	int screenY = 0;
+	int pressId = -1;
+	int pressValue = -1;
+	int keyCode = 0;
+	int delta = 0;
+	bool primary = true;
+	bool bubbles = true;
+	bool cancelable = true;
+	bool defaultPrevented = false;
+	bool propagationStopped = false;
+	EventPhase eventPhase = EventPhase::None;
+	TouchPoint touches[1]{};
+	TouchPoint targetTouches[1]{};
+	TouchPoint changedTouches[1]{};
+	int touchesLength = 0;
+	int targetTouchesLength = 0;
+	int changedTouchesLength = 0;
+
+	const char *typeName() const;
+	void preventDefault();
+	void stopPropagation();
+};
+
+using EventListener = std::function<void(PointerEvent &)>;
+using EventListenerId = std::uint64_t;
+inline constexpr EventListenerId kInvalidEventListenerId = 0;
+
+class TouchRuntime {
+public:
+	static bool start();
+	static void poll(int nowMs);
+	static void setDispatchEnabled(bool enabled);
+	static bool dispatchEnabled();
+	static void queueTouchEvent(TouchPhase phase, bool touching, int x, int y, int pointerId = 0);
+	// Panel-physical -> logical (orientation-rotated) coordinate mapping.
+	static void transformTouchToLogical(int *x, int *y);
+	// Returns true if the event may have changed what's on screen (a real
+	// down/move/up that fired handlers), so the caller can render immediately
+	// instead of waiting for the next timer frame. Redundant moves (finger held
+	// still, same coords) return false.
+	static bool dispatchEvent(const Event &event);
+	// True if a finger is currently down AND fired a down/move/up within the last
+	// `windowMs` ms. Lets the frame loop keep rendering back-to-back through a drag
+	// (like momentum's overrun catch-up) instead of stalling for the next touch
+	// event after each frame. Goes false on a static hold so there's no busy-render.
+	static bool gestureActiveWithin(int nowMs, int windowMs);
+	static void resetGestureState();
+};
+
+}  // namespace gea::framework::events

package/include/gea/embedded.h

@@ -0,0 +1,13 @@
+// Gea embedded framework.
+//
+// Generated app code targets the framework UI, canvas, services, and host
+// device classes directly. Platform glue stays below this layer.
+
+#pragma once
+
+// Full framework umbrella = host platform layer + the UI engine (document) and
+// reactive (signal) layers. App/engine code includes this; host package code
+// includes gea/embedded-host.h instead (no engine/reactive dependency).
+#include "gea/embedded-host.h"
+#include "ui/document.h"
+#include "ui/signal.h"

package/include/gea/reactive_runtime.h

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// @geastack/core — reactive-apply runtime support.
+//
+// Source fragment fused into a program's translation unit by the gea plugin
+// (geatsc-plugin-gea inserts `#include "gea/reactive_runtime.h"` right after the
+// runtime include, ONLY when the program uses reactivity). NOT self-contained:
+// it relies on the JS-language runtime already being in scope (gea_cpp_value,
+// gea_cpp_key, gea_cpp_queue_microtask, gea::runtime::coerce::to_boolean — all
+// defined earlier in the TU via runtime_pch.h). This is the reactivity FEATURE,
+// so it lives in the framework (GPL), separate from the GPL+RLE language runtime.
+
+#pragma once
+
+static void __attribute__((noinline)) gea_cpp_run_reactive_apply(const std::shared_ptr<std::function<void()>> &apply) {
+  if (apply && *apply) (*apply)();
+}
+static void __attribute__((noinline)) gea_cpp_schedule_reactive_apply(
+  const std::shared_ptr<std::function<void()>> &apply,
+  const std::shared_ptr<bool> &pending
+) {
+  if (!pending || *pending) return;
+  *pending = true;
+  gea_cpp_queue_microtask([apply, pending]() mutable -> void {
+    if (pending) *pending = false;
+    gea_cpp_run_reactive_apply(apply);
+  });
+}
+// (Removed gea_cpp_bind_direct_reactive_apply — the dead "observe-direct"
+// fast-path of the dynamic-store fallback. Its `__sym_GEA_OBSERVE_DIRECT` gate
+// had no setter anywhere in source, so it always returned false and every caller
+// fell through to the typed-store path. Deleted 2026-06-27.)

package/include/gea.h

@@ -0,0 +1,14 @@
+#pragma once
+
+#include "app.h"
+#include "apps.h"
+#include "audio.h"
+#include "ble.h"
+#include "display.h"
+#include "i2c.h"
+#include "image.h"
+#include "imu.h"
+#include "power.h"
+#include "runtime.h"
+#include "touch.h"
+#include "wifi.h"

package/include/gea_perf_config.h

@@ -0,0 +1,96 @@
+#pragma once
+
+// ============================================================================
+// ONE master switch for ALL gea per-frame perf instrumentation.
+//
+//   GEA_EMBEDDED_PERF
+//
+// governs every perf subsystem at once — frame/phase timing, the esp32
+// scheduler harvest + "perf:"/"perf-lite:" lines, per-op refresh & canvas 2D
+// stats, the requestAnimationFrame queue timing, and heap diagnostics. When it
+// is 0, ALL of that is compiled out: no esp_timer/chrono reads, no counter
+// increments, no stat resets, no log output — zero machinery, zero cost.
+//
+// When it is 1 (the development default), each subsystem flag below takes its
+// own value, so a build can still enable just one line (e.g. set
+// GEA_FRAME_PERF_LOG and leave the rest) for targeted profiling.
+//
+// A production target flips perf off in ONE place — its CMakeLists / sdkconfig
+// sets GEA_EMBEDDED_PERF=0 — instead of remembering to zero each sub-flag.
+//
+// This header is the single source of truth for the sub-flag defaults; it is
+// included by the lib perf consumers directly and by the esp32 perf consumers
+// transitively through memory_config.h. The build's own -D defines (seen before
+// any header) still win for an individual flag; the master override below then
+// forces every flag off when the master is off, regardless of those -D values.
+// ============================================================================
+
+#ifndef GEA_EMBEDDED_PERF
+#define GEA_EMBEDDED_PERF 1
+#endif
+
+// --- individual subsystem flags (consulted only when the master is on) ------
+
+// App "gea.perf:" rolling-window line + its per-phase timing (gea_app_entry.cpp).
+#ifndef GEA_FRAME_PERF_LOG
+#define GEA_FRAME_PERF_LOG 1
+#endif
+
+// esp32 frame-scheduler per-frame harvest + "perf:" line (frame_scheduler.cpp).
+#ifndef GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG
+#define GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG 1
+#endif
+
+// esp32 frame-scheduler compact "perf-lite:" line.
+#ifndef GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LITE
+#define GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LITE 0
+#endif
+
+// Per-op refresh timing (ScopedRefreshStat; refresh_perf.h + tree_render/render).
+#ifndef GEA_EMBEDDED_UI_REFRESH_PERF
+#define GEA_EMBEDDED_UI_REFRESH_PERF 1
+#endif
+
+// Per-op canvas 2D timing (canvas_element.cpp).
+#ifndef GEA_EMBEDDED_CANVAS_PERF_DETAIL
+#define GEA_EMBEDDED_CANVAS_PERF_DETAIL 0
+#endif
+
+// requestAnimationFrame queue timing (host/timers.cpp).
+#ifndef GEA_EMBEDDED_RAF_PERF
+#define GEA_EMBEDDED_RAF_PERF 1
+#endif
+
+// Heap diagnostics logging (memory_config.h consumers).
+#ifndef GEA_EMBEDDED_HEAP_DIAGNOSTICS_LOG
+#define GEA_EMBEDDED_HEAP_DIAGNOSTICS_LOG 0
+#endif
+
+// The esp32 frame scheduler's "geafps: PRODFPS=" line. Deliberately NOT under
+// the master switch below: its whole purpose is to report the true frame rate
+// of a build with GEA_EMBEDDED_PERF=0, where every other perf line is stripped.
+// It does need a switch of its own, though, because it is otherwise one INFO
+// line per second for the life of the device -- which overwrites an app's log
+// ring and drowns a serial capture within minutes. On by default so no existing
+// board changes behaviour.
+#ifndef GEA_EMBEDDED_FRAME_SCHEDULER_FPS_LOG
+#define GEA_EMBEDDED_FRAME_SCHEDULER_FPS_LOG 1
+#endif
+
+// --- master OFF forces every subsystem OFF ----------------------------------
+#if !GEA_EMBEDDED_PERF
+#undef GEA_FRAME_PERF_LOG
+#define GEA_FRAME_PERF_LOG 0
+#undef GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG
+#define GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LOG 0
+#undef GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LITE
+#define GEA_EMBEDDED_FRAME_SCHEDULER_PERF_LITE 0
+#undef GEA_EMBEDDED_UI_REFRESH_PERF
+#define GEA_EMBEDDED_UI_REFRESH_PERF 0
+#undef GEA_EMBEDDED_CANVAS_PERF_DETAIL
+#define GEA_EMBEDDED_CANVAS_PERF_DETAIL 0
+#undef GEA_EMBEDDED_RAF_PERF
+#define GEA_EMBEDDED_RAF_PERF 0
+#undef GEA_EMBEDDED_HEAP_DIAGNOSTICS_LOG
+#define GEA_EMBEDDED_HEAP_DIAGNOSTICS_LOG 0
+#endif

package/include/geaos/abi.h

@@ -0,0 +1,165 @@
+#pragma once
+//
+// geaos app ABI — the stable boundary between a dynamically-loaded gea app and
+// the geaos core + backends. See docs/geaos-app-platform.md.
+//
+// This is a **C ABI on purpose**: the loader boundary must not depend on C++
+// name mangling or C++ ABI stability. Apps are authored in TSX/C++, but the
+// surface they bind to is this plain-C table of function pointers.
+//
+// BINDING (same surface, two transports):
+//   - esp32 (in-process): the core fills this table with thin thunks over the
+//     `gea::framework::*Backend` classes — effectively the jump table the
+//     loader patches. Zero IPC.
+//   - Linux (cross-process): the core fills it with proxy thunks that marshal
+//     to the geaos compositor process. Real isolation.
+//
+// VERSIONING: bump GEAOS_ABI_VERSION on any layout/semantics change. The app
+// records the version it was built against; the loader refuses a mismatch.
+//
+// STRINGS: UTF-8. Inbound strings are caller-owned `const char *`. Outbound
+// strings are written into a caller-provided buffer: pass `*len` = capacity,
+// it is overwritten with the written length (excluding the NUL). NUMBERS use
+// gea's value model (double) except explicit sizes/handles. A NULL function
+// pointer (or NULL sub-table) means "unavailable on this target / not granted".
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define GEAOS_ABI_VERSION 1u
+
+// --- capabilities -----------------------------------------------------------
+// Declared in the app manifest; the loader acquires/grants the matching
+// per-target resources (e.g. esp32 brings up the WiFi/BLE backends only when
+// granted — see docs §9) and leaves the sub-table NULL when not granted.
+typedef enum {
+  GEAOS_CAP_NONE    = 0,
+  GEAOS_CAP_WIFI    = 1u << 0,
+  GEAOS_CAP_BLE     = 1u << 1,
+  GEAOS_CAP_SENSORS = 1u << 2,
+  GEAOS_CAP_CAMERA  = 1u << 3,
+  GEAOS_CAP_AUDIO   = 1u << 4,
+  GEAOS_CAP_STORAGE = 1u << 5,
+} GeaosCapability;
+typedef uint32_t GeaosCapabilityMask;
+
+// --- service tables (mirror gea::framework::*Backend) -----------------------
+
+typedef struct GeaosSystemApi {
+  void     (*log)(const char *msg);
+  double   (*now_ms)(void);
+  uint32_t (*abi_version)(void);
+} GeaosSystemApi;
+
+typedef struct GeaosMemoryApi {
+  double (*internal_free)(void);
+  double (*internal_largest_free_block)(void);
+  double (*internal_minimum_free)(void);
+  double (*psram_free)(void);
+} GeaosMemoryApi;
+
+typedef struct GeaosDisplayApi {
+  double (*brightness)(void);
+  void   (*set_brightness)(double v);
+  // The reactive UI render path (tree mutation + present) is provided by the
+  // shared core runtime, not per-call here. Its exact placement relative to a
+  // dynamically-loaded app is the Phase 2 decision (doc §5/§13); this sub-table
+  // is the device-level display control only.
+} GeaosDisplayApi;
+
+typedef struct GeaosInputApi {
+  bool (*take_back_pressed)(void);  // one-shot: reads and clears the flag
+} GeaosInputApi;
+
+typedef struct GeaosWifiApi {
+  bool   (*enabled)(void);
+  void   (*set_enabled)(bool enabled);
+  bool   (*connected)(void);
+  double (*rssi)(void);
+  void   (*ssid)(char *out, int *len);
+  void   (*ip)(char *out, int *len);
+  void   (*mac)(char *out, int *len);
+  void   (*configure)(const char *ssid, const char *password);
+  void   (*start_scan)(void);
+  bool   (*scanning)(void);
+  double (*scan_count)(void);
+  void   (*scan_ssid_at)(double index, char *out, int *len);
+  double (*scan_rssi_at)(double index);
+  bool   (*scan_secured_at)(double index);
+} GeaosWifiApi;
+
+typedef struct GeaosBluetoothApi {
+  void   (*init)(const char *device_name, double appearance, const char *mac);
+  bool   (*enabled)(void);
+  void   (*set_enabled)(bool enabled);
+  void   (*start_advertising)(void);
+  void   (*stop_advertising)(void);
+  bool   (*connected)(void);
+  bool   (*bound)(void);
+  double (*battery_level)(void);
+  void   (*key_tap)(double hid_code);
+  void   (*key_down)(double modifier, double hid_code);
+  void   (*key_up)(void);
+  void   (*mouse_move)(double dx, double dy, double buttons, double wheel);
+  void   (*mouse_click)(double button);
+} GeaosBluetoothApi;
+
+typedef struct GeaosSensorsApi {
+  void   (*init)(void);
+  void   (*close)(void);
+  double (*tilt_x)(void);
+  double (*tilt_y)(void);
+  double (*accel_x)(void);
+  double (*accel_y)(void);
+  double (*accel_z)(void);
+  double (*gyro_x)(void);
+  double (*gyro_y)(void);
+  double (*gyro_z)(void);
+} GeaosSensorsApi;
+
+// The aggregate syscall table handed to the app at init. A sub-table is NULL
+// when the target lacks it or the capability was not granted.
+typedef struct GeaosServices {
+  uint32_t abi_version;  // == GEAOS_ABI_VERSION the core implements
+  const GeaosSystemApi    *system;
+  const GeaosMemoryApi    *memory;
+  const GeaosDisplayApi   *display;
+  const GeaosInputApi     *input;
+  const GeaosWifiApi      *wifi;       // NULL unless GEAOS_CAP_WIFI granted
+  const GeaosBluetoothApi *bluetooth;  // NULL unless GEAOS_CAP_BLE granted
+  const GeaosSensorsApi   *sensors;    // NULL unless GEAOS_CAP_SENSORS granted
+  // camera / audio / storage / power: formalized in Phase 3 as the surface settles.
+} GeaosServices;
+
+// --- app lifecycle (the app implements; the loader drives) ------------------
+// Mirrors gea::framework::app::Application (init/frame/toggleSettings) plus a
+// teardown hook the dynamic model needs for clean unload.
+typedef struct GeaosAppLifecycle {
+  void (*init)(const GeaosServices *services, int width, int height, double device_pixel_ratio);
+  void (*frame)(int timestamp_ms);
+  void (*toggle_settings)(void);  // may be NULL
+  void (*teardown)(void);         // called before unload; may be NULL
+} GeaosAppLifecycle;
+
+// --- app descriptor (the app exports exactly one) ---------------------------
+typedef struct GeaosAppDescriptor {
+  uint32_t            abi_version;   // GEAOS_ABI_VERSION the app was built for
+  const char         *id;           // stable app id
+  const char         *name;         // display name
+  GeaosCapabilityMask capabilities; // services the app needs
+  GeaosAppLifecycle   lifecycle;
+} GeaosAppDescriptor;
+
+// Each app exports this single symbol. The loader resolves it (esp32: via the
+// fixed-slot/jump-table binding; Linux: dlsym / the IPC handshake), checks
+// abi_version + capabilities, then drives the lifecycle.
+#define GEAOS_APP_ENTRY_SYMBOL "geaos_app_descriptor"
+const GeaosAppDescriptor *geaos_app_descriptor(void);
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif

package/include/geolocation.h

@@ -0,0 +1,126 @@
+#pragma once
+
+namespace gea::framework::geolocation {
+
+namespace detail {
+
+// Read a numeric/bool field off a boxed record, keeping the fallback when the
+// field is absent. The value-bridges below run only at dynamic boundaries
+// (module-boundary records, boxed callbacks) — typed lowering never calls
+// them; they exist so the generated record converters compile (same pattern
+// as host/media.h).
+template <typename T, typename Value>
+T fieldOr(const Value &value, const char *name, T fallback)
+{
+	if constexpr (requires { value.record_get_literal(name); }) {
+		const auto field = value.record_get_literal(name);
+		if constexpr (requires { field.is_nullish(); static_cast<T>(field); }) {
+			if (!field.is_nullish()) return static_cast<T>(field);
+		}
+	}
+	return fallback;
+}
+
+}  // namespace detail
+
+struct GeolocationCoordinates {
+	double latitude = 0.0;
+	double longitude = 0.0;
+	double altitude = 0.0;
+	double accuracy = -1.0;
+	double altitudeAccuracy = -1.0;
+	double heading = -1.0;
+	double speed = -1.0;
+
+	template <typename Value>
+	static GeolocationCoordinates __gea_native_from_value(const Value &value)
+	{
+		GeolocationCoordinates out{};
+		out.latitude = detail::fieldOr(value, "latitude", out.latitude);
+		out.longitude = detail::fieldOr(value, "longitude", out.longitude);
+		out.altitude = detail::fieldOr(value, "altitude", out.altitude);
+		out.accuracy = detail::fieldOr(value, "accuracy", out.accuracy);
+		out.altitudeAccuracy = detail::fieldOr(value, "altitudeAccuracy", out.altitudeAccuracy);
+		out.heading = detail::fieldOr(value, "heading", out.heading);
+		out.speed = detail::fieldOr(value, "speed", out.speed);
+		return out;
+	}
+};
+
+struct GeolocationPosition {
+	GeolocationCoordinates coords;
+	double timestamp = 0.0;
+	bool hasFix = false;
+
+	template <typename Value>
+	static GeolocationPosition __gea_native_from_value(const Value &value)
+	{
+		GeolocationPosition out{};
+		if constexpr (requires { value.record_get_literal("coords"); }) {
+			const auto coords = value.record_get_literal("coords");
+			if constexpr (requires { coords.is_nullish(); }) {
+				if (!coords.is_nullish()) out.coords = GeolocationCoordinates::__gea_native_from_value(coords);
+			}
+		}
+		out.timestamp = detail::fieldOr(value, "timestamp", out.timestamp);
+		out.hasFix = detail::fieldOr(value, "hasFix", out.hasFix);
+		return out;
+	}
+};
+
+struct GeolocationPositionError {
+	double code = 2.0;
+	const char *message = "Position unavailable";
+
+	// `message` keeps its default: a boxed record's string has no storage a
+	// stable const char* could borrow from.
+	template <typename Value>
+	static GeolocationPositionError __gea_native_from_value(const Value &value)
+	{
+		GeolocationPositionError out{};
+		out.code = detail::fieldOr(value, "code", out.code);
+		return out;
+	}
+};
+
+struct GeolocationOptions {
+	bool enableHighAccuracy = false;
+	double timeout = 0.0;
+	double maximumAge = 0.0;
+
+	template <typename Value>
+	static GeolocationOptions __gea_native_from_value(const Value &value)
+	{
+		GeolocationOptions out{};
+		out.enableHighAccuracy = detail::fieldOr(value, "enableHighAccuracy", out.enableHighAccuracy);
+		out.timeout = detail::fieldOr(value, "timeout", out.timeout);
+		out.maximumAge = detail::fieldOr(value, "maximumAge", out.maximumAge);
+		return out;
+	}
+};
+
+class GeolocationDriver {
+public:
+	virtual ~GeolocationDriver() = default;
+
+	virtual bool init() = 0;
+	virtual bool hasFix() const = 0;
+	virtual GeolocationPosition currentPosition() const = 0;
+};
+
+class GeolocationAdapter {
+public:
+	static void setDriver(GeolocationDriver *driver);
+	static GeolocationDriver *driver();
+
+	bool init() const;
+	bool hasFix() const;
+	GeolocationPosition currentPosition() const;
+};
+
+inline GeolocationAdapter geolocation()
+{
+	return GeolocationAdapter{};
+}
+
+}  // namespace gea::framework::geolocation

package/include/gpio.h

@@ -0,0 +1,61 @@
+#pragma once
+
+// Digital pins, and a single-wire addressable LED strand.
+//
+// A board with no display still has to be able to say something. Until now the
+// only outputs an app could reach were the panel and the log, which left a bare
+// module — the exact hardware headless support was added for — with nothing it
+// could drive. These two are the smallest primitives that fix that: a pin you
+// can set, and the RGB LED that is the one output almost every devkit ships.
+//
+// Platforms without the hardware implement these as no-ops that report failure,
+// so an app written against them still runs everywhere; it simply lights
+// nothing. `ok` is therefore "this board did it", not "the call was valid".
+
+namespace gea::platform::gpio {
+
+class Gpio {
+public:
+	// Configure before use. Returns false when the pin is not a usable GPIO on
+	// this chip, or when the platform has no GPIO at all.
+	static bool configureOutput(int pin);
+	static bool configureInput(int pin, bool pull_up);
+	static bool write(int pin, bool level);
+	// Reads low as false. A pin that was never configured, or a platform with no
+	// GPIO, also reads false — callers that care must check configureInput().
+	static bool read(int pin);
+};
+
+// WS2812-family LED on one data pin: the "onboard RGB LED" of most ESP32-S3
+// devkits. Colours are staged by setPixel and only reach the strand on show(),
+// because the protocol rewrites the whole strand in one timed burst.
+class AddressableLed {
+public:
+	// The default way to turn one LED on or off: attaches the pin if it is not
+	// already attached, writes the colour and clocks it out, in one call. A
+	// board's "onboard LED" is a single WS2812 on one pin, and that case should
+	// not cost three calls and a piece of retained state to express. Black
+	// (0, 0, 0) is off.
+	static bool set(int pin, int r, int g, int b);
+
+	// Dark. The same thing as set(pin, 0, 0, 0) -- a WS2812 has no separate
+	// "off", black IS off -- spelled as its own verb because that is what a
+	// caller looks for, and because writing three zeros to mean "off" reads as
+	// an accident at the call site. The channel stays attached, so turning the
+	// LED back on costs one transmit and no re-allocation.
+	static bool off(int pin);
+
+	// The multi-pixel path, for a real strand where one transmit per FRAME beats
+	// one per pixel: attach once, setPixel each element, show to clock the whole
+	// buffer out. `set` is exactly these three for a strand of one.
+	static bool attach(int pin, int count);
+	static bool setPixel(int index, int r, int g, int b);
+	static bool show();
+
+	// Give the RMT channel back. The ESP32-S3 has four TX channels, so a strand
+	// an app has finished with should not hold one, and the pin can then be
+	// driven as a plain output again.
+	static void detach();
+};
+
+}  // namespace gea::platform::gpio