@tileflow/react-native 0.1.0-alpha.0 → 0.1.0-alpha.2

package/dist/internal/camera.d.ts

@@ -1,4 +1,4 @@
-import { M as MapView, a as MapViewChangeEvent, b as MapInitialViewInputs, c as MapCameraProps } from '../contract-DWs-lDPo.js';
+import { M as MapView, a as MapViewChangeEvent, b as MapInitialViewInputs, c as MapCameraProps } from '../contract-Bwl-gB-I.js';
 import '@maplibre/maplibre-react-native';
 import 'react';
 import 'react-native';

package/dist/internal/initial-view.d.ts

@@ -1,4 +1,4 @@
-import { b as MapInitialViewInputs, M as MapView } from '../contract-DWs-lDPo.js';
+import { b as MapInitialViewInputs, M as MapView } from '../contract-Bwl-gB-I.js';
 import '@maplibre/maplibre-react-native';
 import 'react';
 import 'react-native';

package/dist/internal/native-appearance.d.ts

@@ -1,4 +1,4 @@
-import { y as MapThemeSelection, f as MapColorScheme } from '../contract-DWs-lDPo.js';
+import { z as MapThemeSelection, f as MapColorScheme } from '../contract-Bwl-gB-I.js';
 import '@maplibre/maplibre-react-native';
 import 'react';
 import 'react-native';

package/dist/internal/source-state.d.ts

@@ -1,5 +1,5 @@
 import { TileflowNativeSourceState } from '@tileflow/core/native';
-import { v as MapSourceState } from '../contract-DWs-lDPo.js';
+import { v as MapSourceState } from '../contract-Bwl-gB-I.js';
 import '@maplibre/maplibre-react-native';
 import 'react';
 import 'react-native';

package/ios/TFNativeTheme.h

@@ -0,0 +1,28 @@
+#import <QuartzCore/QuartzCore.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Pure helpers for theme transitions and blends on MapLibre iOS. UI-queue use only where noted.
+
+/** The projective transform taking four points to four points (h[8] = 1), or NO when degenerate. */
+FOUNDATION_EXPORT BOOL TFThemeHomography(const CGPoint from[_Nonnull 4], const CGPoint to[_Nonnull 4], double h[_Nonnull 9]);
+/** A homography as a layer transform for anchor point (0, 0). */
+FOUNDATION_EXPORT CATransform3D TFThemeTransform(const double h[_Nonnull 9]);
+/** The MapLibre iOS key of a style-specification layer property. */
+FOUNDATION_EXPORT NSString *TFThemeStyleKey(NSString *property);
+/** A hex, rgb(a), hsl(a), or transparent colour, or nil. */
+FOUNDATION_EXPORT UIColor *_Nullable TFThemeColor(NSString *text);
+/** Whether every element is a number (not a boolean). */
+FOUNDATION_EXPORT BOOL TFThemeNumbers(NSArray *array);
+/** Whether a value can be set at run time: constants and expressions that read no feature data. */
+FOUNDATION_EXPORT BOOL TFThemeCameraValue(id _Nullable value, NSUInteger depth);
+/**
+ * A style-specification value as the expression MapLibre iOS expects for `key`; nil resets it.
+ * `supported` is NO, with nil, for a value MapLibre iOS cannot take at run time.
+ */
+FOUNDATION_EXPORT NSExpression *_Nullable TFThemeExpression(id _Nullable value, NSString *key, BOOL *supported);
+/** Pattern artwork mixed in premultiplied pixels: `from` at 1 - t plus `to` at t. */
+FOUNDATION_EXPORT UIImage *TFThemeMixImage(UIImage *from, UIImage *to, double t);
+
+NS_ASSUME_NONNULL_END

package/ios/TFNativeTheme.mm

@@ -0,0 +1,198 @@
+#import "TFNativeTheme.h"
+#import <MapLibre/MapLibre.h>
+#import <algorithm>
+#import <cctype>
+#import <cmath>
+
+// The projective transform taking four points to four points (h[8] = 1), or NO when degenerate.
+BOOL TFThemeHomography(const CGPoint from[4], const CGPoint to[4], double h[9]) {
+	double rows[8][9];
+	for (int i = 0; i < 4; i++) {
+		double x = from[i].x, y = from[i].y, u = to[i].x, v = to[i].y;
+		double first[9] = {x, y, 1, 0, 0, 0, -u * x, -u * y, u};
+		double second[9] = {0, 0, 0, x, y, 1, -v * x, -v * y, v};
+		for (int k = 0; k < 9; k++) { rows[2 * i][k] = first[k]; rows[2 * i + 1][k] = second[k]; }
+	}
+	for (int column = 0; column < 8; column++) {
+		int pivot = column;
+		for (int row = column + 1; row < 8; row++) if (std::fabs(rows[row][column]) > std::fabs(rows[pivot][column])) pivot = row;
+		if (std::fabs(rows[pivot][column]) < 1e-12) return NO;
+		if (pivot != column) for (int k = 0; k < 9; k++) std::swap(rows[pivot][k], rows[column][k]);
+		for (int row = 0; row < 8; row++) {
+			if (row == column) continue;
+			double factor = rows[row][column] / rows[column][column];
+			for (int k = column; k < 9; k++) rows[row][k] -= factor * rows[column][k];
+		}
+	}
+	for (int i = 0; i < 8; i++) { h[i] = rows[i][8] / rows[i][i]; if (!std::isfinite(h[i])) return NO; }
+	h[8] = 1;
+	return YES;
+}
+
+// MapLibre iOS names layer properties after Cocoa conventions; everything else is camel case.
+NSString *TFThemeStyleKey(NSString *property) {
+	static NSDictionary<NSString *, NSString *> *renamed;
+	static dispatch_once_t once;
+	dispatch_once(&once, ^{
+		renamed = @{
+			@"circle-pitch-scale": @"circleScaleAlignment", @"circle-translate": @"circleTranslation", @"circle-translate-anchor": @"circleTranslationAnchor",
+			@"fill-antialias": @"fillAntialiased", @"fill-translate": @"fillTranslation", @"fill-translate-anchor": @"fillTranslationAnchor",
+			@"fill-extrusion-translate": @"fillExtrusionTranslation", @"fill-extrusion-translate-anchor": @"fillExtrusionTranslationAnchor",
+			@"fill-extrusion-vertical-gradient": @"fillExtrusionHasVerticalGradient", @"icon-allow-overlap": @"iconAllowsOverlap",
+			@"icon-ignore-placement": @"iconIgnoresPlacement", @"icon-image": @"iconImageName", @"icon-keep-upright": @"keepsIconUpright",
+			@"icon-rotate": @"iconRotation", @"icon-size": @"iconScale", @"icon-translate": @"iconTranslation", @"icon-translate-anchor": @"iconTranslationAnchor",
+			@"line-dasharray": @"lineDashPattern", @"line-translate": @"lineTranslation", @"line-translate-anchor": @"lineTranslationAnchor",
+			@"raster-brightness-max": @"maximumRasterBrightness", @"raster-brightness-min": @"minimumRasterBrightness",
+			@"raster-hue-rotate": @"rasterHueRotation", @"raster-resampling": @"rasterResamplingMode", @"symbol-avoid-edges": @"symbolAvoidsEdges",
+			@"text-allow-overlap": @"textAllowsOverlap", @"text-field": @"text", @"text-font": @"textFontNames", @"text-ignore-placement": @"textIgnoresPlacement",
+			@"text-justify": @"textJustification", @"text-keep-upright": @"keepsTextUpright", @"text-max-angle": @"maximumTextAngle",
+			@"text-max-width": @"maximumTextWidth", @"text-rotate": @"textRotation", @"text-size": @"textFontSize", @"text-translate": @"textTranslation",
+			@"text-translate-anchor": @"textTranslationAnchor", @"text-writing-mode": @"textWritingModes",
+		};
+	});
+	NSString *key = renamed[property];
+	if (key) return key;
+	NSMutableString *camel = [NSMutableString string];
+	BOOL upper = NO;
+	for (NSUInteger index = 0; index < property.length; index++) {
+		unichar character = [property characterAtIndex:index];
+		if (character == '-') { upper = YES; continue; }
+		[camel appendFormat:@"%C", upper ? (unichar)toupper(character) : character];
+		upper = NO;
+	}
+	return camel;
+}
+static BOOL TFThemeChannel(NSString *text, double scale, double *out) {
+	NSString *trimmed = [text stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceCharacterSet];
+	BOOL percentage = [trimmed hasSuffix:@"%"];
+	if (percentage) trimmed = [trimmed substringToIndex:trimmed.length - 1];
+	NSScanner *scanner = [NSScanner scannerWithString:trimmed];
+	double value;
+	if (![scanner scanDouble:&value] || !scanner.isAtEnd || !std::isfinite(value)) return NO;
+	*out = percentage ? value / 100.0 * scale : value;
+	return YES;
+}
+// Hex, rgb(a), and hsl(a) colours; nil for anything else, which MapLibre then parses itself.
+UIColor *TFThemeColor(NSString *text) {
+	NSString *colour = [[text stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceCharacterSet] lowercaseString];
+	if ([colour isEqual:@"transparent"]) return [UIColor colorWithRed:0 green:0 blue:0 alpha:0];
+	if ([colour hasPrefix:@"#"]) {
+		NSString *hex = [colour substringFromIndex:1];
+		if (hex.length == 3 || hex.length == 4) {
+			NSMutableString *full = [NSMutableString string];
+			for (NSUInteger index = 0; index < hex.length; index++) { unichar digit = [hex characterAtIndex:index]; [full appendFormat:@"%C%C", digit, digit]; }
+			hex = full;
+		}
+		if (hex.length != 6 && hex.length != 8) return nil;
+		unsigned long long number = 0;
+		NSScanner *scanner = [NSScanner scannerWithString:hex];
+		if (![scanner scanHexLongLong:&number] || !scanner.isAtEnd) return nil;
+		if (hex.length == 6) number = (number << 8) | 0xff;
+		return [UIColor colorWithRed:((number >> 24) & 0xff) / 255.0 green:((number >> 16) & 0xff) / 255.0 blue:((number >> 8) & 0xff) / 255.0 alpha:(number & 0xff) / 255.0];
+	}
+	NSRange open = [colour rangeOfString:@"("];
+	if (open.location == NSNotFound || ![colour hasSuffix:@")"]) return nil;
+	NSString *function = [colour substringToIndex:open.location];
+	NSString *body = [colour substringWithRange:NSMakeRange(open.location + 1, colour.length - open.location - 2)];
+	NSMutableArray<NSString *> *parts = [NSMutableArray array];
+	for (NSString *part in [body componentsSeparatedByCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@", /"]]) if (part.length) [parts addObject:part];
+	if (parts.count < 3 || parts.count > 4) return nil;
+	double alpha = 1;
+	if (parts.count == 4 && !TFThemeChannel(parts[3], 1, &alpha)) return nil;
+	if ([function isEqual:@"rgb"] || [function isEqual:@"rgba"]) {
+		double red, green, blue;
+		if (!TFThemeChannel(parts[0], 255, &red) || !TFThemeChannel(parts[1], 255, &green) || !TFThemeChannel(parts[2], 255, &blue)) return nil;
+		return [UIColor colorWithRed:red / 255.0 green:green / 255.0 blue:blue / 255.0 alpha:alpha];
+	}
+	if ([function isEqual:@"hsl"] || [function isEqual:@"hsla"]) {
+		double hue, saturation, lightness;
+		if (!TFThemeChannel(parts[0], 1, &hue) || !TFThemeChannel(parts[1], 1, &saturation) || !TFThemeChannel(parts[2], 1, &lightness)) return nil;
+		double chroma = (1 - std::fabs(2 * lightness - 1)) * saturation;
+		double sector = std::fmod(std::fmod(hue, 360) + 360, 360) / 60;
+		double x = chroma * (1 - std::fabs(std::fmod(sector, 2) - 1));
+		double r = 0, g = 0, b = 0;
+		if (sector < 1) { r = chroma; g = x; } else if (sector < 2) { r = x; g = chroma; } else if (sector < 3) { g = chroma; b = x; }
+		else if (sector < 4) { g = x; b = chroma; } else if (sector < 5) { r = x; b = chroma; } else { r = chroma; b = x; }
+		double offset = lightness - chroma / 2;
+		return [UIColor colorWithRed:r + offset green:g + offset blue:b + offset alpha:alpha];
+	}
+	return nil;
+}
+BOOL TFThemeNumbers(NSArray *array) {
+	for (id item in array) if (![item isKindOfClass:NSNumber.class] || CFGetTypeID((__bridge CFTypeRef)item) == CFBooleanGetTypeID()) return NO;
+	return YES;
+}
+// MapLibre iOS converts expressions through NSExpression, which cannot round-trip every expression
+// that reads feature data or combines conditions. Blend plans set only camera values at run time;
+// anything else is left unchanged rather than risked.
+BOOL TFThemeCameraValue(id value, NSUInteger depth) {
+	static NSSet<NSString *> *refused;
+	static dispatch_once_t once;
+	dispatch_once(&once, ^{
+		refused = [NSSet setWithArray:@[@"!", @"!has", @"!in", @"accumulated", @"all", @"any", @"distance", @"feature-state", @"geometry-type",
+			@"get", @"global-state", @"has", @"heatmap-density", @"id", @"in", @"line-progress", @"none", @"properties", @"within"]];
+	});
+	if (![value isKindOfClass:NSArray.class]) return YES;
+	if (depth > 32) return NO;
+	NSArray *array = value;
+	if (array.count && [array[0] isKindOfClass:NSString.class]) {
+		if ([refused containsObject:array[0]]) return NO;
+		if ([array[0] isEqual:@"literal"]) return YES;
+	}
+	for (id item in array) if (!TFThemeCameraValue(item, depth + 1)) return NO;
+	return YES;
+}
+// A style-specification value as the NSExpression MapLibre iOS expects for `key`; nil resets it.
+NSExpression *TFThemeExpression(id value, NSString *key, BOOL *supported) {
+	*supported = YES;
+	if (!value || value == NSNull.null) return nil;
+	if ([value isKindOfClass:NSString.class]) {
+		if ([key hasSuffix:@"Color"]) {
+			// MapLibre iOS cannot cast a colour name at run time; such a value is left unchanged.
+			UIColor *colour = TFThemeColor(value);
+			*supported = colour != nil;
+			return colour ? [NSExpression expressionForConstantValue:colour] : nil;
+		}
+		return [NSExpression expressionForConstantValue:value];
+	}
+	if ([value isKindOfClass:NSNumber.class]) return [NSExpression expressionForConstantValue:value];
+	if ([value isKindOfClass:NSArray.class]) {
+		NSArray *array = value;
+		if (array.count == 2 && TFThemeNumbers(array) && ([key hasSuffix:@"Translation"] || [key hasSuffix:@"Offset"]))
+			return [NSExpression expressionForConstantValue:[NSValue valueWithCGVector:CGVectorMake([array[0] doubleValue], [array[1] doubleValue])]];
+		if (TFThemeNumbers(array)) return [NSExpression expressionForConstantValue:array];
+		BOOL strings = YES;
+		for (id item in array) strings = strings && [item isKindOfClass:NSString.class];
+		if (strings && [key isEqual:@"textFontNames"]) return [NSExpression expressionForConstantValue:array];
+	}
+	return [NSExpression expressionWithMLNJSONObject:value];
+}
+// Pattern artwork mixed in premultiplied pixels: `from` at 1 - t plus `to` at t.
+UIImage *TFThemeMixImage(UIImage *from, UIImage *to, double t) {
+	if (t <= 0) return from;
+	if (t >= 1) return to;
+	CGImageRef a = from.CGImage, b = to.CGImage;
+	if (!a || !b || CGImageGetWidth(a) != CGImageGetWidth(b) || CGImageGetHeight(a) != CGImageGetHeight(b)) return t < 0.5 ? from : to;
+	size_t width = CGImageGetWidth(a), height = CGImageGetHeight(a);
+	CGColorSpaceRef space = CGColorSpaceCreateDeviceRGB();
+	CGContextRef context = CGBitmapContextCreate(NULL, width, height, 8, width * 4, space, (CGBitmapInfo)kCGImageAlphaPremultipliedLast);
+	CGColorSpaceRelease(space);
+	if (!context) return t < 0.5 ? from : to;
+	CGRect rect = CGRectMake(0, 0, width, height);
+	CGContextSetAlpha(context, 1 - t); CGContextDrawImage(context, rect, a);
+	CGContextSetBlendMode(context, kCGBlendModePlusLighter); CGContextSetAlpha(context, t); CGContextDrawImage(context, rect, b);
+	CGImageRef mixed = CGBitmapContextCreateImage(context);
+	CGContextRelease(context);
+	if (!mixed) return t < 0.5 ? from : to;
+	UIImage *image = [UIImage imageWithCGImage:mixed scale:from.scale orientation:UIImageOrientationUp];
+	CGImageRelease(mixed);
+	return from.renderingMode == UIImageRenderingModeAlwaysTemplate ? [image imageWithRenderingMode:UIImageRenderingModeAlwaysTemplate] : image;
+}
+// The homography as a layer transform for anchor point (0, 0): row vectors, perspective in m14/m24.
+CATransform3D TFThemeTransform(const double h[9]) {
+	CATransform3D transform = CATransform3DIdentity;
+	transform.m11 = h[0]; transform.m12 = h[3]; transform.m14 = h[6];
+	transform.m21 = h[1]; transform.m22 = h[4]; transform.m24 = h[7];
+	transform.m41 = h[2]; transform.m42 = h[5]; transform.m44 = h[8];
+	return transform;
+}

package/ios/TileflowNativeSurface.mm

@@ -5,8 +5,10 @@
 #import <MapLibreReactNative/MLRNMapView.h>
 #import <MapLibreReactNative/MLRNCamera.h>
 #import <QuartzCore/QuartzCore.h>
+#import <algorithm>
 #import "TFAdmissionEngine.h"
 #import "TFNativeSurfaceState.h"
+#import "TFNativeTheme.h"
 #import <cmath>
 
 static void TFSurfaceInvalid(void) {
@@ -67,6 +69,32 @@ static MLRNCamera *TFSurfaceCamera(UIView *root, MLRNMapView *map) {
 	return found;
 }
 
+// The view MapLibre draws into: the subview backed by a Metal (or OpenGL) layer.
+static UIView *TFSurfaceRenderView(MLNMapView *map) {
+	for (UIView *view in map.subviews) {
+		NSString *name = NSStringFromClass(view.layer.class);
+		if ([name containsString:@"Metal"] || [name containsString:@"EAGL"]) return view;
+	}
+	return nil;
+}
+// A snapshot of one frame over the rendering view. It keeps four ground points of that frame and
+// follows them with the ground plane's projective transform while the camera moves.
+@interface TFSurfaceCover : NSObject
+@property (nonatomic, strong) UIView *view;
+@property (nonatomic, copy) NSArray<NSValue *> *corners;
+@property (nonatomic, copy) NSArray<NSValue *> *anchors;
+@property (nonatomic) BOOL fading;
+@end
+@implementation TFSurfaceCover
+@end
+@interface TFSurfaceReveal : NSObject
+@property (nonatomic) double duration;
+@property (nonatomic, strong) NSMutableArray<TFSurfaceCover *> *covers;
+@property (nonatomic, copy) RCTPromiseResolveBlock resolve;
+@end
+@implementation TFSurfaceReveal
+@end
+
 @interface TFSurfaceLayoutProbe : UIView
 @property (nonatomic, copy) dispatch_block_t changed;
 @end
@@ -90,8 +118,19 @@ static MLRNCamera *TFSurfaceCamera(UIView *root, MLRNMapView *map) {
 @property (nonatomic) BOOL retiring;
 @property (nonatomic) BOOL foreground;
 @property (nonatomic) BOOL observing;
+@property (nonatomic, strong) NSMutableArray<TFSurfaceCover *> *covers;
+@property (nonatomic, strong) NSMutableArray<TFSurfaceReveal *> *reveals;
+@property (nonatomic, strong) NSMutableArray<TFSurfaceReveal *> *settling;
+@property (nonatomic, copy, nullable) dispatch_block_t revealDeadline;
+@property (nonatomic, copy, nullable) NSString *themedToken;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, MLNStyleLayer *> *themedLayers;
+@property (nonatomic, strong) NSMutableDictionary<NSString *, UIImage *> *themedImages;
 - (void)attach;
+- (NSUInteger)applyThemeValues:(NSDictionary *)values;
 - (void)retire;
+- (BOOL)cover;
+- (void)reveal:(double)duration resolve:(RCTPromiseResolveBlock)resolve;
+- (void)discardCovers;
 - (BOOL)owns;
 - (MLNStyle *)style;
 - (NSDictionary *)view;
@@ -114,6 +153,7 @@ static MLRNCamera *TFSurfaceCamera(UIView *root, MLRNMapView *map) {
 }
 - (void)attach {
 	self.token = @""; self.detached = [NSMutableArray array]; self.previous = self.map.delegate;
+	self.covers = [NSMutableArray array]; self.reveals = [NSMutableArray array]; self.settling = [NSMutableArray array];
 	if ([self.previous isKindOfClass:TFSurfaceAttachment.class]) TFSurfaceInvalid();
 	self.map.delegate = self;
 	[self.map addObserver:self forKeyPath:@"delegate" options:0 context:(__bridge void *)self]; self.observing = YES;
@@ -149,8 +189,182 @@ static MLRNCamera *TFSurfaceCamera(UIView *root, MLRNMapView *map) {
 	for (NSUInteger index = 0; index < 4; index++) visible = visible && [snapshot[index] doubleValue] > 0;
 	[self.state layout:visible];
 }
+- (BOOL)cover {
+	if (UIAccessibilityIsReduceMotionEnabled() || !self.foreground || !self.root.window || !self.style) return NO;
+	for (TFSurfaceCover *existing in self.covers) if (!existing.fading) return YES;
+	UIView *render = TFSurfaceRenderView(self.map);
+	CGRect frame = render.frame;
+	if (!render || frame.size.width < 1 || frame.size.height < 1 || self.covers.count >= 4) return NO;
+	UIView *snapshot = [render snapshotViewAfterScreenUpdates:NO];
+	if (!snapshot) return NO;
+	snapshot.userInteractionEnabled = NO; snapshot.accessibilityElementsHidden = YES;
+	snapshot.layer.anchorPoint = CGPointZero; snapshot.frame = frame;
+	// Ground points below the horizon at any supported pitch, in map view coordinates.
+	CGFloat width = frame.size.width, height = frame.size.height;
+	NSMutableArray<NSValue *> *corners = [NSMutableArray array], *anchors = [NSMutableArray array];
+	for (NSValue *value in @[[NSValue valueWithCGPoint:CGPointMake(width * 0.1, height * 0.45)], [NSValue valueWithCGPoint:CGPointMake(width * 0.9, height * 0.45)],
+		[NSValue valueWithCGPoint:CGPointMake(width * 0.9, height * 0.9)], [NSValue valueWithCGPoint:CGPointMake(width * 0.1, height * 0.9)]]) {
+		CGPoint point = value.CGPointValue;
+		CLLocationCoordinate2D coordinate = [self.map convertPoint:CGPointMake(point.x + frame.origin.x, point.y + frame.origin.y) toCoordinateFromView:self.map];
+		if (!std::isfinite(coordinate.latitude) || !std::isfinite(coordinate.longitude) || std::fabs(coordinate.latitude) > 90) return NO;
+		[corners addObject:value];
+		[anchors addObject:[NSValue valueWithBytes:&coordinate objCType:@encode(CLLocationCoordinate2D)]];
+	}
+	TFSurfaceCover *cover = [TFSurfaceCover new];
+	cover.view = snapshot; cover.corners = corners; cover.anchors = anchors;
+	// Newer covers go below older ones, which keep fading on top.
+	[self.map insertSubview:snapshot aboveSubview:render];
+	[self.covers addObject:cover];
+	return YES;
+}
+- (void)followCovers {
+	if (!self.covers.count) return;
+	UIView *render = TFSurfaceRenderView(self.map);
+	if (!render) return;
+	CGPoint origin = render.frame.origin;
+	for (TFSurfaceCover *cover in self.covers) {
+		CGPoint from[4], to[4];
+		for (int index = 0; index < 4; index++) {
+			from[index] = cover.corners[index].CGPointValue;
+			CLLocationCoordinate2D coordinate;
+			[cover.anchors[index] getValue:&coordinate size:sizeof(coordinate)];
+			CGPoint point = [self.map convertCoordinate:coordinate toPointToView:self.map];
+			if (!std::isfinite(point.x) || !std::isfinite(point.y)) return;
+			to[index] = CGPointMake(point.x - origin.x, point.y - origin.y);
+		}
+		double h[9];
+		if (!TFThemeHomography(from, to, h)) continue;
+		[CATransaction begin]; [CATransaction setDisableActions:YES];
+		cover.view.layer.position = origin; cover.view.layer.transform = TFThemeTransform(h);
+		[CATransaction commit];
+	}
+}
+- (void)reveal:(double)duration resolve:(RCTPromiseResolveBlock)resolve {
+	TFSurfaceReveal *reveal = [TFSurfaceReveal new];
+	reveal.duration = duration; reveal.resolve = resolve; reveal.covers = [self.covers mutableCopy];
+	if (!reveal.covers.count) { resolve(@{@"revealed": @YES}); return; }
+	[self.reveals addObject:reveal];
+	// Fades start on the next complete frame, or after ten seconds at most.
+	if (!self.revealDeadline) {
+		__weak TFSurfaceAttachment *weakSelf = self;
+		dispatch_block_t deadline = dispatch_block_create((dispatch_block_flags_t)0, ^{ weakSelf.revealDeadline = nil; [weakSelf startReveals]; });
+		self.revealDeadline = deadline;
+		dispatch_after(dispatch_time(DISPATCH_TIME_NOW, 10 * NSEC_PER_SEC), dispatch_get_main_queue(), deadline);
+	}
+	[self.map triggerRepaint];
+}
+- (void)startReveals {
+	if (self.revealDeadline) { dispatch_block_cancel(self.revealDeadline); self.revealDeadline = nil; }
+	NSArray<TFSurfaceReveal *> *reveals = [self.reveals copy];
+	[self.reveals removeAllObjects];
+	for (TFSurfaceReveal *reveal in reveals) {
+		for (TFSurfaceCover *cover in reveal.covers) {
+			if (cover.fading) continue;
+			cover.fading = YES;
+			__weak TFSurfaceAttachment *weakSelf = self;
+			[UIView animateWithDuration:reveal.duration / 1000.0 delay:0 options:UIViewAnimationOptionCurveEaseInOut | UIViewAnimationOptionAllowUserInteraction
+				animations:^{ cover.view.alpha = 0; } completion:^(__unused BOOL finished) { [weakSelf removeCover:cover]; }];
+		}
+		[self settle:reveal];
+	}
+}
+- (void)removeCover:(TFSurfaceCover *)cover {
+	[cover.view.layer removeAllAnimations]; [cover.view removeFromSuperview];
+	[self.covers removeObject:cover];
+	for (TFSurfaceReveal *reveal in [self.settling copy]) [self settle:reveal];
+}
+// A reveal resolves once every cover that existed when it was requested is gone.
+- (void)settle:(TFSurfaceReveal *)reveal {
+	for (TFSurfaceCover *cover in reveal.covers) if ([self.covers containsObject:cover]) {
+		if (![self.settling containsObject:reveal]) [self.settling addObject:reveal];
+		return;
+	}
+	[self.settling removeObject:reveal];
+	if (reveal.resolve) { RCTPromiseResolveBlock resolve = reveal.resolve; reveal.resolve = nil; resolve(@{@"revealed": @YES}); }
+}
+- (void)discardCovers {
+	if (self.revealDeadline) { dispatch_block_cancel(self.revealDeadline); self.revealDeadline = nil; }
+	for (TFSurfaceCover *cover in [self.covers copy]) { [cover.view.layer removeAllAnimations]; [cover.view removeFromSuperview]; }
+	[self.covers removeAllObjects];
+	NSArray *reveals = [self.reveals arrayByAddingObjectsFromArray:self.settling];
+	[self.reveals removeAllObjects]; [self.settling removeAllObjects];
+	for (TFSurfaceReveal *reveal in reveals) if (reveal.resolve) { RCTPromiseResolveBlock resolve = reveal.resolve; reveal.resolve = nil; resolve(@{@"revealed": @YES}); }
+}
+- (NSUInteger)applyThemeValues:(NSDictionary *)values {
+	MLNStyle *style = self.style;
+	if (!style) TFSurfaceInvalid();
+	if (![self.themedToken isEqual:self.token]) {
+		// Layers and original artwork belong to one style.
+		self.themedToken = self.token; self.themedLayers = [NSMutableDictionary dictionary]; self.themedImages = [NSMutableDictionary dictionary];
+	}
+	NSUInteger applied = 0;
+	for (NSString *group in @[@"paint", @"layout"]) {
+		id entries = values[group];
+		if (!entries) continue;
+		if (![entries isKindOfClass:NSArray.class] || [entries count] > 8192) TFSurfaceInvalid();
+		for (id entry in entries) {
+			if (![entry isKindOfClass:NSArray.class] || [entry count] != 3 || ![entry[0] isKindOfClass:NSString.class] || ![entry[1] isKindOfClass:NSString.class]) TFSurfaceInvalid();
+			NSString *identifier = entry[0];
+			MLNStyleLayer *layer = self.themedLayers[identifier];
+			if (!layer) {
+				layer = [style layerWithIdentifier:identifier];
+				if (!layer) continue;
+				self.themedLayers[identifier] = layer;
+			}
+			if ([entry[1] isEqual:@"visibility"]) {
+				// Per-theme copies of a layer switch by visibility, a plain flag.
+				layer.visible = ![entry[2] isEqual:@"none"];
+				applied++;
+				continue;
+			}
+			NSString *key = TFThemeStyleKey(entry[1]);
+			if (![layer respondsToSelector:NSSelectorFromString(key)] || !TFThemeCameraValue(entry[2], 0)) continue;
+			// A value MapLibre rejects keeps its previous value; the rest of the batch still applies.
+			BOOL supported;
+			NSExpression *expression = TFThemeExpression(entry[2], key, &supported);
+			if (!supported) continue;
+			@try { [layer setValue:expression forKey:key]; applied++; }
+			@catch (__unused NSException *exception) {}
+		}
+	}
+	id images = values[@"images"];
+	if (images) {
+		if (![images isKindOfClass:NSArray.class] || [images count] > 64) TFSurfaceInvalid();
+		// Originals are read before any artwork is replaced, so tuples can share names.
+		for (NSArray *entry in images) {
+			if (![entry isKindOfClass:NSArray.class] || entry.count != 4) TFSurfaceInvalid();
+			for (NSUInteger index = 0; index < 3; index++) {
+				if (![entry[index] isKindOfClass:NSString.class]) TFSurfaceInvalid();
+				if (!self.themedImages[entry[index]]) { UIImage *image = [style imageForName:entry[index]]; if (image) self.themedImages[entry[index]] = image; }
+			}
+		}
+		for (NSArray *entry in images) {
+			UIImage *from = self.themedImages[entry[1]], *to = self.themedImages[entry[2]];
+			double t = TFSurfaceNumber(entry[3], 0, 1);
+			if (!from || !to) continue;
+			[style setImage:TFThemeMixImage(from, to, t) forName:entry[0]];
+			applied++;
+		}
+	}
+	id light = values[@"light"];
+	if (light) {
+		if (![light isKindOfClass:NSDictionary.class]) TFSurfaceInvalid();
+		MLNLight *next = style.light ?: [MLNLight new];
+		id colour = light[@"color"], intensity = light[@"intensity"], position = light[@"position"];
+		if ([colour isKindOfClass:NSString.class]) { UIColor *parsed = TFThemeColor(colour); if (parsed) next.color = [NSExpression expressionForConstantValue:parsed]; }
+		if ([intensity isKindOfClass:NSNumber.class]) next.intensity = [NSExpression expressionForConstantValue:intensity];
+		if ([position isKindOfClass:NSArray.class] && [position count] == 3 && TFThemeNumbers(position)) {
+			MLNSphericalPosition spherical = MLNSphericalPositionMake([position[0] doubleValue], [position[1] doubleValue], [position[2] doubleValue]);
+			next.position = [NSExpression expressionForConstantValue:[NSValue valueWithMLNSphericalPosition:spherical]];
+		}
+		style.light = next;
+		applied++;
+	}
+	return applied;
+}
 - (void)retire {
 	if (self.retiring) return;
+	[self discardCovers];
 	self.retiring = YES; [self.state close];
 	if (self.deadline) dispatch_block_cancel(self.deadline); self.deadline = nil;
 	if (self.layoutCancel) self.layoutCancel(); self.layoutCancel = nil;
@@ -165,23 +379,23 @@ static MLRNCamera *TFSurfaceCamera(UIView *root, MLRNMapView *map) {
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapView:mapView didFinishLoadingStyle:style];
 }
 - (void)mapViewWillStartRenderingFrame:(MLNMapView *)mapView {
-	if ([self owns]) { [self sampleLayout]; [self.state frameStart:self.style]; }
+	if ([self owns]) { [self sampleLayout]; [self.state frameStart:self.style]; [self followCovers]; }
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapViewWillStartRenderingFrame:mapView];
 }
 - (void)mapViewDidFinishRenderingMap:(MLNMapView *)mapView fullyRendered:(BOOL)fully {
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapViewDidFinishRenderingMap:mapView fullyRendered:fully];
 }
 - (void)mapViewDidFinishRenderingFrame:(MLNMapView *)mapView fullyRendered:(BOOL)fully {
-	if ([self owns]) [self.state frameEnd:self.style fully:fully];
+	if ([self owns]) { [self.state frameEnd:self.style fully:fully]; if (fully && self.reveals.count) [self startReveals]; }
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapViewDidFinishRenderingFrame:mapView fullyRendered:fully];
 }
 - (void)mapViewDidFinishRenderingFrame:(MLNMapView *)mapView fullyRendered:(BOOL)fully frameEncodingTime:(double)encoding frameRenderingTime:(double)rendering {
-	if ([self owns]) [self.state frameEnd:self.style fully:fully];
+	if ([self owns]) { [self.state frameEnd:self.style fully:fully]; if (fully && self.reveals.count) [self startReveals]; }
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapViewDidFinishRenderingFrame:mapView fullyRendered:fully frameEncodingTime:encoding frameRenderingTime:rendering];
 	else if ([self.previous respondsToSelector:@selector(mapViewDidFinishRenderingFrame:fullyRendered:)]) [self.previous mapViewDidFinishRenderingFrame:mapView fullyRendered:fully];
 }
 - (void)mapViewDidFinishRenderingFrame:(MLNMapView *)mapView fullyRendered:(BOOL)fully renderingStats:(MLNRenderingStats *)stats {
-	if ([self owns]) [self.state frameEnd:self.style fully:fully];
+	if ([self owns]) { [self.state frameEnd:self.style fully:fully]; if (fully && self.reveals.count) [self startReveals]; }
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapViewDidFinishRenderingFrame:mapView fullyRendered:fully renderingStats:stats];
 	else if ([self.previous respondsToSelector:@selector(mapViewDidFinishRenderingFrame:fullyRendered:)]) [self.previous mapViewDidFinishRenderingFrame:mapView fullyRendered:fully];
 }
@@ -194,7 +408,7 @@ static MLRNCamera *TFSurfaceCamera(UIView *root, MLRNMapView *map) {
 	else if ([self.previous respondsToSelector:@selector(mapView:regionWillChangeAnimated:)]) [self.previous mapView:mapView regionWillChangeAnimated:animated];
 }
 - (void)mapView:(MLNMapView *)mapView regionIsChangingWithReason:(MLNCameraChangeReason)reason {
-	if ([self owns]) [self.state gestureChange:self.view];
+	if ([self owns]) { [self.state gestureChange:self.view]; [self followCovers]; }
 	if ([self.previous respondsToSelector:_cmd]) [self.previous mapView:mapView regionIsChangingWithReason:reason];
 	else if ([self.previous respondsToSelector:@selector(mapViewRegionIsChanging:)]) [self.previous mapViewRegionIsChanging:mapView];
 }
@@ -338,6 +552,40 @@ RCT_REMAP_METHOD(cancelCamera, cancelCameraForSurface:(NSString *)identifier seq
 	@try { if (!TFAdmissionValidToken(identifier)) TFSurfaceInvalid(); [self.surfaces[identifier].state cancelCommand:TFSurfaceInteger(sequence)]; resolve(@{@"cancelled": @YES}); }
 	@catch (NSException *exception) { TFSurfaceReject(reject); }
 }
+static double TFSurfaceDuration(id value) {
+	if (![value isKindOfClass:NSNumber.class] || CFGetTypeID((__bridge CFTypeRef)value) == CFBooleanGetTypeID()) TFSurfaceInvalid();
+	double number = [value doubleValue];
+	if (!std::isfinite(number) || number < 0 || number > 5000 || std::floor(number) != number) TFSurfaceInvalid();
+	return number;
+}
+RCT_REMAP_METHOD(coverSurface, coverSurface:(NSString *)identifier duration:(NSNumber *)duration resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		TFSurfaceAttachment *surface = [self current:identifier allowFailed:NO];
+		double milliseconds = TFSurfaceDuration(duration);
+		resolve(@{@"covered": @(milliseconds > 0 && [surface cover])});
+	} @catch (NSException *exception) { TFSurfaceReject(reject); }
+}
+RCT_REMAP_METHOD(revealSurface, revealSurface:(NSString *)identifier duration:(NSNumber *)duration resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		TFSurfaceAttachment *surface = [self current:identifier allowFailed:YES];
+		[surface reveal:TFSurfaceDuration(duration) resolve:resolve];
+	} @catch (NSException *exception) { TFSurfaceReject(reject); }
+}
+RCT_REMAP_METHOD(applyThemeValues, applyThemeValuesForSurface:(NSString *)identifier style:(NSString *)token values:(NSDictionary *)values resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		TFSurfaceAttachment *surface = [self current:identifier allowFailed:NO];
+		if (![values isKindOfClass:NSDictionary.class] || ![surface.token isEqual:token]) TFSurfaceInvalid();
+		NSUInteger applied = [surface applyThemeValues:values];
+		resolve(@{@"applied": @(applied)});
+	} @catch (NSException *exception) { TFSurfaceReject(reject); }
+}
+RCT_REMAP_METHOD(discardSurfaceCover, discardSurfaceCover:(NSString *)identifier resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject) {
+	@try {
+		if (!TFAdmissionValidToken(identifier)) TFSurfaceInvalid();
+		[self.surfaces[identifier] discardCovers];
+		resolve(@{@"discarded": @YES});
+	} @catch (NSException *exception) { TFSurfaceReject(reject); }
+}
 - (void)retire:(TFSurfaceAttachment *)surface resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject {
 	[surface retire];
 	if (!surface.root.window) { [self.surfaces removeObjectForKey:surface.identifier]; resolve(@{@"detached": @YES}); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/react-native",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "license": "Apache-2.0",
   "description": "Tileflow maps, camera control and semantic interactions for React Native.",
   "type": "module",
@@ -36,7 +36,7 @@
     }
   },
   "dependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.27 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.31 <0.1.0-beta.0",
     "@tileflow/interactions": ">=0.1.0-alpha.4 <0.1.0-beta.0"
   },
   "peerDependencies": {