@overpunch/opszstepper 1.0.18

package/README.md

@@ -0,0 +1,212 @@
+# opszStepper
+
+[![npm](https://img.shields.io/npm/v/%40overpunch%2Fopszstepper.svg)](https://www.npmjs.com/package/@overpunch/opszstepper) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![part of liiift type-tools](https://img.shields.io/badge/liiift-type--tools-blueviolet)](https://github.com/over-punch/type-tools)
+
+`font-optical-sizing: auto` only works for variable fonts with an `opsz` axis. opszStepper solves the other case: professional typeface families that ship separate font files for each optical size cut (Micro, Text, Display) with no axis at all. It automatically swaps the correct cut onto an element as its `font-size` changes.
+
+**[opszstepper.com](https://opszstepper.com)** · [npm](https://www.npmjs.com/package/@overpunch/opszstepper) · [GitHub](https://github.com/over-punch/opszStepper)
+
+TypeScript · Zero dependencies · React + Vanilla JS
+
+![opszStepper applies the Micro, Text, and Display cuts of Cormorant to the word "Typography" at 15px, 24px, and 60px — each size gets the cut drawn for it](https://raw.githubusercontent.com/over-punch/opszStepper/main/assets/hero.png?v=1)
+
+---
+
+## Install
+
+```bash
+npm install @overpunch/opszstepper
+```
+
+---
+
+## Usage
+
+> **Next.js App Router:** this library uses browser APIs. Add `"use client"` to any component file that imports from it.
+
+### What are optical cuts?
+
+Many professional editorial typefaces ship as a family of separate font files — each drawn specifically for a different size range. Halyard has Halyard Micro (captions and footnotes), Halyard Text (body), and Halyard Display (headlines). Tiempos has Tiempos Fine, Tiempos Text, and Tiempos Headline. Each cut has different contrast, spacing, and stroke weight tuned for its intended size. CSS has no mechanism to switch between them automatically — `font-optical-sizing: auto` only controls the `opsz` axis of a single variable font file. opszStepper fills that gap.
+
+Scaling one cut to every size is the problem opszStepper avoids. On the left, a single Display cut is used at all sizes — fine when large, but its high contrast and tight spacing turn spindly and fragile when shrunk. On the right, opszStepper swaps in the cut drawn for each size:
+
+![Comparison: the left column scales a single Display cut to small, medium, and large sizes, where it reads thin and fragile when small; the right column shows opszStepper swapping to the Micro, Text, and Display cuts so each size is legible](https://raw.githubusercontent.com/over-punch/opszStepper/main/assets/compare.png?v=1)
+
+### Two modes: family hot-swap or `opsz` axis
+
+opszStepper covers both ways type families ship optical sizes:
+
+1. **Multi-family hot-swap** *(the primary case)* — separate font files per cut (Halyard Micro / Text / Display). Give each cut a different `family`; opszStepper sets `font-family` to the matching cut as `font-size` crosses each threshold. Every example below uses this mode.
+2. **Single variable font, `opsz` axis** — one variable font with an `opsz` axis (Fraunces, Recursive, Amstelvar). Use the *same* `family` in every cut and add an `opszValue` per cut; opszStepper writes `font-variation-settings: "opsz" <value>` instead of swapping files. Optional `opszMin`/`opszMax` clamp the value to the font's fvar range:
+
+```ts
+cuts: [
+  { family: 'Fraunces, serif', maxSize: 13,              opszValue: 9,  opszMin: 9, opszMax: 144 },
+  { family: 'Fraunces, serif', minSize: 13, maxSize: 28, opszValue: 24, opszMin: 9, opszMax: 144 },
+  { family: 'Fraunces, serif', minSize: 28,              opszValue: 72, opszMin: 9, opszMax: 144 },
+]
+```
+
+This steps the axis at discrete thresholds with hysteresis, which is useful when you want explicit control over the `opsz` value per size band rather than the browser's continuous `font-optical-sizing: auto`.
+
+### React component
+
+```tsx
+import { OpszStepperText } from '@overpunch/opszstepper'
+
+<OpszStepperText
+  cuts={[
+    { family: 'Halyard Micro, sans-serif', maxSize: 13 },
+    { family: 'Halyard Text, sans-serif', minSize: 13, maxSize: 28 },
+    { family: 'Halyard Display, sans-serif', minSize: 28 },
+  ]}
+>
+  Your paragraph text here...
+</OpszStepperText>
+```
+
+### React hook
+
+```tsx
+import { useOpszStepper } from '@overpunch/opszstepper'
+
+// Inside a React component:
+const ref = useOpszStepper({
+  cuts: [
+    { family: 'Halyard Micro, sans-serif', maxSize: 13 },
+    { family: 'Halyard Text, sans-serif', minSize: 13, maxSize: 28 },
+    { family: 'Halyard Display, sans-serif', minSize: 28 },
+  ],
+})
+return <p ref={ref}>{children}</p>
+```
+
+The hook starts a `ResizeObserver` on the element and re-evaluates the active cut each time the element's size changes (which triggers a re-read of `font-size`). It restarts automatically when `cuts.length` or `hysteresis` changes, and cleans up on unmount.
+
+### Vanilla JS — with ResizeObserver
+
+```ts
+import { startOpszStepper } from '@overpunch/opszstepper'
+
+const el = document.querySelector('p')
+
+const cuts = [
+  { family: 'Halyard Micro, sans-serif', maxSize: 13 },
+  { family: 'Halyard Text, sans-serif', minSize: 13, maxSize: 28 },
+  { family: 'Halyard Display, sans-serif', minSize: 28 },
+]
+
+let stop = startOpszStepper(el, { cuts })
+
+// Later — stop the observer and restore original fontFamily:
+// stop()
+```
+
+### Vanilla JS — one-shot
+
+```ts
+import { applyOpszStepper } from '@overpunch/opszstepper'
+
+const el = document.querySelector('p')
+
+applyOpszStepper(el, {
+  cuts: [
+    { family: 'Halyard Micro, sans-serif', maxSize: 13 },
+    { family: 'Halyard Text, sans-serif', minSize: 13, maxSize: 28 },
+    { family: 'Halyard Display, sans-serif', minSize: 28 },
+  ],
+})
+
+// Later — restore original fontFamily:
+// removeOpszStepper(el)
+```
+
+### TypeScript
+
+```ts
+import type { OpszStepperCut, OpszStepperOptions } from '@overpunch/opszstepper'
+
+const cuts: OpszStepperCut[] = [
+  { family: 'Tiempos Fine, serif', maxSize: 13 },
+  { family: 'Tiempos Text, serif', minSize: 13, maxSize: 28 },
+  { family: 'Tiempos Headline, serif', minSize: 28 },
+]
+
+const opts: OpszStepperOptions = { cuts, hysteresis: 2 }
+```
+
+---
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `cuts` | *(required)* | Array of `OpszStepperCut` objects defining each optical size cut and the font-size range it applies to. Each cut has a `family` string (CSS `font-family` value), an optional `minSize` in px (inclusive, default `0`), and an optional `maxSize` in px (exclusive, default `Infinity`). Ranges should be contiguous and non-overlapping — see the cuts configuration guide below |
+| `cut.opszValue` | `undefined` | *(per-cut, `opsz`-axis mode only)* When set, opszStepper writes `font-variation-settings: "opsz" <value>` on the element instead of swapping `family`. Use with a single variable font shared across all cuts — see [Two modes](#two-modes-family-hot-swap-or-opsz-axis) |
+| `cut.opszMin` / `cut.opszMax` | `undefined` | *(per-cut, `opsz`-axis mode only)* Clamp the written `opszValue` to the font's fvar `opsz` axis range. Ignored unless `opszValue` is set |
+| `hysteresis` | `1` | Dead zone in px around each cut boundary. When font-size sits within `hysteresis` px of a threshold, the current cut is held rather than switching. Prevents oscillation when font-size is computed to hover right at a boundary due to sub-pixel rendering or responsive scaling. Increase to `2`–`4` if you observe rapid toggling |
+| `onCutChange` | `undefined` | Callback fired each time the active cut changes. Receives the newly applied `OpszStepperCut`. Useful for logging, analytics, or synchronising sibling elements |
+| `as` | `'p'` | HTML element to render. Accepts any valid React element type, e.g. `'h1'`, `'div'`, `'span'`. *(React component only)* |
+
+---
+
+## Cuts configuration guide
+
+A cut is active when the element's computed `font-size` satisfies `minSize <= fontSize < maxSize`. The bounds are in CSS pixels as returned by `getComputedStyle(el).fontSize`.
+
+Structure cuts as contiguous ranges — each `maxSize` should equal the next cut's `minSize`:
+
+```ts
+cuts: [
+  { family: 'Halyard Micro, sans-serif',   maxSize: 13       },  // 0px – 13px
+  { family: 'Halyard Text, sans-serif',    minSize: 13, maxSize: 28 },  // 13px – 28px
+  { family: 'Halyard Display, sans-serif', minSize: 28       },  // 28px – ∞
+]
+```
+
+You can omit the smallest cut's `minSize` (defaults to `0`) and the largest cut's `maxSize` (defaults to `Infinity`). If font-size falls outside all defined ranges — which should not happen with a complete contiguous set — the active cut is left unchanged.
+
+**Hysteresis at boundaries:** if font-size is `13.4px` and the active cut was Halyard Text (`minSize: 13`), the tool will not switch to Halyard Micro until `fontSize < 13 - hysteresis` (i.e. `< 12` with the default `hysteresis: 1`). Moving in the other direction — Text to Display — requires `fontSize > 28 + hysteresis` (i.e. `> 29`). This prevents flicker when a responsive layout computes font-size to a value that oscillates across a boundary.
+
+---
+
+## How it works
+
+`startOpszStepper` reads the element's computed `font-size` via `getComputedStyle(el).fontSize` and finds the matching cut. It then sets `el.style.fontFamily` to that cut's `family` string, overriding whatever the stylesheet specifies. The original `fontFamily` value is stored in a `WeakMap` keyed by element so it can be restored exactly when `removeOpszStepper` or the stop function is called.
+
+A `ResizeObserver` watches the element for size changes. In responsive layouts, `font-size` is typically driven by `clamp()`, viewport units, or container queries — all of which can change as the element or viewport resizes. Each observer callback re-reads `font-size` and applies hysteresis logic before switching cuts, so a cut swap only fires when the size has moved clearly past a threshold.
+
+**`document.fonts.load()` is not awaited.** The cut swap is immediate — opszStepper sets `font-family` and the browser handles the font load. If a cut's font file has not yet loaded, the browser will show a fallback until it arrives (standard FOUT behaviour). If you need to eliminate FOUT, preload each cut's font file in the document `<head>` using `<link rel="preload" as="font">`. opszStepper does not manage font loading.
+
+**Original fontFamily is saved and restored.** When `removeOpszStepper(el)` or the stop function from `startOpszStepper` is called, the element's `style.fontFamily` is reset to exactly the value it had before the first call. If the element had no inline `fontFamily`, it is restored to an empty string (clearing the inline property, deferring to the stylesheet).
+
+---
+
+## 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.
+
+### Regenerating the README visuals
+
+The hero and comparison images live in `assets/` and are produced by a committed, re-runnable harness in `scripts/` (it renders the three real Cormorant optical cuts in headless Chromium and screenshots each scene). `assets/` and `scripts/` are kept out of the npm tarball — the package ships `dist` only.
+
+```bash
+npm i -D playwright && npx playwright install chromium
+node scripts/capture.mjs   # writes assets/hero.png and assets/compare.png
+```
+
+Bump the `?v=N` cache-buster on the image URLs in this README after regenerating.
+
+---
+
+## Future improvements
+
+- **Container query support** — re-evaluate cuts in response to `@container` size changes, not just element resize, for components embedded in container-query layouts where `font-size` is driven by container width
+- **Smooth crossfade** — optionally apply a short CSS `transition: font-family` equivalent using a brief opacity fade between cuts to soften the swap on large editorial pages
+- **Multi-element sync** — a `syncGroup` option to tie multiple elements to the same active cut, so a heading and its pull-quote always use the same optical cut at all times
+- **Font preload hints** — automatically inject `<link rel="preload">` tags for all cut font files on first call, so the browser can fetch them before they are needed
+- **SSR hydration** — detect the correct cut server-side via a CSS custom property or data attribute so the initial render uses the right `font-family` without a post-hydration swap

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("react"),x=require("react/jsx-runtime"),p=new WeakMap,y=new WeakMap,l=new WeakMap,F=1;function d(t,n){for(let e=0;e<t.length;e++){const s=t[e],i=s.minSize??0,r=s.maxSize??1/0;if(n>=i&&n<r)return e}return-1}function v(t,n,e,s){const i=d(t,n);if(i===-1)return e===-1?i:e;if(e===-1)return i;if(i===e)return e;const r=t[e],a=t[i];if(i>e){const o=(a.minSize??0)+s;return n>o?i:e}else{const o=(r.minSize??0)-s;return n<o?i:e}}function z(t,n){const e=window.scrollY;if(t.style.fontFamily=n.family,n.opszValue!==void 0){const s=n.opszMin??-1/0,i=n.opszMax??1/0,r=Math.min(i,Math.max(s,n.opszValue));t.style.fontVariationSettings=`"opsz" ${r}`}else t.style.fontVariationSettings&&(t.style.fontVariationSettings="");requestAnimationFrame(()=>{Math.abs(window.scrollY-e)>2&&window.scrollTo({top:e,behavior:"instant"})})}function g(t,n){if(typeof window>"u")return;const{cuts:e,onCutChange:s}=n;if(!e||e.length===0)return;const i=parseFloat(getComputedStyle(t).fontSize);if(isNaN(i))return;const r=d(e,i);if(r===-1)return;const a=e[r];p.has(t)||p.set(t,t.style.fontFamily),z(t,a),l.set(t,r),s==null||s(a)}function w(t,n){if(typeof window>"u")return()=>{};const{cuts:e,onCutChange:s}=n,i=n.hysteresis??F;if(!e||e.length===0)return()=>{};const r=y.get(t);r&&r(),p.has(t)||p.set(t,t.style.fontFamily),g(t,n);const a=new ResizeObserver(()=>{const c=parseFloat(getComputedStyle(t).fontSize);if(isNaN(c))return;const S=l.get(t)??-1,f=v(e,c,S,i);f!==S&&f!==-1&&(z(t,e[f]),l.set(t,f),s==null||s(e[f]))});a.observe(t);const o=()=>{a.disconnect();const c=p.get(t);c!==void 0&&(t.style.fontFamily=c,t.style.fontVariationSettings="",p.delete(t)),l.delete(t),y.delete(t)};return y.set(t,o),o}function b(t){const n=y.get(t);if(n){n();return}if(p.has(t)){const e=p.get(t);t.style.fontFamily=e??"",t.style.fontVariationSettings="",p.delete(t),l.delete(t)}}function O(t){const n=u.useRef(null),e=u.useRef(t);e.current=t;const s=u.useRef(null),i=JSON.stringify(t.cuts),{hysteresis:r}=t;return u.useLayoutEffect(()=>{var o;const a=n.current;if(a)return(o=s.current)==null||o.call(s),s.current=w(a,e.current),()=>{var c;(c=s.current)==null||c.call(s),s.current=null}},[i,r]),n}const h=u.forwardRef(function({children:n,as:e="p",cuts:s,hysteresis:i,onCutChange:r,...a},o){const f=O({cuts:s,hysteresis:i,onCutChange:r}),M=u.useCallback(m=>{f.current=m,typeof o=="function"?o(m):o&&(o.current=m)},[o]);return x.jsx(e,{ref:M,...a,children:n})});h.displayName="OpszStepperText";exports.OpszStepperText=h;exports.applyOpszStepper=g;exports.removeOpszStepper=b;exports.startOpszStepper=w;exports.useOpszStepper=O;

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { default as default_2 } from 'react';
+import { RefObject } from 'react';
+
+/**
+ * One-shot application of the correct optical cut for the element's current
+ * computed font-size. No ResizeObserver — use when you want manual control.
+ * Note: hysteresis is not applied here; use startOpszStepper for hysteresis support.
+ *
+ * @param el      - Target element
+ * @param options - OpszStepperOptions
+ */
+export declare function applyOpszStepper(el: HTMLElement, options: OpszStepperOptions): void;
+
+/**
+ * A single optical size cut definition: a font-family string and the font-size
+ * range in px over which it should be active.
+ *
+ * Two usage modes:
+ * 1. Multi-family hot-swap (e.g. Halyard Micro / Text / Display):
+ *    set `family` to the CSS font-family string for each cut. Leave `opszValue` unset.
+ * 2. Single variable-font opsz axis (e.g. Recursive, Fraunces, Amstelvar):
+ *    set `family` to the single variable font family, and set `opszValue` to the
+ *    `opsz` axis value to apply at this cut. The tool will write
+ *    `font-variation-settings: "opsz" <value>` on the element.
+ *    Optionally provide `opszMin` and `opszMax` to clamp the value against the
+ *    font's fvar axis range.
+ */
+export declare interface OpszStepperCut {
+    /**
+     * The CSS font-family string for this optical cut.
+     * e.g. 'Halyard Display, sans-serif' or '"Tiempos Display", serif'
+     * For variable-font opsz mode, use the same family string in all cuts.
+     */
+    family: string;
+    /** Min font-size in px (inclusive) for this cut to apply. Default: 0 */
+    minSize?: number;
+    /** Max font-size in px (exclusive) for this cut to apply. Default: Infinity */
+    maxSize?: number;
+    /**
+     * Optional `opsz` axis value to write as `font-variation-settings: "opsz" <value>`.
+     * Use this when all cuts share one variable font and you want to drive the opsz axis
+     * directly rather than hot-swapping font families.
+     * When provided, `font-variation-settings: normal` is written first to clear any
+     * inherited axis values before applying the new `opsz` value.
+     * Clamped between `opszMin` and `opszMax` when those are supplied.
+     */
+    opszValue?: number;
+    /**
+     * Minimum allowed value for the `opsz` axis (from the font's fvar table).
+     * Only used when `opszValue` is set. Clamps the written value from below.
+     */
+    opszMin?: number;
+    /**
+     * Maximum allowed value for the `opsz` axis (from the font's fvar table).
+     * Only used when `opszValue` is set. Clamps the written value from above.
+     */
+    opszMax?: number;
+}
+
+/** Options controlling the opszStepper effect */
+export declare interface OpszStepperOptions {
+    /**
+     * The optical size cuts, ordered from smallest to largest.
+     * Each cut defines a font-family string and the font-size range it applies to.
+     * Ranges should be contiguous and non-overlapping.
+     *
+     * @example Multi-family hot-swap
+     * cuts: [
+     *   { family: 'Halyard Micro, sans-serif', maxSize: 13 },
+     *   { family: 'Halyard Text, sans-serif', minSize: 13, maxSize: 28 },
+     *   { family: 'Halyard Display, sans-serif', minSize: 28 },
+     * ]
+     *
+     * @example Single variable font opsz axis
+     * cuts: [
+     *   { family: 'Fraunces, serif', maxSize: 13, opszValue: 9, opszMin: 9, opszMax: 144 },
+     *   { family: 'Fraunces, serif', minSize: 13, maxSize: 28, opszValue: 24, opszMin: 9, opszMax: 144 },
+     *   { family: 'Fraunces, serif', minSize: 28, opszValue: 72, opszMin: 9, opszMax: 144 },
+     * ]
+     */
+    cuts: OpszStepperCut[];
+    /**
+     * Hysteresis dead zone in px per threshold. Prevents oscillation when
+     * font-size sits exactly at a cut boundary. Only used by startOpszStepper;
+     * applyOpszStepper always does a direct cut lookup without hysteresis.
+     * Default: 1
+     */
+    hysteresis?: number;
+    /**
+     * Callback fired each time the active cut changes.
+     * Receives the new cut that was applied.
+     */
+    onCutChange?: (cut: OpszStepperCut) => void;
+}
+
+/** A stop function returned by startOpszStepper. Call it to disconnect the observer and restore the element. */
+export declare type OpszStepperStop = () => void;
+
+/**
+ * Drop-in component that automatically swaps between optical size cuts
+ * of a typeface family as the element's font-size changes.
+ * Forwards the ref to the root element while also attaching the internal hook ref.
+ * Accepts all standard HTML and ARIA attributes.
+ */
+export declare const OpszStepperText: default_2.ForwardRefExoticComponent<OpszStepperTextProps & default_2.RefAttributes<HTMLElement>>;
+
+/**
+ * Props for the OpszStepperText component.
+ * Extends OpszStepperOptions plus all standard HTML attributes (including ARIA)
+ * so that aria-label, role, tabIndex, id, etc. are accepted and forwarded to the DOM.
+ */
+declare interface OpszStepperTextProps extends OpszStepperOptions, default_2.HTMLAttributes<HTMLElement> {
+    /** HTML element to render. Default: 'p' */
+    as?: default_2.ElementType;
+}
+
+/**
+ * Restore the element's original fontFamily and disconnect any running
+ * ResizeObserver started by startOpszStepper. No-op if never applied.
+ *
+ * @param el - Element previously passed to startOpszStepper or applyOpszStepper
+ */
+export declare function removeOpszStepper(el: HTMLElement): void;
+
+/**
+ * Start a ResizeObserver-backed optical cut watcher on an element.
+ * Re-evaluates the correct cut each time the element's size changes
+ * (which can cause font-size to change in responsive designs).
+ *
+ * Applies the correct cut immediately on first call.
+ * If called a second time on the same element, the prior observer is stopped
+ * first to avoid orphaned observers.
+ *
+ * @param el      - Target element
+ * @param options - OpszStepperOptions
+ * @returns         A stop function that disconnects the observer and restores the original fontFamily
+ */
+export declare function startOpszStepper(el: HTMLElement, options: OpszStepperOptions): OpszStepperStop;
+
+/**
+ * React hook that starts an opszStepper observer on the returned ref'd element.
+ * Calls startOpszStepper in useLayoutEffect and stores the returned stop function.
+ *
+ * Re-runs (stops and restarts the observer) whenever any cut's family, minSize, or
+ * maxSize changes, or when cuts are added/removed, or when hysteresis changes.
+ * A stable JSON serialisation of the cuts array is used as the dependency key so
+ * that same-length arrays with different content also trigger a restart.
+ *
+ * Note: onCutChange is kept in a ref and never used as a dependency — it is always
+ * read fresh from optionsRef on each observer callback, so it does not need to be
+ * stable across renders.
+ *
+ * Cleans up on unmount.
+ *
+ * @param options - OpszStepperOptions
+ * @returns         A ref to attach to the target element
+ */
+export declare function useOpszStepper(options: OpszStepperOptions): RefObject<HTMLElement | null>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,114 @@
+import { useRef as S, useLayoutEffect as z, forwardRef as h, useCallback as M } from "react";
+import { jsx as F } from "react/jsx-runtime";
+const f = /* @__PURE__ */ new WeakMap(), y = /* @__PURE__ */ new WeakMap(), p = /* @__PURE__ */ new WeakMap(), x = 1;
+function d(t, e) {
+  for (let n = 0; n < t.length; n++) {
+    const s = t[n], i = s.minSize ?? 0, o = s.maxSize ?? 1 / 0;
+    if (e >= i && e < o)
+      return n;
+  }
+  return -1;
+}
+function O(t, e, n, s) {
+  const i = d(t, e);
+  if (i === -1) return n === -1 ? i : n;
+  if (n === -1) return i;
+  if (i === n) return n;
+  const o = t[n], a = t[i];
+  if (i > n) {
+    const r = (a.minSize ?? 0) + s;
+    return e > r ? i : n;
+  } else {
+    const r = (o.minSize ?? 0) - s;
+    return e < r ? i : n;
+  }
+}
+function g(t, e) {
+  const n = window.scrollY;
+  if (t.style.fontFamily = e.family, e.opszValue !== void 0) {
+    const s = e.opszMin ?? -1 / 0, i = e.opszMax ?? 1 / 0, o = Math.min(i, Math.max(s, e.opszValue));
+    t.style.fontVariationSettings = `"opsz" ${o}`;
+  } else
+    t.style.fontVariationSettings && (t.style.fontVariationSettings = "");
+  requestAnimationFrame(() => {
+    Math.abs(window.scrollY - n) > 2 && window.scrollTo({ top: n, behavior: "instant" });
+  });
+}
+function v(t, e) {
+  if (typeof window > "u") return;
+  const { cuts: n, onCutChange: s } = e;
+  if (!n || n.length === 0) return;
+  const i = parseFloat(getComputedStyle(t).fontSize);
+  if (isNaN(i)) return;
+  const o = d(n, i);
+  if (o === -1) return;
+  const a = n[o];
+  f.has(t) || f.set(t, t.style.fontFamily), g(t, a), p.set(t, o), s == null || s(a);
+}
+function V(t, e) {
+  if (typeof window > "u") return () => {
+  };
+  const { cuts: n, onCutChange: s } = e, i = e.hysteresis ?? x;
+  if (!n || n.length === 0) return () => {
+  };
+  const o = y.get(t);
+  o && o(), f.has(t) || f.set(t, t.style.fontFamily), v(t, e);
+  const a = new ResizeObserver(() => {
+    const c = parseFloat(getComputedStyle(t).fontSize);
+    if (isNaN(c)) return;
+    const l = p.get(t) ?? -1, u = O(n, c, l, i);
+    u !== l && u !== -1 && (g(t, n[u]), p.set(t, u), s == null || s(n[u]));
+  });
+  a.observe(t);
+  const r = () => {
+    a.disconnect();
+    const c = f.get(t);
+    c !== void 0 && (t.style.fontFamily = c, t.style.fontVariationSettings = "", f.delete(t)), p.delete(t), y.delete(t);
+  };
+  return y.set(t, r), r;
+}
+function R(t) {
+  const e = y.get(t);
+  if (e) {
+    e();
+    return;
+  }
+  if (f.has(t)) {
+    const n = f.get(t);
+    t.style.fontFamily = n ?? "", t.style.fontVariationSettings = "", f.delete(t), p.delete(t);
+  }
+}
+function b(t) {
+  const e = S(null), n = S(t);
+  n.current = t;
+  const s = S(null), i = JSON.stringify(t.cuts), { hysteresis: o } = t;
+  return z(() => {
+    var r;
+    const a = e.current;
+    if (a)
+      return (r = s.current) == null || r.call(s), s.current = V(a, n.current), () => {
+        var c;
+        (c = s.current) == null || c.call(s), s.current = null;
+      };
+  }, [i, o]), e;
+}
+const N = h(
+  function({ children: e, as: n = "p", cuts: s, hysteresis: i, onCutChange: o, ...a }, r) {
+    const u = b({ cuts: s, hysteresis: i, onCutChange: o }), w = M(
+      (m) => {
+        u.current = m, typeof r == "function" ? r(m) : r && (r.current = m);
+      },
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [r]
+    );
+    return /* @__PURE__ */ F(n, { ref: w, ...a, children: e });
+  }
+);
+N.displayName = "OpszStepperText";
+export {
+  N as OpszStepperText,
+  v as applyOpszStepper,
+  R as removeOpszStepper,
+  V as startOpszStepper,
+  b as useOpszStepper
+};

package/dist/opszstepper.webflow.min.js

@@ -0,0 +1 @@
+var OpszStepper=(function(u){"use strict";const r=new WeakMap,z=new WeakMap,d=new WeakMap,N=1;function g(t,n){for(let o=0;o<t.length;o++){const s=t[o],i=s.minSize??0,e=s.maxSize??1/0;if(n>=i&&n<e)return o}return-1}function O(t,n,o,s){const i=g(t,n);if(i===-1)return o===-1?i:o;if(o===-1)return i;if(i===o)return o;const e=t[o],a=t[i];if(i>o){const c=(a.minSize??0)+s;return n>c?i:o}else{const c=(e.minSize??0)-s;return n<c?i:o}}function v(t,n){const o=window.scrollY;if(t.style.fontFamily=n.family,n.opszValue!==void 0){const s=n.opszMin??-1/0,i=n.opszMax??1/0,e=Math.min(i,Math.max(s,n.opszValue));t.style.fontVariationSettings=`"opsz" ${e}`}else t.style.fontVariationSettings&&(t.style.fontVariationSettings="");requestAnimationFrame(()=>{Math.abs(window.scrollY-o)>2&&window.scrollTo({top:o,behavior:"instant"})})}function F(t,n){if(typeof window>"u")return;const{cuts:o,onCutChange:s}=n;if(!o||o.length===0)return;const i=parseFloat(getComputedStyle(t).fontSize);if(isNaN(i))return;const e=g(o,i);if(e===-1)return;const a=o[e];r.has(t)||r.set(t,t.style.fontFamily),v(t,a),d.set(t,e),s==null||s(a)}function x(t,n){if(typeof window>"u")return()=>{};const{cuts:o,onCutChange:s}=n,i=n.hysteresis??N;if(!o||o.length===0)return()=>{};const e=z.get(t);e&&e(),r.has(t)||r.set(t,t.style.fontFamily),F(t,n);const a=new ResizeObserver(()=>{const f=parseFloat(getComputedStyle(t).fontSize);if(isNaN(f))return;const y=d.get(t)??-1,p=O(o,f,y,i);p!==y&&p!==-1&&(v(t,o[p]),d.set(t,p),s==null||s(o[p]))});a.observe(t);const c=()=>{a.disconnect();const f=r.get(t);f!==void 0&&(t.style.fontFamily=f,t.style.fontVariationSettings="",r.delete(t)),d.delete(t),z.delete(t)};return z.set(t,c),c}function b(t){const n=z.get(t);if(n){n();return}if(r.has(t)){const o=r.get(t);t.style.fontFamily=o??"",t.style.fontVariationSettings="",r.delete(t),d.delete(t)}}const V="data-opszstepper",S=new WeakMap;function C(t,n,o,s){const i=[];for(const e of t.split(",")){const a=e.trim();if(!a)continue;const[c,f]=a.split(":");if(f===void 0)continue;const y=parseFloat(f.trim());if(isNaN(y))continue;const[p,P]=c.split("-"),h=parseFloat((p??"").trim()),w=parseFloat((P??"").trim()),l={family:n,opszValue:y};isNaN(h)||(l.minSize=h),isNaN(w)||(l.maxSize=w),o!==void 0&&(l.opszMin=o),s!==void 0&&(l.opszMax=s),i.push(l)}return i}function T(t){if(!Array.isArray(t))return[];const n=[];for(const o of t){if(!o||typeof o!="object")continue;const s=o;if(typeof s.family!="string")continue;const i={family:s.family};typeof s.minSize=="number"&&(i.minSize=s.minSize),typeof s.maxSize=="number"&&(i.maxSize=s.maxSize),typeof s.opszValue=="number"&&(i.opszValue=s.opszValue),typeof s.opszMin=="number"&&(i.opszMin=s.opszMin),typeof s.opszMax=="number"&&(i.opszMax=s.opszMax),n.push(i)}return n}function A(t){const n=t.dataset;let o=[];if(n.osCuts)try{o=T(JSON.parse(n.osCuts))}catch{console.error("OpszStepper: data-os-cuts is not valid JSON — ignoring.")}if(o.length===0&&n.osFamily&&n.osOpsz){const i=n.osOpszMin!==void 0?parseFloat(n.osOpszMin):void 0,e=n.osOpszMax!==void 0?parseFloat(n.osOpszMax):void 0;o=C(n.osOpsz,n.osFamily,i!==void 0&&!isNaN(i)?i:void 0,e!==void 0&&!isNaN(e)?e:void 0)}const s={cuts:o};if(n.osHysteresis!==void 0){const i=parseFloat(n.osHysteresis);isNaN(i)||(s.hysteresis=i)}return s}function E(t){M(t);const n=A(t);if(n.cuts.length===0){console.warn("OpszStepper: no valid cuts found on element — skipping.");return}const o=x(t,n);S.set(t,{stop:o})}function M(t){const n=S.get(t);if(!n){b(t);return}n.stop(),S.delete(t)}function m(t=document){t.querySelectorAll(`[${V}]`).forEach(E)}function I(t=document){m(t)}function k(){const t=()=>{var n;(n=document.fonts)!=null&&n.ready?document.fonts.ready.then(()=>m()).catch(()=>m()):m()};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",t,{once:!0}):t()}return k(),u.destroy=M,u.init=m,u.restart=I,Object.defineProperty(u,Symbol.toStringTag,{value:"Module"}),u})({});

package/package.json

@@ -0,0 +1,84 @@
+{
+	"name": "@overpunch/opszstepper",
+	"version": "1.0.18",
+	"description": "Multi-cut optical family hot-swap by font-size — automatically applies Micro, Text, or Display cuts based on the element's computed font-size",
+	"type": "module",
+	"main": "dist/index.cjs",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "vite build",
+		"build:webflow": "vite build --config vite.webflow.config.ts",
+		"test": "vitest run",
+		"test:run": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "npm run test && npm run build && npm run build:webflow"
+	},
+	"peerDependencies": {
+		"react": ">=17",
+		"react-dom": ">=17"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
+		"@types/react": "^19.0.0",
+		"@vitejs/plugin-react": "^4.0.0",
+		"happy-dom": "^20.10.6",
+		"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",
+		"web-typography",
+		"frontend",
+		"liiift-studio",
+		"optical-size",
+		"font-family",
+		"opsz",
+		"optical-sizing",
+		"font-swap",
+		"fluid-type",
+		"multi-cut",
+		"responsive-type",
+		"responsive-design",
+		"typographic",
+		"zero-dependencies",
+		"react",
+		"typescript",
+		"css"
+	],
+	"author": "Quinn Keaveney <quinn@liiift.studio>",
+	"license": "MIT",
+	"homepage": "https://opszstepper.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/over-punch/opszStepper.git"
+	},
+	"bugs": {
+		"url": "https://github.com/over-punch/opszStepper/issues"
+	},
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}