react-native-magnetkit 0.0.0-stage → 0.1.0

package/src/core/calibration-core.ts

@@ -0,0 +1,112 @@
+/* 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, type CalibrationFit, type CalibrationSpot } 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 const DEFAULT_SPOTS: Array<[number, number]> = [[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: CalibrationIO, opts: CalibrationOptions = {}) {
+  const SPOTS = opts.spots ?? DEFAULT_SPOTS;
+  const spots: CalibrationSpot[] = [];
+  let i = 0;
+  let hold: MagnetFrame[] = [];
+  let lastFrame: MagnetFrame | null = null;
+  let lastFrameAt = 0;
+  const zeroUntil = performance.now() + 1500;
+  let done = false;
+  let resolve!: (f: CalibrationFit | null) => void;
+  const promise = new Promise<CalibrationFit | null>((r) => (resolve = r));
+
+  const spotAt = (k: number): Pt => {
+    const v = io.viewport();
+    return { x: SPOTS[k][0] * v.x, y: SPOTS[k][1] * v.y };
+  };
+  const state = (phase: CalibrationState["phase"], progress = 0, fit: CalibrationFit | null = null): CalibrationState => ({
+    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: CalibrationState) => opts.onUpdate?.(s);
+
+  const finish = (phase: "done" | "failed" | "cancelled", fit: CalibrationFit | null) => {
+    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: number) => { const v = hold.map((h) => h.delta[j]).sort((a, b) => a - b); return v[v.length >> 1]; };
+    const m: [number, number, number] = [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/src/core/field.ts

@@ -0,0 +1,295 @@
+/* The Magnetic UI physics, ported from Magnetic Home (Android) / the iOS
+   wallet demo: every element is a small rigid body on a stiff damped string
+   to its place. A magnet beside the phone (not over the glass) pulls each by
+   its nearest point (1/d³, capped), so it also tilts; bodies collide and
+   rest against the screen's rounded edge; the strings bring everything back
+   when it leaves. All lengths in screen dp (= CSS px on Android Chrome). */
+
+import type { MagnetFrame, Pt } from "./types";
+
+export type Box = { left: number; top: number; right: number; bottom: number };
+
+const w = (b: Box) => b.right - b.left;
+const h = (b: Box) => b.bottom - b.top;
+const offsetBox = (b: Box, dx: number, dy: number): Box => ({ left: b.left + dx, top: b.top + dy, right: b.right + dx, bottom: b.bottom + dy });
+const inset = (b: Box, d: number): Box => ({ left: b.left + d, top: b.top + d, right: b.right - d, bottom: b.bottom - d });
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+
+export class Particle {
+  home: Box = { left: 0, top: 0, right: 0, bottom: 0 };
+  corner = 8;
+  ox = 0;
+  oy = 0;
+  vx = 0;
+  vy = 0;
+  angle = 0;
+  spin = 0;
+  atEdge = false;
+  get mass() { return Math.max(1, (w(this.home) * h(this.home)) / 1000); }
+  get inertia() { return (this.mass * (w(this.home) ** 2 + h(this.home) ** 2)) / 12; }
+  get center(): Pt { return { x: (this.home.left + this.home.right) / 2 + this.ox, y: (this.home.top + this.home.bottom) / 2 + this.oy }; }
+  get resting() { return Math.abs(this.ox) < 0.2 && Math.abs(this.oy) < 0.2 && Math.abs(this.vx) < 2 && Math.abs(this.vy) < 2 && Math.abs(this.angle) < 0.001; }
+}
+
+export class MagneticField {
+  parts = new Map<string, Particle>();
+  magnet: Pt | null = null;
+  overGlass = false;
+  private lastT = 0;
+  private gate = 0;
+  private lostAt = 0;
+  private strengths: Array<[number, number]> = [];
+
+  screenCorner = 40;
+  stiffness = 150;
+  damping = 21;
+  force = 30000;
+  reach = 150;
+  maxForce = 26000;
+  standoff = 40;
+  softening = 40;
+  nearBand = 90;
+  farBand = 320;
+  tiltGain = 0.5;
+  maxTilt = 0.1;
+  spinStiffness = 80;
+  spinDamping = 12;
+  restitution = 0.3;
+  wallRestitution = 0.25;
+  restingSpeed = 250;
+  wallFriction = 0.35;
+
+  setHome(id: string, b: Box, corner: number) {
+    let p = this.parts.get(id);
+    if (!p) this.parts.set(id, (p = new Particle()));
+    p.home = b;
+    p.corner = corner;
+  }
+
+  get active() { return this.gate > 0.01 || [...this.parts.values()].some((p) => !p.resting); }
+
+  relax(now: number) { this.simulate(now, null); }
+
+  step(r: MagnetFrame, now: number, screenBox: Box, face: number) {
+    const dt = this.lastT > 0 ? Math.min(1 / 30, Math.max(1 / 240, now - this.lastT)) : 1 / 60;
+    const p = r.pos;
+    if (r.strength > 4 && p) {
+      const m = this.magnet;
+      if (m) {
+        const jump = Math.hypot(p.x - m.x, p.y - m.y);
+        const k = 1 - Math.exp(-dt / (jump > 200 ? 0.4 : 0.08));
+        this.magnet = { x: m.x + (p.x - m.x) * k, y: m.y + (p.y - m.y) * k };
+      } else this.magnet = p;
+      this.lostAt = now;
+    } else if (now - this.lostAt > 0.15) this.magnet = null;
+    // Leaving: the field falling well below its peak of the last half second.
+    this.strengths.push([now, r.strength]);
+    while (this.strengths.length && now - this.strengths[0][0] > 0.5) this.strengths.shift();
+    const recentMax = Math.max(...this.strengths.map((s) => s[1]));
+    const leaving = recentMax > 25 ? clamp((r.strength / recentMax - 0.15) / 0.3, 0, 1) : 1;
+    // Over the glass: no pull at all (the field along the face, or well inside and above).
+    const along = ((face < 0 ? -1 : 1) * r.delta[2]) / Math.max(1e-6, r.strength);
+    const m = this.magnet;
+    const inside = !!m && this.outside(m, screenBox) < -25 && (r.height ?? 0) > 0.8;
+    if (r.strength > 4) {
+      if (along > 0.2 || inside) this.overGlass = true;
+      else if (along < 0) this.overGlass = false;
+    }
+    let target = 0;
+    if (m && !this.overGlass) {
+      const field = clamp((r.strength - 10) / 25, 0, 1);
+      const real = clamp((r.presence - 0.2) / 0.4, 0, 1);
+      target = field * real * leaving;
+    }
+    this.gate += (target - this.gate) * (1 - Math.exp(-dt / (target > this.gate ? 0.08 : 0.04)));
+    this.simulate(now, screenBox);
+  }
+
+  private outside(p: Pt, s: Box) {
+    const dx = Math.max(s.left - p.x, p.x - s.right), dy = Math.max(s.top - p.y, p.y - s.bottom);
+    if (dx > 0 || dy > 0) return Math.hypot(Math.max(0, dx), Math.max(0, dy));
+    return Math.max(dx, dy);
+  }
+
+  private nearestEdge(m: Pt, s: Box): Pt {
+    const dl = m.x - s.left, dr = s.right - m.x, dt = m.y - s.top, db = s.bottom - m.y;
+    const mn = Math.min(dl, dr, dt, db);
+    return mn === dl ? { x: -1, y: 0 } : mn === dr ? { x: 1, y: 0 } : mn === dt ? { x: 0, y: -1 } : { x: 0, y: 1 };
+  }
+
+  private pullPoint(m: Pt, s: Box): Pt {
+    let qx = clamp(m.x, s.left, s.right), qy = clamp(m.y, s.top, s.bottom);
+    let nx = m.x - qx, ny = m.y - qy;
+    if (Math.hypot(nx, ny) < 1) {
+      const e = this.nearestEdge(m, s);
+      if (e.x) qx = e.x < 0 ? s.left : s.right;
+      else qy = e.y < 0 ? s.top : s.bottom;
+      nx = e.x; ny = e.y;
+    }
+    const l = Math.max(1e-6, Math.hypot(nx, ny));
+    return { x: qx + (nx / l) * this.standoff, y: qy + (ny / l) * this.standoff };
+  }
+
+  private proximity(m: Pt, s: Box) {
+    return clamp(1 - (this.outside(m, s) - this.nearBand) / (this.farBand - this.nearBand), 0, 1);
+  }
+
+  private direction(c: Pt, m: Pt, s: Box): Pt {
+    let rx = m.x - c.x, ry = m.y - c.y;
+    const rl = Math.max(1e-6, Math.hypot(rx, ry));
+    rx /= rl; ry /= rl;
+    let ex = m.x - clamp(m.x, s.left, s.right), ey = m.y - clamp(m.y, s.top, s.bottom);
+    if (Math.hypot(ex, ey) < 1) {
+      const e = this.nearestEdge(m, s);
+      ex = e.x; ey = e.y;
+    }
+    const el = Math.max(1e-6, Math.hypot(ex, ey));
+    ex /= el; ey /= el;
+    const k = 0.65;
+    let dx = ex * k + rx * (1 - k), dy = ey * k + ry * (1 - k);
+    const dl = Math.max(1e-6, Math.hypot(dx, dy));
+    return { x: dx / dl, y: dy / dl };
+  }
+
+  private simulate(now: number, screenBox: Box | null) {
+    const dt = this.lastT > 0 ? Math.min(1 / 30, Math.max(1 / 240, now - this.lastT)) : 1 / 60;
+    this.lastT = now;
+    for (const p of this.parts.values()) {
+      if (w(p.home) <= 0) continue;
+      let ax = -this.stiffness * p.ox - this.damping * p.vx;
+      let ay = -this.stiffness * p.oy - this.damping * p.vy;
+      let torque = 0;
+      const raw = this.magnet;
+      if (raw && screenBox && this.gate > 0.01) {
+        const m = this.pullPoint(raw, screenBox);
+        const c = p.center;
+        const pw = w(p.home), ph = h(p.home);
+        const box = offsetBox(p.home, p.ox, p.oy);
+        const qx = clamp(m.x, box.left, box.right), qy = clamp(m.y, box.top, box.bottom);
+        const dist = Math.hypot(m.x - qx, m.y - qy) + this.softening;
+        const f = Math.min(this.maxForce, this.force * (this.reach / dist) ** 3) * this.gate * this.proximity(raw, screenBox);
+        const u = this.direction(c, m, screenBox);
+        ax += f * u.x;
+        ay += f * u.y;
+        // Gripped by its nearest point: an off-centre pull turns it.
+        const ca = Math.cos(p.angle), sa = Math.sin(p.angle);
+        const lx = (m.x - c.x) * ca + (m.y - c.y) * sa, ly = -(m.x - c.x) * sa + (m.y - c.y) * ca;
+        const nlx = clamp(lx, -pw / 2, pw / 2), nly = clamp(ly, -ph / 2, ph / 2);
+        const nx = nlx * ca - nly * sa, ny = nlx * sa + nly * ca;
+        torque = (this.tiltGain * (nx * f * u.y - ny * f * u.x)) / ((pw * pw + ph * ph) / 12);
+        if (p.atEdge) torque *= 0.4;
+      }
+      p.vx += ax * dt; p.vy += ay * dt;
+      const v = Math.hypot(p.vx, p.vy);
+      if (v > 2600) { p.vx = (p.vx / v) * 2600; p.vy = (p.vy / v) * 2600; }
+      p.ox += p.vx * dt; p.oy += p.vy * dt;
+      p.spin += (torque - this.spinStiffness * p.angle - this.spinDamping * p.spin) * dt;
+      p.angle += p.spin * dt;
+      if (Math.abs(p.angle) > this.maxTilt) { p.angle = clamp(p.angle, -this.maxTilt, this.maxTilt); p.spin *= 0.4; }
+    }
+    if (!screenBox) return;
+    const list = [...this.parts.values()].filter((p) => w(p.home) > 0);
+    for (let it = 0; it < 4; it++) {
+      for (let i = 0; i < list.length; i++) for (let j = i + 1; j < list.length; j++) this.collide(list[i], list[j]);
+      for (const p of list) this.contain(p, screenBox);
+    }
+    for (const p of list) p.angle = clamp(p.angle, -this.maxTilt, this.maxTilt);
+  }
+
+  /** Two boxes (separating axes): push apart by mass; a real knock bounces and spins them. */
+  private collide(a: Particle, b: Particle) {
+    const ca = a.center, cb = b.center;
+    const haw = w(a.home) / 2, hah = h(a.home) / 2, hbw = w(b.home) / 2, hbh = h(b.home) / 2;
+    if (Math.abs(cb.x - ca.x) > haw + hbw + 20 || Math.abs(cb.y - ca.y) > hah + hbh + 20) return;
+    const axA = [{ x: Math.cos(a.angle), y: Math.sin(a.angle) }, { x: -Math.sin(a.angle), y: Math.cos(a.angle) }];
+    const axB = [{ x: Math.cos(b.angle), y: Math.sin(b.angle) }, { x: -Math.sin(b.angle), y: Math.cos(b.angle) }];
+    const dx = cb.x - ca.x, dy = cb.y - ca.y;
+    let best = Infinity, nX = 0, nY = 0;
+    for (const n of [...axA, ...axB]) {
+      const ra = haw * Math.abs(axA[0].x * n.x + axA[0].y * n.y) + hah * Math.abs(axA[1].x * n.x + axA[1].y * n.y);
+      const rb = hbw * Math.abs(axB[0].x * n.x + axB[0].y * n.y) + hbh * Math.abs(axB[1].x * n.x + axB[1].y * n.y);
+      const dist = dx * n.x + dy * n.y;
+      const overlap = ra + rb - Math.abs(dist);
+      if (overlap <= 0) return;
+      if (overlap < best) { best = overlap; nX = dist < 0 ? -n.x : n.x; nY = dist < 0 ? -n.y : n.y; }
+    }
+    // Page elements can overlap where they live (a title's box over its icon):
+    // those pairs never collide, or they would shove each other forever.
+    const ha = a.home, hb = b.home;
+    if (ha.left < hb.right - 1 && hb.left < ha.right - 1 && ha.top < hb.bottom - 1 && hb.top < ha.bottom - 1) return;
+    const wa = 1 / a.mass, wb = 1 / b.mass;
+    const k = best / (wa + wb);
+    a.ox -= nX * k * wa; a.oy -= nY * k * wa;
+    b.ox += nX * k * wb; b.oy += nY * k * wb;
+    const vn = (b.vx - a.vx) * nX + (b.vy - a.vy) * nY;
+    if (vn < 0) {
+      const knock = -vn > this.restingSpeed;
+      const j = (-(1 + (knock ? this.restitution : 0)) * vn) / (wa + wb);
+      a.vx -= nX * j * wa; a.vy -= nY * j * wa;
+      b.vx += nX * j * wb; b.vy += nY * j * wb;
+      if (!knock) return;
+      const pcx = (ca.x + cb.x) / 2, pcy = (ca.y + cb.y) / 2;
+      a.spin -= (0.5 * ((pcx - ca.x) * nY - (pcy - ca.y) * nX) * j) / a.inertia;
+      b.spin += (0.5 * ((pcx - cb.x) * nY - (pcy - cb.y) * nX) * j) / b.inertia;
+    }
+  }
+
+  /** 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(p: Particle, screenBox: Box) {
+    const s: Box = {
+      left: Math.min(screenBox.left, p.home.left), top: Math.min(screenBox.top, p.home.top),
+      right: Math.max(screenBox.right, p.home.right), bottom: Math.max(screenBox.bottom, p.home.bottom),
+    };
+    const c = p.center;
+    const hw = w(p.home) / 2, hh = h(p.home) / 2;
+    const r = Math.min(p.corner, Math.min(hw, hh));
+    const inner = inset(s, r);
+    const rr = Math.max(0, this.screenCorner - r);
+    const ca = Math.cos(p.angle), sa = Math.sin(p.angle);
+    let wx = 0, wy = 0, worst = 0, wpx = c.x, wpy = c.y;
+    for (const [sx, sy] of [[-1, -1], [1, -1], [1, 1], [-1, 1]]) {
+      const lx = sx * (hw - r), ly = sy * (hh - r);
+      const qx = c.x + lx * ca - ly * sa, qy = c.y + lx * sa + ly * ca;
+      const corr = pushInside(qx, qy, inner, rr);
+      const len = Math.hypot(corr.x, corr.y);
+      if (len > worst) { worst = len; wx = corr.x; wy = corr.y; wpx = qx; wpy = qy; }
+    }
+    if (worst < 0.5) { p.atEdge = false; return; }
+    const wasAtEdge = p.atEdge;
+    p.atEdge = true;
+    p.ox += wx; p.oy += wy;
+    const nx = wx / worst, ny = wy / worst;
+    const vn = p.vx * nx + p.vy * ny;
+    if (vn < 0) {
+      // Held against the edge: it just stops there, friction holds it. A real hit bounces a little.
+      const resting = wasAtEdge && -vn < 900;
+      const hit = resting ? 0 : -vn;
+      const e = resting ? 0 : this.wallRestitution;
+      p.vx -= (1 + e) * vn * nx; p.vy -= (1 + e) * vn * ny;
+      const vn2 = p.vx * nx + p.vy * ny;
+      const tx = p.vx - vn2 * nx, ty = p.vy - vn2 * ny;
+      const tl = Math.hypot(tx, ty);
+      if (tl > 1e-6) {
+        const drop = resting ? Math.min(tl, this.wallFriction * -vn) / tl : 0.15;
+        p.vx -= tx * drop; p.vy -= ty * drop;
+      }
+      if (resting) p.spin *= 0.7;
+      else p.spin += (0.5 * ((wpx - c.x) * ny - (wpy - c.y) * nx) * hit * p.mass) / p.inertia;
+    }
+  }
+}
+
+function pushInside(qx: number, qy: number, rect: Box, radius: number): Pt {
+  const cx = qx < rect.left + radius ? rect.left + radius : qx > rect.right - radius ? rect.right - radius : null;
+  const cy = qy < rect.top + radius ? rect.top + radius : qy > rect.bottom - radius ? rect.bottom - radius : null;
+  if (cx != null && cy != null && radius > 0) {
+    const d = Math.hypot(qx - cx, qy - cy);
+    if (d <= radius) return { x: 0, y: 0 };
+    return { x: ((cx - qx) * (d - radius)) / d, y: ((cy - qy) * (d - radius)) / d };
+  }
+  let vx = 0, vy = 0;
+  if (qx < rect.left) vx = rect.left - qx; else if (qx > rect.right) vx = rect.right - qx;
+  if (qy < rect.top) vy = rect.top - qy; else if (qy > rect.bottom) vy = rect.bottom - qy;
+  return { x: vx, y: vy };
+}

package/src/core/fit.ts

@@ -0,0 +1,55 @@
+/* ── Calibration ───────────────────────────────────────────────────────
+   The magnet held still over a few known spots. One magnetometer gives
+   three numbers per spot; a dipole whose axis points at the screen,
+   seen from the sensor, explains them with four unknowns: which face is
+   toward the phone, its strength, where the sensor sits, and how high
+   the magnet was held. A grid over those, the strength solved in closed
+   form, picks the best fit. */
+
+import type { Pt } from "./types";
+
+export type CalibrationSpot = { screen: Pt; delta: [number, number, number] };
+export type CalibrationFit = { face: 1 | -1; strength: number; sensor: Pt; height: number; error: number };
+
+/** Android dp per cm (160 dp per inch); an iPhone is ~60 pt per cm. */
+const DP_PER_CM = 160 / 2.54;
+
+function unitField(offX: number, offY: number, h: number, face: number): [number, number, number] {
+  // Field at the sensor from a unit dipole (moment along ±z) at (offX, offY, h) cm.
+  const r = Math.hypot(offX, offY, h);
+  const rx = -offX / r, ry = -offY / r, rz = -h / r;
+  const mDotR = face * rz;
+  const k = 1 / (r * r * r);
+  return [k * 3 * mDotR * rx, k * 3 * mDotR * ry, k * (3 * mDotR * rz - face)];
+}
+
+export function fitCalibration(spots: CalibrationSpot[], screenDp: Pt, PPCM = DP_PER_CM): CalibrationFit | null {
+  if (spots.length < 3) return null;
+  const norm = spots.reduce((a, s) => a + s.delta[0] ** 2 + s.delta[1] ** 2 + s.delta[2] ** 2, 0);
+  let best: CalibrationFit | null = null;
+  for (const face of [1, -1] as const) {
+    for (let sx = 0; sx <= screenDp.x; sx += 8) {
+      for (let sy = -30; sy <= screenDp.y * 0.5; sy += 8) {
+        for (let h = 0.6; h <= 5.01; h += 0.2) {
+          let bg = 0, gg = 0;
+          const gs = spots.map((s) => {
+            const g = unitField((s.screen.x - sx) / PPCM, -(s.screen.y - sy) / PPCM, h, face);
+            bg += g[0] * s.delta[0] + g[1] * s.delta[1] + g[2] * s.delta[2];
+            gg += g[0] * g[0] + g[1] * g[1] + g[2] * g[2];
+            return g;
+          });
+          const k = bg / gg;
+          if (!(k > 0)) continue;
+          let err = 0;
+          spots.forEach((s, i) => {
+            const g = gs[i];
+            err += (s.delta[0] - k * g[0]) ** 2 + (s.delta[1] - k * g[1]) ** 2 + (s.delta[2] - k * g[2]) ** 2;
+          });
+          err /= norm;
+          if (!best || err < best.error) best = { face, strength: k, sensor: { x: sx, y: sy }, height: h, error: err };
+        }
+      }
+    }
+  }
+  return best;
+}

package/src/core/types.ts

@@ -0,0 +1,32 @@
+/* What the magnet model answers, shared by the web bridge and React Native. */
+
+export type Pt = { x: number; y: number };
+
+export type MagnetFrame = {
+  t: number;
+  /** Where the magnet is, screen dp (null while the locator is unsure). */
+  pos: Pt | null;
+  spread: number;
+  height: number | null;
+  presence: number;
+  pull: number;
+  strength: number;
+  /** Field change from the zero, µT, device axes (x right, y up, z out of the screen). */
+  delta: [number, number, number];
+  tooClose: boolean;
+  calibrating: boolean;
+};
+
+export type MagnetGesture =
+  | { g: "tap"; at: Pt | null }
+  | { g: "push" | "pullAway"; speed: number }
+  | { g: "swipe"; dir: Pt; speed: number };
+
+export type ModelHello = {
+  screenDp: [number, number];
+  grabStage: number;
+  face: number | null;
+  strength: number | null;
+  sensorDp: [number, number];
+  model: boolean;
+};

package/src/hooks.ts

@@ -0,0 +1,32 @@
+import { useEffect, useRef, useState } from "react";
+import { Magnet } from "./magnet";
+import type { NativeMagnetFrame, NativeMagnetGesture } from "./MagnetKitModule";
+
+/** Every reading, without re-rendering (once per display frame). */
+export function useMagnetFrame(cb: (f: NativeMagnetFrame) => void) {
+  const ref = useRef(cb);
+  ref.current = cb;
+  useEffect(() => Magnet.addFrameListener((f) => ref.current(f)), []);
+}
+
+/** The latest reading as state, at most one render per animation frame. */
+export function useMagnet(): NativeMagnetFrame | null {
+  const [frame, setFrame] = useState<NativeMagnetFrame | null>(Magnet.frame);
+  useEffect(() => {
+    let raf = 0;
+    let pending: NativeMagnetFrame | null = null;
+    const off = Magnet.addFrameListener((f) => {
+      pending = f;
+      if (!raf) raf = requestAnimationFrame(() => { raf = 0; setFrame(pending); });
+    });
+    return () => { off(); cancelAnimationFrame(raf); };
+  }, []);
+  return frame;
+}
+
+/** Air taps, pushes, pull-aways and swipes. */
+export function useMagnetGestures(cb: (g: NativeMagnetGesture) => void) {
+  const ref = useRef(cb);
+  ref.current = cb;
+  useEffect(() => Magnet.addGestureListener((g) => ref.current(g)), []);
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export { Magnet } from "./magnet";
+export type { NativeMagnetFrame as MagnetFrame, NativeMagnetGesture as MagnetGesture, StoredMagnet } from "./MagnetKitModule";
+export type { Pt } from "./core/types";
+export { useMagnet, useMagnetFrame, useMagnetGestures } from "./hooks";
+export { MagneticView, getMagneticField, type MagneticViewProps } from "./MagneticView";
+export { MagnetCalibration, calibrate, type MagnetCalibrationProps } from "./MagnetCalibration";
+export { DEFAULT_SPOTS, type CalibrationState, type CalibrationOptions } from "./core/calibration-core";
+export { fitCalibration, type CalibrationFit, type CalibrationSpot } from "./core/fit";
+export { MagneticField, Particle, type Box } from "./core/field";

package/src/magnet.ts

@@ -0,0 +1,77 @@
+/* One magnet session for the app: the native side runs while anything
+   listens and stops when the last listener leaves. */
+
+import Native, { type NativeMagnetFrame, type NativeMagnetGesture, type StoredMagnet } from "./MagnetKitModule";
+import type { CalibrationFit } from "./core/fit";
+
+type Subscription = { remove(): void };
+
+let users = 0;
+let frameSub: Subscription | null = null;
+const frameListeners = new Set<(f: NativeMagnetFrame) => void>();
+const gestureListeners = new Set<(g: NativeMagnetGesture) => void>();
+let gestureSub: Subscription | null = null;
+
+function retain() {
+  if (users++ > 0) return;
+  frameSub = Native.addListener("onFrame", (f) => {
+    Magnet.frame = f;
+    Magnet.frameAt = performance.now();
+    frameListeners.forEach((l) => l(f));
+  });
+  gestureSub = Native.addListener("onGesture", (g) => gestureListeners.forEach((l) => l(g)));
+  Native.start();
+}
+
+function release() {
+  if (--users > 0) return;
+  users = 0;
+  frameSub?.remove();
+  gestureSub?.remove();
+  frameSub = gestureSub = null;
+  Magnet.frame = null;
+  Native.stop();
+}
+
+export const Magnet = {
+  /** The latest reading while anything listens. */
+  frame: null as NativeMagnetFrame | null,
+  /** When it arrived, performance.now() ms (its own `t` is the native clock). */
+  frameAt: 0,
+
+  /** The phone has a magnetometer. */
+  isAvailable: (): boolean => Native.isAvailable(),
+  /** Magnet.mfxl is in the app (see the config plugin). Without it readings
+   *  still come, but nothing is located and there are no air taps. */
+  hasModel: (): boolean => Native.hasModel(),
+
+  /** Every reading, once per display frame. Starts the sensor; returns an unsubscribe function. */
+  addFrameListener(l: (f: NativeMagnetFrame) => void) {
+    frameListeners.add(l);
+    retain();
+    return () => {
+      if (frameListeners.delete(l)) release();
+    };
+  },
+
+  /** Air taps, pushes, pull-aways and swipes. Starts the sensor; returns an unsubscribe function. */
+  addGestureListener(l: (g: NativeMagnetGesture) => void) {
+    gestureListeners.add(l);
+    retain();
+    return () => {
+      if (gestureListeners.delete(l)) release();
+    };
+  },
+
+  /** Take a new zero (keep magnets away for a second). */
+  zero: () => Native.zero(),
+
+  /** The calibrated magnet, kept across launches; null before a calibration. */
+  getMagnet: (): StoredMagnet | null => Native.getMagnet(),
+  setMagnet: (fit: Pick<CalibrationFit, "face" | "strength" | "sensor">) =>
+    Native.setMagnet(fit.face, fit.strength, fit.sensor.x, fit.sensor.y),
+  clearMagnet: () => Native.clearMagnet(),
+
+  /** The screen as the readings measure it: size (points / dp) and points per cm. */
+  screen: () => Native.screen(),
+};