@geastack/apple 0.2.8

package/targets/macos/main/canvas_view.mm

@@ -0,0 +1,176 @@
+#import "canvas_view.h"
+
+#include "ui/tree_internal.h"
+#include "canvas.h"
+#include "events.h"
+#include "host/display_orientation.h"
+#include "pixel.h"
+
+#include <algorithm>
+#include <cmath>
+
+extern "C" void gea_macos_touch_set_state(int touching, int x, int y);
+
+namespace {
+
+// Single shared scratch buffer for RGB565→RGBA8888 expansion. Sized lazily to
+// the largest canvas seen. -drawRect: is main-thread-only so no locking.
+std::uint8_t *g_scratch = nullptr;
+size_t g_scratchBytes = 0;
+
+std::uint8_t *ensureScratch(size_t bytes)
+{
+	if (g_scratchBytes < bytes) {
+		void *grown = std::realloc(g_scratch, bytes);
+		if (!grown) return nullptr;
+		g_scratch = static_cast<std::uint8_t *>(grown);
+		g_scratchBytes = bytes;
+	}
+	return g_scratch;
+}
+
+}  // namespace
+
+@implementation GeaCanvasView
+
+- (instancetype)initWithFrame:(NSRect)frame
+{
+	self = [super initWithFrame:frame];
+	if (self) {
+		_nodeId = -1;
+	}
+	return self;
+}
+
+// Stay UNFLIPPED. The canvas pixel buffer is stored top-down (row 0 = top),
+// which is what CGContextDrawImage expects when the destination context uses
+// default Quartz (bottom-up) coords. Setting isFlipped:YES would make AppKit
+// apply an implicit Y-inversion and the image would render upside-down. The
+// renderer that positions this view already converts CSS top-left coords to
+// AppKit bottom-left when computing our frame, so unflipped is correct.
+- (BOOL)isFlipped { return NO; }
+
+// Mouse → framework touch events, mirroring the iOS renderer's dispatchTouch
+// flow. Canvas apps (maps, games) read gesture coordinates off onPointerDown/
+// Move/Up — the AppKit click recognizer only fires coordinate-less presses, so
+// without this a drag never pans and every tap lands at 0,0. The recognizer's
+// delegate declines canvas views, so events arrive here exactly once.
+- (BOOL)acceptsFirstMouse:(NSEvent *)event
+{
+	(void)event;
+	return YES;
+}
+
+- (void)dispatchMousePhase:(gea::framework::events::TouchPhase)phase
+                  touching:(bool)touching
+                     event:(NSEvent *)event
+{
+	if (self.nodeId < 0) return;
+	auto &tree = gea::embedded::ui::Tree::instance();
+	if (self.nodeId >= tree.nodeCount()) return;
+	const auto *canvas = tree.canvas(self.nodeId);
+	const NSRect bounds = self.bounds;
+	if (!canvas || bounds.size.width <= 0 || bounds.size.height <= 0) return;
+
+	// View point (bottom-up) → top-down surface coords, scaled to the canvas
+	// pixel grid (drawRect stretches the canvas into the view bounds, so input
+	// must apply the inverse of that stretch to stay aligned).
+	const NSPoint p = [self convertPoint:event.locationInWindow fromView:nil];
+	const double scaleX = canvas->width() / bounds.size.width;
+	const double scaleY = canvas->height() / bounds.size.height;
+	const int lx = std::clamp((int)std::lround(p.x * scaleX), 0, canvas->width() - 1);
+	const int ly = std::clamp((int)std::lround((bounds.size.height - 1 - p.y) * scaleY), 0,
+	                          canvas->height() - 1);
+
+	// The latest-move cache holds PANEL-NATIVE coordinates (the hardware touch
+	// controller contract): the dispatcher re-reads Move coords from it through
+	// transformTouchToLogical, so store the inverse-transformed point.
+	namespace od = gea::framework::display::detail;
+	using gea::framework::display::DisplayOrientation;
+	int px = lx;
+	int py = ly;
+	switch (od::DisplayOrientationState::orientation()) {
+	case DisplayOrientation::LandscapePrimary:
+		px = ly;
+		py = od::DisplayOrientationState::nativeHeight() - 1 - lx;
+		break;
+	case DisplayOrientation::LandscapeSecondary:
+		px = od::DisplayOrientationState::nativeWidth() - 1 - ly;
+		py = lx;
+		break;
+	case DisplayOrientation::PortraitSecondary:
+		px = od::DisplayOrientationState::nativeWidth() - 1 - lx;
+		py = od::DisplayOrientationState::nativeHeight() - 1 - ly;
+		break;
+	case DisplayOrientation::PortraitPrimary:
+	default:
+		break;
+	}
+	gea_macos_touch_set_state(touching ? 1 : 0, px, py);
+
+	gea::framework::events::Event ev{};
+	ev.type = gea::framework::events::EventType::Touch;
+	ev.touchPhase = phase;
+	ev.touching = touching;
+	ev.x = lx;
+	ev.y = ly;
+	ev.pointerId = 0;
+	gea::framework::events::TouchRuntime::dispatchEvent(ev);
+}
+
+- (void)mouseDown:(NSEvent *)event
+{
+	[self dispatchMousePhase:gea::framework::events::TouchPhase::Down touching:true event:event];
+}
+
+- (void)mouseDragged:(NSEvent *)event
+{
+	[self dispatchMousePhase:gea::framework::events::TouchPhase::Move touching:true event:event];
+}
+
+- (void)mouseUp:(NSEvent *)event
+{
+	[self dispatchMousePhase:gea::framework::events::TouchPhase::Up touching:false event:event];
+}
+
+- (void)drawRect:(NSRect)dirtyRect
+{
+	(void)dirtyRect;
+	if (self.nodeId < 0) return;
+	auto &tree = gea::embedded::ui::Tree::instance();
+	if (self.nodeId >= tree.nodeCount()) return;
+	const auto *canvas = tree.canvas(self.nodeId);
+	if (!canvas) return;
+	const std::uint16_t *src = canvas->pixels();
+	const int w = canvas->width();
+	const int h = canvas->height();
+	if (!src || w <= 0 || h <= 0) return;
+
+	const size_t bytes = (size_t)w * (size_t)h * 4;
+	std::uint8_t *dst = ensureScratch(bytes);
+	if (!dst) return;
+	for (int i = 0; i < w * h; i++) {
+		int r, g, b;
+		gea::framework::graphics::pixel::unpackRgb565(src[i], &r, &g, &b);
+		dst[i * 4 + 0] = static_cast<std::uint8_t>((r * 255 + 15) / 31);
+		dst[i * 4 + 1] = static_cast<std::uint8_t>((g * 255 + 31) / 63);
+		dst[i * 4 + 2] = static_cast<std::uint8_t>((b * 255 + 15) / 31);
+		dst[i * 4 + 3] = 0xFF;
+	}
+
+	CGColorSpaceRef cs = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+	CGDataProviderRef provider = CGDataProviderCreateWithData(NULL, dst, bytes, NULL);
+	const uint32_t bitmapInfo = (uint32_t)kCGImageAlphaNoneSkipLast | (uint32_t)kCGBitmapByteOrder32Big;
+	CGImageRef img = CGImageCreate((size_t)w, (size_t)h, 8, 32, (size_t)w * 4,
+	                               cs, bitmapInfo,
+	                               provider, NULL, false, kCGRenderingIntentDefault);
+
+	CGContextRef ctx = [[NSGraphicsContext currentContext] CGContext];
+	CGContextDrawImage(ctx, NSRectToCGRect(self.bounds), img);
+
+	CGImageRelease(img);
+	CGDataProviderRelease(provider);
+	CGColorSpaceRelease(cs);
+}
+
+@end

package/targets/macos/main/color_convert.h

@@ -0,0 +1,18 @@
+#pragma once
+
+#include <cstdint>
+
+#ifdef __OBJC__
+@class NSColor;
+#endif
+
+namespace gea::macos {
+
+#ifdef __OBJC__
+NSColor *rgb565ToNSColor(std::uint16_t rgb565);
+#endif
+
+// Caller-owns the returned CGColorRef; release with CGColorRelease.
+struct CGColor *rgb565ToCGColor(std::uint16_t rgb565);
+
+}  // namespace gea::macos

package/targets/macos/main/color_convert.mm

@@ -0,0 +1,39 @@
+#import <AppKit/AppKit.h>
+
+#include "color_convert.h"
+#include "pixel.h"
+
+namespace gea::macos {
+
+namespace {
+
+void unpack(std::uint16_t rgb565, CGFloat *r, CGFloat *g, CGFloat *b)
+{
+	int ri, gi, bi;
+	gea::framework::graphics::pixel::unpackRgb565(rgb565, &ri, &gi, &bi);
+	*r = static_cast<CGFloat>(ri) / 31.0;
+	*g = static_cast<CGFloat>(gi) / 63.0;
+	*b = static_cast<CGFloat>(bi) / 31.0;
+}
+
+}  // namespace
+
+NSColor *rgb565ToNSColor(std::uint16_t rgb565)
+{
+	CGFloat r, g, b;
+	unpack(rgb565, &r, &g, &b);
+	return [NSColor colorWithSRGBRed:r green:g blue:b alpha:1.0];
+}
+
+CGColor *rgb565ToCGColor(std::uint16_t rgb565)
+{
+	CGFloat r, g, b;
+	unpack(rgb565, &r, &g, &b);
+	CGFloat comps[4] = {r, g, b, 1.0};
+	CGColorSpaceRef cs = CGColorSpaceCreateWithName(kCGColorSpaceSRGB);
+	CGColorRef color = CGColorCreate(cs, comps);
+	CGColorSpaceRelease(cs);
+	return color;
+}
+
+}  // namespace gea::macos

package/targets/macos/main/font_registry.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#include <cstdint>
+
+#ifdef __OBJC__
+#import <AppKit/AppKit.h>
+@class NSFont;
+@class NSString;
+#endif
+
+namespace gea::macos {
+
+#ifdef __OBJC__
+// Returns an NSFont for the given gea font id at the requested pixel size.
+// fontId comes from the framework's lookupFontFamily which we override below
+// to assign stable ids the first time each family is seen. Unknown ids fall
+// back to the system font.
+NSFont *fontForId(int fontId, int sizePx);
+
+// Walks `directoryPath` for .ttf / .otf files and registers each with
+// CTFontManager in the process scope. Returns the count of newly registered
+// fonts; already-registered files are silently skipped. Call once at startup
+// after the app bundle is known.
+int registerCustomTtfDirectory(NSString *directoryPath);
+
+// Picks the right NSLineBreakMode for `text` rendered in `font` within
+// `maxWidth` points. Returns word-wrap when every space-separated chunk fits
+// on a line by itself, otherwise char-wrap so that a long unbreakable run
+// (like "TYPOGRAPHY") gets split mid-glyph instead of overflowing and being
+// clipped at the field edge. Shared between the host measurement hook and
+// the NSTextField renderer so both compute identical geometry.
+NSLineBreakMode lineBreakModeForText(NSString *text, NSFont *font, CGFloat maxWidth);
+#endif
+
+}  // namespace gea::macos

package/targets/macos/main/font_registry.mm

@@ -0,0 +1,350 @@
+#import <AppKit/AppKit.h>
+#import <CoreText/CoreText.h>
+
+#include "font_registry.h"
+#include "graphics/font.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cmath>
+#include <cstdint>
+#include <cstring>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+
+namespace gea::macos {
+
+namespace {
+
+// Family name registry. Indexed by familyId; ids are handed out in the order
+// the framework first asks for them. CSS family lookups all flow through
+// generated::lookupFontFamily below.
+//
+// Construct-on-first-use, NOT namespace-scope globals: an app with a static
+// `font-family` CSS rule (maps' device-fonts.css) registers it from a GLOBAL
+// CONSTRUCTOR — the generated GeaPluginCppPreludeRegistration calls
+// registerStaticFontFamilyRule → lookupFontFamily during dyld initializers,
+// which may run BEFORE this translation unit's own initializers. With plain
+// globals the unordered_map was still zeroed BSS at that point (max load
+// factor 0 → __next_prime overflow_error → abort at launch), and locking the
+// unconstructed mutex is UB. A function-local static is constructed on first
+// use (thread-safe since C++11), so the registry is valid whenever reached.
+struct FamilyRegistry {
+	std::mutex lock;
+	std::vector<std::string> names;
+	std::unordered_map<std::string, int> byName;
+};
+
+FamilyRegistry &familyRegistry()
+{
+	static FamilyRegistry registry;
+	return registry;
+}
+
+int registerFamily(const std::string &name)
+{
+	FamilyRegistry &registry = familyRegistry();
+	std::scoped_lock guard(registry.lock);
+	auto it = registry.byName.find(name);
+	if (it != registry.byName.end()) return it->second;
+	const int id = static_cast<int>(registry.names.size());
+	registry.names.push_back(name);
+	registry.byName.emplace(name, id);
+	return id;
+}
+
+NSString *familyForId(int id)
+{
+	FamilyRegistry &registry = familyRegistry();
+	std::scoped_lock guard(registry.lock);
+	if (id < 0 || static_cast<size_t>(id) >= registry.names.size()) return nil;
+	return [NSString stringWithUTF8String:registry.names[id].c_str()];
+}
+
+// Raw TTF/OTF bytes of the bundle's custom fonts, keyed by lowercased family
+// name. The engine's runtime TTF rasterizer (GEA_EMBEDDED_TTF_RUNTIME_FONTS)
+// bakes canvas glyph atlases from these via lookupRuntimeTtfFontForFamily —
+// without it, ctx.fillText fell back to the builtin bitmap font and canvas
+// labels (maps' place pins) rendered garbled. The byte buffers must live for
+// the process lifetime: the rasterizer keeps stbtt_fontinfo pointers into
+// them across atlas rebuilds. Construct-on-first-use for the same dyld-
+// initializer-ordering reason as FamilyRegistry above.
+struct TtfByteRegistry {
+	std::mutex lock;
+	std::unordered_map<std::string, std::vector<std::uint8_t>> byFamily;
+};
+
+TtfByteRegistry &ttfByteRegistry()
+{
+	static TtfByteRegistry registry;
+	return registry;
+}
+
+std::string lowercased(const std::string &value)
+{
+	std::string out = value;
+	std::transform(out.begin(), out.end(), out.begin(), [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+	return out;
+}
+
+void registerTtfBytesForFamily(NSString *path)
+{
+	NSData *data = [NSData dataWithContentsOfFile:path];
+	if (data.length == 0) return;
+	CTFontDescriptorRef desc = CTFontManagerCreateFontDescriptorFromData((__bridge CFDataRef)data);
+	if (!desc) return;
+	CFStringRef family = (CFStringRef)CTFontDescriptorCopyAttribute(desc, kCTFontFamilyNameAttribute);
+	CFRelease(desc);
+	if (!family) return;
+	char buf[256] = {0};
+	const bool ok = CFStringGetCString(family, buf, sizeof(buf), kCFStringEncodingUTF8);
+	CFRelease(family);
+	if (!ok || !buf[0]) return;
+	const auto *bytes = static_cast<const std::uint8_t *>(data.bytes);
+	TtfByteRegistry &registry = ttfByteRegistry();
+	std::scoped_lock guard(registry.lock);
+	// First face wins (e.g. Inter-Regular before other weights of the family):
+	// the runtime rasterizer keys on the family alone.
+	registry.byFamily.emplace(lowercased(buf), std::vector<std::uint8_t>(bytes, bytes + data.length));
+}
+
+}  // namespace
+
+// Non-anonymous accessor for the generated-hook namespace below: resolve a
+// framework familyId to the bundled TTF bytes feeding the runtime rasterizer.
+const std::uint8_t *runtimeTtfBytesForFamilyId(int familyId, unsigned long *length)
+{
+	if (length) *length = 0;
+	NSString *family = familyForId(familyId);
+	if (!family || family.length == 0) return nullptr;
+	TtfByteRegistry &registry = ttfByteRegistry();
+	std::scoped_lock guard(registry.lock);
+	const auto it = registry.byFamily.find(lowercased(family.UTF8String));
+	if (it == registry.byFamily.end()) return nullptr;
+	if (length) *length = it->second.size();
+	return it->second.data();
+}
+
+static NSFont *self_resolveFont(int fontId, CGFloat size);
+
+NSFont *fontForId(int fontId, int sizePx)
+{
+	CGFloat size = sizePx > 0 ? static_cast<CGFloat>(sizePx) : [NSFont systemFontSize];
+
+	// Cache resolved fonts by (fontId, size). `+[NSFont fontWithName:size:]` and
+	// the CTFontDescriptor fallback below both do a CoreText font-descriptor
+	// match, which is expensive — and this is called for EVERY text node on
+	// EVERY frame (renderer sync + layout measurement). Without this cache,
+	// CoreText font matching dominated the profile and pegged a CPU core. The
+	// set of (family, size) pairs an app uses is tiny, so the cache stays small.
+	static NSMutableDictionary<NSNumber *, NSFont *> *cache;
+	static dispatch_once_t once;
+	dispatch_once(&once, ^{ cache = [NSMutableDictionary dictionary]; });
+	NSNumber *key = @(static_cast<long long>(fontId) * 100000LL + llround(size));
+	@synchronized(cache) {
+		NSFont *hit = cache[key];
+		if (hit) return hit;
+	}
+	NSFont *resolved = self_resolveFont(fontId, size);
+	if (resolved) {
+		@synchronized(cache) { cache[key] = resolved; }
+	}
+	return resolved;
+}
+
+static NSFont *self_resolveFont(int fontId, CGFloat size)
+{
+	NSString *family = familyForId(fontId);
+	if (!family || family.length == 0) return [NSFont systemFontOfSize:size];
+	// CSS system-font keywords map to the actual system UI font — San Francisco
+	// on macOS. There is no PostScript face literally named "-apple-system", so
+	// `+[NSFont fontWithName:@"-apple-system"]` returns nil and we'd otherwise
+	// fall through to a wrong family. systemFontOfSize: IS San Francisco.
+	NSString *lower = family.lowercaseString;
+	if ([lower isEqualToString:@"-apple-system"] || [lower isEqualToString:@"system-ui"] ||
+	    [lower isEqualToString:@"blinkmacsystemfont"] || [lower hasPrefix:@".applesystemuifont"] ||
+	    [lower hasPrefix:@".sf"] || [lower isEqualToString:@"san francisco"] ||
+	    [lower isEqualToString:@"sf pro"] || [lower isEqualToString:@"sf pro text"]) {
+		return [NSFont systemFontOfSize:size];
+	}
+	NSFont *font = [NSFont fontWithName:family size:size];
+	if (font) return font;
+	// CTFont's family lookup is more forgiving than NSFont's PostScript-name
+	// lookup — fall back to building a CTFont with the family attribute.
+	NSDictionary *attrs = @{
+		(__bridge NSString *)kCTFontFamilyNameAttribute: family,
+		(__bridge NSString *)kCTFontSizeAttribute: @(size),
+	};
+	CTFontDescriptorRef desc = CTFontDescriptorCreateWithAttributes((__bridge CFDictionaryRef)attrs);
+	CTFontRef ct = CTFontCreateWithFontDescriptor(desc, size, NULL);
+	CFRelease(desc);
+	if (ct) {
+		NSFont *resolved = (__bridge_transfer NSFont *)ct;
+		return resolved;
+	}
+	return [NSFont systemFontOfSize:size];
+}
+
+int registerCustomTtfDirectory(NSString *directoryPath)
+{
+	NSFileManager *fm = [NSFileManager defaultManager];
+	BOOL isDir = NO;
+	if (![fm fileExistsAtPath:directoryPath isDirectory:&isDir] || !isDir) return 0;
+	NSArray<NSString *> *entries = [fm contentsOfDirectoryAtPath:directoryPath error:nil];
+	int count = 0;
+	for (NSString *name in entries) {
+		NSString *lower = name.lowercaseString;
+		if (![lower hasSuffix:@".ttf"] && ![lower hasSuffix:@".otf"]) continue;
+		NSString *path = [directoryPath stringByAppendingPathComponent:name];
+		registerTtfBytesForFamily(path);
+		CFErrorRef err = NULL;
+		CFURLRef url = (__bridge CFURLRef)[NSURL fileURLWithPath:path];
+		if (CTFontManagerRegisterFontsForURL(url, kCTFontManagerScopeProcess, &err)) {
+			count++;
+		} else if (err) {
+			NSError *e = (__bridge_transfer NSError *)err;
+			// kCTFontManagerErrorAlreadyRegistered == 105 — fine on rebuilds.
+			if (e.code != 105) {
+				NSLog(@"[gea] failed to register font %@: %@", name, e.localizedDescription);
+			}
+		}
+	}
+	return count;
+}
+
+}  // namespace gea::macos
+
+// Strong overrides of the framework's weak font-lookup hooks for the AppKit
+// renderer. The Thermalright target uses Gea's generated raster font atlas
+// instead, so these host-font overrides must stay out of that build.
+#if !GEA_MACOS_THERMALRIGHT_DISPLAY_TARGET
+namespace gea::framework::graphics::generated {
+
+int lookupFontFamily(const char *family)
+{
+	if (!family || !family[0]) return -1;
+	return gea::macos::registerFamily(std::string(family));
+}
+
+const RasterizedFontData *lookupFontForFamily(int, int) { return nullptr; }
+const RasterizedFontData *lookupFont(int) { return nullptr; }
+void ensureLinked() {}
+
+// Feeds the engine's runtime TTF rasterizer (canvas ctx.fillText). AppKit
+// text nodes never come through here — they resolve native NSFonts via
+// fontForId above.
+const std::uint8_t *lookupRuntimeTtfFontForFamily(int familyId, unsigned long *length)
+{
+	return gea::macos::runtimeTtfBytesForFamilyId(familyId, length);
+}
+
+}  // namespace gea::framework::graphics::generated
+#endif
+
+namespace gea::macos {
+
+// Choose a line-break mode that breaks AT word boundaries when possible,
+// falling back to mid-character when an unbreakable run is wider than the
+// available width. The renderer and the measurement path share this logic
+// so AppKit's render geometry always matches the framework's measurement.
+NSLineBreakMode lineBreakModeForText(NSString *text, NSFont *font, CGFloat maxWidth)
+{
+	if (maxWidth <= 0 || text.length == 0 || !font) return NSLineBreakByWordWrapping;
+	NSDictionary *probeAttrs = @{ NSFontAttributeName: font };
+	// Split on whitespace and check each chunk individually. If even one
+	// "word" wouldn't fit on a line by itself, word-wrap can't help us —
+	// we'd render that word overflowing the field width and the parent
+	// tile's overflow:hidden would clip it mid-glyph with no indication.
+	// Char-wrap breaks inside the word so all of it stays visible.
+	NSArray<NSString *> *chunks = [text componentsSeparatedByCharactersInSet:
+	    [NSCharacterSet whitespaceAndNewlineCharacterSet]];
+	for (NSString *chunk in chunks) {
+		if (chunk.length == 0) continue;
+		CGFloat chunkWidth = [chunk sizeWithAttributes:probeAttrs].width;
+		if (chunkWidth > maxWidth) return NSLineBreakByCharWrapping;
+	}
+	return NSLineBreakByWordWrapping;
+}
+
+}  // namespace gea::macos
+
+// Host text-measurement hook for the AppKit renderer. The Thermalright target
+// has no AppKit text renderer; it wants the framework's generated-font metrics.
+#if !GEA_MACOS_THERMALRIGHT_DISPLAY_TARGET
+extern "C" bool gea_host_measure_text(const char *text,
+                                      int maxWidth,
+                                      int fontId,
+                                      int fontSize,
+                                      int *outWidth,
+                                      int *outHeight)
+{
+	if (!outWidth || !outHeight) return false;
+	if (!text || !text[0]) {
+		*outWidth = 0;
+		*outHeight = 0;
+		return true;
+	}
+
+	// Memoize by (text, maxWidth, fontId, fontSize): the layout engine re-measures
+	// EVERY text node on EVERY layout pass, and a pass now runs on every
+	// interaction. NSTextFieldCell.cellSizeForBounds:/sizeWithAttributes:
+	// dominated the interaction profile; the inputs fully determine the result,
+	// so a cache turns repeat measurements (the stable note list) into O(1).
+	static std::mutex measureLock;
+	static std::unordered_map<std::string, std::pair<int, int>> measureCache;
+	std::string key;
+	key.reserve(std::strlen(text) + 24);
+	key.append(text);
+	key.push_back('\x1f');
+	key.append(std::to_string(maxWidth));
+	key.push_back('\x1f');
+	key.append(std::to_string(fontId));
+	key.push_back('\x1f');
+	key.append(std::to_string(fontSize));
+	{
+		std::scoped_lock guard(measureLock);
+		auto it = measureCache.find(key);
+		if (it != measureCache.end()) {
+			*outWidth = it->second.first;
+			*outHeight = it->second.second;
+			return true;
+		}
+	}
+
+	NSFont *font = gea::macos::fontForId(fontId, fontSize);
+	if (!font) return false;
+	NSString *str = [NSString stringWithUTF8String:text] ?: @"";
+	const CGFloat boundedMax = maxWidth > 0 ? maxWidth : CGFLOAT_MAX;
+	NSMutableParagraphStyle *paragraph = [[NSMutableParagraphStyle alloc] init];
+	paragraph.lineBreakMode = gea::macos::lineBreakModeForText(str, font, boundedMax);
+	NSDictionary *attrs = @{
+		NSFontAttributeName: font,
+		NSParagraphStyleAttributeName: paragraph,
+	};
+	NSAttributedString *attributed = [[NSAttributedString alloc] initWithString:str attributes:attrs];
+	// Use an actual NSTextFieldCell to measure: this is exactly what the
+	// renderer's NSTextField uses to lay text out, so the size we report
+	// here is the size AppKit will draw into — no off-by-side-bearing,
+	// no kerning surprise, no device-metrics vs typographic gap. Sizing
+	// against a fresh cell of size (maxWidth, large) returns the wrapped
+	// height + the actual line width AppKit needs.
+	NSTextFieldCell *cell = [[NSTextFieldCell alloc] init];
+	cell.bezeled = NO;
+	cell.bordered = NO;
+	cell.drawsBackground = NO;
+	cell.wraps = YES;
+	cell.attributedStringValue = attributed;
+	const NSSize cellSize = [cell cellSizeForBounds:NSMakeRect(0, 0, boundedMax, CGFLOAT_MAX)];
+	*outWidth = static_cast<int>(std::ceil(cellSize.width));
+	*outHeight = static_cast<int>(std::ceil(cellSize.height));
+	{
+		std::scoped_lock guard(measureLock);
+		if (measureCache.size() > 8192) measureCache.clear();  // bound unbounded growth
+		measureCache.emplace(std::move(key), std::make_pair(*outWidth, *outHeight));
+	}
+	return true;
+}
+#endif

package/targets/macos/main/image_bridge.h

@@ -0,0 +1,16 @@
+#pragma once
+
+#ifdef __OBJC__
+@class NSImage;
+#endif
+
+namespace gea::macos {
+
+#ifdef __OBJC__
+// Returns an NSImage built from the ImageStore slot at imageId, or nil if
+// the slot is empty / invalid. Pixels are converted from RGB565 (+ optional
+// alpha channel) to RGBA8888. Caller owns the result via ARC.
+NSImage *imageForId(int imageId);
+#endif
+
+}  // namespace gea::macos

package/targets/macos/main/image_bridge.mm

@@ -0,0 +1,52 @@
+#import <AppKit/AppKit.h>
+
+#include "image_bridge.h"
+#include "image.h"
+#include "pixel.h"
+
+namespace gea::macos {
+
+NSImage *imageForId(int imageId)
+{
+	using namespace gea::framework::graphics;
+	if (imageId < 0) return nil;
+	auto &store = ImageStore::instance();
+	const int w = store.width(imageId);
+	const int h = store.height(imageId);
+	const std::uint16_t *src = store.currentPixels(imageId);
+	const std::uint8_t *alpha = store.currentAlpha(imageId);
+	if (w <= 0 || h <= 0 || !src) return nil;
+
+	const NSInteger pixelCount = w * h;
+	NSMutableData *rgba = [NSMutableData dataWithLength:(NSUInteger)(pixelCount * 4)];
+	std::uint8_t *dst = static_cast<std::uint8_t *>(rgba.mutableBytes);
+	for (NSInteger i = 0; i < pixelCount; i++) {
+		int r, g, b;
+		pixel::unpackRgb565(src[i], &r, &g, &b);
+		dst[i * 4 + 0] = static_cast<std::uint8_t>((r * 255 + 15) / 31);
+		dst[i * 4 + 1] = static_cast<std::uint8_t>((g * 255 + 31) / 63);
+		dst[i * 4 + 2] = static_cast<std::uint8_t>((b * 255 + 15) / 31);
+		dst[i * 4 + 3] = alpha ? alpha[i] : 0xFF;
+	}
+
+	NSBitmapImageRep *rep =
+	    [[NSBitmapImageRep alloc] initWithBitmapDataPlanes:NULL
+	                                            pixelsWide:w
+	                                            pixelsHigh:h
+	                                         bitsPerSample:8
+	                                       samplesPerPixel:4
+	                                              hasAlpha:YES
+	                                              isPlanar:NO
+	                                        colorSpaceName:NSDeviceRGBColorSpace
+	                                          bitmapFormat:NSBitmapFormatAlphaNonpremultiplied
+	                                           bytesPerRow:w * 4
+	                                          bitsPerPixel:32];
+	if (!rep) return nil;
+	memcpy([rep bitmapData], dst, (size_t)(pixelCount * 4));
+
+	NSImage *img = [[NSImage alloc] initWithSize:NSMakeSize(w, h)];
+	[img addRepresentation:rep];
+	return img;
+}
+
+}  // namespace gea::macos