@liiift-studio/magnettype 1.0.0

package/README.md

@@ -0,0 +1,196 @@
+# magnetType
+
+CSS `font-variation-settings` applies a single value to the whole element — there is no native way to drive axis values per word from cursor proximity, or to selectively widen visually confusable characters for legibility. magnetType adds both.
+
+**[magnettype.com](https://magnettype.com)** · [npm](https://www.npmjs.com/package/@liiift-studio/magnettype) · [GitHub](https://github.com/Liiift-Studio/MagnetType)
+
+TypeScript · Zero dependencies · React + Vanilla JS
+
+---
+
+## Install
+
+```bash
+npm install @liiift-studio/magnettype
+```
+
+---
+
+## Usage
+
+> **Next.js App Router:** this library uses browser APIs. Add `"use client"` to any component file that imports from it.
+
+> **Variable font required:** magnetType sets `font-variation-settings` per word or per character. The target font must support the axes you specify (e.g. a font with a `wght` axis for weight-based field effects, or a `wdth` axis for legibility mode). The effect is invisible with fonts that do not have variable axis support.
+
+### React component — field mode
+
+```tsx
+import { MagnetTypeText } from '@liiift-studio/magnettype'
+
+<MagnetTypeText
+  mode="field"
+  axes={{ wght: [300, 700] }}
+  radius={150}
+  falloff="quadratic"
+  magnetMode="attract"
+>
+  Your paragraph text here...
+</MagnetTypeText>
+```
+
+### React hook — field mode
+
+```tsx
+import { useMagnetType } from '@liiift-studio/magnettype'
+
+// Inside a React component:
+const ref = useMagnetType({ mode: 'field', axes: { wght: [300, 700] }, radius: 150 })
+return <p ref={ref}>{children}</p>
+```
+
+The hook starts the cursor-proximity rAF loop on mount and tears it down cleanly on unmount. In field mode, no `ResizeObserver` is needed — the loop reads live `getBoundingClientRect` positions on every frame. After fonts load (`document.fonts.ready`), the hook re-runs to ensure measurements are taken on the loaded font.
+
+### React component — legibility mode
+
+```tsx
+import { MagnetTypeText } from '@liiift-studio/magnettype'
+
+<MagnetTypeText mode="legibility" wdthBoost={8}>
+  Visually confusable characters like il1I and 0O are subtly widened.
+</MagnetTypeText>
+```
+
+### Vanilla JS — field mode
+
+```ts
+import { startMagnetType, removeMagnetType, getCleanHTML } from '@liiift-studio/magnettype'
+
+const el = document.querySelector('p')
+const original = getCleanHTML(el)
+const opts = { mode: 'field', axes: { wght: [300, 700] }, radius: 150 }
+
+let stop
+
+function run() {
+  if (stop) stop()
+  stop = startMagnetType(el, original, opts)
+}
+
+document.fonts.ready.then(run)
+
+// Later — cancel the loop and restore original markup:
+// stop()
+// removeMagnetType(el, original)
+```
+
+### Vanilla JS — legibility mode
+
+```ts
+import { applyMagnetType, removeMagnetType, getCleanHTML } from '@liiift-studio/magnettype'
+
+const el = document.querySelector('p')
+const original = getCleanHTML(el)
+const opts = { mode: 'legibility', wdthBoost: 8 }
+
+function run() {
+  applyMagnetType(el, original, opts)
+}
+
+run()
+document.fonts.ready.then(run)
+
+const ro = new ResizeObserver(() => run())
+ro.observe(el)
+
+// Later — disconnect and restore original markup:
+// ro.disconnect()
+// removeMagnetType(el, original)
+```
+
+### TypeScript
+
+```ts
+import type { MagnetTypeOptions, FalloffType, MagnetModeType } from '@liiift-studio/magnettype'
+
+const fieldOpts: MagnetTypeOptions = {
+  mode: 'field',
+  axes: { wght: [300, 700], wdth: [90, 110] },
+  radius: 120,
+  falloff: 'quadratic' as FalloffType,
+  magnetMode: 'attract' as MagnetModeType,
+}
+
+const legibilityOpts: MagnetTypeOptions = {
+  mode: 'legibility',
+  wdthBoost: 6,
+}
+```
+
+---
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `mode` | `'field'` | `'field'` — cursor proximity drives per-word `font-variation-settings` via a continuous rAF loop. `'legibility'` — static per-character `wdth` boost applied to visually confusable characters; no cursor interaction needed |
+| `axes` | `{ wght: [300, 500] }` | *(field mode only)* Map of axis tag → `[restValue, peakValue]`. `restValue` is applied when the cursor is beyond the radius; `peakValue` when the cursor is directly over the word. Multiple axes are supported simultaneously |
+| `radius` | `120` | *(field mode only)* Pixel radius over which the field effect fades. Words with their centre beyond this distance from the cursor receive `restValue` |
+| `falloff` | `'quadratic'` | *(field mode only)* Falloff curve. `'linear'` — strength decreases linearly with distance. `'quadratic'` — strength decreases as distance², giving a tighter hot zone and a sharper peak feel |
+| `magnetMode` | `'attract'` | *(field mode only)* `'attract'` — words near the cursor approach `peakValue`. `'repel'` — words near the cursor stay at `restValue`; words farther away approach `peakValue` |
+| `wdthBoost` | `6` | *(legibility mode only)* `wdth` axis units added to confusable characters, scaled by risk level. Risk 3 characters (`i l 1 I`) receive the full boost; risk 2 characters (`r 0 O`) receive ⅔; risk 1 characters (`n m o b d p q c e`) receive ⅓ |
+| `as` | `'p'` | HTML element to render, e.g. `'h1'`, `'div'`, `'span'`. Accepts any valid React element type. *(React component only)* |
+
+---
+
+## How it works
+
+### Field mode
+
+On activation, magnetType wraps each word in the element in an `mt-word` span. A `mousemove` listener records the cursor's `clientX`/`clientY` coordinates, and a `requestAnimationFrame` loop runs continuously while the cursor is inside the element. Each frame, the loop batch-reads every word span's `getBoundingClientRect`, computes the Euclidean distance from the cursor to each word's centre, and maps that distance through the falloff formula to a normalised strength value in `[0, 1]`:
+
+```
+normalised = max(0, 1 − distance / radius)
+strength   = normalised² (quadratic) or normalised (linear)
+```
+
+Each word's `font-variation-settings` is then set to the interpolated axis value between `restValue` and `peakValue`, with `attract` mode mapping `strength=1` to `peakValue` and `repel` mode inverting that relationship. Reads are batched before writes on every frame to avoid layout thrashing. When the cursor leaves the element, the loop fires one final frame to reset all words to `restValue`, then idles.
+
+The base `fontVariationSettings` string is read from the computed style of the element once at startup, and each per-word override patches only the affected axes — all parent-defined axes are preserved.
+
+### Legibility mode
+
+magnetType scans all text nodes in the element using recursive `childNodes` traversal and checks each character against a built-in confusable character table. Confusable characters are grouped into three risk levels: `il1I` (risk 3, high confusion), `r 0 O` and related pairs (risk 2), and `n m o b d p q c e` (risk 1, low confusion). Each confusable character is wrapped in an `mt-char` span with a `wdth` axis boost proportional to its risk level — making similar-looking characters slightly wider and more distinct. Non-confusable characters pass through as plain text nodes, with adjacent non-confusable characters consolidated into single text nodes to keep the DOM lean.
+
+### No layout shift
+
+In field mode, the rAF loop drives only `font-variation-settings` values on per-word spans — it does not change element widths, margins, padding, or position. If you use only a `wght` axis, advance widths are not affected and no reflow occurs. If you include a `wdth` axis, character advance widths will change, which may cause lines to reflow. To prevent this, consider constraining axis ranges or combining with a `scaleX` transform on the container.
+
+In legibility mode, the `wdth` axis boost widens individual confusable characters, which shifts surrounding characters slightly. This is intentional — the point is to make the characters physically wider and more distinct. The shift is small by default (`wdthBoost: 6`) and does not cause line breaks to change.
+
+### `prefers-reduced-motion`
+
+Field mode respects `prefers-reduced-motion: reduce`. If the media query matches at the time `startMagnetType` is called, the function returns immediately without wrapping words or starting the rAF loop, and returns a no-op stop function. Legibility mode is a static DOM transformation and is not affected by this preference.
+
+---
+
+## Dev notes
+
+### `next` in root devDependencies
+
+`package.json` at the repo root lists `next` as a devDependency. This is a **Vercel detection workaround** — not a real dependency of the npm package. Vercel's build system inspects the root `package.json` to detect the framework; without `next` present it falls back to a static build and skips the Next.js pipeline, breaking the `/site` subdirectory deploy.
+
+The package itself has zero runtime dependencies. Do not remove this entry.
+
+---
+
+## Future improvements
+
+- **Touch support** — `touchmove` events for mobile field mode; currently `mousemove`-only, so the effect is desktop-exclusive
+- **Smooth transition on stop** — animate axis values back to `restValue` over a short duration when the cursor leaves, rather than snapping on the next rAF tick
+- **Custom confusable table** — allow callers to pass their own `Record<string, number>` to override or extend the built-in character risk map for language- or font-specific tuning
+- **Axis clamping** — optional per-axis min/max clamp to prevent axis values from exceeding a font's supported range, avoiding undefined browser rendering behaviour
+- **SSR hydration** — pre-render legibility mode markup on the server so boosted characters are present from first paint without a client-side flash
+
+---
+
+Current version: v0.0.1

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const x=require("react"),I=require("react/jsx-runtime"),j={i:3,l:3,1:3,I:3,r:2,n:1,m:1,0:2,O:2,o:1,b:1,d:1,p:1,q:1,c:1,e:1},S={word:"mt-word",char:"mt-char",probe:"mt-probe"},N={axes:{wght:[300,500]},radius:120,falloff:"quadratic",magnetMode:"attract",wdthBoost:6};function F(e,n=[]){return e.nodeType===Node.TEXT_NODE?n.push(e):e.childNodes.forEach(o=>F(o,n)),n}function H(e,n,o){if(!e||e==="normal")return`"${n}" ${o}`;const r=new RegExp(`(["'])${n}\\1\\s+[\\d.eE+-]+`),t=`"${n}" ${o}`;return r.test(e)?e.replace(r,t):`${e}, ${t}`}function B(e,n){let o=e;for(const[r,t]of Object.entries(n))o=H(o,r,t);return o}function V(e){const n=e.cloneNode(!0),o=n.querySelectorAll(`.${S.word}, .${S.char}`);return Array.from(o).reverse().forEach(t=>{const l=t.parentNode;if(l){for(;t.firstChild;)l.insertBefore(t.firstChild,t);l.removeChild(t)}}),n.innerHTML}function X(e,n){e.innerHTML=n}function k(e,n,o={}){if(typeof window>"u")return;const r=window.scrollY,t=o.wdthBoost??N.wdthBoost;e.innerHTML=n;const l=F(e),a=getComputedStyle(e).fontVariationSettings;for(const h of l){const y=h.textContent??"";if(!y||!y.split("").some(m=>m in j))continue;const M=document.createDocumentFragment();for(const m of y){const p=j[m];if(p===void 0){const s=M.lastChild;s&&s.nodeType===Node.TEXT_NODE?s.textContent+=m:M.appendChild(document.createTextNode(m))}else{const s=t*(p/3),c=document.createElement("span");c.className=S.char;const f=a.match(/"wdth"\s+([\d.eE+-]+)/),E=(f?parseFloat(f[1]):100)+s;c.style.fontVariationSettings=H(a,"wdth",E),c.textContent=m,M.appendChild(c)}}h.parentNode.replaceChild(M,h)}requestAnimationFrame(()=>{typeof window<"u"&&Math.abs(window.scrollY-r)>2&&window.scrollTo({top:r,behavior:"instant"})})}function W(e,n,o={}){if(typeof window>"u")return()=>{};if(window.matchMedia("(prefers-reduced-motion: reduce)").matches)return e.innerHTML=n,()=>{};const r=o.axes??N.axes,t=o.radius??N.radius,l=o.falloff??N.falloff,a=o.magnetMode??N.magnetMode,h=window.scrollY;e.innerHTML=n;const y=F(e),u=[];for(const i of y){const d=i.textContent??"";if(!d.trim())continue;const w=d.split(/(\S+)/),T=document.createDocumentFragment();for(let g=0;g<w.length;g+=2){const R=w[g],b=w[g+1];if(!b)continue;const q=w[g+3]===void 0?w[g+2]??"":"",v=document.createElement("span");v.className=S.word,v.textContent=R+b+q,T.appendChild(v),u.push(v)}i.parentNode.replaceChild(T,i)}if(requestAnimationFrame(()=>{typeof window<"u"&&Math.abs(window.scrollY-h)>2&&window.scrollTo({top:h,behavior:"instant"})}),u.length===0)return()=>{};const M=getComputedStyle(e).fontVariationSettings,m=B(M,Object.fromEntries(Object.entries(r).map(([i,[d]])=>[i,d])));u.forEach(i=>{i.style.fontVariationSettings=m});let p=-9999,s=-9999,c=!1,f=0,C=!0;function E(i,d){const[w,T]=r[i]??[300,500],g=a==="repel"?1-d:d;return w+(T-w)*g}function L(){if(!C)return;if(!c){u.forEach(d=>{d.style.fontVariationSettings=m}),f=0;return}const i=u.map(d=>d.getBoundingClientRect());u.forEach((d,w)=>{const T=i[w],g=T.left+T.width/2,R=T.top+T.height/2,b=Math.sqrt((p-g)**2+(s-R)**2),A=Math.max(0,1-b/t),q=l==="quadratic"?A*A:A,v={};for(const $ of Object.keys(r))v[$]=E($,q);d.style.fontVariationSettings=B(M,v)}),f=requestAnimationFrame(L)}function O(i){p=i.clientX,s=i.clientY,c||(c=!0),f===0&&(f=requestAnimationFrame(L))}function Y(){c=!1,f===0&&(f=requestAnimationFrame(L))}return e.addEventListener("mousemove",O),e.addEventListener("mouseleave",Y),()=>{C=!1,cancelAnimationFrame(f),e.removeEventListener("mousemove",O),e.removeEventListener("mouseleave",Y),e.innerHTML=n}}function _(e){const n=x.useRef(null),o=x.useRef(null),r=x.useRef(e);r.current=e;const t=x.useRef(null),l=e.mode??"field",{axes:a,radius:h,falloff:y,magnetMode:u,wdthBoost:M}=e,m=a?JSON.stringify(a):void 0,p=x.useCallback(()=>{const s=n.current;if(!s)return;o.current===null&&(o.current=V(s)),t.current&&(t.current(),t.current=null),(r.current.mode??"field")==="field"?t.current=W(s,o.current,r.current):k(s,o.current,r.current)},[l,m,h,y,u,M]);return x.useLayoutEffect(()=>{if(p(),typeof ResizeObserver>"u")return()=>{t.current&&(t.current(),t.current=null)};if((r.current.mode??"field")==="field")return()=>{t.current&&(t.current(),t.current=null)};let s=0,c=0;const f=new ResizeObserver(C=>{const E=Math.round(C[0].contentRect.width);E!==s&&(s=E,cancelAnimationFrame(c),c=requestAnimationFrame(p))});return f.observe(n.current),()=>{f.disconnect(),cancelAnimationFrame(c),t.current&&(t.current(),t.current=null)}},[p]),x.useEffect(()=>{document.fonts.ready.then(p)},[p]),n}const D=x.forwardRef(function({children:n,as:o="p",className:r,style:t,...l},a){const h=_(l),y=x.useCallback(u=>{h.current=u,typeof a=="function"?a(u):a&&(a.current=u)},[a]);return I.jsx(o,{ref:y,className:r,style:t,children:n})});D.displayName="MagnetTypeText";exports.MAGNET_TYPE_CLASSES=S;exports.MagnetTypeText=D;exports.applyMagnetType=k;exports.getCleanHTML=V;exports.removeMagnetType=X;exports.startMagnetType=W;exports.useMagnetType=_;

package/dist/index.d.ts

@@ -0,0 +1,142 @@
+import { default as default_2 } from 'react';
+import { RefObject } from 'react';
+
+/**
+ * Apply per-character wdth boost to visually confusable characters (legibility mode).
+ *
+ * Wraps each character in a span with a boosted wdth axis value proportional to
+ * the character's confusion risk level. Non-confusable characters are left unwrapped.
+ *
+ * @param element      - Target element (must be in the live DOM and visible)
+ * @param originalHTML - Clean HTML snapshot from getCleanHTML()
+ * @param options      - MagnetTypeOptions; only wdthBoost is used here
+ */
+export declare function applyMagnetType(element: HTMLElement, originalHTML: string, options?: MagnetTypeOptions): void;
+
+/** Falloff curve for the cursor proximity field */
+export declare type FalloffType = 'linear' | 'quadratic';
+
+/**
+ * Returns the innerHTML of an element with all magnetType injected markup removed,
+ * unwrapping their children in place. Safe to call multiple times — idempotent.
+ */
+export declare function getCleanHTML(el: HTMLElement): string;
+
+/** CSS class names injected by magnetType — use these to target generated markup */
+export declare const MAGNET_TYPE_CLASSES: {
+    /** Applied to each word span in field mode */
+    readonly word: "mt-word";
+    /** Applied to each character span in legibility mode */
+    readonly char: "mt-char";
+    /** Applied to measurement probe spans (never in final output) */
+    readonly probe: "mt-probe";
+};
+
+/** Whether cursor proximity attracts toward peak or repels toward rest */
+export declare type MagnetModeType = 'attract' | 'repel';
+
+/** Which mode magnetType operates in */
+export declare type MagnetTypeModeType = 'field' | 'legibility';
+
+/**
+ * Options for the magnetType effect.
+ *
+ * Two modes share this options type:
+ * - 'field'      — cursor proximity drives per-word variable font axis values
+ * - 'legibility' — per-character wdth boost for visually confusable characters
+ */
+export declare interface MagnetTypeOptions {
+    /**
+     * Operating mode. Default: 'field'
+     *
+     * - **'field'** — cursor proximity drives per-word font-variation-settings.
+     * - **'legibility'** — per-character wdth boost for confusable characters; no cursor needed.
+     */
+    mode?: MagnetTypeModeType;
+    /**
+     * Map of axis tag → [restValue, peakValue].
+     * restValue is applied at full distance; peakValue when cursor is directly over the word.
+     * Default: { wght: [300, 500] }
+     */
+    axes?: Record<string, [number, number]>;
+    /**
+     * Pixel radius over which the field effect fades.
+     * Words beyond this distance receive restValue. Default: 120
+     */
+    radius?: number;
+    /**
+     * Falloff curve. Default: 'quadratic'
+     *
+     * - **'linear'** — strength decreases linearly with distance
+     * - **'quadratic'** — strength decreases as distance², giving a tighter hot zone
+     */
+    falloff?: FalloffType;
+    /**
+     * Attraction or repulsion mode. Default: 'attract'
+     *
+     * - **'attract'** — words near cursor approach peakValue
+     * - **'repel'** — words near cursor stay at restValue; far words approach peakValue
+     */
+    magnetMode?: MagnetModeType;
+    /**
+     * wdth axis units to add to confusable characters. Default: 6
+     *
+     * Risk 1 characters receive wdthBoost × (1/3).
+     * Risk 2 characters receive wdthBoost × (2/3).
+     * Risk 3 characters receive wdthBoost × (3/3) = full boost.
+     */
+    wdthBoost?: number;
+}
+
+/**
+ * Drop-in component that applies the magnetType effect to its children.
+ * Forwards the ref to the root element while also attaching the internal hook ref.
+ */
+export declare const MagnetTypeText: default_2.ForwardRefExoticComponent<MagnetTypeTextProps & default_2.RefAttributes<HTMLElement>>;
+
+/** Props for MagnetTypeText — extends all MagnetTypeOptions */
+declare interface MagnetTypeTextProps extends MagnetTypeOptions {
+    children: default_2.ReactNode;
+    /** HTML element to render. Default: 'p' */
+    as?: default_2.ElementType;
+    className?: string;
+    style?: default_2.CSSProperties;
+}
+
+/**
+ * Remove magnetType markup and restore the element to its original HTML.
+ *
+ * @param element      - The element that was previously modified
+ * @param originalHTML - The snapshot passed to applyMagnetType
+ */
+export declare function removeMagnetType(element: HTMLElement, originalHTML: string): void;
+
+/**
+ * Start the cursor-field effect on an element.
+ *
+ * Wraps each word in a span, then listens for mousemove events to drive per-word
+ * font-variation-settings based on cursor distance. Uses a requestAnimationFrame
+ * loop for smooth axis interpolation. Resets all words to restValue on mouseleave.
+ *
+ * @param element      - Target element (must be in the live DOM and visible)
+ * @param originalHTML - Clean HTML snapshot from getCleanHTML()
+ * @param options      - MagnetTypeOptions; axes, radius, falloff, magnetMode are used
+ * @returns            - A stop function. Call it to cancel the rAF loop and restore markup.
+ */
+export declare function startMagnetType(element: HTMLElement, originalHTML: string, options?: MagnetTypeOptions): () => void;
+
+/**
+ * React hook that applies the magnetType effect to a ref'd element.
+ *
+ * For mode: 'field' — starts the cursor proximity rAF loop via startMagnetType.
+ * The stop function is called on unmount and when options change.
+ * No ResizeObserver needed — the rAF loop reads live getBoundingClientRect each frame.
+ *
+ * For mode: 'legibility' — applies the static per-character wdth boost via applyMagnetType.
+ * Re-runs on container width changes via ResizeObserver, and after fonts load.
+ *
+ * Defaults to 'field' mode if mode is undefined.
+ */
+export declare function useMagnetType(options: MagnetTypeOptions): RefObject<HTMLElement | null>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,208 @@
+import { useRef as A, useCallback as j, useLayoutEffect as W, useEffect as k, forwardRef as D } from "react";
+import { jsx as I } from "react/jsx-runtime";
+const B = {
+  i: 3,
+  l: 3,
+  1: 3,
+  I: 3,
+  // il1I confusion
+  r: 2,
+  n: 1,
+  m: 1,
+  // rn/m similarity
+  0: 2,
+  O: 2,
+  o: 1,
+  // 0/O similarity
+  b: 1,
+  d: 1,
+  p: 1,
+  q: 1,
+  // mirrored pairs
+  c: 1,
+  e: 1
+  // similar bowls
+}, L = {
+  /** Applied to each word span in field mode */
+  word: "mt-word",
+  /** Applied to each character span in legibility mode */
+  char: "mt-char",
+  /** Applied to measurement probe spans (never in final output) */
+  probe: "mt-probe"
+}, C = {
+  axes: { wght: [300, 500] },
+  radius: 120,
+  falloff: "quadratic",
+  magnetMode: "attract",
+  wdthBoost: 6
+};
+function q(e, n = []) {
+  return e.nodeType === Node.TEXT_NODE ? n.push(e) : e.childNodes.forEach((o) => q(o, n)), n;
+}
+function H(e, n, o) {
+  if (!e || e === "normal") return `"${n}" ${o}`;
+  const r = new RegExp(`(["'])${n}\\1\\s+[\\d.eE+-]+`), t = `"${n}" ${o}`;
+  return r.test(e) ? e.replace(r, t) : `${e}, ${t}`;
+}
+function V(e, n) {
+  let o = e;
+  for (const [r, t] of Object.entries(n))
+    o = H(o, r, t);
+  return o;
+}
+function X(e) {
+  const n = e.cloneNode(!0), o = n.querySelectorAll(
+    `.${L.word}, .${L.char}`
+  );
+  return Array.from(o).reverse().forEach((t) => {
+    const l = t.parentNode;
+    if (l) {
+      for (; t.firstChild; ) l.insertBefore(t.firstChild, t);
+      l.removeChild(t);
+    }
+  }), n.innerHTML;
+}
+function P(e, n) {
+  e.innerHTML = n;
+}
+function _(e, n, o = {}) {
+  if (typeof window > "u") return;
+  const r = window.scrollY, t = o.wdthBoost ?? C.wdthBoost;
+  e.innerHTML = n;
+  const l = q(e), a = getComputedStyle(e).fontVariationSettings;
+  for (const h of l) {
+    const y = h.textContent ?? "";
+    if (!y || !y.split("").some((m) => m in B)) continue;
+    const M = document.createDocumentFragment();
+    for (const m of y) {
+      const p = B[m];
+      if (p === void 0) {
+        const s = M.lastChild;
+        s && s.nodeType === Node.TEXT_NODE ? s.textContent += m : M.appendChild(document.createTextNode(m));
+      } else {
+        const s = t * (p / 3), c = document.createElement("span");
+        c.className = L.char;
+        const u = a.match(/"wdth"\s+([\d.eE+-]+)/), v = (u ? parseFloat(u[1]) : 100) + s;
+        c.style.fontVariationSettings = H(a, "wdth", v), c.textContent = m, M.appendChild(c);
+      }
+    }
+    h.parentNode.replaceChild(M, h);
+  }
+  requestAnimationFrame(() => {
+    typeof window < "u" && Math.abs(window.scrollY - r) > 2 && window.scrollTo({ top: r, behavior: "instant" });
+  });
+}
+function z(e, n, o = {}) {
+  if (typeof window > "u") return () => {
+  };
+  if (window.matchMedia("(prefers-reduced-motion: reduce)").matches)
+    return e.innerHTML = n, () => {
+    };
+  const r = o.axes ?? C.axes, t = o.radius ?? C.radius, l = o.falloff ?? C.falloff, a = o.magnetMode ?? C.magnetMode, h = window.scrollY;
+  e.innerHTML = n;
+  const y = q(e), f = [];
+  for (const i of y) {
+    const d = i.textContent ?? "";
+    if (!d.trim()) continue;
+    const w = d.split(/(\S+)/), x = document.createDocumentFragment();
+    for (let g = 0; g < w.length; g += 2) {
+      const F = w[g], N = w[g + 1];
+      if (!N) continue;
+      const R = w[g + 3] === void 0 ? w[g + 2] ?? "" : "", T = document.createElement("span");
+      T.className = L.word, T.textContent = F + N + R, x.appendChild(T), f.push(T);
+    }
+    i.parentNode.replaceChild(x, i);
+  }
+  if (requestAnimationFrame(() => {
+    typeof window < "u" && Math.abs(window.scrollY - h) > 2 && window.scrollTo({ top: h, behavior: "instant" });
+  }), f.length === 0) return () => {
+  };
+  const M = getComputedStyle(e).fontVariationSettings, m = V(
+    M,
+    Object.fromEntries(Object.entries(r).map(([i, [d]]) => [i, d]))
+  );
+  f.forEach((i) => {
+    i.style.fontVariationSettings = m;
+  });
+  let p = -9999, s = -9999, c = !1, u = 0, E = !0;
+  function v(i, d) {
+    const [w, x] = r[i] ?? [300, 500], g = a === "repel" ? 1 - d : d;
+    return w + (x - w) * g;
+  }
+  function S() {
+    if (!E) return;
+    if (!c) {
+      f.forEach((d) => {
+        d.style.fontVariationSettings = m;
+      }), u = 0;
+      return;
+    }
+    const i = f.map((d) => d.getBoundingClientRect());
+    f.forEach((d, w) => {
+      const x = i[w], g = x.left + x.width / 2, F = x.top + x.height / 2, N = Math.sqrt((p - g) ** 2 + (s - F) ** 2), b = Math.max(0, 1 - N / t), R = l === "quadratic" ? b * b : b, T = {};
+      for (const $ of Object.keys(r))
+        T[$] = v($, R);
+      d.style.fontVariationSettings = V(M, T);
+    }), u = requestAnimationFrame(S);
+  }
+  function O(i) {
+    p = i.clientX, s = i.clientY, c || (c = !0), u === 0 && (u = requestAnimationFrame(S));
+  }
+  function Y() {
+    c = !1, u === 0 && (u = requestAnimationFrame(S));
+  }
+  return e.addEventListener("mousemove", O), e.addEventListener("mouseleave", Y), () => {
+    E = !1, cancelAnimationFrame(u), e.removeEventListener("mousemove", O), e.removeEventListener("mouseleave", Y), e.innerHTML = n;
+  };
+}
+function U(e) {
+  const n = A(null), o = A(null), r = A(e);
+  r.current = e;
+  const t = A(null), l = e.mode ?? "field", { axes: a, radius: h, falloff: y, magnetMode: f, wdthBoost: M } = e, m = a ? JSON.stringify(a) : void 0, p = j(() => {
+    const s = n.current;
+    if (!s) return;
+    o.current === null && (o.current = X(s)), t.current && (t.current(), t.current = null), (r.current.mode ?? "field") === "field" ? t.current = z(s, o.current, r.current) : _(s, o.current, r.current);
+  }, [l, m, h, y, f, M]);
+  return W(() => {
+    if (p(), typeof ResizeObserver > "u")
+      return () => {
+        t.current && (t.current(), t.current = null);
+      };
+    if ((r.current.mode ?? "field") === "field")
+      return () => {
+        t.current && (t.current(), t.current = null);
+      };
+    let s = 0, c = 0;
+    const u = new ResizeObserver((E) => {
+      const v = Math.round(E[0].contentRect.width);
+      v !== s && (s = v, cancelAnimationFrame(c), c = requestAnimationFrame(p));
+    });
+    return u.observe(n.current), () => {
+      u.disconnect(), cancelAnimationFrame(c), t.current && (t.current(), t.current = null);
+    };
+  }, [p]), k(() => {
+    document.fonts.ready.then(p);
+  }, [p]), n;
+}
+const G = D(
+  function({ children: n, as: o = "p", className: r, style: t, ...l }, a) {
+    const h = U(l), y = j(
+      (f) => {
+        h.current = f, typeof a == "function" ? a(f) : a && (a.current = f);
+      },
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [a]
+    );
+    return /* @__PURE__ */ I(o, { ref: y, className: r, style: t, children: n });
+  }
+);
+G.displayName = "MagnetTypeText";
+export {
+  L as MAGNET_TYPE_CLASSES,
+  G as MagnetTypeText,
+  _ as applyMagnetType,
+  X as getCleanHTML,
+  P as removeMagnetType,
+  z as startMagnetType,
+  U as useMagnetType
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+	"name": "@liiift-studio/magnettype",
+	"version": "1.0.0",
+	"description": "Cursor-field per-word variable font axis variation and per-character legibility mode",
+	"type": "module",
+	"main": "dist/index.cjs",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "vite build",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"lint": "tsc --noEmit",
+		"prepublishOnly": "npm run test && npm run build"
+	},
+	"peerDependencies": {
+		"react": ">=17",
+		"react-dom": ">=17"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@types/react": "^19.0.0",
+		"@vitejs/plugin-react": "^4.0.0",
+		"happy-dom": "^12.0.0",
+		"next": "16.2.2",
+		"react": "^19.0.0",
+		"typescript": "^5.0.0",
+		"vite": "^6.0.0",
+		"vite-plugin-dts": "^4.0.0",
+		"vitest": "^3.0.0"
+	},
+	"keywords": [
+		"typography",
+		"typographic",
+		"variable-font",
+		"font-variation-settings",
+		"cursor",
+		"mouse",
+		"proximity",
+		"field",
+		"legibility",
+		"wdth",
+		"wght",
+		"zero-dependencies",
+		"react",
+		"typescript",
+		"css"
+	],
+	"author": "Quinn Keaveney <quinn@liiift.studio>",
+	"license": "MIT",
+	"homepage": "https://magnettype.com",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Liiift-Studio/MagnetType.git"
+	},
+	"bugs": {
+		"url": "https://github.com/Liiift-Studio/MagnetType/issues"
+	},
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}