@rafaelaugusto/jolt-native 0.0.0-stage → 0.1.0-beta.13

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rafael Augusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# Jolt native property runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Optional NativeScript plugin for `@rafaelaugusto/jolt/native`. Install this package alongside Jolt and rebuild the app. Core Jolt does not depend on this plugin.
+
+```sh
+npm install @rafaelaugusto/jolt @rafaelaugusto/jolt-native
+```
+
+Includes compiled scalar/compound playback, MapKit and SceneKit sinks on iOS, and a MapLibre sink on Android. It does not install MapLibre; the app chooses its SDK version. Reference demo: MapLibre Android 11.8.0, NativeScript 9.1, iOS 26 / Android 16. Minimum NativeScript 8.9; native helper APIs require iOS 13+ / Android API 23+ (the app/runtime or SDK may require newer).
+
+See the [native properties guide](https://jolt.rafaelaugusto.dev/guide/native-properties) for capabilities, authoring, ownership and execution limits.
+
+Release maintainers: publish this optional package together with compatible core releases (`npm publish` from this directory). Build and pack the core at the repository root. The demo uses local file dependencies and never needs the package published for validation.

package/index.js

@@ -0,0 +1,2 @@
+// NativeScript discovers this optional plugin through package dependencies.
+export {}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@rafaelaugusto/jolt-native",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.13",
+  "description": "Optional compiled property adapters for Jolt (MapKit, MapLibre and SceneKit).",
+  "license": "MIT",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "platforms/ios",
+    "platforms/android/java",
+    "platforms/android/include.gradle",
+    "platforms/android/proguard-rules.pro"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@rafaelaugusto/jolt": ">=0.1.0-beta.13",
+    "@nativescript/core": ">=8.9.0"
+  },
+  "nativescript": {
+    "platforms": {
+      "ios": "8.9.0",
+      "android": "8.9.0"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafaelaugustos/jolt.git",
+    "directory": "packages/native"
+  }
+}

package/platforms/android/include.gradle

@@ -0,0 +1,6 @@
+def dependency = nativescriptDependencies.find { it.name == '@rafaelaugusto/jolt-native' }
+if (dependency != null) {
+    android.buildTypes.all {
+        proguardFile new File(rootDir, "${dependency.directory}/platforms/android/proguard-rules.pro")
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/MapLibrePropertySink.java

@@ -0,0 +1,60 @@
+package org.rafaelaugusto.jolt;
+
+import java.lang.reflect.Constructor;
+import java.lang.reflect.Field;
+import java.lang.reflect.Method;
+
+/** Optional MapLibre integration: cached reflection avoids a core dependency on the SDK. */
+public final class MapLibrePropertySink extends PropertySink {
+    private final boolean camera;
+    private final Constructor<?> coordinate, builder;
+    private final Method read, write, build, targetMethod, zoom, tilt, bearing, cameraUpdate;
+    private final Method latitude, longitude;
+    private final Field cameraTarget, cameraZoom, cameraTilt, cameraBearing;
+    public MapLibrePropertySink(Object target, boolean camera) {
+        super(target,camera?5:2); this.camera=camera;
+        try {
+            Class<?> latLng=Class.forName("org.maplibre.android.geometry.LatLng");
+            coordinate=latLng.getConstructor(double.class,double.class);
+            latitude=latLng.getMethod("getLatitude"); longitude=latLng.getMethod("getLongitude");
+            if(camera) {
+                Class<?> position=Class.forName("org.maplibre.android.camera.CameraPosition");
+                Class<?> b=Class.forName("org.maplibre.android.camera.CameraPosition$Builder");
+                Class<?> update=Class.forName("org.maplibre.android.camera.CameraUpdate");
+                builder=b.getConstructor(); build=b.getMethod("build");
+                targetMethod=b.getMethod("target",latLng); zoom=b.getMethod("zoom",double.class);
+                tilt=b.getMethod("tilt",double.class); bearing=b.getMethod("bearing",double.class);
+                cameraUpdate=Class.forName("org.maplibre.android.camera.CameraUpdateFactory").getMethod("newCameraPosition",position);
+                read=target.getClass().getMethod("getCameraPosition"); write=target.getClass().getMethod("moveCamera",update);
+                cameraTarget=position.getField("target"); cameraZoom=position.getField("zoom");
+                cameraTilt=position.getField("tilt"); cameraBearing=position.getField("bearing");
+            } else {
+                read=target.getClass().getMethod("getPosition"); write=target.getClass().getMethod("setPosition",latLng);
+                builder=null; build=targetMethod=zoom=tilt=bearing=cameraUpdate=null;
+                cameraTarget=cameraZoom=cameraTilt=cameraBearing=null;
+            }
+        } catch(ReflectiveOperationException e) { throw new IllegalArgumentException("MapLibre adapter needs a compatible MapLibreMap or Marker",e); }
+    }
+    public double[] read() {
+        Object object=target.get(); if(object==null) return new double[getDimensions()];
+        try {
+            Object value=read.invoke(object), p=camera?cameraTarget.get(value):value;
+            double lat=((Number)latitude.invoke(p)).doubleValue(), lon=((Number)longitude.invoke(p)).doubleValue();
+            return camera?new double[]{lat,lon,cameraZoom.getDouble(value),cameraTilt.getDouble(value),cameraBearing.getDouble(value)}:new double[]{lat,lon};
+        } catch(ReflectiveOperationException e) { throw new IllegalStateException(e); }
+    }
+    public void write(double[] values) {
+        Object object=target.get(); if(object==null) return;
+        try {
+            double lat=Math.max(-85.05112878,Math.min(85.05112878,values[0]));
+            double lon=((values[1]+180)%360+360)%360-180;
+            Object p=coordinate.newInstance(lat,lon);
+            if(!camera) write.invoke(object,p);
+            else {
+                Object b=builder.newInstance(); targetMethod.invoke(b,p);
+                zoom.invoke(b,Math.max(0,Math.min(24,values[2]))); tilt.invoke(b,Math.max(0,Math.min(60,values[3])));
+                bearing.invoke(b,values[4]); write.invoke(object,cameraUpdate.invoke(null,build.invoke(b)));
+            }
+        } catch(ReflectiveOperationException e) { throw new IllegalStateException(e); }
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/PropertyPlayer.java

@@ -0,0 +1,85 @@
+package org.rafaelaugusto.jolt;
+
+import android.animation.Animator;
+import android.animation.AnimatorListenerAdapter;
+import android.animation.ValueAnimator;
+import android.view.animation.LinearInterpolator;
+
+/** Native sampled compound-property playback. No JS animation-update listener. */
+public final class PropertyPlayer {
+    public interface Listener { void onEnd(boolean completed); }
+    private PropertySink sink;
+    private Listener listener;
+    private final double[] times, values, finalValue;
+    private final double duration, delay;
+    private final int repeats, dimensions;
+    private final boolean reverse;
+    private ValueAnimator animator;
+    private boolean suppressed, stopped, counted;
+    private long frames;
+    private static int active;
+
+    public PropertyPlayer(PropertySink sink, double[] times, double[] values, double[] finalValue,
+                          double duration, double delay, double repeat, boolean reverse, Listener listener) {
+        if (!sink.isCompiled() || times.length<2 || values.length!=times.length*sink.getDimensions())
+            throw new IllegalArgumentException("Expected compiled sink and matching keyframes");
+        this.sink=sink; this.times=times.clone(); this.values=values.clone(); this.finalValue=finalValue.clone();
+        this.duration=Math.max(1,duration); this.delay=delay; this.repeats=repeat<0?-1:(int)repeat;
+        this.reverse=reverse; this.listener=listener; this.dimensions=sink.getDimensions();
+        control(0,false);
+    }
+    public static int activeCount() { return active; }
+    public long getFrames() { return frames; }
+    private void count(boolean running) {
+        if(counted==running) return;
+        counted=running; active+=running?1:-1;
+    }
+    private void apply(double progress) {
+        if(stopped) return;
+        if(!sink.isAlive()) { end(false); return; }
+        int low=0, high=times.length-1;
+        while(low+1<high) { int mid=(low+high)/2; if(times[mid]<=progress) low=mid; else high=mid; }
+        double span=times[high]-times[low], t=span>0?Math.max(0,Math.min(1,(progress-times[low])/span)):1;
+        double[] result=new double[dimensions];
+        for(int i=0;i<dimensions;i++) result[i]=values[low*dimensions+i]+(values[high*dimensions+i]-values[low*dimensions+i])*t;
+        write(result);
+    }
+    private void write(double[] value) {
+        try { if(sink!=null && sink.isAlive()) { sink.write(value); frames++; } else end(false); }
+        catch(RuntimeException e) { android.util.Log.e("Jolt","Native property write failed",e); end(false); }
+    }
+    private void end(boolean completed) {
+        count(false);
+        if(listener!=null && !stopped) listener.onEnd(completed);
+        if(!completed) cancel();
+    }
+    public void control(double time, boolean paused) {
+        if(stopped) return;
+        suppressed=true;
+        if(animator!=null) { animator.removeAllUpdateListeners(); animator.removeAllListeners(); animator.cancel(); }
+        animator=ValueAnimator.ofFloat(0,1);
+        animator.setInterpolator(new LinearInterpolator()); animator.setDuration((long)duration);
+        animator.setStartDelay((long)Math.max(0,delay-time)); animator.setRepeatCount(repeats);
+        animator.setRepeatMode(reverse?ValueAnimator.REVERSE:ValueAnimator.RESTART);
+        animator.addUpdateListener(value -> { if(!suppressed) apply(((Number)value.getAnimatedValue()).doubleValue()); });
+        animator.addListener(new AnimatorListenerAdapter() {
+            @Override public void onAnimationEnd(Animator animation) {
+                if(!suppressed && !stopped) { write(finalValue); end(true); }
+            }
+        });
+        animator.start();
+        if(paused) animator.pause();
+        if(time>=delay) animator.setCurrentPlayTime((long)Math.max(0,time-delay));
+        suppressed=false;
+        double local=Math.max(0,time-delay), iteration=Math.floor(local/duration), progress=(local%duration)/duration;
+        if(reverse && iteration%2>=1) progress=1-progress;
+        if(repeats>=0 && time>=delay+duration*(repeats+1)) write(finalValue); else apply(progress);
+        count(!paused && !stopped && (repeats<0 || time<delay+duration*(repeats+1)));
+    }
+    public void cancel() {
+        if(stopped) return;
+        stopped=true; listener=null; count(false);
+        if(animator!=null) { animator.removeAllUpdateListeners(); animator.removeAllListeners(); animator.cancel(); animator=null; }
+        sink=null;
+    }
+}

package/platforms/android/java/org/rafaelaugusto/jolt/PropertySink.java

@@ -0,0 +1,48 @@
+package org.rafaelaugusto.jolt;
+
+import java.lang.ref.WeakReference;
+import java.lang.reflect.Method;
+
+/** Implement in compiled Java/Kotlin. Property writes and reads run on Android's UI thread. */
+public abstract class PropertySink {
+    protected final WeakReference<Object> target;
+    private final int dimensions;
+    protected PropertySink(Object target, int dimensions) { this.target=new WeakReference<>(target); this.dimensions=dimensions; }
+    public final int getDimensions() { return dimensions; }
+    public boolean isAlive() { return target.get()!=null; }
+    public final boolean isCompiled() {
+        return !java.lang.reflect.Proxy.isProxyClass(getClass()) && !getClass().getName().startsWith("com.tns.gen.");
+    }
+    public abstract double[] read();
+    public abstract void write(double[] values);
+    public void dispose() { target.clear(); }
+
+    /** Numeric JavaBean property, with cached reflection and no JS setter. */
+    public static PropertySink scalar(Object target, String getter, String setter) {
+        return new Scalar(target, getter, setter);
+    }
+    private static final class Scalar extends PropertySink {
+        private final Method getter, setter;
+        private final boolean useFloat;
+        Scalar(Object target, String get, String set) {
+            super(target,1);
+            try {
+                getter=target.getClass().getMethod(get);
+                Class<?> type=getter.getReturnType();
+                if (type!=float.class && type!=double.class) throw new IllegalArgumentException("Scalar properties must return float or double");
+                setter=target.getClass().getMethod(set,type); useFloat=type==float.class;
+            } catch (ReflectiveOperationException e) { throw new IllegalArgumentException("Unsupported numeric native property",e); }
+        }
+        public double[] read() {
+            Object object=target.get(); if(object==null) return new double[]{0};
+            try { return new double[]{((Number)getter.invoke(object)).doubleValue()}; }
+            catch (ReflectiveOperationException e) { throw new IllegalStateException(e); }
+        }
+        public void write(double[] values) {
+            Object object=target.get(); if(object==null) return;
+            try {
+                if(useFloat) setter.invoke(object, (float)values[0]); else setter.invoke(object,values[0]);
+            } catch (ReflectiveOperationException e) { throw new IllegalStateException(e); }
+        }
+    }
+}

package/platforms/android/proguard-rules.pro

@@ -0,0 +1,13 @@
+-keep class org.rafaelaugusto.jolt.PropertySink { *; }
+-keep class org.rafaelaugusto.jolt.PropertySink$* { *; }
+-keep class org.rafaelaugusto.jolt.PropertyPlayer { *; }
+-keep class org.rafaelaugusto.jolt.PropertyPlayer$* { *; }
+-keep class org.rafaelaugusto.jolt.MapLibrePropertySink { *; }
+# Optional MapLibre adapters cache these SDK methods/fields by name.
+-keep class org.maplibre.android.geometry.LatLng { *; }
+-keep class org.maplibre.android.camera.CameraPosition { *; }
+-keep class org.maplibre.android.camera.CameraPosition$Builder { *; }
+-keep class org.maplibre.android.camera.CameraUpdate { *; }
+-keep class org.maplibre.android.camera.CameraUpdateFactory { *; }
+-keepclassmembers class org.maplibre.android.maps.MapLibreMap { public *** getCameraPosition(...); public void moveCamera(...); }
+-keepclassmembers class org.maplibre.android.annotations.Marker { public *** getPosition(...); public void setPosition(...); }

package/platforms/ios/build.xcconfig

@@ -0,0 +1 @@
+OTHER_LDFLAGS = $(inherited) -framework MapKit -framework SceneKit

package/platforms/ios/src/JoltPropertyPlayer.h

@@ -0,0 +1,28 @@
+#import <Foundation/Foundation.h>
+NS_ASSUME_NONNULL_BEGIN
+
+/** Subclass in compiled Objective-C/Swift. Targets are weak; writes run on the main thread. */
+@interface JoltPropertySink : NSObject
+- (instancetype)initWithTarget:(NSObject *)target dimensions:(NSUInteger)dimensions;
++ (instancetype)scalarTarget:(NSObject *)target keyPath:(NSString *)keyPath;
+@property(nonatomic, weak, readonly, nullable) NSObject *target;
+@property(nonatomic, readonly) NSUInteger dimensions;
+@property(nonatomic, readonly) BOOL alive;
+@property(nonatomic, readonly) BOOL compiled;
+- (NSArray<NSNumber *> *)read;
+- (void)write:(NSArray<NSNumber *> *)values;
+- (void)dispose;
+@end
+
+@interface JoltPropertyPlayer : NSObject
++ (instancetype)startSink:(JoltPropertySink *)sink times:(NSArray<NSNumber *> *)times
+                   values:(NSArray<NSNumber *> *)values finalValue:(NSArray<NSNumber *> *)finalValue
+                 duration:(double)duration delay:(double)delay repeat:(double)repeat reverse:(BOOL)reverse
+               completion:(void (^)(BOOL))completion;
+@property(nonatomic, readonly) double elapsed;
+@property(nonatomic, readonly) NSUInteger frames;
++ (NSUInteger)activeCount;
+- (void)control:(double)elapsed paused:(BOOL)paused;
+- (void)cancel;
+@end
+NS_ASSUME_NONNULL_END

package/platforms/ios/src/JoltPropertyPlayer.m

@@ -0,0 +1,130 @@
+#import "JoltPropertyPlayer.h"
+#import <QuartzCore/QuartzCore.h>
+#import <UIKit/UIKit.h>
+#import <objc/runtime.h>
+
+@interface JoltPropertySink ()
+@property(nonatomic, weak, readwrite) NSObject *target;
+@property(nonatomic, readwrite) NSUInteger dimensions;
+@end
+@interface JoltScalarSink : JoltPropertySink
+@property(nonatomic, copy) NSString *keyPath;
++ (instancetype)target:(NSObject *)target keyPath:(NSString *)keyPath;
+@end
+@implementation JoltPropertySink
+- (instancetype)initWithTarget:(NSObject *)target dimensions:(NSUInteger)dimensions {
+    if ((self = [super init])) { _target = target; _dimensions = dimensions; }
+    return self;
+}
++ (instancetype)scalarTarget:(NSObject *)target keyPath:(NSString *)keyPath { return [JoltScalarSink target:target keyPath:keyPath]; }
+- (BOOL)alive { return self.target != nil; }
+- (BOOL)compiled { return class_getImageName(self.class) != NULL; }
+- (NSArray<NSNumber *> *)read { [self doesNotRecognizeSelector:_cmd]; return @[]; }
+- (void)write:(NSArray<NSNumber *> *)values { [self doesNotRecognizeSelector:_cmd]; }
+- (void)dispose { self.target = nil; }
+@end
+
+@implementation JoltScalarSink
++ (instancetype)target:(NSObject *)target keyPath:(NSString *)keyPath {
+    JoltScalarSink *sink = [[self alloc] initWithTarget:target dimensions:1]; sink.keyPath = keyPath;
+    NSAssert([[target valueForKeyPath:keyPath] isKindOfClass:NSNumber.class], @"Expected a numeric native property");
+    return sink;
+}
+- (NSArray<NSNumber *> *)read { return @[[self.target valueForKeyPath:self.keyPath] ?: @0]; }
+- (void)write:(NSArray<NSNumber *> *)values {
+    [CATransaction begin]; [CATransaction setDisableActions:YES];
+    [self.target setValue:values[0] forKeyPath:self.keyPath];
+    [CATransaction commit];
+}
+@end
+
+@interface JoltPropertyPlayer ()
+@property(nonatomic, strong, nullable) JoltPropertySink *sink;
+@property(nonatomic, copy) NSArray<NSNumber *> *times, *values, *finalValue;
+@property(nonatomic) double duration, delay, repeats, anchor, offset;
+@property(nonatomic) BOOL reverse, paused, stopped, ended;
+@property(nonatomic, readwrite) NSUInteger frames;
+@property(nonatomic, copy, nullable) void (^completion)(BOOL);
+@end
+@implementation JoltPropertyPlayer
+static NSMutableSet<JoltPropertyPlayer *> *playing;
+static CADisplayLink *displayLink;
++ (void)initialize { if (self == JoltPropertyPlayer.class) playing = [NSMutableSet new]; }
++ (void)schedule {
+    if (playing.count && !displayLink) {
+        displayLink = [CADisplayLink displayLinkWithTarget:self selector:@selector(tick:)];
+        if (@available(iOS 15.0, *)) {
+            float rate = MIN(120, UIScreen.mainScreen.maximumFramesPerSecond);
+            displayLink.preferredFrameRateRange = CAFrameRateRangeMake(MIN(80, rate), rate, rate);
+        }
+        [displayLink addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];
+    } else if (!playing.count) { [displayLink invalidate]; displayLink = nil; }
+}
++ (void)tick:(CADisplayLink *)frame {
+    for (JoltPropertyPlayer *player in playing.allObjects) {
+        if (!player.sink.alive) { [player end:NO]; continue; }
+        [player apply:player.elapsed];
+        if (isfinite(player.repeats) && player.elapsed >= player.delay + player.duration * (player.repeats + 1)) [player end:YES];
+    }
+}
++ (instancetype)startSink:(JoltPropertySink *)sink times:(NSArray<NSNumber *> *)times
+                   values:(NSArray<NSNumber *> *)values finalValue:(NSArray<NSNumber *> *)finalValue
+                 duration:(double)duration delay:(double)delay repeat:(double)repeat reverse:(BOOL)reverse
+               completion:(void (^)(BOOL))completion {
+    NSParameterAssert(NSThread.isMainThread);
+    NSParameterAssert(sink.compiled && sink.dimensions && values.count == times.count * sink.dimensions && finalValue.count == sink.dimensions);
+    JoltPropertyPlayer *player = [self new];
+    player.sink = sink; player.times = times; player.values = values; player.finalValue = finalValue;
+    player.duration = MAX(0.001, duration); player.delay = delay; player.repeats = repeat; player.reverse = reverse;
+    player.anchor = CACurrentMediaTime() * 1000; player.completion = completion;
+    [player apply:0];
+    if (!player.ended) { [playing addObject:player]; [self schedule]; }
+    return player;
+}
+- (double)elapsed { return self.offset + (self.paused ? 0 : CACurrentMediaTime() * 1000 - self.anchor); }
+- (void)apply:(double)elapsed {
+    if (self.stopped || !self.sink.alive) return;
+    @try {
+        if (isfinite(self.repeats) && elapsed >= self.delay + self.duration * (self.repeats + 1)) {
+            [self.sink write:self.finalValue]; self.frames++; return;
+        }
+        double time = MAX(0, elapsed - self.delay), iteration = floor(time / self.duration);
+        double progress = fmod(time, self.duration) / self.duration;
+        if (self.reverse && fmod(iteration, 2) >= 1) progress = 1 - progress;
+        NSUInteger low = 0, high = self.times.count - 1;
+        while (low + 1 < high) {
+            NSUInteger mid = (low + high) / 2;
+            if (self.times[mid].doubleValue <= progress) low = mid; else high = mid;
+        }
+        double start = self.times[low].doubleValue, finish = self.times[high].doubleValue;
+        double t = finish > start ? MIN(1, MAX(0, (progress-start)/(finish-start))) : 1;
+        NSUInteger n = self.sink.dimensions;
+        NSMutableArray *value = [NSMutableArray arrayWithCapacity:n];
+        for (NSUInteger i=0; i<n; i++) {
+            double a=self.values[low*n+i].doubleValue, b=self.values[high*n+i].doubleValue;
+            [value addObject:@(a+(b-a)*t)];
+        }
+        [self.sink write:value]; self.frames++;
+    } @catch (NSException *exception) { NSLog(@"Jolt native property failed: %@", exception.reason); [self end:NO]; }
+}
+- (void)control:(double)elapsed paused:(BOOL)paused {
+    if (self.stopped) return;
+    self.offset=elapsed; self.anchor=CACurrentMediaTime()*1000; self.paused=paused; self.ended=NO;
+    [self apply:elapsed];
+    if (paused || self.ended) [playing removeObject:self]; else [playing addObject:self];
+    [JoltPropertyPlayer schedule];
+}
+- (void)end:(BOOL)completed {
+    if (self.ended || self.stopped) return;
+    self.ended=YES;
+    [playing removeObject:self]; [JoltPropertyPlayer schedule];
+    if (self.completion) self.completion(completed);
+}
+- (void)cancel {
+    if (self.stopped) return;
+    self.stopped=YES; self.completion=nil;
+    [playing removeObject:self]; self.sink=nil;
+    [JoltPropertyPlayer schedule];
+}
++ (NSUInteger)activeCount { return playing.count; }
+@end

package/platforms/ios/src/JoltReferenceProperties.h

@@ -0,0 +1,8 @@
+#import "JoltPropertyPlayer.h"
+NS_ASSUME_NONNULL_BEGIN
+@interface JoltReferenceProperties : NSObject
++ (JoltPropertySink *)mapCoordinate:(NSObject *)annotation;
++ (JoltPropertySink *)mapCamera:(NSObject *)mapView;
++ (JoltPropertySink *)scenePose:(NSObject *)node;
+@end
+NS_ASSUME_NONNULL_END

package/platforms/ios/src/JoltReferenceProperties.m

@@ -0,0 +1,63 @@
+#import "JoltReferenceProperties.h"
+#import <MapKit/MapKit.h>
+#import <SceneKit/SceneKit.h>
+
+static double longitude(double value) { return fmod(fmod(value+180,360)+360,360)-180; }
+@interface JoltMapCoordinateSink : JoltPropertySink @end
+@implementation JoltMapCoordinateSink
+- (NSArray<NSNumber *> *)read {
+    CLLocationCoordinate2D p=[(id<MKAnnotation>)self.target coordinate];
+    return @[@(p.latitude),@(p.longitude)];
+}
+- (void)write:(NSArray<NSNumber *> *)values {
+    id<MKAnnotation> target=(id)self.target;
+    if(target) target.coordinate=CLLocationCoordinate2DMake(MAX(-90,MIN(90,values[0].doubleValue)),longitude(values[1].doubleValue));
+}
+@end
+@interface JoltMapCameraSink : JoltPropertySink @end
+@implementation JoltMapCameraSink
+- (NSArray<NSNumber *> *)read {
+    MKMapCamera *camera=[(MKMapView *)self.target camera];
+    return @[@(camera.centerCoordinate.latitude),@(camera.centerCoordinate.longitude),@(camera.altitude),@(camera.pitch),@(camera.heading)];
+}
+- (void)write:(NSArray<NSNumber *> *)values {
+    MKMapView *map=(id)self.target;
+    if(!map) return;
+    MKMapCamera *camera=[map.camera copy];
+    camera.centerCoordinate=CLLocationCoordinate2DMake(MAX(-90,MIN(90,values[0].doubleValue)),longitude(values[1].doubleValue));
+    camera.altitude=MAX(1,values[2].doubleValue); camera.pitch=MAX(0,MIN(80,values[3].doubleValue)); camera.heading=values[4].doubleValue;
+    [map setCamera:camera animated:NO];
+}
+@end
+@interface JoltScenePoseSink : JoltPropertySink @end
+@implementation JoltScenePoseSink
+- (NSArray<NSNumber *> *)read {
+    SCNNode *node=(id)self.target;
+    SCNNode *presented=node.presentationNode ?: node;
+    SCNVector3 p=presented.position; SCNQuaternion q=presented.orientation;
+    return @[@(p.x),@(p.y),@(p.z),@(q.x),@(q.y),@(q.z),@(q.w)];
+}
+- (void)write:(NSArray<NSNumber *> *)values {
+    SCNNode *node=(id)self.target; if(!node) return;
+    [SCNTransaction begin]; [SCNTransaction setDisableActions:YES];
+    node.position=SCNVector3Make(values[0].floatValue,values[1].floatValue,values[2].floatValue);
+    double x=values[3].doubleValue,y=values[4].doubleValue,z=values[5].doubleValue,w=values[6].doubleValue;
+    double norm=sqrt(x*x+y*y+z*z+w*w);
+    node.orientation=norm>0?SCNVector4Make(x/norm,y/norm,z/norm,w/norm):SCNVector4Make(0,0,0,1);
+    [SCNTransaction commit];
+}
+@end
+@implementation JoltReferenceProperties
++ (JoltPropertySink *)mapCoordinate:(NSObject *)annotation {
+    NSParameterAssert([annotation conformsToProtocol:@protocol(MKAnnotation)] && [annotation respondsToSelector:@selector(setCoordinate:)]);
+    return [[JoltMapCoordinateSink alloc] initWithTarget:annotation dimensions:2];
+}
++ (JoltPropertySink *)mapCamera:(NSObject *)mapView {
+    NSParameterAssert([mapView isKindOfClass:MKMapView.class]);
+    return [[JoltMapCameraSink alloc] initWithTarget:mapView dimensions:5];
+}
++ (JoltPropertySink *)scenePose:(NSObject *)node {
+    NSParameterAssert([node isKindOfClass:SCNNode.class]);
+    return [[JoltScenePoseSink alloc] initWithTarget:node dimensions:7];
+}
+@end

package/platforms/ios/src/module.modulemap

@@ -0,0 +1,5 @@
+module JoltNativeProperties {
+    header "JoltPropertyPlayer.h"
+    header "JoltReferenceProperties.h"
+    export *
+}