react-native-magnetkit 0.0.0-stage → 0.1.0

package/android/src/main/java/dev/libraries/magnetkit/Vec3.kt

@@ -0,0 +1,30 @@
+package dev.libraries.magnetkit
+
+import kotlin.math.sqrt
+
+/** A 3-D vector in device axes (x right, y toward the top edge, z out of the screen). */
+data class Vec3(val x: Double, val y: Double, val z: Double) {
+    operator fun plus(o: Vec3) = Vec3(x + o.x, y + o.y, z + o.z)
+    operator fun minus(o: Vec3) = Vec3(x - o.x, y - o.y, z - o.z)
+    operator fun times(k: Double) = Vec3(x * k, y * k, z * k)
+    operator fun div(k: Double) = Vec3(x / k, y / k, z / k)
+    operator fun unaryMinus() = Vec3(-x, -y, -z)
+    fun dot(o: Vec3) = x * o.x + y * o.y + z * o.z
+    val length: Double get() = sqrt(x * x + y * y + z * z)
+
+    companion object {
+        val ZERO = Vec3(0.0, 0.0, 0.0)
+    }
+}
+
+/** A point or vector on the screen, dp (x right, y down). */
+data class Pt(val x: Double, val y: Double) {
+    operator fun plus(o: Pt) = Pt(x + o.x, y + o.y)
+    operator fun minus(o: Pt) = Pt(x - o.x, y - o.y)
+    operator fun times(k: Double) = Pt(x * k, y * k)
+    val length: Double get() = sqrt(x * x + y * y)
+
+    companion object {
+        val ZERO = Pt(0.0, 0.0)
+    }
+}

package/android/src/main/java/dev/libraries/magnetkit/rn/MagnetKitModule.kt

@@ -0,0 +1,172 @@
+package dev.libraries.magnetkit.rn
+
+import android.content.Context
+import android.os.Build
+import android.util.DisplayMetrics
+import android.view.Choreographer
+import android.view.WindowManager
+import dev.libraries.magnetkit.MagnetGesture
+import dev.libraries.magnetkit.MagnetModel
+import dev.libraries.magnetkit.MagnetSource
+import dev.libraries.magnetkit.Pt
+import expo.modules.kotlin.functions.Queues
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+
+/**
+ * MagnetKit for React Native: runs `MagnetSource` (the magnet model) every
+ * display frame while JavaScript listens, and sends each reading and each
+ * gesture as an event. Positions are dp from the window's top left, as React
+ * Native lays out (edge to edge). The model (Magnet.mfxl) comes from the
+ * app's assets.
+ */
+class MagnetKitModule : Module() {
+  private var source: MagnetSource? = null
+  private var gestureId = 0
+  private var running = false
+  private var screen = Pt(0.0, 0.0)
+
+  private val context: Context get() = requireNotNull(appContext.reactContext) { "React context is gone" }
+  private val prefs get() = context.getSharedPreferences("magnetkit-rn", Context.MODE_PRIVATE)
+
+  private val frame = object : Choreographer.FrameCallback {
+    override fun doFrame(frameTimeNanos: Long) {
+      if (!running) return
+      tick(frameTimeNanos / 1e9)
+      Choreographer.getInstance().postFrameCallback(this)
+    }
+  }
+
+  override fun definition() = ModuleDefinition {
+    Name("MagnetKit")
+
+    Events("onFrame", "onGesture")
+
+    Function("isAvailable") { MagnetSource.get(context).isSensorAvailable }
+
+    Function("hasModel") { MagnetModel.bundled(context) != null }
+
+    AsyncFunction("start") { start() }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("stop") { stop() }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("zero") { source?.calibrate() }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("setMagnet") { face: Int, strength: Double, x: Double, y: Double ->
+      prefs.edit()
+        .putInt("face", if (face < 0) -1 else 1)
+        .putFloat("strength", strength.toFloat())
+        .putFloat("sensorX", x.toFloat())
+        .putFloat("sensorY", y.toFloat())
+        .apply()
+      applyMagnet()
+    }.runOnQueue(Queues.MAIN)
+
+    AsyncFunction("clearMagnet") {
+      prefs.edit().clear().apply()
+      applyMagnet()
+    }.runOnQueue(Queues.MAIN)
+
+    Function("getMagnet") {
+      val p = prefs
+      if (!p.contains("face")) return@Function null
+      mapOf(
+        "face" to p.getInt("face", 1),
+        "strength" to p.getFloat("strength", 0f).toDouble(),
+        "sensor" to mapOf("x" to p.getFloat("sensorX", 0f).toDouble(), "y" to p.getFloat("sensorY", 0f).toDouble()),
+      )
+    }
+
+    Function("screen") {
+      val s = screenDp()
+      mapOf("width" to s.x, "height" to s.y, "pointsPerCm" to MagnetSource.get(context).config.pointsPerCm)
+    }
+
+    OnDestroy {
+      android.os.Handler(android.os.Looper.getMainLooper()).post { stop() }
+    }
+  }
+
+  /** The calibrated magnet, or a guess (sensor near the top centre, face and
+   *  strength unknown) so the locator still answers before a calibration. */
+  private fun applyMagnet() {
+    val s = source ?: MagnetSource.get(context)
+    val cfg = s.config
+    screen = screenDp()
+    cfg.screenSize = screen
+    val p = prefs
+    if (p.contains("face")) {
+      cfg.magnetFace = p.getInt("face", 1)
+      cfg.magnetStrength = p.getFloat("strength", 5000f).toDouble()
+      cfg.sensorPosition = Pt(p.getFloat("sensorX", 0f).toDouble(), p.getFloat("sensorY", 0f).toDouble())
+    } else {
+      cfg.magnetFace = null
+      cfg.magnetStrength = null
+      cfg.sensorPosition = Pt(screen.x / 2, 1.1 * cfg.pointsPerCm)
+    }
+    cfg.locatorEnabled = true
+  }
+
+  private fun start() {
+    if (running) return
+    val s = MagnetSource.get(context)
+    source = s
+    applyMagnet()
+    s.attach()
+    gestureId = s.addGestureListener { g -> sendEvent("onGesture", gesture(g)) }
+    running = true
+    Choreographer.getInstance().postFrameCallback(frame)
+  }
+
+  private fun stop() {
+    if (!running) return
+    running = false
+    Choreographer.getInstance().removeFrameCallback(frame)
+    source?.let { it.removeGestureListener(gestureId); it.detach() }
+  }
+
+  private fun tick(now: Double) {
+    val r = (source ?: return).reading(now)
+    sendEvent(
+      "onFrame",
+      mapOf(
+        "t" to now * 1000,
+        "pos" to r.screenPosition?.let { mapOf("x" to it.x, "y" to it.y) },
+        "spread" to r.screenSpread,
+        "height" to r.height,
+        "presence" to r.presence,
+        "pull" to r.pull,
+        "strength" to r.strength,
+        "delta" to listOf(r.delta.x, r.delta.y, r.delta.z),
+        "toward" to mapOf("x" to r.toward.x, "y" to r.toward.y),
+        "polarity" to r.polarity,
+        "distance" to r.distance.takeIf { it.isFinite() },
+        "approachSpeed" to r.approachSpeed,
+        "tooClose" to r.tooClose,
+        "calibrating" to r.calibrating,
+        "zeroed" to r.calibrated,
+      ),
+    )
+  }
+
+  private fun gesture(g: MagnetGesture): Map<String, Any?> = when (g) {
+    is MagnetGesture.Tap -> mapOf("g" to "tap", "at" to g.at?.let { mapOf("x" to it.x, "y" to it.y) })
+    is MagnetGesture.Push -> mapOf("g" to "push", "speed" to g.speed)
+    is MagnetGesture.PullAway -> mapOf("g" to "pullAway", "speed" to g.speed)
+    is MagnetGesture.Swipe -> mapOf("g" to "swipe", "dir" to mapOf("x" to g.direction.x, "y" to g.direction.y), "speed" to g.speed)
+  }
+
+  /** The window's size, dp. */
+  private fun screenDp(): Pt {
+    val ctx = context
+    val d = ctx.resources.displayMetrics.density.toDouble()
+    return if (Build.VERSION.SDK_INT >= 30) {
+      val b = ctx.getSystemService(WindowManager::class.java).maximumWindowMetrics.bounds
+      Pt(b.width() / d, b.height() / d)
+    } else {
+      @Suppress("DEPRECATION")
+      val m = DisplayMetrics().also { ctx.getSystemService(WindowManager::class.java).defaultDisplay.getRealMetrics(it) }
+      Pt(m.widthPixels / d, m.heightPixels / d)
+    }
+  }
+}

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require("./plugin/withMagnetKit");

package/build/MagnetCalibration.d.ts

@@ -0,0 +1,13 @@
+import { type CalibrationOptions } from "./core/calibration-core";
+/** Runs a calibration; resolves with the fit (already kept by the phone), or null. */
+export declare function calibrate(opts?: CalibrationOptions): {
+    promise: Promise<import(".").CalibrationFit | null>;
+    cancel: () => void;
+};
+export type MagnetCalibrationProps = {
+    visible: boolean;
+    /** true when a calibration was kept. */
+    onClose?: (ok: boolean) => void;
+};
+/** A ready-made calibration screen: five rings, full screen, cancel button. */
+export declare function MagnetCalibration({ visible, onClose }: MagnetCalibrationProps): import("react").JSX.Element;

package/build/MagnetCalibration.js

@@ -0,0 +1,58 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* Calibration: the magnet held still over five rings, fitted to its face,
+   strength and where the sensor sits, kept on the phone across launches.
+   `calibrate()` runs it headless; <MagnetCalibration> is a ready-made
+   full-screen version. */
+import { useEffect, useRef, useState } from "react";
+import { Dimensions, Modal, Pressable, StyleSheet, Text, View } from "react-native";
+import { runCalibration } from "./core/calibration-core";
+import { Magnet } from "./magnet";
+/** Runs a calibration; resolves with the fit (already kept by the phone), or null. */
+export function calibrate(opts = {}) {
+    const screen = Magnet.screen();
+    return runCalibration({
+        zero: () => { Magnet.zero(); },
+        addFrameListener: (l) => Magnet.addFrameListener(l),
+        setMagnet: (fit) => { Magnet.setMagnet(fit); },
+        viewport: () => {
+            const w = Dimensions.get("window");
+            return { x: w.width, y: w.height };
+        },
+        // The window is the screen (edge to edge), as the readings measure it.
+        toScreen: (p) => p,
+        screenSize: () => ({ x: screen.width, y: screen.height }),
+        pointsPerCm: screen.pointsPerCm,
+    }, opts);
+}
+/** A ready-made calibration screen: five rings, full screen, cancel button. */
+export function MagnetCalibration({ visible, onClose }) {
+    const [s, setS] = useState(null);
+    const closeRef = useRef(onClose);
+    closeRef.current = onClose;
+    const cancelRef = useRef(() => { });
+    useEffect(() => {
+        if (!visible)
+            return;
+        const run = calibrate({ onUpdate: setS });
+        cancelRef.current = run.cancel;
+        run.promise.then((fit) => closeRef.current?.(!!fit));
+        return () => run.cancel();
+    }, [visible]);
+    const open = visible && !!s && s.phase !== "done" && s.phase !== "cancelled";
+    const spot = s?.spot ?? null;
+    const win = Dimensions.get("window");
+    const msg = !s ? "" : s.phase === "zeroing" ? "Keep the magnet away for a moment…"
+        : s.phase === "failed" ? "That didn't fit. Try again, holding the magnet still over each ring."
+            : `Ring ${s.index + 1} of ${s.total}: hold the magnet 1–2 cm above it and keep it still.`;
+    const diag = !s ? "" : s.field == null ? "No readings yet." : `${s.field.toFixed(0)} µT${s.zeroing ? " · zeroing" : ""}`;
+    return (_jsx(Modal, { visible: open, transparent: true, animationType: "fade", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: () => cancelRef.current(), children: _jsxs(View, { style: styles.root, children: [spot && (_jsx(View, { style: [styles.ring, { left: spot.x - 36, top: spot.y - 36 }], children: _jsx(View, { style: [styles.fill, { transform: [{ scale: s?.progress ?? 0 }] }] }) })), _jsx(Text, { style: [styles.msg, { top: spot ? (spot.y < win.height / 2 ? spot.y + 64 : spot.y - 120) : win.height * 0.4 }], children: msg }), _jsx(Text, { style: styles.diag, children: diag }), _jsx(Pressable, { onPress: () => cancelRef.current(), style: styles.cancel, accessibilityRole: "button", children: _jsx(Text, { style: styles.cancelText, children: "Cancel" }) })] }) }));
+}
+const styles = StyleSheet.create({
+    root: { flex: 1, backgroundColor: "rgba(0,0,0,0.94)" },
+    ring: { position: "absolute", width: 72, height: 72, borderRadius: 36, borderWidth: 3, borderColor: "#fff" },
+    fill: { position: "absolute", left: 7, top: 7, right: 7, bottom: 7, borderRadius: 30, backgroundColor: "#4f9cff" },
+    msg: { position: "absolute", left: 16, right: 16, color: "#fff", fontSize: 16, lineHeight: 24, fontWeight: "500", textAlign: "center" },
+    diag: { position: "absolute", left: 16, right: 16, bottom: 88, color: "#9a9a9a", fontSize: 13, lineHeight: 18, textAlign: "center" },
+    cancel: { position: "absolute", alignSelf: "center", bottom: 32, height: 40, paddingHorizontal: 18, borderRadius: 999, backgroundColor: "#2a2a2a", justifyContent: "center" },
+    cancelText: { color: "#fff", fontSize: 14, fontWeight: "500" },
+});

package/build/MagnetKitModule.d.ts

@@ -0,0 +1,52 @@
+import { NativeModule } from "expo";
+import type { MagnetFrame, Pt } from "./core/types";
+/** A reading as the native side sends it: the web kit's frame and a little more. */
+export type NativeMagnetFrame = MagnetFrame & {
+    /** Unit vector, screen axes, toward the magnet (the bearing without the locator). */
+    toward: Pt;
+    /** +1 attracts, −1 repels. */
+    polarity: number;
+    /** Rough distance to the magnet, cm; null when none is near. */
+    distance: number | null;
+    /** How fast the magnet comes toward the phone, cm/s (negative: away). */
+    approachSpeed: number;
+    /** The phone has a zero to measure from. */
+    zeroed: boolean;
+};
+export type NativeMagnetGesture = {
+    g: "tap";
+    at: Pt | null;
+} | {
+    g: "push" | "pullAway";
+    speed: number;
+} | {
+    g: "swipe";
+    dir: Pt;
+    speed: number;
+};
+export type StoredMagnet = {
+    face: 1 | -1;
+    strength: number;
+    sensor: Pt;
+};
+type Events = {
+    onFrame(f: NativeMagnetFrame): void;
+    onGesture(g: NativeMagnetGesture): void;
+};
+declare class MagnetKitNative extends NativeModule<Events> {
+    isAvailable(): boolean;
+    hasModel(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    zero(): Promise<void>;
+    setMagnet(face: number, strength: number, x: number, y: number): Promise<void>;
+    clearMagnet(): Promise<void>;
+    getMagnet(): StoredMagnet | null;
+    screen(): {
+        width: number;
+        height: number;
+        pointsPerCm: number;
+    };
+}
+declare const _default: MagnetKitNative;
+export default _default;

package/build/MagnetKitModule.js

@@ -0,0 +1,2 @@
+import { requireNativeModule } from "expo";
+export default requireNativeModule("MagnetKit");

package/build/MagneticView.d.ts

@@ -0,0 +1,15 @@
+import { type ComponentRef, type ForwardRefExoticComponent, type ReactNode, type RefAttributes } from "react";
+import { View, type ViewProps } from "react-native";
+import { MagneticField } from "./core/field";
+export type ViewRef = ComponentRef<typeof View>;
+/** The shared field, to tune (stiffness, damping, force, reach, screenCorner…). */
+export declare function getMagneticField(): MagneticField;
+export type MagneticViewProps = ViewProps & {
+    /** Corner radius used for collisions; defaults to the style's borderRadius. */
+    corner?: number;
+    /** Off: the view stays put. */
+    enabled?: boolean;
+    children?: ReactNode;
+};
+/** A View the magnet pulls. Put several on screen; they collide with each other. */
+export declare const MagneticView: ForwardRefExoticComponent<MagneticViewProps & RefAttributes<ViewRef>>;

package/build/MagneticView.js

@@ -0,0 +1,129 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/* The Magnetic UI pull for React Native: every <MagneticView> is a small
+   rigid body on a stiff damped string to its place, pulled toward a magnet
+   held beside the phone; bodies collide, rest against the screen's rounded
+   edge, and come back when it leaves. One field for the app, run on the JS
+   thread; transforms are set through Animated values, without re-renders. */
+import { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { AccessibilityInfo, Animated, Dimensions, StyleSheet } from "react-native";
+import { MagneticField } from "./core/field";
+import { Magnet } from "./magnet";
+const bodies = new Map();
+let field = null;
+let raf = 0;
+let offFrames = null;
+let reduceMotion = false;
+let lastMeasure = 0;
+let face = 1;
+let faceAt = -1;
+let nextId = 0;
+AccessibilityInfo.isReduceMotionEnabled?.().then((v) => (reduceMotion = v)).catch(() => { });
+AccessibilityInfo.addEventListener?.("reduceMotionChanged", (v) => (reduceMotion = v));
+/** The shared field, to tune (stiffness, damping, force, reach, screenCorner…). */
+export function getMagneticField() {
+    if (!field) {
+        field = new MagneticField();
+        field.screenCorner = 44;
+    }
+    return field;
+}
+function measure(id) {
+    const b = bodies.get(id);
+    const p = field?.parts.get(id);
+    // Measure only at rest: the transform would move the box.
+    if (!b?.view.current || (p && !p.resting))
+        return;
+    b.view.current.measureInWindow((x, y, w, h) => {
+        if (w > 0 && h > 0)
+            b.box = { left: x, top: y, right: x + w, bottom: y + h };
+    });
+}
+function tick() {
+    raf = requestAnimationFrame(tick);
+    const f = getMagneticField();
+    const now = performance.now() / 1000;
+    // Layout moves without telling us (scrolling, keyboard): measure resting bodies now and then.
+    if (now - lastMeasure > 0.5 && !f.active) {
+        lastMeasure = now;
+        bodies.forEach((_, id) => measure(id));
+    }
+    if (now - faceAt > 1) {
+        faceAt = now;
+        face = Magnet.getMagnet()?.face ?? 1;
+    }
+    for (const [id, b] of bodies)
+        if (b.box)
+            f.setHome(id, b.box, b.corner);
+    const frame = Magnet.frame;
+    const win = Dimensions.get("window");
+    const screenBox = { left: 0, top: 0, right: win.width, bottom: win.height };
+    if (frame && !reduceMotion && performance.now() - Magnet.frameAt < 500)
+        f.step(frame, now, screenBox, face);
+    else
+        f.relax(now);
+    for (const [id, b] of bodies) {
+        const p = f.parts.get(id);
+        if (!p)
+            continue;
+        if (p.resting) {
+            b.x.setValue(0);
+            b.y.setValue(0);
+            b.r.setValue(0);
+        }
+        else {
+            b.x.setValue(p.ox);
+            b.y.setValue(p.oy);
+            b.r.setValue(p.angle);
+        }
+    }
+}
+function register(b) {
+    const id = String(nextId++);
+    bodies.set(id, b);
+    if (bodies.size === 1) {
+        offFrames = Magnet.addFrameListener(() => { });
+        raf = requestAnimationFrame(tick);
+    }
+    return {
+        id,
+        remove() {
+            bodies.delete(id);
+            field?.parts.delete(id);
+            if (bodies.size === 0) {
+                cancelAnimationFrame(raf);
+                offFrames?.();
+                offFrames = null;
+            }
+        },
+    };
+}
+/** A View the magnet pulls. Put several on screen; they collide with each other. */
+export const MagneticView = forwardRef(function MagneticView({ corner, enabled = true, style, onLayout, children, ...rest }, forwarded) {
+    const view = useRef(null);
+    useImperativeHandle(forwarded, () => view.current);
+    const anim = useRef({ x: new Animated.Value(0), y: new Animated.Value(0), r: new Animated.Value(0) }).current;
+    const flat = StyleSheet.flatten(style) ?? {};
+    const radius = corner ?? (typeof flat.borderRadius === "number" ? flat.borderRadius : 8);
+    const reg = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const r = register({ view, x: anim.x, y: anim.y, r: anim.r, corner: radius, box: null });
+        reg.current = r;
+        measure(r.id);
+        return () => {
+            r.remove();
+            reg.current = null;
+            anim.x.setValue(0);
+            anim.y.setValue(0);
+            anim.r.setValue(0);
+        };
+    }, [enabled, radius, anim]);
+    const rotate = anim.r.interpolate({ inputRange: [-1, 1], outputRange: ["-1rad", "1rad"] });
+    const own = Array.isArray(flat.transform) ? flat.transform : [];
+    return (_jsx(Animated.View, { ref: view, ...rest, style: [style, { transform: [{ translateX: anim.x }, { translateY: anim.y }, { rotate }, ...own] }], onLayout: (e) => {
+            if (reg.current)
+                measure(reg.current.id);
+            onLayout?.(e);
+        }, children: children }));
+});

package/build/core/calibration-core.d.ts

@@ -0,0 +1,43 @@
+import { type CalibrationFit } from "./fit";
+import type { MagnetFrame, Pt } from "./types";
+export type CalibrationState = {
+    phase: "zeroing" | "spot" | "done" | "failed" | "cancelled";
+    /** Which spot (0-based) and how many. */
+    index: number;
+    total: number;
+    /** Where to draw the ring, in the app's own coordinates (client px, or RN points). */
+    spot: Pt | null;
+    /** 0…1, how long the magnet has been held still over this spot. */
+    progress: number;
+    /** The field reported right now, µT; null while no readings arrive. */
+    field: number | null;
+    /** True while the phone is taking its zero. */
+    zeroing: boolean;
+    fit: CalibrationFit | null;
+};
+export type CalibrationOptions = {
+    /** Spots as fractions of the viewport. Five by default: middle, top, bottom, left, right. */
+    spots?: Array<[number, number]>;
+    onUpdate?: (s: CalibrationState) => void;
+};
+/** What a calibration needs from where the readings come from. */
+export type CalibrationIO = {
+    /** Take a new zero (keep magnets away). */
+    zero(): void;
+    addFrameListener(l: (f: MagnetFrame) => void): () => void;
+    /** Hand the fit to the phone. */
+    setMagnet(fit: CalibrationFit): void;
+    /** The area the rings are drawn in, in the app's own coordinates. */
+    viewport(): Pt;
+    /** The app's coordinates onto the screen's, as the readings use. */
+    toScreen(p: Pt): Pt;
+    /** The screen's size and density, as the readings use. */
+    screenSize(): Pt;
+    pointsPerCm: number;
+};
+export declare const DEFAULT_SPOTS: Array<[number, number]>;
+/** Runs a calibration; resolves with the fit (already handed to the phone), or null. */
+export declare function runCalibration(io: CalibrationIO, opts?: CalibrationOptions): {
+    promise: Promise<CalibrationFit | null>;
+    cancel: () => void;
+};

package/build/core/calibration-core.js

@@ -0,0 +1,84 @@
+/* Calibration without UI or transport: the magnet held still over a few
+   spots on the screen, fitted to the magnet's face, strength and the
+   sensor's spot. Shared by the web bridge and React Native, which each
+   hand it a `CalibrationIO`. */
+import { fitCalibration } from "./fit";
+export const DEFAULT_SPOTS = [[0.5, 0.45], [0.5, 0.12], [0.5, 0.88], [0.15, 0.5], [0.85, 0.5]];
+/** Runs a calibration; resolves with the fit (already handed to the phone), or null. */
+export function runCalibration(io, opts = {}) {
+    const SPOTS = opts.spots ?? DEFAULT_SPOTS;
+    const spots = [];
+    let i = 0;
+    let hold = [];
+    let lastFrame = null;
+    let lastFrameAt = 0;
+    const zeroUntil = performance.now() + 1500;
+    let done = false;
+    let resolve;
+    const promise = new Promise((r) => (resolve = r));
+    const spotAt = (k) => {
+        const v = io.viewport();
+        return { x: SPOTS[k][0] * v.x, y: SPOTS[k][1] * v.y };
+    };
+    const state = (phase, progress = 0, fit = null) => ({
+        phase, index: i, total: SPOTS.length, spot: phase === "spot" ? spotAt(i) : null, progress,
+        field: lastFrame && performance.now() - lastFrameAt < 2000 ? lastFrame.strength : null,
+        zeroing: !!lastFrame?.calibrating, fit,
+    });
+    const emit = (s) => opts.onUpdate?.(s);
+    const finish = (phase, fit) => {
+        if (done)
+            return;
+        done = true;
+        off();
+        clearInterval(tick);
+        emit(state(phase, 1, fit));
+        resolve(fit);
+    };
+    io.zero();
+    emit(state("zeroing"));
+    const tick = setInterval(() => {
+        if (!done && performance.now() < zeroUntil)
+            emit(state("zeroing"));
+    }, 300);
+    const off = io.addFrameListener((f) => {
+        lastFrame = f;
+        lastFrameAt = performance.now();
+        if (performance.now() < zeroUntil || f.calibrating) {
+            emit(state("zeroing"));
+            return;
+        }
+        if (f.strength < 15) {
+            hold = [];
+            emit(state("spot", 0));
+            return;
+        }
+        hold.push(f);
+        hold = hold.filter((h) => h.t > f.t - 1200);
+        const med = (j) => { const v = hold.map((h) => h.delta[j]).sort((a, b) => a - b); return v[v.length >> 1]; };
+        const m = [med(0), med(1), med(2)];
+        const spread = Math.max(...hold.map((h) => Math.hypot(h.delta[0] - m[0], h.delta[1] - m[1], h.delta[2] - m[2])));
+        if (spread > Math.max(4, 0.12 * f.strength)) {
+            hold = [f];
+            emit(state("spot", 0));
+            return;
+        }
+        const progress = Math.min(1, (f.t - hold[0].t) / 1000);
+        emit(state("spot", progress));
+        if (progress < 1)
+            return;
+        spots.push({ screen: io.toScreen(spotAt(i)), delta: m });
+        i++;
+        hold = [];
+        if (i < SPOTS.length) {
+            emit(state("spot", 0));
+            return;
+        }
+        const fit = fitCalibration(spots, io.screenSize(), io.pointsPerCm);
+        if (!fit)
+            return finish("failed", null);
+        io.setMagnet(fit);
+        finish("done", fit);
+    });
+    return { promise, cancel: () => finish("cancelled", null) };
+}

package/build/core/field.d.ts

@@ -0,0 +1,64 @@
+import type { MagnetFrame, Pt } from "./types";
+export type Box = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+export declare class Particle {
+    home: Box;
+    corner: number;
+    ox: number;
+    oy: number;
+    vx: number;
+    vy: number;
+    angle: number;
+    spin: number;
+    atEdge: boolean;
+    get mass(): number;
+    get inertia(): number;
+    get center(): Pt;
+    get resting(): boolean;
+}
+export declare class MagneticField {
+    parts: Map<string, Particle>;
+    magnet: Pt | null;
+    overGlass: boolean;
+    private lastT;
+    private gate;
+    private lostAt;
+    private strengths;
+    screenCorner: number;
+    stiffness: number;
+    damping: number;
+    force: number;
+    reach: number;
+    maxForce: number;
+    standoff: number;
+    softening: number;
+    nearBand: number;
+    farBand: number;
+    tiltGain: number;
+    maxTilt: number;
+    spinStiffness: number;
+    spinDamping: number;
+    restitution: number;
+    wallRestitution: number;
+    restingSpeed: number;
+    wallFriction: number;
+    setHome(id: string, b: Box, corner: number): void;
+    get active(): boolean;
+    relax(now: number): void;
+    step(r: MagnetFrame, now: number, screenBox: Box, face: number): void;
+    private outside;
+    private nearestEdge;
+    private pullPoint;
+    private proximity;
+    private direction;
+    private simulate;
+    /** Two boxes (separating axes): push apart by mass; a real knock bounces and spins them. */
+    private collide;
+    /** Keep a body inside the screen's rounded rectangle. A body whose home is
+     *  already cut by the screen's edge may rest there, but go no further out. */
+    private contain;
+}