magnetkit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Antalik
+
+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,59 @@
-# Temporary Holding Version
+# magnetkit
 
-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.
+Magnetic UI for React on the web: a real magnet beside an Android phone
+pulls your interface. Browsers can't read the raw magnetometer, so the
+[Magnet Bridge app](https://libraries.dev/downloads/MagnetBridge.apk) runs
+the on-device magnet model on the phone and serves its answers to the sites
+you allow; this package talks to it and turns the readings into motion.
+
+Docs and live demo: https://libraries.dev/magnetic
+
+## Install
+
+```sh
+npm install magnetkit
+```
+
+React 18+. Your site ships no model file.
+
+## Use
+
+```tsx
+import { useRef, useState } from "react";
+import { MagnetCalibration, useMagnetBridge, useMagnetGestures, useMagneticPull } from "magnetkit";
+
+export function Header() {
+  const ref = useRef<HTMLElement>(null);
+  const { state, connect, calibrated } = useMagnetBridge();
+  const [calibrating, setCalibrating] = useState(false);
+
+  useMagneticPull(ref);   // everything marked data-magnetic is pulled and springs back
+  useMagnetGestures((g) => { if (g.g === "tap") openMenu(); });
+
+  return (
+    <header ref={ref}>
+      <a data-magnetic href="/">Home</a>
+      <a data-magnetic href="/docs">Docs</a>
+      {state !== "open" ? <button onClick={connect}>Connect magnet</button>
+        : !calibrated ? <button onClick={() => setCalibrating(true)}>Calibrate</button> : null}
+      <MagnetCalibration open={calibrating} onClose={() => setCalibrating(false)} />
+    </header>
+  );
+}
+```
+
+- `useMagnet()` gives the latest reading as state; `useMagnetFrame(cb)` every
+  reading without rendering. Positions are screen dp:
+  `getMagnetBridge().toClient(p)` turns them into page px.
+- `calibrate(bridge, { onUpdate })` runs a calibration headless.
+- `simulateMagnetWithPointer()` lets the pointer play the magnet while you
+  develop without a phone.
+- `MagneticField` is the physics on its own, for canvas or anything else.
+
+Visitors need the Magnet Bridge app on an Android phone (Android 10+): they
+tap Start bridge, then connect from your page. Android Chrome asks once to
+allow local network access. iPhone browsers can't take part.
+
+## License
+
+MIT. The model runs inside the Magnet Bridge app.

package/dist/index.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const k=require("react/jsx-runtime"),C=require("react"),I=160/2.54;function H(i,t,e,o){const s=Math.hypot(i,t,e),n=-i/s,r=-t/s,l=-e/s,a=o*l,m=1/(s*s*s);return[m*3*a*n,m*3*a*r,m*(3*a*l-o)]}function G(i,t,e=I){if(i.length<3)return null;const o=i.reduce((n,r)=>n+r.delta[0]**2+r.delta[1]**2+r.delta[2]**2,0);let s=null;for(const n of[1,-1])for(let r=0;r<=t.x;r+=8)for(let l=-30;l<=t.y*.5;l+=8)for(let a=.6;a<=5.01;a+=.2){let m=0,d=0;const y=i.map(h=>{const u=H((h.screen.x-r)/e,-(h.screen.y-l)/e,a,n);return m+=u[0]*h.delta[0]+u[1]*h.delta[1]+u[2]*h.delta[2],d+=u[0]*u[0]+u[1]*u[1]+u[2]*u[2],u}),f=m/d;if(!(f>0))continue;let c=0;i.forEach((h,u)=>{const S=y[u];c+=(h.delta[0]-f*S[0])**2+(h.delta[1]-f*S[1])**2+(h.delta[2]-f*S[2])**2}),c/=o,(!s||c<s.error)&&(s={face:n,strength:f,sensor:{x:r,y:l},height:a,error:c})}return s}const U="ws://127.0.0.1:47613";class O{constructor(){this.frame=null,this.hello=null,this.device="",this.version=0,this.state="idle",this.onFrame=null,this.onGesture=null,this.onState=null,this.frameListeners=new Set,this.gestureListeners=new Set,this.stateListeners=new Set,this.ws=null,this.touchOffset=null,addEventListener("touchstart",t=>{const e=t.touches[0];e&&(this.touchOffset={x:e.screenX-e.clientX,y:e.screenY-e.clientY})},{passive:!0})}addFrameListener(t){return this.frameListeners.add(t),()=>{this.frameListeners.delete(t)}}addGestureListener(t){return this.gestureListeners.add(t),()=>{this.gestureListeners.delete(t)}}addStateListener(t){return this.stateListeners.add(t),()=>{this.stateListeners.delete(t)}}zero(){this.send({type:"calibrate"})}setMagnet(t){this.send({type:"set-magnet",face:t.face,strength:t.strength,sensor:[t.sensor.x,t.sensor.y]})}connect(){return this.state==="open"||this.state==="connecting"?Promise.resolve(this.state==="open"):(this.set("connecting"),new Promise(t=>{let e=!1;const o=n=>{e||(e=!0,t(n))};let s;try{s=new WebSocket(U)}catch{return this.set("failed"),o(!1)}this.ws=s,s.onopen=()=>{this.set("open"),o(!0)},s.onclose=()=>{this.ws=null,this.frame=null,this.set("failed"),o(!1)},s.onmessage=n=>this.receive(String(n.data))}))}send(t){this.ws&&this.ws.readyState===WebSocket.OPEN&&this.ws.send(JSON.stringify(t))}offset(){return this.touchOffset??{x:0,y:Math.max(0,screen.height-innerHeight)}}toClient(t){const e=this.offset();return{x:t.x-e.x,y:t.y-e.y}}toScreen(t){const e=this.offset();return{x:t.x+e.x,y:t.y+e.y}}set(t){this.state=t,this.emitState()}emitState(){var t;(t=this.onState)==null||t.call(this),this.stateListeners.forEach(e=>e())}receive(t){var o,s;let e;try{e=JSON.parse(t)}catch{return}if(e.type==="m"){const n={t:e.t,pos:e.pos?{x:e.pos[0],y:e.pos[1]}:null,spread:e.sp??0,height:e.h??null,presence:e.p??1,pull:e.pull??0,strength:e.s??0,delta:e.d??[0,0,0],tooClose:!!e.tc,calibrating:!!e.cal};this.frame=n,(o=this.onFrame)==null||o.call(this,n),this.frameListeners.forEach(r=>r(n))}else if(e.type==="gesture"){const n=e.g==="tap"?{g:"tap",at:e.at?{x:e.at[0],y:e.at[1]}:null}:e;(s=this.onGesture)==null||s.call(this,n),this.gestureListeners.forEach(r=>r(n))}else e.type==="model-hello"?(this.hello=e,this.emitState()):e.type==="hello"&&(this.device=`${e.manufacturer} ${e.model}`,this.version=Number(e.version)||0,this.emitState())}}const P=i=>i.right-i.left,$=i=>i.bottom-i.top,W=(i,t,e)=>({left:i.left+t,top:i.top+e,right:i.right+t,bottom:i.bottom+e}),N=(i,t)=>({left:i.left+t,top:i.top+t,right:i.right-t,bottom:i.bottom-t}),T=(i,t,e)=>Math.min(e,Math.max(t,i));class j{constructor(){this.home={left:0,top:0,right:0,bottom:0},this.corner=8,this.ox=0,this.oy=0,this.vx=0,this.vy=0,this.angle=0,this.spin=0,this.atEdge=!1}get mass(){return Math.max(1,P(this.home)*$(this.home)/1e3)}get inertia(){return this.mass*(P(this.home)**2+$(this.home)**2)/12}get center(){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)<.2&&Math.abs(this.oy)<.2&&Math.abs(this.vx)<2&&Math.abs(this.vy)<2&&Math.abs(this.angle)<.001}}class X{constructor(){this.parts=new Map,this.magnet=null,this.overGlass=!1,this.lastT=0,this.gate=0,this.lostAt=0,this.strengths=[],this.screenCorner=40,this.stiffness=150,this.damping=21,this.force=3e4,this.reach=150,this.maxForce=26e3,this.standoff=40,this.softening=40,this.nearBand=90,this.farBand=320,this.tiltGain=.5,this.maxTilt=.1,this.spinStiffness=80,this.spinDamping=12,this.restitution=.3,this.wallRestitution=.25,this.restingSpeed=250,this.wallFriction=.35}setHome(t,e,o){let s=this.parts.get(t);s||this.parts.set(t,s=new j),s.home=e,s.corner=o}get active(){return this.gate>.01||[...this.parts.values()].some(t=>!t.resting)}relax(t){this.simulate(t,null)}step(t,e,o,s){const n=this.lastT>0?Math.min(.03333333333333333,Math.max(.004166666666666667,e-this.lastT)):.016666666666666666,r=t.pos;if(t.strength>4&&r){const c=this.magnet;if(c){const h=Math.hypot(r.x-c.x,r.y-c.y),u=1-Math.exp(-n/(h>200?.4:.08));this.magnet={x:c.x+(r.x-c.x)*u,y:c.y+(r.y-c.y)*u}}else this.magnet=r;this.lostAt=e}else e-this.lostAt>.15&&(this.magnet=null);for(this.strengths.push([e,t.strength]);this.strengths.length&&e-this.strengths[0][0]>.5;)this.strengths.shift();const l=Math.max(...this.strengths.map(c=>c[1])),a=l>25?T((t.strength/l-.15)/.3,0,1):1,m=(s<0?-1:1)*t.delta[2]/Math.max(1e-6,t.strength),d=this.magnet,y=!!d&&this.outside(d,o)<-25&&(t.height??0)>.8;t.strength>4&&(m>.2||y?this.overGlass=!0:m<0&&(this.overGlass=!1));let f=0;if(d&&!this.overGlass){const c=T((t.strength-10)/25,0,1),h=T((t.presence-.2)/.4,0,1);f=c*h*a}this.gate+=(f-this.gate)*(1-Math.exp(-n/(f>this.gate?.08:.04))),this.simulate(e,o)}outside(t,e){const o=Math.max(e.left-t.x,t.x-e.right),s=Math.max(e.top-t.y,t.y-e.bottom);return o>0||s>0?Math.hypot(Math.max(0,o),Math.max(0,s)):Math.max(o,s)}nearestEdge(t,e){const o=t.x-e.left,s=e.right-t.x,n=t.y-e.top,r=e.bottom-t.y,l=Math.min(o,s,n,r);return l===o?{x:-1,y:0}:l===s?{x:1,y:0}:l===n?{x:0,y:-1}:{x:0,y:1}}pullPoint(t,e){let o=T(t.x,e.left,e.right),s=T(t.y,e.top,e.bottom),n=t.x-o,r=t.y-s;if(Math.hypot(n,r)<1){const a=this.nearestEdge(t,e);a.x?o=a.x<0?e.left:e.right:s=a.y<0?e.top:e.bottom,n=a.x,r=a.y}const l=Math.max(1e-6,Math.hypot(n,r));return{x:o+n/l*this.standoff,y:s+r/l*this.standoff}}proximity(t,e){return T(1-(this.outside(t,e)-this.nearBand)/(this.farBand-this.nearBand),0,1)}direction(t,e,o){let s=e.x-t.x,n=e.y-t.y;const r=Math.max(1e-6,Math.hypot(s,n));s/=r,n/=r;let l=e.x-T(e.x,o.left,o.right),a=e.y-T(e.y,o.top,o.bottom);if(Math.hypot(l,a)<1){const h=this.nearestEdge(e,o);l=h.x,a=h.y}const m=Math.max(1e-6,Math.hypot(l,a));l/=m,a/=m;const d=.65;let y=l*d+s*(1-d),f=a*d+n*(1-d);const c=Math.max(1e-6,Math.hypot(y,f));return{x:y/c,y:f/c}}simulate(t,e){const o=this.lastT>0?Math.min(.03333333333333333,Math.max(.004166666666666667,t-this.lastT)):.016666666666666666;this.lastT=t;for(const n of this.parts.values()){if(P(n.home)<=0)continue;let r=-this.stiffness*n.ox-this.damping*n.vx,l=-this.stiffness*n.oy-this.damping*n.vy,a=0;const m=this.magnet;if(m&&e&&this.gate>.01){const y=this.pullPoint(m,e),f=n.center,c=P(n.home),h=$(n.home),u=W(n.home,n.ox,n.oy),S=T(y.x,u.left,u.right),v=T(y.y,u.top,u.bottom),g=Math.hypot(y.x-S,y.y-v)+this.softening,x=Math.min(this.maxForce,this.force*(this.reach/g)**3)*this.gate*this.proximity(m,e),M=this.direction(f,y,e);r+=x*M.x,l+=x*M.y;const E=Math.cos(n.angle),p=Math.sin(n.angle),b=(y.x-f.x)*E+(y.y-f.y)*p,w=-(y.x-f.x)*p+(y.y-f.y)*E,L=T(b,-c/2,c/2),F=T(w,-h/2,h/2),z=L*E-F*p,R=L*p+F*E;a=this.tiltGain*(z*x*M.y-R*x*M.x)/((c*c+h*h)/12),n.atEdge&&(a*=.4)}n.vx+=r*o,n.vy+=l*o;const d=Math.hypot(n.vx,n.vy);d>2600&&(n.vx=n.vx/d*2600,n.vy=n.vy/d*2600),n.ox+=n.vx*o,n.oy+=n.vy*o,n.spin+=(a-this.spinStiffness*n.angle-this.spinDamping*n.spin)*o,n.angle+=n.spin*o,Math.abs(n.angle)>this.maxTilt&&(n.angle=T(n.angle,-this.maxTilt,this.maxTilt),n.spin*=.4)}if(!e)return;const s=[...this.parts.values()].filter(n=>P(n.home)>0);for(let n=0;n<4;n++){for(let r=0;r<s.length;r++)for(let l=r+1;l<s.length;l++)this.collide(s[r],s[l]);for(const r of s)this.contain(r,e)}for(const n of s)n.angle=T(n.angle,-this.maxTilt,this.maxTilt)}collide(t,e){const o=t.center,s=e.center,n=P(t.home)/2,r=$(t.home)/2,l=P(e.home)/2,a=$(e.home)/2;if(Math.abs(s.x-o.x)>n+l+20||Math.abs(s.y-o.y)>r+a+20)return;const m=[{x:Math.cos(t.angle),y:Math.sin(t.angle)},{x:-Math.sin(t.angle),y:Math.cos(t.angle)}],d=[{x:Math.cos(e.angle),y:Math.sin(e.angle)},{x:-Math.sin(e.angle),y:Math.cos(e.angle)}],y=s.x-o.x,f=s.y-o.y;let c=1/0,h=0,u=0;for(const p of[...m,...d]){const b=n*Math.abs(m[0].x*p.x+m[0].y*p.y)+r*Math.abs(m[1].x*p.x+m[1].y*p.y),w=l*Math.abs(d[0].x*p.x+d[0].y*p.y)+a*Math.abs(d[1].x*p.x+d[1].y*p.y),L=y*p.x+f*p.y,F=b+w-Math.abs(L);if(F<=0)return;F<c&&(c=F,h=L<0?-p.x:p.x,u=L<0?-p.y:p.y)}const S=t.home,v=e.home;if(S.left<v.right-1&&v.left<S.right-1&&S.top<v.bottom-1&&v.top<S.bottom-1)return;const g=1/t.mass,x=1/e.mass,M=c/(g+x);t.ox-=h*M*g,t.oy-=u*M*g,e.ox+=h*M*x,e.oy+=u*M*x;const E=(e.vx-t.vx)*h+(e.vy-t.vy)*u;if(E<0){const p=-E>this.restingSpeed,b=-(1+(p?this.restitution:0))*E/(g+x);if(t.vx-=h*b*g,t.vy-=u*b*g,e.vx+=h*b*x,e.vy+=u*b*x,!p)return;const w=(o.x+s.x)/2,L=(o.y+s.y)/2;t.spin-=.5*((w-o.x)*u-(L-o.y)*h)*b/t.inertia,e.spin+=.5*((w-s.x)*u-(L-s.y)*h)*b/e.inertia}}contain(t,e){const o={left:Math.min(e.left,t.home.left),top:Math.min(e.top,t.home.top),right:Math.max(e.right,t.home.right),bottom:Math.max(e.bottom,t.home.bottom)},s=t.center,n=P(t.home)/2,r=$(t.home)/2,l=Math.min(t.corner,Math.min(n,r)),a=N(o,l),m=Math.max(0,this.screenCorner-l),d=Math.cos(t.angle),y=Math.sin(t.angle);let f=0,c=0,h=0,u=s.x,S=s.y;for(const[E,p]of[[-1,-1],[1,-1],[1,1],[-1,1]]){const b=E*(n-l),w=p*(r-l),L=s.x+b*d-w*y,F=s.y+b*y+w*d,z=_(L,F,a,m),R=Math.hypot(z.x,z.y);R>h&&(h=R,f=z.x,c=z.y,u=L,S=F)}if(h<.5){t.atEdge=!1;return}const v=t.atEdge;t.atEdge=!0,t.ox+=f,t.oy+=c;const g=f/h,x=c/h,M=t.vx*g+t.vy*x;if(M<0){const E=v&&-M<900,p=E?0:-M,b=E?0:this.wallRestitution;t.vx-=(1+b)*M*g,t.vy-=(1+b)*M*x;const w=t.vx*g+t.vy*x,L=t.vx-w*g,F=t.vy-w*x,z=Math.hypot(L,F);if(z>1e-6){const R=E?Math.min(z,this.wallFriction*-M)/z:.15;t.vx-=L*R,t.vy-=F*R}E?t.spin*=.7:t.spin+=.5*((u-s.x)*x-(S-s.y)*g)*p*t.mass/t.inertia}}}function _(i,t,e,o){const s=i<e.left+o?e.left+o:i>e.right-o?e.right-o:null,n=t<e.top+o?e.top+o:t>e.bottom-o?e.bottom-o:null;if(s!=null&&n!=null&&o>0){const a=Math.hypot(i-s,t-n);return a<=o?{x:0,y:0}:{x:(s-i)*(a-o)/a,y:(n-t)*(a-o)/a}}let r=0,l=0;return i<e.left?r=e.left-i:i>e.right&&(r=e.right-i),t<e.top?l=e.top-t:t>e.bottom&&(l=e.bottom-t),{x:r,y:l}}const B=[[.5,.45],[.5,.12],[.5,.88],[.15,.5],[.85,.5]];function Y(i,t={}){const e=t.spots??B,o=[];let s=0,n=[],r=null,l=0;const a=performance.now()+1500;let m=!1,d;const y=new Promise(g=>d=g),f=g=>{const x=i.viewport();return{x:e[g][0]*x.x,y:e[g][1]*x.y}},c=(g,x=0,M=null)=>({phase:g,index:s,total:e.length,spot:g==="spot"?f(s):null,progress:x,field:r&&performance.now()-l<2e3?r.strength:null,zeroing:!!(r!=null&&r.calibrating),fit:M}),h=g=>{var x;return(x=t.onUpdate)==null?void 0:x.call(t,g)},u=(g,x)=>{m||(m=!0,v(),clearInterval(S),h(c(g,1,x)),d(x))};i.zero(),h(c("zeroing"));const S=setInterval(()=>{!m&&performance.now()<a&&h(c("zeroing"))},300),v=i.addFrameListener(g=>{if(r=g,l=performance.now(),performance.now()<a||g.calibrating){h(c("zeroing"));return}if(g.strength<15){n=[],h(c("spot",0));return}n.push(g),n=n.filter(w=>w.t>g.t-1200);const x=w=>{const L=n.map(F=>F.delta[w]).sort((F,z)=>F-z);return L[L.length>>1]},M=[x(0),x(1),x(2)];if(Math.max(...n.map(w=>Math.hypot(w.delta[0]-M[0],w.delta[1]-M[1],w.delta[2]-M[2])))>Math.max(4,.12*g.strength)){n=[g],h(c("spot",0));return}const p=Math.min(1,(g.t-n[0].t)/1e3);if(h(c("spot",p)),p<1)return;if(o.push({screen:i.toScreen(f(s)),delta:M}),s++,n=[],s<e.length){h(c("spot",0));return}const b=G(o,i.screenSize(),i.pointsPerCm);if(!b)return u("failed",null);i.setMagnet(b),u("done",b)});return{promise:y,cancel:()=>u("cancelled",null)}}function D(i,t={}){return Y({zero:()=>i.zero(),addFrameListener:e=>i.addFrameListener(e),setMagnet:e=>i.setMagnet(e),viewport:()=>({x:innerWidth,y:innerHeight}),toScreen:e=>i.toScreen(e),screenSize:()=>{const e=i.hello;return e?{x:e.screenDp[0],y:e.screenDp[1]}:{x:screen.width,y:screen.height}},pointsPerCm:160/2.54},t)}let J=null;function A(){return J??(J=new O)}function K(){var e;const i=A(),t=C.useSyncExternalStore(o=>i.addStateListener(o),()=>{var o,s;return`${i.state}|${i.device}|${((o=i.hello)==null?void 0:o.grabStage)??""}|${((s=i.hello)==null?void 0:s.face)??""}`},()=>"idle||");return{bridge:i,state:i.state,device:i.device,calibrated:((e=i.hello)==null?void 0:e.grabStage)===2,connect:()=>i.connect(),key:t}}function Q(i){const t=C.useRef(i);t.current=i,C.useEffect(()=>A().addFrameListener(e=>t.current(e)),[])}function V(){const[i,t]=C.useState(A().frame);return C.useEffect(()=>{let e=0,o=null;const s=A().addFrameListener(n=>{o=n,e||(e=requestAnimationFrame(()=>{e=0,t(o)}))});return()=>{s(),cancelAnimationFrame(e)}},[]),i}function Z(i){const t=C.useRef(i);t.current=i,C.useEffect(()=>A().addGestureListener(e=>t.current(e)),[])}function q(i,t={}){const{selector:e="[data-magnetic]",enabled:o=!0}=t;C.useEffect(()=>{const s=i.current;if(!s||!o||matchMedia("(prefers-reduced-motion: reduce)").matches)return;const n=A(),r=new X;r.screenCorner=24,t.stiffness!=null&&(r.stiffness=t.stiffness),t.damping!=null&&(r.damping=t.damping),t.force!=null&&(r.force=t.force),t.reach!=null&&(r.reach=t.reach);let l=[];const a=()=>{l.forEach(f=>f.el.style.transform=""),l=[...s.querySelectorAll(e)].filter(f=>f.getBoundingClientRect().width>0).map((f,c)=>{getComputedStyle(f).display==="inline"&&(f.style.display="inline-block");const h=f.getBoundingClientRect();return{id:String(c),el:f,box:{left:h.left+scrollX,top:h.top+scrollY,right:h.right+scrollX,bottom:h.bottom+scrollY},corner:parseFloat(getComputedStyle(f).borderTopLeftRadius)||6}}),r.parts.clear()};a();const m=()=>a();addEventListener("resize",m);let d=0;const y=()=>{var S;const f=performance.now()/1e3,c=n.offset();for(const v of l)r.setHome(v.id,{left:v.box.left-scrollX+c.x,top:v.box.top-scrollY+c.y,right:v.box.right-scrollX+c.x,bottom:v.box.bottom-scrollY+c.y},v.corner);const h=n.frame,u={left:c.x,top:c.y,right:c.x+innerWidth,bottom:c.y+innerHeight};h?r.step(h,f,u,((S=n.hello)==null?void 0:S.face)??1):r.relax(f);for(const v of l){const g=r.parts.get(v.id);g&&(v.el.style.transform=g.resting?"":`translate(${g.ox.toFixed(2)}px, ${g.oy.toFixed(2)}px) rotate(${g.angle.toFixed(4)}rad)`)}d=requestAnimationFrame(y)};return d=requestAnimationFrame(y),()=>{cancelAnimationFrame(d),removeEventListener("resize",m),l.forEach(f=>f.el.style.transform="")}},[i,e,o,t.stiffness,t.damping,t.force,t.reach])}function tt({open:i,onClose:t}){const[e,o]=C.useState(null),s=C.useRef(t);s.current=t;const n=C.useRef(()=>{});if(C.useEffect(()=>{if(!i)return;const m=D(A(),{onUpdate:o});return n.current=m.cancel,m.promise.then(d=>{var y;return(y=s.current)==null?void 0:y.call(s,!!d)}),()=>m.cancel()},[i]),!i||!e||e.phase==="done"||e.phase==="cancelled")return null;const r=e.phase==="zeroing"?"Keep the magnet away for a moment…":e.phase==="failed"?"That didn't fit. Try again, holding the magnet still over each ring.":`Ring ${e.index+1} of ${e.total}: hold the magnet 1–2 cm above it and keep it still.`,l=e.field==null?"No readings from the bridge. Open Magnet Bridge and tap Start bridge.":`${e.field.toFixed(0)} µT${e.zeroing?" · zeroing":""}`,a=e.spot;return k.jsxs("div",{style:{position:"fixed",inset:0,zIndex:2147483e3,background:"rgba(0,0,0,0.94)",color:"#fff",font:"500 16px/24px system-ui, sans-serif",touchAction:"none"},children:[a&&k.jsx("div",{style:{position:"absolute",left:a.x,top:a.y,width:72,height:72,margin:-36,borderRadius:"50%",boxShadow:"inset 0 0 0 3px #fff"},children:k.jsx("i",{style:{position:"absolute",inset:10,borderRadius:"50%",background:"#4f9cff",transform:`scale(${e.progress.toFixed(3)})`}})}),k.jsx("p",{style:{position:"absolute",left:16,right:16,top:a?a.y<innerHeight/2?a.y+64:a.y-120:"40%",margin:0,textAlign:"center"},children:r}),k.jsx("p",{style:{position:"absolute",left:16,right:16,bottom:88,margin:0,textAlign:"center",font:"400 13px/18px system-ui, sans-serif",color:"#9a9a9a"},children:l}),k.jsx("button",{type:"button",onClick:()=>n.current(),style:{position:"absolute",left:"50%",bottom:32,transform:"translateX(-50%)",height:40,padding:"0 18px",border:0,borderRadius:999,background:"#2a2a2a",color:"#fff",font:"500 14px/1 system-ui, sans-serif"},children:"Cancel"})]})}function et(i=A()){let t=!1,e={x:0,y:0};const o=i.offset.bind(i);i.offset=()=>({x:0,y:0});const s=a=>{t=!0,e={x:a.clientX,y:a.clientY}},n=a=>{e={x:a.clientX,y:a.clientY}},r=()=>{t=!1};addEventListener("pointerdown",s),addEventListener("pointermove",n),addEventListener("pointerup",r);const l=window.setInterval(()=>{i.frame={t:performance.now(),pos:t?e:null,spread:20,height:null,presence:1,pull:t?.8:0,strength:t?80:0,delta:t?[0,0,-40]:[0,0,0],tooClose:!1,calibrating:!1}},20);return()=>{clearInterval(l),removeEventListener("pointerdown",s),removeEventListener("pointermove",n),removeEventListener("pointerup",r),i.offset=o}}exports.DEFAULT_SPOTS=B;exports.MagnetBridge=O;exports.MagnetCalibration=tt;exports.MagneticField=X;exports.Particle=j;exports.calibrate=D;exports.fitCalibration=G;exports.getMagnetBridge=A;exports.runCalibration=Y;exports.simulateMagnetWithPointer=et;exports.useMagnet=V;exports.useMagnetBridge=K;exports.useMagnetFrame=Q;exports.useMagnetGestures=Z;exports.useMagneticPull=q;

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { RefObject } from 'react';
+
+export declare type Box = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+
+/** Runs a calibration; resolves with the fit (already sent to the phone), or null. */
+export declare function calibrate(bridge: MagnetBridge, opts?: CalibrationOptions): {
+    promise: Promise<CalibrationFit | null>;
+    cancel: () => void;
+};
+
+export declare type CalibrationFit = {
+    face: 1 | -1;
+    strength: number;
+    sensor: Pt;
+    height: number;
+    error: number;
+};
+
+/** What a calibration needs from where the readings come from. */
+export declare 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 type CalibrationOptions = {
+    /** Spots as fractions of the viewport. Five by default: middle, top, bottom, left, right. */
+    spots?: Array<[number, number]>;
+    onUpdate?: (s: CalibrationState) => void;
+};
+
+export declare type CalibrationSpot = {
+    screen: Pt;
+    delta: [number, number, number];
+};
+
+export declare 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 declare const DEFAULT_SPOTS: Array<[number, number]>;
+
+export declare function fitCalibration(spots: CalibrationSpot[], screenDp: Pt, PPCM?: number): CalibrationFit | null;
+
+/** The page's bridge. Nothing connects until you call `connect()`. */
+export declare function getMagnetBridge(): MagnetBridge;
+
+export declare class MagnetBridge {
+    frame: MagnetFrame | null;
+    hello: ModelHello | null;
+    device: string;
+    /** The app's protocol version (0.5 sends to each page on its own). */
+    version: number;
+    state: "idle" | "connecting" | "open" | "failed";
+    onFrame: ((f: MagnetFrame) => void) | null;
+    onGesture: ((g: MagnetGesture) => void) | null;
+    onState: (() => void) | null;
+    private frameListeners;
+    private gestureListeners;
+    private stateListeners;
+    /** Every reading (~50 a second). Returns an unsubscribe function. */
+    addFrameListener(l: (f: MagnetFrame) => void): () => void;
+    /** Air taps, pushes, pull-aways and swipes. Returns an unsubscribe function. */
+    addGestureListener(l: (g: MagnetGesture) => void): () => void;
+    /** Connection state, device and calibration changes. Returns an unsubscribe function. */
+    addStateListener(l: () => void): () => void;
+    /** Take a new zero on the phone (keep magnets away for a second). */
+    zero(): void;
+    /** Hand the phone a fitted calibration (see fitCalibration). */
+    setMagnet(fit: {
+        face: 1 | -1;
+        strength: number;
+        sensor: Pt;
+    }): void;
+    private ws;
+    private touchOffset;
+    constructor();
+    connect(): Promise<boolean>;
+    send(obj: unknown): void;
+    /** Screen dp → client px. The viewport runs to the bottom of the screen on
+     *  Android Chrome, so the bars above it are what is left of the screen. */
+    offset(): Pt;
+    toClient(p: Pt): Pt;
+    toScreen(p: Pt): Pt;
+    private set;
+    private emitState;
+    private receive;
+}
+
+/** A ready-made calibration screen: five rings, full screen, cancel button. */
+export declare function MagnetCalibration({ open, onClose }: {
+    open: boolean;
+    onClose?: (ok: boolean) => void;
+}): JSX_2.Element | null;
+
+export declare 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 declare type MagnetGesture = {
+    g: "tap";
+    at: Pt | null;
+} | {
+    g: "push" | "pullAway";
+    speed: number;
+} | {
+    g: "swipe";
+    dir: Pt;
+    speed: number;
+};
+
+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;
+}
+
+export declare type MagneticPullOptions = {
+    /** Which elements inside the container move. Default `[data-magnetic]`. */
+    selector?: string;
+    enabled?: boolean;
+    /** Tuning, as MagneticField's: spring stiffness, damping, force, reach (px). */
+    stiffness?: number;
+    damping?: number;
+    force?: number;
+    reach?: number;
+};
+
+export declare type ModelHello = {
+    screenDp: [number, number];
+    grabStage: number;
+    face: number | null;
+    strength: number | null;
+    sensorDp: [number, number];
+    model: boolean;
+};
+
+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 type Pt = {
+    x: number;
+    y: 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;
+};
+
+/**
+ * Desktop development without a phone: the pointer plays the magnet. Press
+ * and hold to bring it in, release to take it away. Returns a stop function.
+ */
+export declare function simulateMagnetWithPointer(bridge?: MagnetBridge): () => void;
+
+/** The latest reading as state, at most one render per animation frame. */
+export declare function useMagnet(): MagnetFrame | null;
+
+/** Connection state, device and calibration; re-renders when they change. */
+export declare function useMagnetBridge(): {
+    bridge: MagnetBridge;
+    state: "idle" | "connecting" | "open" | "failed";
+    device: string;
+    calibrated: boolean;
+    connect: () => Promise<boolean>;
+    key: string;
+};
+
+/** Every reading, without re-rendering (~50 a second). */
+export declare function useMagnetFrame(cb: (f: MagnetFrame) => void): void;
+
+/** Air taps, pushes, pull-aways and swipes. */
+export declare function useMagnetGestures(cb: (g: MagnetGesture) => void): void;
+
+/**
+ * The Magnetic UI pull: elements matching `selector` inside the container
+ * are springs to their place, pulled toward a magnet held beside the phone,
+ * and they come back when it leaves. Off with reduced motion.
+ */
+export declare function useMagneticPull(container: RefObject<HTMLElement>, opts?: MagneticPullOptions): void;
+
+export { }

package/dist/index.es.js

@@ -0,0 +1,550 @@
+import { jsxs as X, jsx as $ } from "react/jsx-runtime";
+import { useState as O, useRef as G, useEffect as P, useSyncExternalStore as Y } from "react";
+const I = 160 / 2.54;
+function D(i, t, e, o) {
+  const s = Math.hypot(i, t, e), n = -i / s, r = -t / s, h = -e / s, a = o * h, u = 1 / (s * s * s);
+  return [u * 3 * a * n, u * 3 * a * r, u * (3 * a * h - o)];
+}
+function H(i, t, e = I) {
+  if (i.length < 3) return null;
+  const o = i.reduce((n, r) => n + r.delta[0] ** 2 + r.delta[1] ** 2 + r.delta[2] ** 2, 0);
+  let s = null;
+  for (const n of [1, -1])
+    for (let r = 0; r <= t.x; r += 8)
+      for (let h = -30; h <= t.y * 0.5; h += 8)
+        for (let a = 0.6; a <= 5.01; a += 0.2) {
+          let u = 0, d = 0;
+          const y = i.map((l) => {
+            const g = D((l.screen.x - r) / e, -(l.screen.y - h) / e, a, n);
+            return u += g[0] * l.delta[0] + g[1] * l.delta[1] + g[2] * l.delta[2], d += g[0] * g[0] + g[1] * g[1] + g[2] * g[2], g;
+          }), f = u / d;
+          if (!(f > 0)) continue;
+          let c = 0;
+          i.forEach((l, g) => {
+            const S = y[g];
+            c += (l.delta[0] - f * S[0]) ** 2 + (l.delta[1] - f * S[1]) ** 2 + (l.delta[2] - f * S[2]) ** 2;
+          }), c /= o, (!s || c < s.error) && (s = { face: n, strength: f, sensor: { x: r, y: h }, height: a, error: c });
+        }
+  return s;
+}
+const j = "ws://127.0.0.1:47613";
+class B {
+  constructor() {
+    this.frame = null, this.hello = null, this.device = "", this.version = 0, this.state = "idle", this.onFrame = null, this.onGesture = null, this.onState = null, this.frameListeners = /* @__PURE__ */ new Set(), this.gestureListeners = /* @__PURE__ */ new Set(), this.stateListeners = /* @__PURE__ */ new Set(), this.ws = null, this.touchOffset = null, addEventListener(
+      "touchstart",
+      (t) => {
+        const e = t.touches[0];
+        e && (this.touchOffset = { x: e.screenX - e.clientX, y: e.screenY - e.clientY });
+      },
+      { passive: !0 }
+    );
+  }
+  /** Every reading (~50 a second). Returns an unsubscribe function. */
+  addFrameListener(t) {
+    return this.frameListeners.add(t), () => {
+      this.frameListeners.delete(t);
+    };
+  }
+  /** Air taps, pushes, pull-aways and swipes. Returns an unsubscribe function. */
+  addGestureListener(t) {
+    return this.gestureListeners.add(t), () => {
+      this.gestureListeners.delete(t);
+    };
+  }
+  /** Connection state, device and calibration changes. Returns an unsubscribe function. */
+  addStateListener(t) {
+    return this.stateListeners.add(t), () => {
+      this.stateListeners.delete(t);
+    };
+  }
+  /** Take a new zero on the phone (keep magnets away for a second). */
+  zero() {
+    this.send({ type: "calibrate" });
+  }
+  /** Hand the phone a fitted calibration (see fitCalibration). */
+  setMagnet(t) {
+    this.send({ type: "set-magnet", face: t.face, strength: t.strength, sensor: [t.sensor.x, t.sensor.y] });
+  }
+  connect() {
+    return this.state === "open" || this.state === "connecting" ? Promise.resolve(this.state === "open") : (this.set("connecting"), new Promise((t) => {
+      let e = !1;
+      const o = (n) => {
+        e || (e = !0, t(n));
+      };
+      let s;
+      try {
+        s = new WebSocket(j);
+      } catch {
+        return this.set("failed"), o(!1);
+      }
+      this.ws = s, s.onopen = () => {
+        this.set("open"), o(!0);
+      }, s.onclose = () => {
+        this.ws = null, this.frame = null, this.set("failed"), o(!1);
+      }, s.onmessage = (n) => this.receive(String(n.data));
+    }));
+  }
+  send(t) {
+    this.ws && this.ws.readyState === WebSocket.OPEN && this.ws.send(JSON.stringify(t));
+  }
+  /** Screen dp → client px. The viewport runs to the bottom of the screen on
+   *  Android Chrome, so the bars above it are what is left of the screen. */
+  offset() {
+    return this.touchOffset ?? { x: 0, y: Math.max(0, screen.height - innerHeight) };
+  }
+  toClient(t) {
+    const e = this.offset();
+    return { x: t.x - e.x, y: t.y - e.y };
+  }
+  toScreen(t) {
+    const e = this.offset();
+    return { x: t.x + e.x, y: t.y + e.y };
+  }
+  set(t) {
+    this.state = t, this.emitState();
+  }
+  emitState() {
+    var t;
+    (t = this.onState) == null || t.call(this), this.stateListeners.forEach((e) => e());
+  }
+  receive(t) {
+    var o, s;
+    let e;
+    try {
+      e = JSON.parse(t);
+    } catch {
+      return;
+    }
+    if (e.type === "m") {
+      const n = {
+        t: e.t,
+        pos: e.pos ? { x: e.pos[0], y: e.pos[1] } : null,
+        spread: e.sp ?? 0,
+        height: e.h ?? null,
+        presence: e.p ?? 1,
+        pull: e.pull ?? 0,
+        strength: e.s ?? 0,
+        delta: e.d ?? [0, 0, 0],
+        tooClose: !!e.tc,
+        calibrating: !!e.cal
+      };
+      this.frame = n, (o = this.onFrame) == null || o.call(this, n), this.frameListeners.forEach((r) => r(n));
+    } else if (e.type === "gesture") {
+      const n = e.g === "tap" ? { g: "tap", at: e.at ? { x: e.at[0], y: e.at[1] } : null } : e;
+      (s = this.onGesture) == null || s.call(this, n), this.gestureListeners.forEach((r) => r(n));
+    } else e.type === "model-hello" ? (this.hello = e, this.emitState()) : e.type === "hello" && (this.device = `${e.manufacturer} ${e.model}`, this.version = Number(e.version) || 0, this.emitState());
+  }
+}
+const k = (i) => i.right - i.left, R = (i) => i.bottom - i.top, N = (i, t, e) => ({ left: i.left + t, top: i.top + e, right: i.right + t, bottom: i.bottom + e }), U = (i, t) => ({ left: i.left + t, top: i.top + t, right: i.right - t, bottom: i.bottom - t }), z = (i, t, e) => Math.min(e, Math.max(t, i));
+class W {
+  constructor() {
+    this.home = { left: 0, top: 0, right: 0, bottom: 0 }, this.corner = 8, this.ox = 0, this.oy = 0, this.vx = 0, this.vy = 0, this.angle = 0, this.spin = 0, this.atEdge = !1;
+  }
+  get mass() {
+    return Math.max(1, k(this.home) * R(this.home) / 1e3);
+  }
+  get inertia() {
+    return this.mass * (k(this.home) ** 2 + R(this.home) ** 2) / 12;
+  }
+  get center() {
+    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) < 1e-3;
+  }
+}
+class _ {
+  constructor() {
+    this.parts = /* @__PURE__ */ new Map(), this.magnet = null, this.overGlass = !1, this.lastT = 0, this.gate = 0, this.lostAt = 0, this.strengths = [], this.screenCorner = 40, this.stiffness = 150, this.damping = 21, this.force = 3e4, this.reach = 150, this.maxForce = 26e3, this.standoff = 40, this.softening = 40, this.nearBand = 90, this.farBand = 320, this.tiltGain = 0.5, this.maxTilt = 0.1, this.spinStiffness = 80, this.spinDamping = 12, this.restitution = 0.3, this.wallRestitution = 0.25, this.restingSpeed = 250, this.wallFriction = 0.35;
+  }
+  setHome(t, e, o) {
+    let s = this.parts.get(t);
+    s || this.parts.set(t, s = new W()), s.home = e, s.corner = o;
+  }
+  get active() {
+    return this.gate > 0.01 || [...this.parts.values()].some((t) => !t.resting);
+  }
+  relax(t) {
+    this.simulate(t, null);
+  }
+  step(t, e, o, s) {
+    const n = this.lastT > 0 ? Math.min(0.03333333333333333, Math.max(0.004166666666666667, e - this.lastT)) : 0.016666666666666666, r = t.pos;
+    if (t.strength > 4 && r) {
+      const c = this.magnet;
+      if (c) {
+        const l = Math.hypot(r.x - c.x, r.y - c.y), g = 1 - Math.exp(-n / (l > 200 ? 0.4 : 0.08));
+        this.magnet = { x: c.x + (r.x - c.x) * g, y: c.y + (r.y - c.y) * g };
+      } else this.magnet = r;
+      this.lostAt = e;
+    } else e - this.lostAt > 0.15 && (this.magnet = null);
+    for (this.strengths.push([e, t.strength]); this.strengths.length && e - this.strengths[0][0] > 0.5; ) this.strengths.shift();
+    const h = Math.max(...this.strengths.map((c) => c[1])), a = h > 25 ? z((t.strength / h - 0.15) / 0.3, 0, 1) : 1, u = (s < 0 ? -1 : 1) * t.delta[2] / Math.max(1e-6, t.strength), d = this.magnet, y = !!d && this.outside(d, o) < -25 && (t.height ?? 0) > 0.8;
+    t.strength > 4 && (u > 0.2 || y ? this.overGlass = !0 : u < 0 && (this.overGlass = !1));
+    let f = 0;
+    if (d && !this.overGlass) {
+      const c = z((t.strength - 10) / 25, 0, 1), l = z((t.presence - 0.2) / 0.4, 0, 1);
+      f = c * l * a;
+    }
+    this.gate += (f - this.gate) * (1 - Math.exp(-n / (f > this.gate ? 0.08 : 0.04))), this.simulate(e, o);
+  }
+  outside(t, e) {
+    const o = Math.max(e.left - t.x, t.x - e.right), s = Math.max(e.top - t.y, t.y - e.bottom);
+    return o > 0 || s > 0 ? Math.hypot(Math.max(0, o), Math.max(0, s)) : Math.max(o, s);
+  }
+  nearestEdge(t, e) {
+    const o = t.x - e.left, s = e.right - t.x, n = t.y - e.top, r = e.bottom - t.y, h = Math.min(o, s, n, r);
+    return h === o ? { x: -1, y: 0 } : h === s ? { x: 1, y: 0 } : h === n ? { x: 0, y: -1 } : { x: 0, y: 1 };
+  }
+  pullPoint(t, e) {
+    let o = z(t.x, e.left, e.right), s = z(t.y, e.top, e.bottom), n = t.x - o, r = t.y - s;
+    if (Math.hypot(n, r) < 1) {
+      const a = this.nearestEdge(t, e);
+      a.x ? o = a.x < 0 ? e.left : e.right : s = a.y < 0 ? e.top : e.bottom, n = a.x, r = a.y;
+    }
+    const h = Math.max(1e-6, Math.hypot(n, r));
+    return { x: o + n / h * this.standoff, y: s + r / h * this.standoff };
+  }
+  proximity(t, e) {
+    return z(1 - (this.outside(t, e) - this.nearBand) / (this.farBand - this.nearBand), 0, 1);
+  }
+  direction(t, e, o) {
+    let s = e.x - t.x, n = e.y - t.y;
+    const r = Math.max(1e-6, Math.hypot(s, n));
+    s /= r, n /= r;
+    let h = e.x - z(e.x, o.left, o.right), a = e.y - z(e.y, o.top, o.bottom);
+    if (Math.hypot(h, a) < 1) {
+      const l = this.nearestEdge(e, o);
+      h = l.x, a = l.y;
+    }
+    const u = Math.max(1e-6, Math.hypot(h, a));
+    h /= u, a /= u;
+    const d = 0.65;
+    let y = h * d + s * (1 - d), f = a * d + n * (1 - d);
+    const c = Math.max(1e-6, Math.hypot(y, f));
+    return { x: y / c, y: f / c };
+  }
+  simulate(t, e) {
+    const o = this.lastT > 0 ? Math.min(0.03333333333333333, Math.max(0.004166666666666667, t - this.lastT)) : 0.016666666666666666;
+    this.lastT = t;
+    for (const n of this.parts.values()) {
+      if (k(n.home) <= 0) continue;
+      let r = -this.stiffness * n.ox - this.damping * n.vx, h = -this.stiffness * n.oy - this.damping * n.vy, a = 0;
+      const u = this.magnet;
+      if (u && e && this.gate > 0.01) {
+        const y = this.pullPoint(u, e), f = n.center, c = k(n.home), l = R(n.home), g = N(n.home, n.ox, n.oy), S = z(y.x, g.left, g.right), M = z(y.y, g.top, g.bottom), m = Math.hypot(y.x - S, y.y - M) + this.softening, x = Math.min(this.maxForce, this.force * (this.reach / m) ** 3) * this.gate * this.proximity(u, e), v = this.direction(f, y, e);
+        r += x * v.x, h += x * v.y;
+        const E = Math.cos(n.angle), p = Math.sin(n.angle), b = (y.x - f.x) * E + (y.y - f.y) * p, w = -(y.x - f.x) * p + (y.y - f.y) * E, L = z(b, -c / 2, c / 2), F = z(w, -l / 2, l / 2), T = L * E - F * p, C = L * p + F * E;
+        a = this.tiltGain * (T * x * v.y - C * x * v.x) / ((c * c + l * l) / 12), n.atEdge && (a *= 0.4);
+      }
+      n.vx += r * o, n.vy += h * o;
+      const d = Math.hypot(n.vx, n.vy);
+      d > 2600 && (n.vx = n.vx / d * 2600, n.vy = n.vy / d * 2600), n.ox += n.vx * o, n.oy += n.vy * o, n.spin += (a - this.spinStiffness * n.angle - this.spinDamping * n.spin) * o, n.angle += n.spin * o, Math.abs(n.angle) > this.maxTilt && (n.angle = z(n.angle, -this.maxTilt, this.maxTilt), n.spin *= 0.4);
+    }
+    if (!e) return;
+    const s = [...this.parts.values()].filter((n) => k(n.home) > 0);
+    for (let n = 0; n < 4; n++) {
+      for (let r = 0; r < s.length; r++) for (let h = r + 1; h < s.length; h++) this.collide(s[r], s[h]);
+      for (const r of s) this.contain(r, e);
+    }
+    for (const n of s) n.angle = z(n.angle, -this.maxTilt, this.maxTilt);
+  }
+  /** Two boxes (separating axes): push apart by mass; a real knock bounces and spins them. */
+  collide(t, e) {
+    const o = t.center, s = e.center, n = k(t.home) / 2, r = R(t.home) / 2, h = k(e.home) / 2, a = R(e.home) / 2;
+    if (Math.abs(s.x - o.x) > n + h + 20 || Math.abs(s.y - o.y) > r + a + 20) return;
+    const u = [{ x: Math.cos(t.angle), y: Math.sin(t.angle) }, { x: -Math.sin(t.angle), y: Math.cos(t.angle) }], d = [{ x: Math.cos(e.angle), y: Math.sin(e.angle) }, { x: -Math.sin(e.angle), y: Math.cos(e.angle) }], y = s.x - o.x, f = s.y - o.y;
+    let c = 1 / 0, l = 0, g = 0;
+    for (const p of [...u, ...d]) {
+      const b = n * Math.abs(u[0].x * p.x + u[0].y * p.y) + r * Math.abs(u[1].x * p.x + u[1].y * p.y), w = h * Math.abs(d[0].x * p.x + d[0].y * p.y) + a * Math.abs(d[1].x * p.x + d[1].y * p.y), L = y * p.x + f * p.y, F = b + w - Math.abs(L);
+      if (F <= 0) return;
+      F < c && (c = F, l = L < 0 ? -p.x : p.x, g = L < 0 ? -p.y : p.y);
+    }
+    const S = t.home, M = e.home;
+    if (S.left < M.right - 1 && M.left < S.right - 1 && S.top < M.bottom - 1 && M.top < S.bottom - 1) return;
+    const m = 1 / t.mass, x = 1 / e.mass, v = c / (m + x);
+    t.ox -= l * v * m, t.oy -= g * v * m, e.ox += l * v * x, e.oy += g * v * x;
+    const E = (e.vx - t.vx) * l + (e.vy - t.vy) * g;
+    if (E < 0) {
+      const p = -E > this.restingSpeed, b = -(1 + (p ? this.restitution : 0)) * E / (m + x);
+      if (t.vx -= l * b * m, t.vy -= g * b * m, e.vx += l * b * x, e.vy += g * b * x, !p) return;
+      const w = (o.x + s.x) / 2, L = (o.y + s.y) / 2;
+      t.spin -= 0.5 * ((w - o.x) * g - (L - o.y) * l) * b / t.inertia, e.spin += 0.5 * ((w - s.x) * g - (L - s.y) * l) * b / e.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. */
+  contain(t, e) {
+    const o = {
+      left: Math.min(e.left, t.home.left),
+      top: Math.min(e.top, t.home.top),
+      right: Math.max(e.right, t.home.right),
+      bottom: Math.max(e.bottom, t.home.bottom)
+    }, s = t.center, n = k(t.home) / 2, r = R(t.home) / 2, h = Math.min(t.corner, Math.min(n, r)), a = U(o, h), u = Math.max(0, this.screenCorner - h), d = Math.cos(t.angle), y = Math.sin(t.angle);
+    let f = 0, c = 0, l = 0, g = s.x, S = s.y;
+    for (const [E, p] of [[-1, -1], [1, -1], [1, 1], [-1, 1]]) {
+      const b = E * (n - h), w = p * (r - h), L = s.x + b * d - w * y, F = s.y + b * y + w * d, T = J(L, F, a, u), C = Math.hypot(T.x, T.y);
+      C > l && (l = C, f = T.x, c = T.y, g = L, S = F);
+    }
+    if (l < 0.5) {
+      t.atEdge = !1;
+      return;
+    }
+    const M = t.atEdge;
+    t.atEdge = !0, t.ox += f, t.oy += c;
+    const m = f / l, x = c / l, v = t.vx * m + t.vy * x;
+    if (v < 0) {
+      const E = M && -v < 900, p = E ? 0 : -v, b = E ? 0 : this.wallRestitution;
+      t.vx -= (1 + b) * v * m, t.vy -= (1 + b) * v * x;
+      const w = t.vx * m + t.vy * x, L = t.vx - w * m, F = t.vy - w * x, T = Math.hypot(L, F);
+      if (T > 1e-6) {
+        const C = E ? Math.min(T, this.wallFriction * -v) / T : 0.15;
+        t.vx -= L * C, t.vy -= F * C;
+      }
+      E ? t.spin *= 0.7 : t.spin += 0.5 * ((g - s.x) * x - (S - s.y) * m) * p * t.mass / t.inertia;
+    }
+  }
+}
+function J(i, t, e, o) {
+  const s = i < e.left + o ? e.left + o : i > e.right - o ? e.right - o : null, n = t < e.top + o ? e.top + o : t > e.bottom - o ? e.bottom - o : null;
+  if (s != null && n != null && o > 0) {
+    const a = Math.hypot(i - s, t - n);
+    return a <= o ? { x: 0, y: 0 } : { x: (s - i) * (a - o) / a, y: (n - t) * (a - o) / a };
+  }
+  let r = 0, h = 0;
+  return i < e.left ? r = e.left - i : i > e.right && (r = e.right - i), t < e.top ? h = e.top - t : t > e.bottom && (h = e.bottom - t), { x: r, y: h };
+}
+const K = [[0.5, 0.45], [0.5, 0.12], [0.5, 0.88], [0.15, 0.5], [0.85, 0.5]];
+function Q(i, t = {}) {
+  const e = t.spots ?? K, o = [];
+  let s = 0, n = [], r = null, h = 0;
+  const a = performance.now() + 1500;
+  let u = !1, d;
+  const y = new Promise((m) => d = m), f = (m) => {
+    const x = i.viewport();
+    return { x: e[m][0] * x.x, y: e[m][1] * x.y };
+  }, c = (m, x = 0, v = null) => ({
+    phase: m,
+    index: s,
+    total: e.length,
+    spot: m === "spot" ? f(s) : null,
+    progress: x,
+    field: r && performance.now() - h < 2e3 ? r.strength : null,
+    zeroing: !!(r != null && r.calibrating),
+    fit: v
+  }), l = (m) => {
+    var x;
+    return (x = t.onUpdate) == null ? void 0 : x.call(t, m);
+  }, g = (m, x) => {
+    u || (u = !0, M(), clearInterval(S), l(c(m, 1, x)), d(x));
+  };
+  i.zero(), l(c("zeroing"));
+  const S = setInterval(() => {
+    !u && performance.now() < a && l(c("zeroing"));
+  }, 300), M = i.addFrameListener((m) => {
+    if (r = m, h = performance.now(), performance.now() < a || m.calibrating) {
+      l(c("zeroing"));
+      return;
+    }
+    if (m.strength < 15) {
+      n = [], l(c("spot", 0));
+      return;
+    }
+    n.push(m), n = n.filter((w) => w.t > m.t - 1200);
+    const x = (w) => {
+      const L = n.map((F) => F.delta[w]).sort((F, T) => F - T);
+      return L[L.length >> 1];
+    }, v = [x(0), x(1), x(2)];
+    if (Math.max(...n.map((w) => Math.hypot(w.delta[0] - v[0], w.delta[1] - v[1], w.delta[2] - v[2]))) > Math.max(4, 0.12 * m.strength)) {
+      n = [m], l(c("spot", 0));
+      return;
+    }
+    const p = Math.min(1, (m.t - n[0].t) / 1e3);
+    if (l(c("spot", p)), p < 1) return;
+    if (o.push({ screen: i.toScreen(f(s)), delta: v }), s++, n = [], s < e.length) {
+      l(c("spot", 0));
+      return;
+    }
+    const b = H(o, i.screenSize(), i.pointsPerCm);
+    if (!b) return g("failed", null);
+    i.setMagnet(b), g("done", b);
+  });
+  return { promise: y, cancel: () => g("cancelled", null) };
+}
+function V(i, t = {}) {
+  return Q(
+    {
+      zero: () => i.zero(),
+      addFrameListener: (e) => i.addFrameListener(e),
+      setMagnet: (e) => i.setMagnet(e),
+      viewport: () => ({ x: innerWidth, y: innerHeight }),
+      toScreen: (e) => i.toScreen(e),
+      screenSize: () => {
+        const e = i.hello;
+        return e ? { x: e.screenDp[0], y: e.screenDp[1] } : { x: screen.width, y: screen.height };
+      },
+      // Android dp: 160 per inch.
+      pointsPerCm: 160 / 2.54
+    },
+    t
+  );
+}
+let Z = null;
+function A() {
+  return Z ?? (Z = new B());
+}
+function et() {
+  var e;
+  const i = A(), t = Y(
+    (o) => i.addStateListener(o),
+    () => {
+      var o, s;
+      return `${i.state}|${i.device}|${((o = i.hello) == null ? void 0 : o.grabStage) ?? ""}|${((s = i.hello) == null ? void 0 : s.face) ?? ""}`;
+    },
+    () => "idle||"
+  );
+  return {
+    bridge: i,
+    state: i.state,
+    device: i.device,
+    calibrated: ((e = i.hello) == null ? void 0 : e.grabStage) === 2,
+    connect: () => i.connect(),
+    key: t
+  };
+}
+function nt(i) {
+  const t = G(i);
+  t.current = i, P(() => A().addFrameListener((e) => t.current(e)), []);
+}
+function st() {
+  const [i, t] = O(A().frame);
+  return P(() => {
+    let e = 0, o = null;
+    const s = A().addFrameListener((n) => {
+      o = n, e || (e = requestAnimationFrame(() => {
+        e = 0, t(o);
+      }));
+    });
+    return () => {
+      s(), cancelAnimationFrame(e);
+    };
+  }, []), i;
+}
+function it(i) {
+  const t = G(i);
+  t.current = i, P(() => A().addGestureListener((e) => t.current(e)), []);
+}
+function ot(i, t = {}) {
+  const { selector: e = "[data-magnetic]", enabled: o = !0 } = t;
+  P(() => {
+    const s = i.current;
+    if (!s || !o || matchMedia("(prefers-reduced-motion: reduce)").matches) return;
+    const n = A(), r = new _();
+    r.screenCorner = 24, t.stiffness != null && (r.stiffness = t.stiffness), t.damping != null && (r.damping = t.damping), t.force != null && (r.force = t.force), t.reach != null && (r.reach = t.reach);
+    let h = [];
+    const a = () => {
+      h.forEach((f) => f.el.style.transform = ""), h = [...s.querySelectorAll(e)].filter((f) => f.getBoundingClientRect().width > 0).map((f, c) => {
+        getComputedStyle(f).display === "inline" && (f.style.display = "inline-block");
+        const l = f.getBoundingClientRect();
+        return {
+          id: String(c),
+          el: f,
+          box: { left: l.left + scrollX, top: l.top + scrollY, right: l.right + scrollX, bottom: l.bottom + scrollY },
+          corner: parseFloat(getComputedStyle(f).borderTopLeftRadius) || 6
+        };
+      }), r.parts.clear();
+    };
+    a();
+    const u = () => a();
+    addEventListener("resize", u);
+    let d = 0;
+    const y = () => {
+      var S;
+      const f = performance.now() / 1e3, c = n.offset();
+      for (const M of h)
+        r.setHome(M.id, {
+          left: M.box.left - scrollX + c.x,
+          top: M.box.top - scrollY + c.y,
+          right: M.box.right - scrollX + c.x,
+          bottom: M.box.bottom - scrollY + c.y
+        }, M.corner);
+      const l = n.frame, g = { left: c.x, top: c.y, right: c.x + innerWidth, bottom: c.y + innerHeight };
+      l ? r.step(l, f, g, ((S = n.hello) == null ? void 0 : S.face) ?? 1) : r.relax(f);
+      for (const M of h) {
+        const m = r.parts.get(M.id);
+        m && (M.el.style.transform = m.resting ? "" : `translate(${m.ox.toFixed(2)}px, ${m.oy.toFixed(2)}px) rotate(${m.angle.toFixed(4)}rad)`);
+      }
+      d = requestAnimationFrame(y);
+    };
+    return d = requestAnimationFrame(y), () => {
+      cancelAnimationFrame(d), removeEventListener("resize", u), h.forEach((f) => f.el.style.transform = "");
+    };
+  }, [i, e, o, t.stiffness, t.damping, t.force, t.reach]);
+}
+function rt({ open: i, onClose: t }) {
+  const [e, o] = O(null), s = G(t);
+  s.current = t;
+  const n = G(() => {
+  });
+  if (P(() => {
+    if (!i) return;
+    const u = V(A(), { onUpdate: o });
+    return n.current = u.cancel, u.promise.then((d) => {
+      var y;
+      return (y = s.current) == null ? void 0 : y.call(s, !!d);
+    }), () => u.cancel();
+  }, [i]), !i || !e || e.phase === "done" || e.phase === "cancelled") return null;
+  const r = e.phase === "zeroing" ? "Keep the magnet away for a moment…" : e.phase === "failed" ? "That didn't fit. Try again, holding the magnet still over each ring." : `Ring ${e.index + 1} of ${e.total}: hold the magnet 1–2 cm above it and keep it still.`, h = e.field == null ? "No readings from the bridge. Open Magnet Bridge and tap Start bridge." : `${e.field.toFixed(0)} µT${e.zeroing ? " · zeroing" : ""}`, a = e.spot;
+  return /* @__PURE__ */ X("div", { style: { position: "fixed", inset: 0, zIndex: 2147483e3, background: "rgba(0,0,0,0.94)", color: "#fff", font: "500 16px/24px system-ui, sans-serif", touchAction: "none" }, children: [
+    a && /* @__PURE__ */ $("div", { style: { position: "absolute", left: a.x, top: a.y, width: 72, height: 72, margin: -36, borderRadius: "50%", boxShadow: "inset 0 0 0 3px #fff" }, children: /* @__PURE__ */ $("i", { style: { position: "absolute", inset: 10, borderRadius: "50%", background: "#4f9cff", transform: `scale(${e.progress.toFixed(3)})` } }) }),
+    /* @__PURE__ */ $("p", { style: { position: "absolute", left: 16, right: 16, top: a ? a.y < innerHeight / 2 ? a.y + 64 : a.y - 120 : "40%", margin: 0, textAlign: "center" }, children: r }),
+    /* @__PURE__ */ $("p", { style: { position: "absolute", left: 16, right: 16, bottom: 88, margin: 0, textAlign: "center", font: "400 13px/18px system-ui, sans-serif", color: "#9a9a9a" }, children: h }),
+    /* @__PURE__ */ $("button", { type: "button", onClick: () => n.current(), style: { position: "absolute", left: "50%", bottom: 32, transform: "translateX(-50%)", height: 40, padding: "0 18px", border: 0, borderRadius: 999, background: "#2a2a2a", color: "#fff", font: "500 14px/1 system-ui, sans-serif" }, children: "Cancel" })
+  ] });
+}
+function at(i = A()) {
+  let t = !1, e = { x: 0, y: 0 };
+  const o = i.offset.bind(i);
+  i.offset = () => ({ x: 0, y: 0 });
+  const s = (a) => {
+    t = !0, e = { x: a.clientX, y: a.clientY };
+  }, n = (a) => {
+    e = { x: a.clientX, y: a.clientY };
+  }, r = () => {
+    t = !1;
+  };
+  addEventListener("pointerdown", s), addEventListener("pointermove", n), addEventListener("pointerup", r);
+  const h = window.setInterval(() => {
+    i.frame = {
+      t: performance.now(),
+      pos: t ? e : null,
+      spread: 20,
+      height: null,
+      presence: 1,
+      pull: t ? 0.8 : 0,
+      strength: t ? 80 : 0,
+      delta: t ? [0, 0, -40] : [0, 0, 0],
+      tooClose: !1,
+      calibrating: !1
+    };
+  }, 20);
+  return () => {
+    clearInterval(h), removeEventListener("pointerdown", s), removeEventListener("pointermove", n), removeEventListener("pointerup", r), i.offset = o;
+  };
+}
+export {
+  K as DEFAULT_SPOTS,
+  B as MagnetBridge,
+  rt as MagnetCalibration,
+  _ as MagneticField,
+  W as Particle,
+  V as calibrate,
+  H as fitCalibration,
+  A as getMagnetBridge,
+  Q as runCalibration,
+  at as simulateMagnetWithPointer,
+  st as useMagnet,
+  et as useMagnetBridge,
+  nt as useMagnetFrame,
+  it as useMagnetGestures,
+  ot as useMagneticPull
+};

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "magnetkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Magnetic UI for React on the web: a real magnet near an Android phone pulls your interface, through the Magnet Bridge app that runs the magnet model on the phone.",
+  "type": "module",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.es.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.cjs.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jakubantalik/Libraries.dev.git",
+    "directory": "packages/magnetkit-web"
+  },
+  "homepage": "https://libraries.dev/magnetic",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.7.0",
+    "react-dom": "^18.2.0",
+    "@types/react-dom": "^18.2.0"
+  },
+  "keywords": [
+    "react",
+    "magnet",
+    "magnetometer",
+    "magnetic ui",
+    "android",
+    "physics",
+    "gesture"
+  ],
+  "author": "Jakub Antalik",
+  "license": "MIT"
+}