@geastack/core 0.1.39 → 0.1.40

package/events.cpp

@@ -46,6 +46,8 @@ const char *PointerEvent::typeName() const
 		return "click";
 	case PointerEventType::Input:
 		return "input";
+	case PointerEventType::KeyUp:
+		return "keyup";
 	case PointerEventType::KeyDown:
 		return "keydown";
 	case PointerEventType::Rotary:

package/gea_app_entry.cpp

@@ -268,7 +268,7 @@ void Application::frame(int timestampMs)
 	applicationFramePhaseSet(ApplicationFramePhase::DrainMicrotasks);
 	generated::drainMicrotasks();
 	applicationFramePhaseSet(ApplicationFramePhase::AnimationFrameCallbacks);
-	gea::host::runAnimationFrameCallbacks(static_cast<gea::host::AnimationFrameTimestamp>(timestampMs));
+	gea::host::runAnimationFrameCallbacks(timestampMs);
 	generated::drainMicrotasks();
 	applicationFramePhaseSet(ApplicationFramePhase::Idle);
 #else
@@ -294,7 +294,7 @@ void Application::frame(int timestampMs)
 
 	startUs = phaseClockUs();
 	applicationFramePhaseSet(ApplicationFramePhase::AnimationFrameCallbacks);
-	gea::host::runAnimationFrameCallbacks(static_cast<double>(timestampMs));
+	gea::host::runAnimationFrameCallbacks(timestampMs);
 	applicationFramePhaseSet(ApplicationFramePhase::CallbackMicrotasks);
 	generated::drainMicrotasks();
 	recordFramePhase(ApplicationFramePhase::AnimationFrameCallbacks, phaseClockUs() - startUs);

package/gea_sources.mjs

@@ -59,7 +59,8 @@ export function includeFlags(env = process.env) {
     join(elements, 'ui'),
     geaos,
     join(engine, 'vendor/stb'),
-    join(engine, 'vendor/AnimatedGIF')
+    join(engine, 'vendor/AnimatedGIF'),
+    ...(env.GEA_COMPILER_RUNTIME ? [env.GEA_COMPILER_RUNTIME] : [])
   ].map((dir) => `-I${dir}`)
 }
 
@@ -87,8 +88,8 @@ export function cxxSources(env = process.env) {
     // @geastack/host — platform layer + services
     ...cpp(host, ['input', 'wifi', 'bluetooth', 'geolocation']),
     ...cpp(join(host, 'host'), [
-      'timers', 'worker', 'input', 'display', 'fetch', 'media', 'rtc', 'websocket', 'http', 'wifi',
-      'ble', 'apps', 'audio', 'audio_worklet', 'video', 'mjpeg', 'image', 'touch', 'imu', 'memory', 'camera', 'geolocation',
+      'timers', 'worker', 'input', 'device', 'display', 'fetch', 'media', 'rtc', 'websocket', 'http', 'wifi',
+      'ble', 'apps', 'audio', 'audio_worklet', 'audio_buffer_runtime', 'video', 'mjpeg', 'image', 'touch', 'imu', 'memory', 'camera', 'geolocation',
       'tile_loader'
     ]),
     // framework services (built on the platform abstraction — no target-specific deps)

package/include/audio.h

@@ -7,8 +7,18 @@
 #include <string>
 #include <functional>
 
+// Physical capture/mixer clock shared by the board driver and native hosts.
+// AudioContext and network PCM may use other rates through their resamplers.
+#ifndef GEA_AUDIO_DEVICE_SAMPLE_RATE
+#define GEA_AUDIO_DEVICE_SAMPLE_RATE 16000
+#endif
+
 namespace gea::platform::audio {
 
+inline constexpr int deviceSampleRate = GEA_AUDIO_DEVICE_SAMPLE_RATE;
+static_assert(deviceSampleRate >= 8000 && deviceSampleRate <= 48000,
+              "Audio device sample rate must be between 8000 and 48000 Hz");
+
 enum class OscillatorType {
 	Sine = 0,
 	Square = 1,
@@ -74,7 +84,7 @@ public:
 	static bool playPcm(const std::int16_t *samples, std::size_t sample_count, int sample_rate, int channels);
 	static void stopPlayback();
 	static void flushPlayback();
-	// Continuous 16 kHz mono source; zero means the platform could not attach it.
+	// Continuous mono source at deviceSampleRate; zero means the platform could not attach it.
 	static std::uint64_t playPcmStream(std::function<std::size_t(std::int16_t*, std::size_t)> pull);
 	static void stopPcmStream(std::uint64_t stream);
 	static bool pcmStreamSettled(std::uint64_t stream);

package/include/audio_oscillator.h

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <algorithm>
+#include <optional>
+
+namespace gea::platform::audio {
+
+// Worklet render time and the physical output scheduler can have different
+// origins. Translate an explicit context deadline at the host boundary.
+inline double physicalAudioDeadline(double when, double contextNow,
+                                    double physicalNow) {
+  return when > 0 ? physicalNow + when - contextNow : when;
+}
+
+struct FiniteToneTiming {
+  int durationMs;
+  int delayMs;
+};
+
+// The embedded oscillator backend schedules one finite tone when stop() is
+// first called. It does not support replacing/cancelling an already queued
+// individual voice. Further stops must never submit that voice a second time.
+class FiniteOscillatorSchedule {
+public:
+  void start(double when, double now) {
+    startTime_ = when > 0 ? when : now;
+    started_ = true;
+    submitted_ = false;
+  }
+
+  std::optional<FiniteToneTiming> stop(double when, double now) {
+    if (submitted_)
+      return std::nullopt;
+    submitted_ = true;
+    const double start = started_ ? startTime_ : now;
+    const double end = std::max(when > 0 ? when : now, start);
+    const int duration =
+        static_cast<int>(std::min((end - start) * 1000.0 + 0.5, 2500.0));
+    if (duration <= 0)
+      return std::nullopt;
+    return FiniteToneTiming{
+        duration, static_cast<int>(std::max(start - now, 0.0) * 1000.0 + 0.5)};
+  }
+
+private:
+  double startTime_ = 0;
+  bool started_ = false;
+  bool submitted_ = false;
+};
+
+} // namespace gea::platform::audio

package/include/camera.h

@@ -3,6 +3,7 @@
 #include "pixel.h"
 
 #include <cstdint>
+#include <atomic>
 #include <string>
 
 namespace gea::platform::camera {
@@ -20,6 +21,14 @@ struct DeviceInfo {
 	int sensorHeight = 0;
 };
 
+// Optional encoded-frame producer. The device owns capture/encoding on its
+// worker; reading a frame never waits for a sensor or codec on the UI thread.
+class CameraFrameProvider {
+public:
+	virtual ~CameraFrameProvider() = default;
+	virtual std::string takeFrameDataUrl() = 0;
+};
+
 // Static facade — one active camera at a time on the device. The platform
 // layer maintains the live preview buffer and exposes a small surface that
 // the host bridge forwards into.
@@ -36,6 +45,12 @@ public:
 	static void close();
 	static bool isOpen();
 
+	static void setFrameProvider(CameraFrameProvider *provider) { frameProvider().store(provider); }
+	static std::string captureFrame() {
+		auto *provider = frameProvider().load();
+		return provider ? provider->takeFrameDataUrl() : std::string();
+	}
+
 	static int width();
 	static int height();
 	static int orientation();
@@ -102,6 +117,12 @@ public:
 	static void setWhiteBalance(const std::string &mode, double temperatureK, double tint);
 	static void setFocus(const std::string &mode, double pointX, double pointY);
 	static void setTorch(const std::string &mode, double level);
+
+private:
+	static std::atomic<CameraFrameProvider *> &frameProvider() {
+		static std::atomic<CameraFrameProvider *> provider{nullptr};
+		return provider;
+	}
 };
 
 }  // namespace gea::platform::camera

package/include/captive_dns.h

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+
+namespace gea::framework::network {
+
+// A bounded DNS responder for AP captive portals. Rebuild the question name
+// to avoid retaining compression pointers into discarded additional records.
+inline std::size_t captiveDnsReply(const std::uint8_t *query,
+                                   std::size_t length,
+                                   const std::uint8_t address[4],
+                                   std::uint8_t *reply, std::size_t capacity) {
+  if (length < 12 || length > 512 || capacity < 12 || (query[2] & 0xf8) ||
+      query[4] != 0 || query[5] != 1)
+    return 0;
+  std::memcpy(reply, query, 12);
+  reply[2] = 0x80 | (query[2] & 1);
+  reply[3] = 0x80;
+  std::memset(reply + 6, 0, 6);
+  std::size_t source = 12, target = 12, questionEnd = 0, jumps = 0,
+              nameBytes = 0;
+  for (;;) {
+    if (source >= length)
+      return 0;
+    const auto count = query[source++];
+    if ((count & 0xc0) == 0xc0) {
+      if (source >= length || ++jumps > 8)
+        return 0;
+      const auto offset = ((count & 0x3f) << 8) | query[source++];
+      if (!questionEnd)
+        questionEnd = source;
+      if (offset >= length)
+        return 0;
+      source = offset;
+      continue;
+    }
+    if (count > 63 || source + count > length ||
+        target + count + 1 > capacity || (nameBytes += count + 1) > 255)
+      return 0;
+    reply[target++] = count;
+    if (!count)
+      break;
+    std::memcpy(reply + target, query + source, count);
+    target += count;
+    source += count;
+  }
+  if (!questionEnd)
+    questionEnd = source;
+  if (questionEnd + 4 > length || target + 4 > capacity)
+    return 0;
+  const auto type = (query[questionEnd] << 8) | query[questionEnd + 1];
+  const auto klass = (query[questionEnd + 2] << 8) | query[questionEnd + 3];
+  std::memcpy(reply + target, query + questionEnd, 4);
+  target += 4;
+  // AAAA and other record types receive an empty successful answer so clients
+  // can issue their IPv4 query; this portal only owns its AP IPv4 address.
+  if (klass != 1 || (type != 1 && type != 255))
+    return target;
+  if (target + 16 > capacity)
+    return 0;
+  constexpr std::uint8_t answer[] = {0xc0, 0x0c, 0, 1, 0, 1, 0, 0, 0, 30, 0, 4};
+  std::memcpy(reply + target, answer, sizeof(answer));
+  std::memcpy(reply + target + sizeof(answer), address, 4);
+  reply[7] = 1;
+  return target + 16;
+}
+
+} // namespace gea::framework::network

package/include/display_present.h

@@ -97,6 +97,7 @@ struct HeapCapsFree {
 static constexpr int kInlineCircleEntryCapacity = 32;
 
 struct Command {
+	gea::framework::graphics::ImageReference imageReference;
 	using CircleEntry = gea::framework::graphics::CircleEntry;
 
 	gea::platform::display::DisplayPresentCommandType type =
@@ -149,6 +150,9 @@ struct Command {
 
 struct Frame {
 	std::vector<Command> commands;
+	// Embedded canvas batches preserve bitmap drawing semantics: circle painter
+	// order and the established triangle edge rasterization remain observable.
+	bool bitmapSemantics = false;
 
 	void clear()
 	{
@@ -308,29 +312,44 @@ inline bool commandsEqual(const Command &a, const Command &b)
 	case Type::FillCircleRgb565:
 	case Type::StrokeCircleRgb565:
 		return a.x == b.x && a.y == b.y && a.radius == b.radius && a.color == b.color;
-	case Type::FillCirclesRgb565: {
-		if (a.radius != b.radius || a.circlesCount != b.circlesCount) return false;
-		if (a.circlesCount == 0) return true;
+	case Type::FillCirclesRgb565:
+	{
+		if (a.radius != b.radius || a.circlesCount != b.circlesCount)
+			return false;
+		if (a.circlesCount == 0)
+			return true;
 		const auto *ap = a.circleEntries();
 		const auto *bp = b.circleEntries();
-		if (!ap || !bp) return ap == bp;
-		return std::memcmp(ap, bp,
-		                   static_cast<std::size_t>(a.circlesCount) *
-		                       sizeof(gea::framework::graphics::CircleEntry)) == 0;
+		if (!ap || !bp)
+			return ap == bp;
+		for (int i = 0; i < a.circlesCount; ++i)
+			if (ap[i].x != bp[i].x || ap[i].y != bp[i].y || ap[i].color != bp[i].color)
+				return false;
+		return true;
 	}
-	case Type::FillTrianglesRgb565: {
-		if (a.trianglesCount != b.trianglesCount) return false;
-		if (a.trianglesCount == 0) return true;
+	case Type::FillTrianglesRgb565:
+	{
+		if (a.trianglesCount != b.trianglesCount)
+			return false;
+		if (a.trianglesCount == 0)
+			return true;
 		const auto *ap = a.trianglesBuffer.get();
 		const auto *bp = b.trianglesBuffer.get();
-		if (!ap || !bp) return ap == bp;
-		return std::memcmp(ap, bp,
-		                   static_cast<std::size_t>(a.trianglesCount) *
-		                       sizeof(gea::framework::graphics::TriangleEntry)) == 0;
+		if (!ap || !bp)
+			return ap == bp;
+		for (int i = 0; i < a.trianglesCount; ++i)
+		{
+			const auto &x = ap[i];
+			const auto &y = bp[i];
+			if (x.x0 != y.x0 || x.y0 != y.y0 || x.x1 != y.x1 || x.y1 != y.y1 || x.x2 != y.x2 ||
+				x.y2 != y.y2 || x.color != y.color || x.rowY0 != y.rowY0 || x.rowY1 != y.rowY1)
+				return false;
+		}
+		return true;
 	}
 	case Type::DrawImage:
 		return a.pixels == b.pixels && a.alphaPixels == b.alphaPixels && imagePixelsStable(a) &&
-		       a.srcWidth == b.srcWidth && a.srcHeight == b.srcHeight && a.x == b.x && a.y == b.y;
+			   a.srcWidth == b.srcWidth && a.srcHeight == b.srcHeight && a.x == b.x && a.y == b.y;
 	case Type::DrawImageScaled:
 	case Type::DrawImageRotated90CW:
 		return a.pixels == b.pixels && a.alphaPixels == b.alphaPixels && imagePixelsStable(a) &&
@@ -347,8 +366,9 @@ inline bool commandsEqual(const Command &a, const Command &b)
 	return false;
 }
 
-inline bool extractFrame(const gea::platform::display::DisplayPresentCommand *commands, int commandCount, Frame &frame)
+inline bool extractFrame(const gea::platform::display::DisplayPresentCommand *commands, int commandCount, Frame &frame, bool bitmapSemantics = false)
 {
+	frame.bitmapSemantics = bitmapSemantics;
 	frame.clear();
 	if (!commands || commandCount <= 0) return false;
 	frame.commands.reserve(static_cast<std::size_t>(commandCount));
@@ -435,7 +455,7 @@ inline bool extractFrame(const gea::platform::display::DisplayPresentCommand *co
 					}
 					bool sortedByBucket = false;
 					constexpr int kCircleBucketSortMaxYRange = 2048;
-					if (count <= 65535) {
+					if (!bitmapSemantics && count <= 65535) {
 						int minY = static_cast<int>(src.ys[0]);
 						int maxY = minY;
 						for (int i = 1; i < count; i++) {
@@ -466,8 +486,9 @@ inline bool extractFrame(const gea::platform::display::DisplayPresentCommand *co
 						for (int i = 0; i < count; i++) {
 							buffer[i] = CircleEntry{src.ys[i], src.xs[i], src.colors[i]};
 						}
-						std::sort(buffer, buffer + count,
-							[](const CircleEntry &a, const CircleEntry &b) { return a.y < b.y; });
+						if (!bitmapSemantics)
+							std::sort(buffer, buffer + count,
+								[](const CircleEntry &a, const CircleEntry &b) { return a.y < b.y; });
 					}
 					if (!out.circlesInline) out.circlesBuffer.reset(buffer);
 				}
@@ -571,6 +592,8 @@ inline bool extractFrame(const gea::platform::display::DisplayPresentCommand *co
 			out.alpha = command.fillText.alpha;
 			break;
 		}
+		out.imageReference = gea::framework::graphics::ImageReference(
+			gea::framework::graphics::ImageStore::instance().idForPixels(out.pixels));
 		frame.commands.push_back(std::move(out));
 	}
 	return true;
@@ -696,7 +719,8 @@ inline void rasterCommandRows(gea::framework::graphics::Canvas &canvas,
                               int row,
                               int chunkRows,
                               int displayHeight,
-                              const Command &command)
+                              const Command &command,
+                              bool bitmapSemantics = false)
 {
 	if (!buffer) return;
 	using Type = gea::platform::display::DisplayPresentCommandType;
@@ -765,6 +789,13 @@ inline void rasterCommandRows(gea::framework::graphics::Canvas &canvas,
 		canvas.strokeCircle(command.x - ox, command.y - oy, command.radius, command.color);
 		break;
 	case Type::FillCirclesRgb565: {
+		if (bitmapSemantics) {
+			const auto *circles = command.circleEntries();
+			for (int i = 0; circles && i < command.circlesCount; ++i)
+				canvas.fillCircle(int(circles[i].x) - ox, int(circles[i].y) - oy,
+				    command.radius, circles[i].color);
+			break;
+		}
 		// Hand the whole sorted batch to Canvas's optimized batch entrypoint.
 		// It inlines fillCircleNoDirty's hot path and uses [chunkY0, chunkY1]
 		// as a world-Y band to skip leading + break trailing in one loop.
@@ -777,21 +808,28 @@ inline void rasterCommandRows(gea::framework::graphics::Canvas &canvas,
 		break;
 	}
 	case Type::FillTrianglesRgb565: {
-		// Depth-ordered batch (farthest-first). OPAQUE batches take the span-
-		// occlusion path (front-to-back, each pixel written once); it band-rejects
-		// per chunk internally. TRANSLUCENT must stay painter's back-to-front.
+		// Full-display opaque 3D batches retain their front-to-back occlusion
+		// optimization. Bitmap canvas batches and translucent geometry replay
+		// in producer order, rejecting triangles outside this strip first.
 		const gea::framework::graphics::TriangleEntry *tris = command.trianglesBuffer.get();
 		const int count = command.trianglesCount;
 		if (!tris) break;
-		if (command.alpha == 255) {
+		if (command.alpha == 255 && !bitmapSemantics) {
 			canvas.fillTrianglesOpaqueOccluded(tris, count, ox, oy);
 		} else {
+			// Retained canvas batches preserve producer order. Sparse numeric
+			// geometry needs no coverage bitset; opaque spans avoid per-pixel
+			// comparisons while sharing the public triangle edge definition.
 			const int chunkY1 = row + chunkRows - 1;
 			for (int i = 0; i < count; i++) {
 				const auto &t = tris[i];
 				if (t.rowY1 < row || t.rowY0 > chunkY1) continue;
-				canvas.fillTriangle(t.x0 - ox, t.y0 - oy, t.x1 - ox, t.y1 - oy,
-				                    t.x2 - ox, t.y2 - oy, t.color);
+				if (command.alpha == 255)
+					canvas.fillTriangleOpaque(t.x0 - ox, t.y0 - oy, t.x1 - ox, t.y1 - oy,
+					                         t.x2 - ox, t.y2 - oy, t.color);
+				else
+					canvas.fillTriangle(t.x0 - ox, t.y0 - oy, t.x1 - ox, t.y1 - oy,
+					                    t.x2 - ox, t.y2 - oy, t.color);
 			}
 		}
 		break;
@@ -851,7 +889,7 @@ inline void rasterFrameRows(gea::framework::graphics::pixel::native_t *buffer,
 	gea::framework::graphics::Canvas canvas;
 	canvas.bindPixels(buffer, regionWidth, chunkRows);
 	for (const Command &command : frame.commands) {
-		rasterCommandRows(canvas, buffer, regionX0, regionWidth, row, chunkRows, displayHeight, command);
+		rasterCommandRows(canvas, buffer, regionX0, regionWidth, row, chunkRows, displayHeight, command, frame.bitmapSemantics);
 	}
 }
 
@@ -879,7 +917,7 @@ inline void rasterFrameRowsStrided(gea::framework::graphics::pixel::native_t *bu
 			}
 			continue;
 		}
-		rasterCommandRows(canvas, buffer, regionX0, regionWidth, row, chunkRows, displayHeight, command);
+		rasterCommandRows(canvas, buffer, regionX0, regionWidth, row, chunkRows, displayHeight, command, frame.bitmapSemantics);
 	}
 }
 

package/include/events.h

@@ -4,6 +4,7 @@
 
 #include <cstdint>
 #include <functional>
+#include <memory>
 
 namespace gea::framework::events {
 
@@ -15,7 +16,8 @@ enum class PointerEventType {
 	Input,
 	KeyDown,
 	Rotary,
-	Scroll
+	Scroll,
+	KeyUp
 };
 
 enum class EventPhase {
@@ -51,6 +53,32 @@ struct TouchPoint {
 	int pageY = 0;
 };
 
+// Native callback lowering may copy the event carrier. Its cancellation flags
+// still belong to the same dispatched event, including copies retained later.
+// Allocate shared storage only when a carrier is actually copied.
+class EventControlFlag {
+public:
+  EventControlFlag(bool value = false) : initial_(value) {}
+  EventControlFlag(const EventControlFlag &other) : shared_(other.share()) {}
+  EventControlFlag &operator=(const EventControlFlag &other) {
+    if (this != &other) shared_ = other.share();
+    return *this;
+  }
+  EventControlFlag &operator=(bool value) {
+    if (shared_) *shared_ = value;
+    else initial_ = value;
+    return *this;
+  }
+  operator bool() const { return shared_ ? *shared_ : initial_; }
+private:
+  std::shared_ptr<bool> share() const {
+    if (!shared_) shared_ = std::make_shared<bool>(initial_);
+    return shared_;
+  }
+  bool initial_ = false;
+  mutable std::shared_ptr<bool> shared_;
+};
+
 struct PointerEvent {
 	PointerEventType type;
 	EventTarget target{};
@@ -73,8 +101,8 @@ struct PointerEvent {
 	bool primary = true;
 	bool bubbles = true;
 	bool cancelable = true;
-	bool defaultPrevented = false;
-	bool propagationStopped = false;
+	EventControlFlag defaultPrevented;
+	EventControlFlag propagationStopped;
 	EventPhase eventPhase = EventPhase::None;
 	TouchPoint touches[1]{};
 	TouchPoint targetTouches[1]{};

package/include/gea/embedded.h

@@ -11,3 +11,5 @@
 #include "gea/embedded-host.h"
 #include "ui/document.h"
 #include "ui/signal.h"
+// Debug builds: attributes JSX listeners to nodes for DevTools.
+#include "ui/debugger_listeners.h"

package/include/graphics/font.h

@@ -13,6 +13,7 @@ struct Glyph {
 	int advance = 0;
 	int bearingX = 0;
 	int bearingY = 0;
+	int advance16 = -1;
 };
 
 class Font {
@@ -25,6 +26,12 @@ public:
 	virtual int ascender() const = 0;
 	virtual bool glyph(int codepoint, Glyph *out) const = 0;
 	virtual std::uint8_t coverage(const Glyph &glyph, int row, int col) const = 0;
+	virtual int advance(int codepoint, int nextCodepoint = 0) const
+	{
+		(void)nextCodepoint;
+		Glyph value{};
+		return glyph(codepoint, &value) ? value.advance : sizePx() / 2;
+	}
 };
 
 class BitmapFont : public Font {
@@ -63,6 +70,13 @@ private:
 	static const std::uint8_t glyphs[kGlyphCount][kHeight];
 };
 
+struct FontKerningPair
+{
+	int left = 0;
+	int right = 0;
+	int adjustment16 = 0;
+};
+
 struct RasterizedFontData {
 	int id = 0;
 	int sizePx = 0;
@@ -80,6 +94,10 @@ struct RasterizedFontData {
 	// byte-aligned (stride = (atlasWidth + 3) / 4) and the leftmost pixel of a
 	// byte sits in the most significant bit pair.
 	int atlasBits = 8;
+	int kerningCount = 0;
+	const FontKerningPair *kerning = nullptr;
+	bool strictGlyphLookup = false;
+	int fallbackCodepoint = -1;
 };
 
 class RasterizedFont final : public Font {
@@ -93,6 +111,7 @@ public:
 	int ascender() const final;
 	bool glyph(int codepoint, Glyph *out) const final;
 	std::uint8_t coverage(const Glyph &glyph, int row, int col) const final;
+	int advance(int codepoint, int nextCodepoint = 0) const final;
 	const RasterizedFontData *data() const { return data_; }
 
 private:

package/include/image.h

@@ -3,6 +3,7 @@
 #include "pixel.h"
 
 #include <cstdint>
+#include <utility>
 
 #if GEA_EMBEDDED_SINGLE_THREAD_IMAGE_STORE
 namespace gea::framework::graphics {
@@ -26,7 +27,10 @@ using ImageStoreMutex = std::mutex;
 // tile-grid app (maps) keep ~4 screens of decoded tiles resident in PSRAM for
 // instant pan-back, on top of its persistent SD cache. ~128 KiB/tile (RGB565
 // 256x256) when full → ~12 MiB; the P4 has ample PSRAM.
-inline constexpr int kImageMax = 96;
+#ifndef GEA_EMBEDDED_MAX_IMAGES
+#define GEA_EMBEDDED_MAX_IMAGES 96
+#endif
+inline constexpr int kImageMax = GEA_EMBEDDED_MAX_IMAGES;
 
 enum class ImageFit {
 	Fill = 0,
@@ -119,6 +123,10 @@ public:
 	const pixel::native_t *framePixels(int id, int frame) const;
 	const pixel::native_t *currentPixels(int id) const;
 	const std::uint8_t *currentAlpha(int id) const;
+	// Pins keep decoded pixels alive for nodes and retained render commands.
+	bool retain(int id);
+	void release(int id);
+	int idForPixels(const pixel::native_t *pixels) const;
 	void dispose(int id);
 	void disposeAll();
 	ImageFormat detectFormat(const std::uint8_t *data, int length) const;
@@ -150,6 +158,8 @@ private:
 
 	ImageSlot images_[kImageMax]{};
 	bool used_[kImageMax]{};
+	unsigned references_[kImageMax]{};
+	bool retired_[kImageMax]{};
 	// Guards slot ALLOCATION and DISPOSAL only (reservation-style): the async
 	// tile loader decodes on the second core while the frame task blits and
 	// evicts. A decode reserves its slot under the lock, then fills it
@@ -159,4 +169,32 @@ private:
 	mutable ImageStoreMutex slotMutex_;
 };
 
+// Copyable ownership for retained commands; raw pixel pointers alone do not
+// keep a decoded slot alive.
+class ImageReference {
+public:
+	ImageReference() = default;
+	explicit ImageReference(int id) : id_(ImageStore::instance().retain(id) ? id : -1) {}
+	ImageReference(const ImageReference &other) : ImageReference(other.id_) {}
+	ImageReference(ImageReference &&other) noexcept : id_(other.id_) { other.id_ = -1; }
+	~ImageReference() { ImageStore::instance().release(id_); }
+	ImageReference &operator=(const ImageReference &other) {
+		if (this != &other) {
+			ImageReference next(other);
+			std::swap(id_, next.id_);
+		}
+		return *this;
+	}
+	ImageReference &operator=(ImageReference &&other) noexcept {
+		if (this != &other) {
+			ImageStore::instance().release(id_);
+			id_ = other.id_;
+			other.id_ = -1;
+		}
+		return *this;
+	}
+private:
+	int id_ = -1;
+};
+
 }  // namespace gea::framework::graphics

package/include/input.h

@@ -27,7 +27,18 @@ int consumeRotaryDelta();
 // `keydown` event. keyCode 0 is ignored.
 void queueKeyDown(int keyCode);
 
+// Queue a release in the same ordered stream as key presses.
+void queueKeyUp(int keyCode);
+
+struct HardwareKeyEvent {
+  int keyCode;
+  bool pressed;
+};
+
+// Consume the oldest press or release without changing their order.
+bool consumeKeyEvent(HardwareKeyEvent &event);
+
 // Reads and clears the oldest pending key press. Returns 0 when none pending.
 int consumeKeyDown();
 
-}  // namespace gea::framework::input
+} // namespace gea::framework::input