@rafaelaugusto/jolt 0.1.0-beta.9 → 0.1.0-rc.2

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

@@ -0,0 +1,115 @@
+package org.rafaelaugusto.jolt;
+
+import android.graphics.*;
+import android.graphics.drawable.BitmapDrawable;
+import android.view.*;
+import android.webkit.WebView;
+import android.widget.ImageView;
+import java.lang.ref.WeakReference;
+import java.util.ArrayList;
+
+/** One static return page, retained within a pixel budget. Only the current gesture owns an overlay. */
+public final class SharedNavigationScene extends View {
+    private final ViewGroup root;
+    private final ArrayList<WeakReference<View>> path=new ArrayList<>();
+    private final ArrayList<float[]> poses=new ArrayList<>();
+    private WeakReference<View> detail;
+    private SharedLayoutFlight.Anchor anchor;
+    private SharedLayoutFlight flight;
+    private Bitmap background;
+    private final Paint paint=new Paint(Paint.ANTI_ALIAS_FLAG | Paint.FILTER_BITMAP_FLAG);
+    private final int rootWidth,rootHeight;
+    private RectF pageFrame;
+    private final double budget;
+    private double radius,progress;
+    private boolean disposed,visible;
+    private static int retained,active;
+    private static long retainedPixels;
+    private long ownedPixels;
+    private String failureReason="ready";
+    public String getFailureReason(){return failureReason;}
+    private boolean invalid(String reason){failureReason=reason;return false;}
+
+    private SharedNavigationScene(View source,double budget) {
+        super(source.getContext()); root=(ViewGroup)source.getRootView();
+        this.budget=budget;rootWidth=root.getWidth();rootHeight=root.getHeight();
+        layout(0,0,rootWidth,rootHeight);setWillNotDraw(false);
+        setImportantForAccessibility(IMPORTANT_FOR_ACCESSIBILITY_NO_HIDE_DESCENDANTS);
+    }
+    public long pixels(){return ownedPixels;}
+    public static int retainedCount(){return retained;}
+    public static int activeCount(){return active;}
+    public static long retainedPixelCount(){return retainedPixels;}
+    private static boolean incompatible(View view) {
+        if(view instanceof SurfaceView || view instanceof TextureView || view instanceof WebView)return true;
+        if(view instanceof ViewGroup)for(int i=0;i<((ViewGroup)view).getChildCount();i++)if(incompatible(((ViewGroup)view).getChildAt(i)))return true;
+        return false;
+    }
+    private static float[] pose(View v) {
+        return new float[]{v.getLeft(),v.getTop(),v.getWidth(),v.getHeight(),v.getTranslationX(),v.getTranslationY(),v.getScaleX(),v.getScaleY(),v.getRotation(),v.getScrollX(),v.getScrollY()};
+    }
+    public static SharedNavigationScene capture(View source,View page,boolean image,double radius,double budget) {
+        if(source==null || page==null || !source.isAttachedToWindow() || source.getRootView()!=page.getRootView() || !(source.getRootView() instanceof ViewGroup) || incompatible(page))return null;
+        SharedNavigationScene scene=new SharedNavigationScene(source,budget);
+        SharedLayoutFlight.Anchor anchor=SharedLayoutFlight.anchor(source,image,radius,budget);
+        if(anchor==null)return null;
+        long pagePixels=(long)page.getWidth()*page.getHeight();
+        if(pagePixels<=0 || pagePixels+anchor.pixels()>budget){anchor.dispose();return null;}
+        boolean found=false;
+        for(View p=source;p!=null;p=p.getParent() instanceof View?(View)p.getParent():null) {
+            scene.path.add(new WeakReference<>(p));scene.poses.add(pose(p));
+            if(p==page){found=true;break;}
+        }
+        if(!found){anchor.dispose();return null;}
+        int visibility=source.getVisibility();
+        try {
+            scene.background=Bitmap.createBitmap(page.getWidth(),page.getHeight(),Bitmap.Config.ARGB_8888);
+            source.setVisibility(INVISIBLE);page.draw(new Canvas(scene.background));
+        } catch(OutOfMemoryError | RuntimeException error) { anchor.dispose();if(scene.background!=null)scene.background.recycle();return null; }
+        finally {source.setVisibility(visibility);}
+        int[] a=new int[2],b=new int[2];rootLocation(scene.root,a);page.getLocationOnScreen(b);
+        scene.pageFrame=new RectF(b[0]-a[0],b[1]-a[1],b[0]-a[0]+page.getWidth(),b[1]-a[1]+page.getHeight());
+        scene.anchor=anchor;scene.ownedPixels=pagePixels+anchor.pixels();retained++;retainedPixels+=scene.ownedPixels;
+        return scene;
+    }
+    private static void rootLocation(View root,int[] xy){root.getLocationOnScreen(xy);}
+    public void bind(View view,double radius){this.detail=new WeakReference<>(view);this.radius=radius;}
+    public boolean validSource() {
+        if(disposed || root.getWidth()!=rootWidth || root.getHeight()!=rootHeight || background==null || background.isRecycled())return invalid("viewport-changed");
+        if(anchor.bitmap==null || anchor.bitmap.isRecycled())return invalid("image-unavailable");
+        // Core can detach and rebuild a covered page's native children. Its static JS
+        // identity/content/layout stamp is checked once at gesture start by the adapter.
+        View page=path.get(path.size()-1).get();
+        if(page==null || !page.isAttachedToWindow())return true;
+        for(int i=0;i<path.size();i++) {
+            View v=path.get(i).get();if(v==null)return invalid("source-unavailable");
+            if(i+1<path.size() && v.getParent()!=path.get(i+1).get())return invalid("source-reparented");
+            float[] actual=pose(v),expected=poses.get(i);
+            for(int k=0;k<actual.length;k++)if(Math.abs(actual[k]-expected[k])>.1)return invalid("source-layout-changed");
+        }
+        if(anchor.image) {
+            View view=path.get(0).get();
+            if(!(view instanceof ImageView) || !(((ImageView)view).getDrawable() instanceof BitmapDrawable) || ((BitmapDrawable)((ImageView)view).getDrawable()).getBitmap()!=anchor.bitmap)return invalid("source-image-changed");
+        }
+        return true;
+    }
+    public boolean begin() {
+        finish();View view=detail==null?null:detail.get();
+        if(!validSource())return false;
+        if(view==null || !view.isAttachedToWindow() || view.getRootView()!=root)return invalid("target-unavailable");
+        progress=0;root.getOverlay().add(this);visible=true;active++;
+        try {
+            flight=anchor.image?SharedLayoutFlight.captureNavigationImage(view,radius,budget-ownedPixels):SharedLayoutFlight.capture(view,false,radius,budget-ownedPixels);
+            if(flight==null || !flight.prepareAnchor(anchor,budget-ownedPixels)){finish();return invalid("unsupported-target");}
+            failureReason="ready";flight.updateInteractive(0);return true;
+        } catch(RuntimeException | OutOfMemoryError error) { finish();return invalid("unsupported-target"); }
+    }
+    public boolean isAnimating(){return flight!=null;}
+    public boolean validActive(){return !visible || (validSource() && detail!=null && detail.get()!=null && detail.get().isAttachedToWindow());}
+    public void render(double p){if(flight==null)return;progress=Math.max(0,Math.min(1,p));flight.updateInteractive(progress);invalidate();}
+    @Override protected void onDraw(Canvas canvas) {
+        if(background==null)return;paint.setAlpha((int)Math.round(progress*255));canvas.drawBitmap(background,null,pageFrame,paint);
+    }
+    public void finish(){if(flight!=null){flight.dispose();flight=null;}if(visible){root.getOverlay().remove(this);visible=false;active--;}}
+    public void dispose(){if(disposed)return;finish();disposed=true;if(anchor!=null)anchor.dispose();anchor=null;if(background!=null)background.recycle();background=null;detail=null;path.clear();poses.clear();retained--;retainedPixels-=ownedPixels;}
+}

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

@@ -0,0 +1,39 @@
+package org.rafaelaugusto.jolt;
+
+/** Exact constant-target solution, matching JoltSpringState.h. No per-step allocation. */
+public final class SpringState {
+    public double position, velocity;
+
+    public SpringState(double position, double velocity) {
+        this.position = position;
+        this.velocity = velocity;
+    }
+
+    public void advance(double target, double stiffness, double damping, double mass, double seconds) {
+        if (seconds <= 0) return;
+        double x = position - target;
+        double w = Math.sqrt(stiffness / mass);
+        double z = damping / (2 * Math.sqrt(stiffness * mass));
+        double next, speed;
+        if (Math.abs(z - 1) < 1e-6) {
+            double b = velocity + w * x, e = Math.exp(-w * seconds);
+            next = e * (x + b * seconds);
+            speed = e * (b - w * (x + b * seconds));
+        } else if (z < 1) {
+            double a = z * w, d = w * Math.sqrt(1 - z * z);
+            double b = (velocity + a * x) / d;
+            double c = Math.cos(d * seconds), s = Math.sin(d * seconds), e = Math.exp(-a * seconds);
+            next = e * (x * c + b * s);
+            speed = e * ((-a * x + b * d) * c + (-a * b - x * d) * s);
+        } else {
+            double q = Math.sqrt(z * z - 1);
+            double r1 = -w / (z + q), r2 = -w * (z + q);
+            double c1 = (velocity - r2 * x) / (r1 - r2), c2 = x - c1;
+            double e1 = Math.exp(r1 * seconds), e2 = Math.exp(r2 * seconds);
+            next = c1 * e1 + c2 * e2;
+            speed = c1 * r1 * e1 + c2 * r2 * e2;
+        }
+        position = target + next;
+        velocity = speed;
+    }
+}

package/platforms/android/proguard-rules.pro

@@ -1,4 +1,7 @@
 -keep class org.rafaelaugusto.jolt.ColorTarget { *; }
+-keep class org.rafaelaugusto.jolt.CircleWorld { *; }
+-keep class org.rafaelaugusto.jolt.CircleWorld$* { *; }
+-keep class org.rafaelaugusto.jolt.MotionProbe { *; }
 -keep class org.nativescript.widgets.BorderDrawable { *; }
 -keepnames class org.nativescript.widgets.BoxShadowDrawable
 -keepclassmembers class org.nativescript.widgets.BoxShadowDrawable {
@@ -7,6 +10,8 @@
 -keep class org.rafaelaugusto.jolt.DecorationTarget { *; }
 -keep class org.rafaelaugusto.jolt.KeyboardFollower { *; }
 -keep class org.rafaelaugusto.jolt.KeyboardFollower$* { *; }
+-keep class org.rafaelaugusto.jolt.KeyboardObserver { *; }
+-keep class org.rafaelaugusto.jolt.KeyboardObserver$* { *; }
 -keep class org.rafaelaugusto.jolt.TextReveal { *; }
 -keep class org.rafaelaugusto.jolt.TextReveal$* { *; }
 -keep class org.rafaelaugusto.jolt.NumberRoll { *; }
@@ -15,3 +20,18 @@
 -keep class org.rafaelaugusto.jolt.ImageEffect$* { *; }
 -keep class org.rafaelaugusto.jolt.PhotoZoom { *; }
 -keep class org.rafaelaugusto.jolt.PhotoZoom$* { *; }
+-keep class org.rafaelaugusto.jolt.GradientLayer { *; }
+-keep class org.rafaelaugusto.jolt.GradientLayer$* { *; }
+-keep class org.rafaelaugusto.jolt.ParticleEmitter { *; }
+-keep class org.rafaelaugusto.jolt.ParticleEmitter$* { *; }
+-keep class org.rafaelaugusto.jolt.ReorderSession { *; }
+-keep class org.rafaelaugusto.jolt.ReorderSession$* { *; }
+-keep class org.rafaelaugusto.jolt.ReorderHandle { *; }
+-keep class org.rafaelaugusto.jolt.ReorderHandle$* { *; }
+-keep class org.rafaelaugusto.jolt.ReorderSurface { *; }
+-keep class org.rafaelaugusto.jolt.SharedLayoutFlight { *; }
+-keep class org.rafaelaugusto.jolt.SharedLayoutFlight$* { *; }
+-keep class org.rafaelaugusto.jolt.PredictiveBackSession { *; }
+-keep class org.rafaelaugusto.jolt.PredictiveBackSession$* { *; }
+
+-keep class org.rafaelaugusto.jolt.SharedNavigationScene { *; }

package/platforms/ios/build.xcconfig

@@ -1 +1 @@
-OTHER_LDFLAGS = $(inherited) -framework Metal -framework MetalKit
+OTHER_LDFLAGS = $(inherited) -framework Metal -framework MetalKit -framework CoreMotion

package/platforms/ios/src/JoltBlur.h

@@ -0,0 +1,14 @@
+#import <UIKit/UIKit.h>
+NS_ASSUME_NONNULL_BEGIN
+@interface JoltBlur : NSObject
++ (instancetype)attach:(UIView *)view options:(NSString *)options;
++ (NSInteger)liveCount;
++ (NSInteger)activeCount;
+- (void)paint:(double)amount;
+- (void)play:(NSString *)program;
+- (void)control:(double)time paused:(BOOL)paused;
+- (void)resize;
+- (NSString *)snapshot;
+- (void)dispose;
+@end
+NS_ASSUME_NONNULL_END

package/platforms/ios/src/JoltBlur.m

@@ -0,0 +1,86 @@
+#import "JoltBlur.h"
+#import <QuartzCore/QuartzCore.h>
+
+@interface JoltBlur ()
+@property(nonatomic,weak) UIView *host;
+@property(nonatomic) UIVisualEffectView *surface;
+@property(nonatomic) UIViewPropertyAnimator *material;
+@property(nonatomic) CADisplayLink *clock;
+@property(nonatomic) NSArray<NSNumber *> *times, *values;
+@property(nonatomic) double amount, duration, delay, repeats, anchor, offset;
+@property(nonatomic) BOOL reverse, disposed, paused;
+@property(nonatomic) NSUInteger frames;
+@end
+static NSInteger JoltBlurLive=0, JoltBlurActive=0;
+@implementation JoltBlur
++ (NSInteger)liveCount { return JoltBlurLive; }
++ (NSInteger)activeCount { return JoltBlurActive; }
++ (instancetype)attach:(UIView *)view options:(NSString *)options {
+    NSDictionary *o=[NSJSONSerialization JSONObjectWithData:[options dataUsingEncoding:NSUTF8StringEncoding] options:0 error:nil];
+    JoltBlur *b=[self new];b.host=view;
+    UIBlurEffectStyle style=[o[@"style"] isEqual:@"light"]?UIBlurEffectStyleLight:[o[@"style"] isEqual:@"dark"]?UIBlurEffectStyleDark:UIBlurEffectStyleSystemMaterial;
+    b.surface=[[UIVisualEffectView alloc]initWithEffect:nil];
+    b.surface.userInteractionEnabled=NO;b.surface.accessibilityElementsHidden=YES;
+    b.surface.accessibilityIdentifier=@"jolt:blur";
+    b.surface.autoresizingMask=UIViewAutoresizingFlexibleWidth|UIViewAutoresizingFlexibleHeight;
+    b.surface.clipsToBounds=YES;[view addSubview:b.surface];[b resize];
+    UIVisualEffectView *surface=b.surface;
+    b.material=[[UIViewPropertyAnimator alloc]initWithDuration:1 curve:UIViewAnimationCurveLinear animations:^{surface.effect=[UIBlurEffect effectWithStyle:style];}];
+    b.material.scrubsLinearly=YES;b.material.pausesOnCompletion=YES;
+    [b.material startAnimation];[b.material pauseAnimation];
+    [b paint:[o[@"amount"] doubleValue]];JoltBlurLive++;return b;
+}
+- (void)resize {
+    self.surface.frame=self.host.bounds;
+    self.surface.layer.cornerRadius=self.host.layer.cornerRadius;
+}
+- (void)apply:(double)value {
+    self.amount=MIN(1,MAX(0,value));self.material.fractionComplete=self.amount;
+    // Keep alpha at 1: changing effect-view alpha compromises its backdrop capture.
+    self.surface.hidden=self.amount==0;self.frames++;
+}
+- (void)cancel {
+    if(self.clock){[self.clock invalidate];self.clock=nil;JoltBlurActive--;}
+    self.times=nil;self.values=nil;
+}
+- (void)paint:(double)value {
+    if(self.disposed)return;[self cancel];[self apply:value];
+}
+- (void)play:(NSString *)program {
+    if(self.disposed)return;[self cancel];
+    NSDictionary *p=[NSJSONSerialization JSONObjectWithData:[program dataUsingEncoding:NSUTF8StringEncoding] options:0 error:nil];
+    self.times=p[@"times"];self.values=p[@"values"];self.duration=[p[@"duration"] doubleValue];self.delay=[p[@"delay"] doubleValue];self.repeats=[p[@"repeat"] doubleValue];self.reverse=[p[@"reverse"] boolValue];
+    self.offset=0;self.anchor=CACurrentMediaTime();self.paused=NO;[self advance:0];
+    self.clock=[CADisplayLink displayLinkWithTarget:self selector:@selector(tick:)];
+    [self.clock addToRunLoop:NSRunLoop.mainRunLoop forMode:NSRunLoopCommonModes];JoltBlurActive++;
+}
+- (void)advance:(double)elapsed {
+    if(!self.times.count)return;
+    double t=MAX(0,elapsed-self.delay), fraction;
+    if(self.duration<=0)fraction=elapsed<self.delay?0:(self.reverse && self.repeats>=0 && ((NSInteger)self.repeats%2==1)?0:1);
+    else if(self.repeats>=0 && t>=self.duration*(self.repeats+1))fraction=self.reverse && ((NSInteger)self.repeats%2==1)?0:1;
+    else { double cycles=t/self.duration;long long cycle=(long long)floor(cycles);fraction=cycles-cycle;if(self.reverse && cycle%2==1)fraction=1-fraction; }
+    NSUInteger low=0,high=self.times.count-1;
+    while(high-low>1){NSUInteger mid=(low+high)/2;if(self.times[mid].doubleValue<=fraction)low=mid;else high=mid;}
+    double span=self.times[high].doubleValue-self.times[low].doubleValue;
+    double mix=span>0?MIN(1,MAX(0,(fraction-self.times[low].doubleValue)/span)):1;
+    [self apply:self.values[low].doubleValue+(self.values[high].doubleValue-self.values[low].doubleValue)*mix];
+}
+- (void)tick:(CADisplayLink *)link {
+    double elapsed=self.offset+(CACurrentMediaTime()-self.anchor)*1000;
+    [self advance:elapsed];
+    if(self.repeats>=0 && elapsed>=self.delay+self.duration*(self.repeats+1))[self cancel];
+}
+- (void)control:(double)time paused:(BOOL)paused {
+    if(!self.clock)return;
+    self.offset=time;self.anchor=CACurrentMediaTime();self.paused=paused;self.clock.paused=paused;[self advance:time];
+}
+- (NSString *)snapshot {
+    NSDictionary *s=@{@"backend":@"ios-material",@"amount":@(self.amount),@"appliedAmount":@(self.material?self.material.fractionComplete:0),@"attached":@(!self.disposed),@"nativeAnimations":@(self.clock?1:0),@"frames":@(self.frames),@"width":@(self.surface.bounds.size.width),@"height":@(self.surface.bounds.size.height)};
+    return [[NSString alloc]initWithData:[NSJSONSerialization dataWithJSONObject:s options:0 error:nil] encoding:NSUTF8StringEncoding];
+}
+- (void)dispose {
+    if(self.disposed)return;[self cancel];self.disposed=YES;JoltBlurLive--;
+    [self.material stopAnimation:YES];self.material=nil;[self.surface removeFromSuperview];self.surface=nil;
+}
+@end

package/platforms/ios/src/JoltCircleMath.h

@@ -0,0 +1,191 @@
+#ifndef JOLT_CIRCLE_MATH_H
+#define JOLT_CIRCLE_MATH_H
+#include <math.h>
+#include <stdbool.h>
+#include <string.h>
+#define JOLT_CIRCLE_LIMIT 16
+#define JOLT_CIRCLE_SNAP_LIMIT 8
+#define JOLT_CIRCLE_DT (1.0/240.0)
+#define JOLT_CIRCLE_SPEED 1200.0
+typedef struct {
+    bool enabled;
+    double u,v,length,stiffness,damping;
+} JoltCircleAttachment;
+typedef struct {
+    int count,index,previousIndex;
+    bool active,previousActive;
+    double u[JOLT_CIRCLE_SNAP_LIMIT],v[JOLT_CIRCLE_SNAP_LIMIT];
+    double stiffness,damping,projection;
+} JoltCircleSnap;
+typedef struct {
+    double x,y,vx,vy,r,m,tx,ty,ax,ay,releaseX,releaseY,releaseVX,releaseVY;
+    bool released;
+    bool held,supported;
+    JoltCircleAttachment attachment,drag;
+    JoltCircleSnap snap;
+} JoltCircle;
+typedef struct {
+    JoltCircle bodies[JOLT_CIRCLE_LIMIT]; int count;
+    double width,height,gx,gy,restitution,damping,quiet;
+    unsigned long steps,contacts; bool sleeping;
+} JoltCircleState;
+static inline double JoltCircleClamp(double v,double lo,double hi){return fmax(lo,fmin(hi,v));}
+static inline void JoltCircleLimitVelocity(JoltCircle *b){double speed=hypot(b->vx,b->vy);if(speed>JOLT_CIRCLE_SPEED){b->vx*=JOLT_CIRCLE_SPEED/speed;b->vy*=JOLT_CIRCLE_SPEED/speed;}}
+static inline void JoltCircleWake(JoltCircleState *w){w->sleeping=false;w->quiet=0;}
+static inline bool JoltCircleFits(JoltCircleState *w,double width,double height){
+    double area=0;
+    if(!isfinite(width)||!isfinite(height)||width<=0||height<=0)return false;
+    for(int i=0;i<w->count;i++){JoltCircle *b=&w->bodies[i];if(2*b->r>fmin(width,height))return false;area+=3.141592653589793*b->r*b->r;}
+    return area<=width*height*.4;
+}
+static inline bool JoltCircleKinematic(JoltCircle *b){return b->held&&!b->drag.enabled;}
+static inline void JoltCircleWalls(JoltCircleState *w,JoltCircle *b,bool impulse){
+    double e=w->restitution;
+    if(b->x<=b->r){b->x=b->r;if(b->ax<0)b->supported=true;if(impulse&&!JoltCircleKinematic(b)&&b->vx<0){b->vx=fabs(b->vx)<40?0:-b->vx*e;w->contacts++;}}
+    if(b->x>=w->width-b->r){b->x=w->width-b->r;if(b->ax>0)b->supported=true;if(impulse&&!JoltCircleKinematic(b)&&b->vx>0){b->vx=fabs(b->vx)<40?0:-b->vx*e;w->contacts++;}}
+    if(b->y<=b->r){b->y=b->r;if(b->ay<0)b->supported=true;if(impulse&&!JoltCircleKinematic(b)&&b->vy<0){b->vy=fabs(b->vy)<40?0:-b->vy*e;w->contacts++;}}
+    if(b->y>=w->height-b->r){b->y=w->height-b->r;if(b->ay>0)b->supported=true;if(impulse&&!JoltCircleKinematic(b)&&b->vy>0){b->vy=fabs(b->vy)<40?0:-b->vy*e;w->contacts++;}}
+}
+static inline void JoltCircleContacts(JoltCircleState *w,bool impulse,int iterations){
+    for(int iteration=0;iteration<iterations;iteration++){
+        for(int i=0;i<w->count;i++)for(int j=i+1;j<w->count;j++){
+            JoltCircle *a=&w->bodies[i],*b=&w->bodies[j];
+            double dx=b->x-a->x,dy=b->y-a->y,d=hypot(dx,dy),radius=a->r+b->r;
+            if(d>radius+.02)continue;
+            double nx=d>1e-9?dx/d:1,ny=d>1e-9?dy/d:0;
+            double ia=JoltCircleKinematic(a)?0:1/a->m,ib=JoltCircleKinematic(b)?0:1/b->m,total=ia+ib;
+            if(total==0)continue;
+            double overlap=fmax(0,radius-d);
+            a->x-=nx*overlap*ia/total;a->y-=ny*overlap*ia/total;
+            b->x+=nx*overlap*ib/total;b->y+=ny*overlap*ib/total;
+            if(nx*a->ax+ny*a->ay>hypot(a->ax,a->ay)*.35)a->supported=true;
+            if(-nx*b->ax-ny*b->ay>hypot(b->ax,b->ay)*.35)b->supported=true;
+            double closing=(b->vx-a->vx)*nx+(b->vy-a->vy)*ny;
+            if(impulse&&closing<0){
+                double e=closing < -40?w->restitution:0,jolt=-(1+e)*closing/total;
+                a->vx-=nx*jolt*ia;a->vy-=ny*jolt*ia;b->vx+=nx*jolt*ib;b->vy+=ny*jolt*ib;
+                if(closing < -.1)w->contacts++;
+            }
+        }
+        for(int i=0;i<w->count;i++)JoltCircleWalls(w,&w->bodies[i],impulse);
+    }
+}
+// Targets use normalized coordinates so repeated resizes do not accumulate clamping drift.
+static inline double JoltCircleSnapX(JoltCircleState *w,JoltCircle *b,int index) {
+    return JoltCircleClamp(b->snap.u[index]*w->width,b->r,w->width-b->r);
+}
+static inline double JoltCircleSnapY(JoltCircleState *w,JoltCircle *b,int index) {
+    return JoltCircleClamp(b->snap.v[index]*w->height,b->r,w->height-b->r);
+}
+static inline void JoltCircleAttach(JoltCircleState *w,int index,bool enabled,double x,double y,double length,double stiffness,double damping) {
+    JoltCircle *b=&w->bodies[index];
+    b->attachment=(JoltCircleAttachment){enabled,x/w->width,y/w->height,length,stiffness,damping};
+    b->snap.active=b->snap.previousActive=false;JoltCircleWake(w);
+}
+static inline void JoltCircleSnapTo(JoltCircleState *w,int index,int target) {
+    JoltCircle *b=&w->bodies[index];
+    if(b->held||target<0||target>=b->snap.count)return;
+    b->snap.active=true;b->snap.index=target;JoltCircleWake(w);
+}
+static inline void JoltCircleCancel(JoltCircleState *w,int index) {
+    JoltCircle *b=&w->bodies[index];
+    if(!b->held)return;
+    b->held=false;b->vx=b->vy=0;
+    b->snap.active=b->snap.previousActive;b->snap.index=b->snap.previousIndex;JoltCircleWake(w);
+}
+static inline bool JoltCircleTargetClear(JoltCircleState *w,int index,double x,double y) {
+    JoltCircle *b=&w->bodies[index];
+    for(int i=0;i<w->count;i++)if(i!=index){
+        JoltCircle *other=&w->bodies[i];
+        if(hypot(x-other->x,y-other->y)<b->r+other->r+.001)return false;
+    }
+    return true;
+}
+static inline void JoltCircleStep(JoltCircleState *w) {
+    if(w->sleeping)return;
+    const double dt=JOLT_CIRCLE_DT,decay=exp(-w->damping*dt);
+    bool quiet=true;
+    for(int i=0;i<w->count;i++){
+        JoltCircle *b=&w->bodies[i];b->supported=false;b->ax=w->gx;b->ay=w->gy;
+        if(b->held)quiet=false;
+        if(JoltCircleKinematic(b)){b->vx=(b->tx-b->x)/dt;b->vy=(b->ty-b->y)/dt;quiet=false;}
+        else {
+            double damping=0;
+            if((b->held&&b->drag.enabled)||b->attachment.enabled||b->snap.active){
+                double x,y,length,stiffness;
+                if(b->held&&b->drag.enabled){
+                    x=b->tx;y=b->ty;length=b->drag.length;stiffness=b->drag.stiffness;damping=b->drag.damping;
+                }else if(b->snap.active){
+                    x=JoltCircleSnapX(w,b,b->snap.index);y=JoltCircleSnapY(w,b,b->snap.index);
+                    length=0;stiffness=b->snap.stiffness;damping=b->snap.damping;
+                    // A selected snap is a positional controller; gravity must not offset its dock.
+                    b->ax=b->ay=0;
+                }else {
+                    x=b->attachment.u*w->width;y=b->attachment.v*w->height;
+                    length=b->attachment.length;stiffness=b->attachment.stiffness;damping=b->attachment.damping;
+                }
+                double dx=b->x-x,dy=b->y-y,d=hypot(dx,dy);
+                double nx=d>1e-9?dx/d:0,ny=d>1e-9?dy/d:1;
+                double force=stiffness*(d-length)/b->m;
+                b->ax-=force*nx;b->ay-=force*ny;
+            }
+            // Implicit viscous damping remains bounded for the supported mass/damping range.
+            double divisor=1+damping*dt/b->m;
+            b->vx=(b->vx+b->ax*dt)/divisor*decay;
+            b->vy=(b->vy+b->ay*dt)/divisor*decay;
+        }
+        JoltCircleLimitVelocity(b);b->x+=b->vx*dt;b->y+=b->vy*dt;
+    }
+    JoltCircleContacts(w,true,8);
+    for(int i=0;i<w->count;i++){
+        JoltCircle *b=&w->bodies[i];JoltCircleLimitVelocity(b);
+        double speed=hypot(b->vx,b->vy),force=hypot(b->ax,b->ay);
+        bool equilibrium=force<=1e-9;
+        if(b->snap.active){
+            double x=JoltCircleSnapX(w,b,b->snap.index),y=JoltCircleSnapY(w,b,b->snap.index);
+            equilibrium=hypot(b->x-x,b->y-y)<=.25;
+            if(equilibrium&&speed<=4&&JoltCircleTargetClear(w,i,x,y)){b->x=x;b->y=y;b->vx=b->vy=0;}
+        }else if(b->attachment.enabled){
+            double dx=b->x-b->attachment.u*w->width,dy=b->y-b->attachment.v*w->height;
+            double gravity=hypot(w->gx,w->gy);
+            // Residual force alone hides tangential drift in a stretched spring.
+            if(gravity>1e-9){
+                double length=b->attachment.length+b->m*gravity/b->attachment.stiffness;
+                equilibrium=hypot(dx-length*w->gx/gravity,dy-length*w->gy/gravity)<=.25;
+            }else equilibrium=fabs(hypot(dx,dy)-b->attachment.length)<=.25;
+        }
+        if(speed>4||(!b->supported&&!equilibrium))quiet=false;
+    }
+    w->steps++;w->quiet=quiet?w->quiet+dt:0;
+    if(w->quiet>=.35){w->sleeping=true;for(int i=0;i<w->count;i++)w->bodies[i].vx=w->bodies[i].vy=0;}
+}
+static inline void JoltCircleDrag(JoltCircleState *w,int index,double x,double y) {
+    JoltCircle *b=&w->bodies[index];
+    if(!b->held){b->snap.previousActive=b->snap.active;b->snap.previousIndex=b->snap.index;b->snap.active=false;}
+    b->held=true;double inset=b->drag.enabled?0:b->r;
+    b->tx=JoltCircleClamp(x,inset,w->width-inset);b->ty=JoltCircleClamp(y,inset,w->height-inset);JoltCircleWake(w);
+}
+static inline void JoltCircleRelease(JoltCircleState *w,int index,double vx,double vy) {
+    JoltCircle *b=&w->bodies[index];
+    // A spring-held body releases its integrated momentum, never the pointer velocity.
+    if(!b->held||!b->drag.enabled){b->vx=vx;b->vy=vy;}
+    b->held=false;JoltCircleLimitVelocity(b);
+    b->released=true;b->releaseX=b->x;b->releaseY=b->y;b->releaseVX=b->vx;b->releaseVY=b->vy;
+    if(b->snap.count){
+        double x=b->x+b->vx*b->snap.projection,y=b->y+b->vy*b->snap.projection,best=INFINITY;
+        for(int i=0;i<b->snap.count;i++){
+            double distance=hypot(x-JoltCircleSnapX(w,b,i),y-JoltCircleSnapY(w,b,i));
+            // Strict comparison makes equal-distance ties choose the first configured point.
+            if(distance<best){best=distance;b->snap.index=i;}
+        }
+        b->snap.active=true;
+    }
+    JoltCircleWake(w);
+}
+static inline void JoltCircleResize(JoltCircleState *w,double width,double height) {
+    for(int i=0;i<w->count;i++){
+        JoltCircleCancel(w,i);JoltCircle *b=&w->bodies[i];b->x*=width/w->width;b->y*=height/w->height;b->vx=b->vy=0;
+    }
+    w->width=width;w->height=height;JoltCircleContacts(w,false,64);JoltCircleWake(w);
+}
+#endif

package/platforms/ios/src/JoltCircleWorld.h

@@ -0,0 +1,18 @@
+#import <UIKit/UIKit.h>
+NS_ASSUME_NONNULL_BEGIN
+@interface JoltCircleWorld : NSObject
++ (instancetype)create:(UIView *)container options:(NSString *)options;
+- (void)connect:(UIView *)view index:(NSInteger)index;
+- (void)setEnabled:(BOOL)enabled;
+- (void)resize:(double)width height:(double)height;
+- (void)impulse:(NSInteger)index x:(double)x y:(double)y;
+- (void)attach:(NSInteger)index options:(NSString *)options;
+- (void)snapTo:(NSInteger)index target:(NSInteger)target;
+- (void)reset;
+- (BOOL)supportsPointerSpring;
+- (NSString *)snapshot;
+- (void)dispose;
++ (NSUInteger)worldCount;
++ (NSUInteger)activeCount;
+@end
+NS_ASSUME_NONNULL_END