@overpunch/opszstepper 1.0.18 → 1.1.0

package/README.md

@@ -1,212 +1,216 @@
-# 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
+# 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 sets the `opsz` axis in `font-variation-settings` (keeping any other axes you've set, such as `wght`) 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 the stepper on the element and re-evaluates the active cut whenever its font-size may have changed (see [How it works](#how-it-works)). It restarts when the cuts or `hysteresis` change, follows the element if React replaces it (a changed `as`, a conditional mount), always calls the latest `onCutChange`, and cleans up on unmount.
+
+### Vanilla JS — live
+
+The main entry also exports the React hook and component, so it imports `react`. Without React installed, import from the React-free subpath `@overpunch/opszstepper/core`:
+
+```ts
+import { startOpszStepper } from '@overpunch/opszstepper/core'
+
+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 watching and restore the original styles:
+// 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 the original styles:
+// 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. They can be listed in any order, and a cut with only `maxSize` starts where the previous one ends — see the cuts configuration guide below |
+| `cut.opszValue` | `undefined` | *(per-cut, `opsz`-axis mode only)* When set, opszStepper sets the `opsz` axis in the element's `font-variation-settings`, keeping its other axes. 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. A value larger than half the narrowest cut is reduced to that (with a warning), so a cut can't be skipped |
+| `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 inline `font-family` and `font-variation-settings` (with any `!important`) are saved so they can be restored exactly when `removeOpszStepper` or the stop function is called. In family mode `font-variation-settings` is left alone.
+
+A font-size can change without the element's box changing size (a fixed `line-height`, an inline `<span>`, a fixed-size box), so a `ResizeObserver` alone isn't enough. opszStepper re-checks when the element or its parent resizes (container queries), when a `class` or `style` attribute changes anywhere on the page, and when the window resizes (viewport units, media queries). All watched elements share these observers, and each check reads every font-size first and then writes the changed cuts, so a resize with thousands of elements costs one style recalculation. Hysteresis is applied before switching, so a swap only fires when the size has moved clearly past a threshold.
+
+**Limits:** a font-size change that comes from none of these (for example an animation of `font-size` on a parent) isn't seen until one of them fires; call `applyOpszStepper` yourself in that case. The size used is the computed `font-size`, so CSS `zoom` and transforms don't change the cut. opszStepper doesn't move the page's scroll position: browsers' scroll anchoring handles the small reflow a swap can cause.
+
+**`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`, the inline property is removed (deferring to the stylesheet), and an element that had no `style` attribute is left without one.
+
+---
+
+## 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/core.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=1;function $(t){const e=t.filter(s=>s&&typeof s.family=="string"),n=s=>Number.isFinite(s.minSize)?s.minSize:Number.isFinite(s.maxSize)?s.maxSize-1e-9:1/0,i=[...e].sort((s,u)=>n(s)-n(u)),r=i.map((s,u)=>{const f=i[u-1];return{min:Number.isFinite(s.minSize)?s.minSize:f&&Number.isFinite(f.maxSize)?f.maxSize:0,max:Number.isFinite(s.maxSize)?s.maxSize:1/0,cut:s}});for(let s=0;s<r.length-1;s++)r[s].max===1/0&&(r[s].max=r[s+1].min);return r}function z(t,e){for(let n=0;n<t.length;n++)if(e>=t[n].min&&e<t[n].max)return n;return-1}function R(t,e,n,i){const r=z(t,e);if(n===-1||!t[n])return r;if(r===-1||r===n)return n;const s=t[n];return e>=s.max+i||e<s.min-i?r:n}const A=new Set;function N(t){A.has(t)||(A.add(t),console.warn(t))}function H(t,e){let n=t??g;(!Number.isFinite(n)||n<0)&&(N(`[opszStepper] hysteresis must be a non-negative number; got ${t}, using ${g}`),n=g);const i=Math.min(...e.map(r=>r.max-r.min).filter(r=>Number.isFinite(r)&&r>0));return Number.isFinite(i)&&n>i/2&&(N(`[opszStepper] hysteresis ${n}px is more than half the narrowest cut (${i}px); using ${i/2}px`),n=i/2),n}const a=new Map;function S(t,e){return{value:t.style.getPropertyValue(e),priority:t.style.getPropertyPriority(e)}}function v(t,e,n){n.value?t.style.setProperty(e,n.value,n.priority):t.style.removeProperty(e)}function M(t,e){const n=$(e.cuts),i=H(e.hysteresis,n);let r=a.get(t);return r?(r.cuts=n,r.hysteresis=i,r.onCutChange=e.onCutChange):(r={cuts:n,hysteresis:i,onCutChange:e.onCutChange,activeIndex:-1,origFamily:S(t,"font-family"),origFVS:S(t,"font-variation-settings"),origStyleAttr:t.getAttribute("style"),baseFVS:I(t),writtenFVS:null,writtenStyleAttr:null,live:!1},a.set(t,r)),r}function I(t){const e=getComputedStyle(t);return(typeof e.getPropertyValue=="function"?e.getPropertyValue("font-variation-settings"):e.fontVariationSettings)||"normal"}function L(t,e){const n=`"opsz" ${e}`;if(!t||t==="normal")return n;const i=/(["'])opsz\1\s+-?[\d.eE+-]+/;return i.test(t)?t.replace(i,n):`${t}, ${n}`}function F(t,e,n){const i=e.cuts[n].cut;if(e.writtenFVS!==null&&t.style.getPropertyValue("font-variation-settings")!==e.writtenFVS&&(e.origFVS=S(t,"font-variation-settings"),e.baseFVS=I(t),e.writtenFVS=null),t.style.setProperty("font-family",i.family,e.origFamily.priority),typeof i.opszValue=="number"&&Number.isFinite(i.opszValue)){const r=Number.isFinite(i.opszMin)?i.opszMin:-1/0,s=Number.isFinite(i.opszMax)?i.opszMax:1/0,u=r<=s?Math.min(s,Math.max(r,i.opszValue)):i.opszValue,f=L(e.baseFVS,u);t.style.setProperty("font-variation-settings",f,e.origFVS.priority),e.writtenFVS=t.style.getPropertyValue("font-variation-settings")}else e.writtenFVS!==null&&(v(t,"font-variation-settings",e.origFVS),e.writtenFVS=null);e.activeIndex=n,e.writtenStyleAttr=t.getAttribute("style")}function E(t){const e=a.get(t);e&&(e.writtenStyleAttr!==null&&t.getAttribute("style")===e.writtenStyleAttr?e.origStyleAttr===null?t.removeAttribute("style"):t.setAttribute("style",e.origStyleAttr):(v(t,"font-family",e.origFamily),e.writtenFVS!==null&&v(t,"font-variation-settings",e.origFVS),e.origStyleAttr===null&&!t.getAttribute("style")&&t.removeAttribute("style")),a.delete(t))}const p=new Set;let l=null,O=null;const c=new Map;let y=null,b=!1;function T(){var e;b=!1;const t=[];p.forEach(n=>{const i=a.get(n);if(!i||!n.isConnected)return;const r=parseFloat(getComputedStyle(n).fontSize);if(!Number.isFinite(r))return;const s=R(i.cuts,r,i.activeIndex,i.hysteresis);s!==-1&&s!==i.activeIndex&&t.push([n,i,s])});for(const[n,i,r]of t)F(n,i,r),(e=i.onCutChange)==null||e.call(i,i.cuts[r].cut)}function d(){b||(b=!0,queueMicrotask(T))}function k(){typeof MutationObserver<"u"&&!y&&document.documentElement&&(y=new MutationObserver(d),y.observe(document.documentElement,{attributes:!0,attributeFilter:["class","style","lang","dir"],subtree:!0}),window.addEventListener("resize",d))}function W(){p.size||(l==null||l.disconnect(),l=null,c.clear(),y==null||y.disconnect(),y=null,typeof window<"u"&&window.removeEventListener("resize",d))}function j(t,e){var s;if(typeof window>"u"||!t||!(e!=null&&e.cuts)||e.cuts.length===0)return;const n=parseFloat(getComputedStyle(t).fontSize);if(isNaN(n))return;const i=M(t,e),r=z(i.cuts,n);r!==-1&&r!==i.activeIndex&&(F(t,i,r),(s=i.onCutChange)==null||s.call(i,i.cuts[r].cut))}function q(t,e){var s,u,f;if(typeof window>"u"||!t)return()=>{};if(!(e!=null&&e.cuts)||e.cuts.length===0)return()=>{};(u=(s=a.get(t))==null?void 0:s.stop)==null||u.call(s);const n=M(t,e),i=parseFloat(getComputedStyle(t).fontSize);if(Number.isFinite(i)){const o=z(n.cuts,i);o!==-1&&o!==n.activeIndex&&(F(t,n,o),(f=n.onCutChange)==null||f.call(n,n.cuts[o].cut))}if(k(),p.add(t),n.live=!0,typeof ResizeObserver<"u"&&((!l||O!==ResizeObserver)&&(l=new ResizeObserver(d),O=ResizeObserver,c.clear()),n.ro=l,n.ro.observe(t),n.observedParent=t.parentElement,n.observedParent)){const o=c.get(n.observedParent)??0;o===0&&n.ro.observe(n.observedParent),c.set(n.observedParent,o+1)}const r=()=>{var w,h,V,x,C;if(((w=a.get(t))==null?void 0:w.stop)!==r)return;p.delete(t);const o=a.get(t);if(o!=null&&o.ro&&o.ro===l){(V=(h=o.ro).unobserve)==null||V.call(h,t);const m=o.observedParent;if(m){const P=(c.get(m)??1)-1;P<=0?(c.delete(m),(C=(x=o.ro).unobserve)==null||C.call(x,m)):c.set(m,P)}}E(t),W()};return n.stop=r,r}function D(t){const e=a.get(t);e&&(e.stop?e.stop():E(t))}exports.applyOpszStepper=j;exports.removeOpszStepper=D;exports.startOpszStepper=q;

package/dist/core.d.ts

@@ -0,0 +1,114 @@
+/**
+ * One-shot application of the correct optical cut for the element's current computed font-size.
+ * No watching — use when you want manual control. Hysteresis is not applied here.
+ * onCutChange fires only when the cut actually changes.
+ *
+ * @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;
+
+/**
+ * Restore the element's original styles and stop watching it. No-op if never applied.
+ *
+ * @param el - Element previously passed to startOpszStepper or applyOpszStepper
+ */
+export declare function removeOpszStepper(el: HTMLElement): void;
+
+/**
+ * Start watching an element: applies the correct cut now and again whenever its font-size
+ * changes — from a resize, a class or style change anywhere on the page, or a viewport change.
+ * Calling it again on the same element replaces the earlier watcher.
+ *
+ * @param el      - Target element
+ * @param options - OpszStepperOptions
+ * @returns         A stop function that stops watching and restores the element's original styles
+ */
+export declare function startOpszStepper(el: HTMLElement, options: OpszStepperOptions): OpszStepperStop;
+
+export { }

package/dist/core.js

@@ -0,0 +1,155 @@
+function O(t) {
+  const e = t.filter((s) => s && typeof s.family == "string"), n = (s) => Number.isFinite(s.minSize) ? s.minSize : Number.isFinite(s.maxSize) ? s.maxSize - 1e-9 : 1 / 0, i = [...e].sort((s, u) => n(s) - n(u)), r = i.map((s, u) => {
+    const f = i[u - 1];
+    return { min: Number.isFinite(s.minSize) ? s.minSize : f && Number.isFinite(f.maxSize) ? f.maxSize : 0, max: Number.isFinite(s.maxSize) ? s.maxSize : 1 / 0, cut: s };
+  });
+  for (let s = 0; s < r.length - 1; s++)
+    r[s].max === 1 / 0 && (r[s].max = r[s + 1].min);
+  return r;
+}
+function F(t, e) {
+  for (let n = 0; n < t.length; n++)
+    if (e >= t[n].min && e < t[n].max) return n;
+  return -1;
+}
+function R(t, e, n, i) {
+  const r = F(t, e);
+  if (n === -1 || !t[n]) return r;
+  if (r === -1 || r === n) return n;
+  const s = t[n];
+  return e >= s.max + i || e < s.min - i ? r : n;
+}
+const A = /* @__PURE__ */ new Set();
+function E(t) {
+  A.has(t) || (A.add(t), console.warn(t));
+}
+function T(t, e) {
+  let n = t ?? 1;
+  (!Number.isFinite(n) || n < 0) && (E(`[opszStepper] hysteresis must be a non-negative number; got ${t}, using 1`), n = 1);
+  const i = Math.min(...e.map((r) => r.max - r.min).filter((r) => Number.isFinite(r) && r > 0));
+  return Number.isFinite(i) && n > i / 2 && (E(`[opszStepper] hysteresis ${n}px is more than half the narrowest cut (${i}px); using ${i / 2}px`), n = i / 2), n;
+}
+const a = /* @__PURE__ */ new Map();
+function d(t, e) {
+  return { value: t.style.getPropertyValue(e), priority: t.style.getPropertyPriority(e) };
+}
+function g(t, e, n) {
+  n.value ? t.style.setProperty(e, n.value, n.priority) : t.style.removeProperty(e);
+}
+function I(t, e) {
+  const n = O(e.cuts), i = T(e.hysteresis, n);
+  let r = a.get(t);
+  return r ? (r.cuts = n, r.hysteresis = i, r.onCutChange = e.onCutChange) : (r = {
+    cuts: n,
+    hysteresis: i,
+    onCutChange: e.onCutChange,
+    activeIndex: -1,
+    origFamily: d(t, "font-family"),
+    origFVS: d(t, "font-variation-settings"),
+    origStyleAttr: t.getAttribute("style"),
+    baseFVS: N(t),
+    writtenFVS: null,
+    writtenStyleAttr: null,
+    live: !1
+  }, a.set(t, r)), r;
+}
+function N(t) {
+  const e = getComputedStyle(t);
+  return (typeof e.getPropertyValue == "function" ? e.getPropertyValue("font-variation-settings") : e.fontVariationSettings) || "normal";
+}
+function $(t, e) {
+  const n = `"opsz" ${e}`;
+  if (!t || t === "normal") return n;
+  const i = /(["'])opsz\1\s+-?[\d.eE+-]+/;
+  return i.test(t) ? t.replace(i, n) : `${t}, ${n}`;
+}
+function b(t, e, n) {
+  const i = e.cuts[n].cut;
+  if (e.writtenFVS !== null && t.style.getPropertyValue("font-variation-settings") !== e.writtenFVS && (e.origFVS = d(t, "font-variation-settings"), e.baseFVS = N(t), e.writtenFVS = null), t.style.setProperty("font-family", i.family, e.origFamily.priority), typeof i.opszValue == "number" && Number.isFinite(i.opszValue)) {
+    const r = Number.isFinite(i.opszMin) ? i.opszMin : -1 / 0, s = Number.isFinite(i.opszMax) ? i.opszMax : 1 / 0, u = r <= s ? Math.min(s, Math.max(r, i.opszValue)) : i.opszValue, f = $(e.baseFVS, u);
+    t.style.setProperty("font-variation-settings", f, e.origFVS.priority), e.writtenFVS = t.style.getPropertyValue("font-variation-settings");
+  } else e.writtenFVS !== null && (g(t, "font-variation-settings", e.origFVS), e.writtenFVS = null);
+  e.activeIndex = n, e.writtenStyleAttr = t.getAttribute("style");
+}
+function M(t) {
+  const e = a.get(t);
+  e && (e.writtenStyleAttr !== null && t.getAttribute("style") === e.writtenStyleAttr ? e.origStyleAttr === null ? t.removeAttribute("style") : t.setAttribute("style", e.origStyleAttr) : (g(t, "font-family", e.origFamily), e.writtenFVS !== null && g(t, "font-variation-settings", e.origFVS), e.origStyleAttr === null && !t.getAttribute("style") && t.removeAttribute("style")), a.delete(t));
+}
+const S = /* @__PURE__ */ new Set();
+let l = null, P = null;
+const c = /* @__PURE__ */ new Map();
+let y = null, v = !1;
+function H() {
+  var e;
+  v = !1;
+  const t = [];
+  S.forEach((n) => {
+    const i = a.get(n);
+    if (!i || !n.isConnected) return;
+    const r = parseFloat(getComputedStyle(n).fontSize);
+    if (!Number.isFinite(r)) return;
+    const s = R(i.cuts, r, i.activeIndex, i.hysteresis);
+    s !== -1 && s !== i.activeIndex && t.push([n, i, s]);
+  });
+  for (const [n, i, r] of t)
+    b(n, i, r), (e = i.onCutChange) == null || e.call(i, i.cuts[r].cut);
+}
+function p() {
+  v || (v = !0, queueMicrotask(H));
+}
+function L() {
+  typeof MutationObserver < "u" && !y && document.documentElement && (y = new MutationObserver(p), y.observe(document.documentElement, { attributes: !0, attributeFilter: ["class", "style", "lang", "dir"], subtree: !0 }), window.addEventListener("resize", p));
+}
+function D() {
+  S.size || (l == null || l.disconnect(), l = null, c.clear(), y == null || y.disconnect(), y = null, typeof window < "u" && window.removeEventListener("resize", p));
+}
+function U(t, e) {
+  var s;
+  if (typeof window > "u" || !t || !(e != null && e.cuts) || e.cuts.length === 0) return;
+  const n = parseFloat(getComputedStyle(t).fontSize);
+  if (isNaN(n)) return;
+  const i = I(t, e), r = F(i.cuts, n);
+  r !== -1 && r !== i.activeIndex && (b(t, i, r), (s = i.onCutChange) == null || s.call(i, i.cuts[r].cut));
+}
+function Y(t, e) {
+  var s, u, f;
+  if (typeof window > "u" || !t) return () => {
+  };
+  if (!(e != null && e.cuts) || e.cuts.length === 0) return () => {
+  };
+  (u = (s = a.get(t)) == null ? void 0 : s.stop) == null || u.call(s);
+  const n = I(t, e), i = parseFloat(getComputedStyle(t).fontSize);
+  if (Number.isFinite(i)) {
+    const o = F(n.cuts, i);
+    o !== -1 && o !== n.activeIndex && (b(t, n, o), (f = n.onCutChange) == null || f.call(n, n.cuts[o].cut));
+  }
+  if (L(), S.add(t), n.live = !0, typeof ResizeObserver < "u" && ((!l || P !== ResizeObserver) && (l = new ResizeObserver(p), P = ResizeObserver, c.clear()), n.ro = l, n.ro.observe(t), n.observedParent = t.parentElement, n.observedParent)) {
+    const o = c.get(n.observedParent) ?? 0;
+    o === 0 && n.ro.observe(n.observedParent), c.set(n.observedParent, o + 1);
+  }
+  const r = () => {
+    var w, z, h, x, V;
+    if (((w = a.get(t)) == null ? void 0 : w.stop) !== r) return;
+    S.delete(t);
+    const o = a.get(t);
+    if (o != null && o.ro && o.ro === l) {
+      (h = (z = o.ro).unobserve) == null || h.call(z, t);
+      const m = o.observedParent;
+      if (m) {
+        const C = (c.get(m) ?? 1) - 1;
+        C <= 0 ? (c.delete(m), (V = (x = o.ro).unobserve) == null || V.call(x, m)) : c.set(m, C);
+      }
+    }
+    M(t), D();
+  };
+  return n.stop = r, r;
+}
+function _(t) {
+  const e = a.get(t);
+  e && (e.stop ? e.stop() : M(t));
+}
+export {
+  U as applyOpszStepper,
+  _ as removeOpszStepper,
+  Y as startOpszStepper
+};

package/dist/index.cjs

@@ -1 +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;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("./core.cjs"),r=require("react"),g=require("react/jsx-runtime");function l(s){const[n,o]=r.useState(null),i=r.useMemo(()=>{let e=null;return{get current(){return e},set current(t){t!==e&&(e=t,o(t))}}},[]),p=r.useRef(s);p.current=s;const a=JSON.stringify(s.cuts),{hysteresis:f}=s;return r.useLayoutEffect(()=>n?c.startOpszStepper(n,{...p.current,onCutChange:t=>{var S,u;return(u=(S=p.current).onCutChange)==null?void 0:u.call(S,t)}}):void 0,[n,a,f]),i}const z=r.forwardRef(function({children:n,as:o="p",cuts:i,hysteresis:p,onCutChange:a,...f},e){const u=l({cuts:i,hysteresis:p,onCutChange:a}),y=r.useCallback(O=>{u.current=O,typeof e=="function"?e(O):e&&(e.current=O)},[e]);return g.jsx(o,{ref:y,...f,children:n})});z.displayName="OpszStepperText";exports.applyOpszStepper=c.applyOpszStepper;exports.removeOpszStepper=c.removeOpszStepper;exports.startOpszStepper=c.startOpszStepper;exports.OpszStepperText=z;exports.useOpszStepper=l;

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import { default as default_2 } from 'react';
-import { RefObject } from 'react';
+import { MutableRefObject } 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.
+ * One-shot application of the correct optical cut for the element's current computed font-size.
+ * No watching — use when you want manual control. Hysteresis is not applied here.
+ * onCutChange fires only when the cut actually changes.
  *
  * @param el      - Target element
  * @param options - OpszStepperOptions
@@ -115,25 +115,20 @@ declare interface OpszStepperTextProps extends OpszStepperOptions, default_2.HTM
 }
 
 /**
- * Restore the element's original fontFamily and disconnect any running
- * ResizeObserver started by startOpszStepper. No-op if never applied.
+ * Restore the element's original styles and stop watching it. 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.
+ * Start watching an element: applies the correct cut now and again whenever its font-size
+ * changes — from a resize, a class or style change anywhere on the page, or a viewport change.
+ * Calling it again on the same element replaces the earlier watcher.
  *
  * @param el      - Target element
  * @param options - OpszStepperOptions
- * @returns         A stop function that disconnects the observer and restores the original fontFamily
+ * @returns         A stop function that stops watching and restores the element's original styles
  */
 export declare function startOpszStepper(el: HTMLElement, options: OpszStepperOptions): OpszStepperStop;
 
@@ -146,15 +141,14 @@ export declare function startOpszStepper(el: HTMLElement, options: OpszStepperOp
  * 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.
+ * onCutChange is read from the latest render each time it fires, so it doesn't need to be
+ * stable across renders. The stepper follows the element if React replaces it.
  *
  * 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 declare function useOpszStepper(options: OpszStepperOptions): MutableRefObject<HTMLElement | null>;
 
 export { }

package/dist/index.js

@@ -1,114 +1,46 @@
-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;
+import { startOpszStepper as l } from "./core.js";
+import { applyOpszStepper as j, removeOpszStepper as k } from "./core.js";
+import { useState as S, useMemo as O, useRef as y, useLayoutEffect as z, forwardRef as x, useCallback as R } from "react";
+import { jsx as g } from "react/jsx-runtime";
+function C(r) {
+  const [n, o] = S(null), u = O(() => {
+    let e = null;
+    return {
+      get current() {
+        return e;
+      },
+      set current(t) {
+        t !== e && (e = t, o(t));
+      }
+    };
+  }, []), s = y(r);
+  s.current = r;
+  const c = JSON.stringify(r.cuts), { hysteresis: f } = r;
+  return z(() => n ? l(n, {
+    ...s.current,
+    onCutChange: (t) => {
+      var i, p;
+      return (p = (i = s.current).onCutChange) == null ? void 0 : p.call(i, t);
+    }
+  }) : void 0, [n, c, f]), u;
 }
-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);
+const d = x(
+  function({ children: n, as: o = "p", cuts: u, hysteresis: s, onCutChange: c, ...f }, e) {
+    const p = C({ cuts: u, hysteresis: s, onCutChange: c }), m = R(
+      (a) => {
+        p.current = a, typeof e == "function" ? e(a) : e && (e.current = a);
       },
       // eslint-disable-next-line react-hooks/exhaustive-deps
-      [r]
+      [e]
     );
-    return /* @__PURE__ */ F(n, { ref: w, ...a, children: e });
+    return /* @__PURE__ */ g(o, { ref: m, ...f, children: n });
   }
 );
-N.displayName = "OpszStepperText";
+d.displayName = "OpszStepperText";
 export {
-  N as OpszStepperText,
-  v as applyOpszStepper,
-  R as removeOpszStepper,
-  V as startOpszStepper,
-  b as useOpszStepper
+  d as OpszStepperText,
+  j as applyOpszStepper,
+  k as removeOpszStepper,
+  l as startOpszStepper,
+  C as useOpszStepper
 };

package/dist/opszstepper.webflow.min.js

@@ -1 +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})({});
+var OpszStepper=(function(z){"use strict";function R(t){const e=t.filter(o=>o&&typeof o.family=="string"),n=o=>Number.isFinite(o.minSize)?o.minSize:Number.isFinite(o.maxSize)?o.maxSize-1e-9:1/0,s=[...e].sort((o,u)=>n(o)-n(u)),i=s.map((o,u)=>{const c=s[u-1];return{min:Number.isFinite(o.minSize)?o.minSize:c&&Number.isFinite(c.maxSize)?c.maxSize:0,max:Number.isFinite(o.maxSize)?o.maxSize:1/0,cut:o}});for(let o=0;o<i.length-1;o++)i[o].max===1/0&&(i[o].max=i[o+1].min);return i}function C(t,e){for(let n=0;n<t.length;n++)if(e>=t[n].min&&e<t[n].max)return n;return-1}function H(t,e,n,s){const i=C(t,e);if(n===-1||!t[n])return i;if(i===-1||i===n)return n;const o=t[n];return e>=o.max+s||e<o.min-s?i:n}const M=new Set;function O(t){M.has(t)||(M.add(t),console.warn(t))}function L(t,e){let n=t??1;(!Number.isFinite(n)||n<0)&&(O(`[opszStepper] hysteresis must be a non-negative number; got ${t}, using 1`),n=1);const s=Math.min(...e.map(i=>i.max-i.min).filter(i=>Number.isFinite(i)&&i>0));return Number.isFinite(s)&&n>s/2&&(O(`[opszStepper] hysteresis ${n}px is more than half the narrowest cut (${s}px); using ${s/2}px`),n=s/2),n}const l=new Map;function w(t,e){return{value:t.style.getPropertyValue(e),priority:t.style.getPropertyPriority(e)}}function N(t,e,n){n.value?t.style.setProperty(e,n.value,n.priority):t.style.removeProperty(e)}function _(t,e){const n=R(e.cuts),s=L(e.hysteresis,n);let i=l.get(t);return i?(i.cuts=n,i.hysteresis=s,i.onCutChange=e.onCutChange):(i={cuts:n,hysteresis:s,onCutChange:e.onCutChange,activeIndex:-1,origFamily:w(t,"font-family"),origFVS:w(t,"font-variation-settings"),origStyleAttr:t.getAttribute("style"),baseFVS:A(t),writtenFVS:null,writtenStyleAttr:null,live:!1},l.set(t,i)),i}function A(t){const e=getComputedStyle(t);return(typeof e.getPropertyValue=="function"?e.getPropertyValue("font-variation-settings"):e.fontVariationSettings)||"normal"}function D(t,e){const n=`"opsz" ${e}`;if(!t||t==="normal")return n;const s=/(["'])opsz\1\s+-?[\d.eE+-]+/;return s.test(t)?t.replace(s,n):`${t}, ${n}`}function E(t,e,n){const s=e.cuts[n].cut;if(e.writtenFVS!==null&&t.style.getPropertyValue("font-variation-settings")!==e.writtenFVS&&(e.origFVS=w(t,"font-variation-settings"),e.baseFVS=A(t),e.writtenFVS=null),t.style.setProperty("font-family",s.family,e.origFamily.priority),typeof s.opszValue=="number"&&Number.isFinite(s.opszValue)){const i=Number.isFinite(s.opszMin)?s.opszMin:-1/0,o=Number.isFinite(s.opszMax)?s.opszMax:1/0,u=i<=o?Math.min(o,Math.max(i,s.opszValue)):s.opszValue,c=D(e.baseFVS,u);t.style.setProperty("font-variation-settings",c,e.origFVS.priority),e.writtenFVS=t.style.getPropertyValue("font-variation-settings")}else e.writtenFVS!==null&&(N(t,"font-variation-settings",e.origFVS),e.writtenFVS=null);e.activeIndex=n,e.writtenStyleAttr=t.getAttribute("style")}function P(t){const e=l.get(t);e&&(e.writtenStyleAttr!==null&&t.getAttribute("style")===e.writtenStyleAttr?e.origStyleAttr===null?t.removeAttribute("style"):t.setAttribute("style",e.origStyleAttr):(N(t,"font-family",e.origFamily),e.writtenFVS!==null&&N(t,"font-variation-settings",e.origFVS),e.origStyleAttr===null&&!t.getAttribute("style")&&t.removeAttribute("style")),l.delete(t))}const b=new Set;let p=null,I=null;const y=new Map;let S=null,x=!1;function J(){var e;x=!1;const t=[];b.forEach(n=>{const s=l.get(n);if(!s||!n.isConnected)return;const i=parseFloat(getComputedStyle(n).fontSize);if(!Number.isFinite(i))return;const o=H(s.cuts,i,s.activeIndex,s.hysteresis);o!==-1&&o!==s.activeIndex&&t.push([n,s,o])});for(const[n,s,i]of t)E(n,s,i),(e=s.onCutChange)==null||e.call(s,s.cuts[i].cut)}function h(){x||(x=!0,queueMicrotask(J))}function U(){typeof MutationObserver<"u"&&!S&&document.documentElement&&(S=new MutationObserver(h),S.observe(document.documentElement,{attributes:!0,attributeFilter:["class","style","lang","dir"],subtree:!0}),window.addEventListener("resize",h))}function Y(){b.size||(p==null||p.disconnect(),p=null,y.clear(),S==null||S.disconnect(),S=null,typeof window<"u"&&window.removeEventListener("resize",h))}function k(t,e){var o,u,c;if(typeof window>"u"||!t)return()=>{};if(!(e!=null&&e.cuts)||e.cuts.length===0)return()=>{};(u=(o=l.get(t))==null?void 0:o.stop)==null||u.call(o);const n=_(t,e),s=parseFloat(getComputedStyle(t).fontSize);if(Number.isFinite(s)){const r=C(n.cuts,s);r!==-1&&r!==n.activeIndex&&(E(t,n,r),(c=n.onCutChange)==null||c.call(n,n.cuts[r].cut))}if(U(),b.add(t),n.live=!0,typeof ResizeObserver<"u"&&((!p||I!==ResizeObserver)&&(p=new ResizeObserver(h),I=ResizeObserver,y.clear()),n.ro=p,n.ro.observe(t),n.observedParent=t.parentElement,n.observedParent)){const r=y.get(n.observedParent)??0;r===0&&n.ro.observe(n.observedParent),y.set(n.observedParent,r+1)}const i=()=>{var m,v,g,a,d;if(((m=l.get(t))==null?void 0:m.stop)!==i)return;b.delete(t);const r=l.get(t);if(r!=null&&r.ro&&r.ro===p){(g=(v=r.ro).unobserve)==null||g.call(v,t);const f=r.observedParent;if(f){const $=(y.get(f)??1)-1;$<=0?(y.delete(f),(d=(a=r.ro).unobserve)==null||d.call(a,f)):y.set(f,$)}}P(t),Y()};return n.stop=i,i}function W(t){const e=l.get(t);e&&(e.stop?e.stop():P(t))}const j="data-opszstepper",V=new WeakMap;function q(t,e,n,s){const i=[];for(const o of t.split(",")){const u=o.trim();if(!u)continue;const[c,r]=u.split(":");if(r===void 0)continue;const m=parseFloat(r.trim());if(isNaN(m))continue;const[v,g]=c.replace(/[\u2013\u2014]/g,"-").split("-"),a=parseFloat((v??"").trim()),d=parseFloat((g??"").trim()),f={family:e,opszValue:m};isNaN(a)||(f.minSize=a),isNaN(d)||(f.maxSize=d),n!==void 0&&(f.opszMin=n),s!==void 0&&(f.opszMax=s),i.push(f)}return i}function Q(t){if(!Array.isArray(t))return[];const e=[];for(const n of t){if(!n||typeof n!="object")continue;const s=n;if(typeof s.family!="string")continue;const i={family:s.family},o=g=>{const a=s[g];if(a==null)return;const d=typeof a=="number"?a:typeof a=="string"&&a.trim()!==""?Number(a):NaN;if(Number.isFinite(d))return d;console.warn(`OpszStepper: "${g}" in data-os-cuts must be a number; got ${JSON.stringify(a)} — ignoring it.`)},u=o("minSize");u!==void 0&&(i.minSize=u);const c=o("maxSize");c!==void 0&&(i.maxSize=c);const r=o("opszValue");r!==void 0&&(i.opszValue=r);const m=o("opszMin");m!==void 0&&(i.opszMin=m);const v=o("opszMax");v!==void 0&&(i.opszMax=v),e.push(i)}return e}function B(t){const e=t.dataset;let n=[];if(e.osCuts)try{n=Q(JSON.parse(e.osCuts))}catch{console.error("OpszStepper: data-os-cuts is not valid JSON — ignoring.")}if(n.length===0&&e.osFamily&&e.osOpsz){const i=e.osOpszMin!==void 0?parseFloat(e.osOpszMin):void 0,o=e.osOpszMax!==void 0?parseFloat(e.osOpszMax):void 0;n=q(e.osOpsz,e.osFamily,i!==void 0&&!isNaN(i)?i:void 0,o!==void 0&&!isNaN(o)?o:void 0)}const s={cuts:n};if(e.osHysteresis!==void 0){const i=parseFloat(e.osHysteresis);isNaN(i)||(s.hysteresis=i)}return s}function G(t){T(t);const e=B(t);if(e.cuts.length===0){console.warn("OpszStepper: no valid cuts found on element — skipping.");return}const n=k(t,e);V.set(t,{stop:n})}function T(t){const e=V.get(t);if(!e){W(t);return}e.stop(),V.delete(t)}function F(t=document){t.querySelectorAll(`[${j}]`).forEach(G)}function K(t=document){F(t)}function X(){const t=()=>{var e;(e=document.fonts)!=null&&e.ready?document.fonts.ready.then(()=>F()).catch(()=>F()):F()};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",t,{once:!0}):t()}return X(),z.destroy=T,z.init=F,z.restart=K,Object.defineProperty(z,Symbol.toStringTag,{value:"Module"}),z})({});

package/package.json

@@ -1,84 +1,89 @@
-{
-	"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"
-	}
-}
+{
+	"name": "@overpunch/opszstepper",
+	"version": "1.1.0",
+	"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"
+		},
+		"./core": {
+			"types": "./dist/core.d.ts",
+			"import": "./dist/core.js",
+			"require": "./dist/core.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@overpunch.ca>",
+	"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"
+	}
+}