fetta 1.5.3 → 1.5.5

package/README.md

@@ -2,7 +2,24 @@
 
 Text splitting that keeps kerning intact.
 
-Split text into characters, words, and lines while preserving the original typography. Works with any animation library.
+Split text into chars, words, and lines while preserving original typography. `fetta` provides the framework-agnostic `splitText()` API for vanilla and imperative workflows, `fetta/react` is for React lifecycle and callback-based control, and `fetta/motion` is for Motion-first variants and triggers. `fetta/helpers` adds optional utilities for advanced layered effects.
+
+Docs: https://fetta.dimi.me/
+
+## Installation
+
+```bash
+npm install fetta
+```
+
+## Choose Your Entry Point
+
+| Import | Use when | Size (min + brotli) |
+|------|------|------|
+| `fetta` | You want the framework-agnostic core API (`splitText`) | ~7.04 kB |
+| `fetta/react` | You use React and want callback/lifecycle control | ~8.18 kB |
+| `fetta/motion` | You use Motion variants and built-in triggers | ~13.71 kB |
+| `fetta/helpers` | You need optional utilities for layered split effects | ~742 B |
 
 ## Features
 
@@ -14,186 +31,147 @@ Split text into characters, words, and lines while preserving the original typog
 - **Auto Revert** — Restores original HTML after animations
 - **Masking** — Wrap elements in clip containers for reveal animations
 - **Emoji Support** — Properly handles compound emojis and complex Unicode characters
-- **Accessible** — Automatic screen reader support, even when splitting text with nested links or emphasis
+- **Accessible** — Automatic screen reader support, even with nested links or emphasis
 - **TypeScript** — Full type definitions included
-- **React Component** — Declarative wrapper for React projects
-- **Viewport Triggers** — Scroll enter/leave callbacks with configurable thresholds in React
-- **Library Agnostic** — Works with Motion, GSAP, CSS, or any animation library
+- **Library Agnostic** — Works with Motion, GSAP, CSS, WAAPI, or custom animation code
 
-## Installation
+## Quick Start
 
-```bash
-npm install fetta
-```
+### Vanilla JavaScript (`fetta`)
 
-**Bundle size** (minified + brotli)
-- `fetta`: ~7.04 kB
-- `fetta/react`: ~8.21 kB
-- `fetta/motion`: ~13.68 kB
-- `fetta/helpers`: ~742 B
+```ts
+import { splitText } from "fetta";
+import { animate, stagger } from "motion";
 
-## Quick Start
+const element = document.querySelector("h1");
+const { chars } = splitText(element, { type: "chars" });
 
-### Vanilla JavaScript
+animate(chars, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.02) });
+```
 
-```js
-import { splitText } from 'fetta';
-import { animate, stagger } from 'motion';
+### React Callbacks (`fetta/react`)
 
-const { chars, words, lines, revert } = splitText(
-  document.querySelector('h1'),
-  { type: 'chars,words,lines' }
-);
+```tsx
+import { SplitText } from "fetta/react";
+import { animate, stagger } from "motion";
 
-animate(chars, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.02) });
+<SplitText
+  options={{ type: "words" }}
+  onSplit={({ words }) => {
+    animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
+  }}
+>
+  <h1>Hello World</h1>
+</SplitText>;
 ```
 
-### React
+### Motion Variants (`fetta/motion`)
 
 ```tsx
-import { SplitText } from 'fetta/react';
-import { animate, stagger } from 'motion';
+import { SplitText } from "fetta/motion";
+import { stagger } from "motion";
 
-function Hero() {
-  return (
-    <SplitText
-      onSplit={({ words }) => {
-        animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
-      }}
-    >
-      <h1>Hello World</h1>
-    </SplitText>
-  );
-}
+<SplitText
+  variants={{
+    hidden: { words: { opacity: 0, y: 20 } },
+    visible: { words: { opacity: 1, y: 0 } },
+  }}
+  initial="hidden"
+  animate="visible"
+  transition={{ duration: 0.65, delay: stagger(0.04) }}
+  options={{ type: "words" }}
+>
+  <h1>Hello World</h1>
+</SplitText>;
 ```
 
+`fetta/motion` supports standard Motion targets, per-type targets (`chars` / `words` / `lines` / `wrapper`), and split-aware function variants.
+
 ## API
 
-### `splitText(element, options?)`
+### `splitText(element, options?)` (`fetta`)
 
 Splits text content into characters, words, and/or lines.
 
 ```ts
+import { splitText } from "fetta";
+
 const result = splitText(element, options);
 ```
 
 #### Options
 
 | Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `type` | `string` | `"chars,words,lines"` | What to split: `"chars"`, `"words"`, `"lines"`, or combinations |
+|------|------|------|------|
+| `type` | `SplitType` | `"chars,words,lines"` | What to split: `"chars"`, `"words"`, `"lines"`, or combinations |
 | `charClass` | `string` | `"split-char"` | CSS class for character elements |
 | `wordClass` | `string` | `"split-word"` | CSS class for word elements |
 | `lineClass` | `string` | `"split-line"` | CSS class for line elements |
-| `mask` | `string` | — | Wrap elements in `overflow: clip` container: `"chars"`, `"words"`, or `"lines"` |
+| `mask` | `"chars" \| "words" \| "lines"` | — | Wrap elements in `overflow: clip` container |
 | `autoSplit` | `boolean` | `false` | Re-split on container resize |
-| `onResplit` | `function` | — | Callback after autoSplit/full-resplit replaces split output elements |
-| `onSplit` | `function` | — | Callback after initial split. Return animation/promise for `revertOnComplete` |
-| `revertOnComplete` | `boolean` | `false` | Auto-revert when animation completes |
+| `resplitDebounceMs` | `number` | `100` | Debounce delay for autoSplit/full-resplit width updates (`0` disables debounce) |
+| `onResplit` | `(result) => void` | — | Callback after autoSplit/full-resplit replaces split output elements |
+| `onSplit` | `(result) => CallbackReturn` | — | Callback after initial split. Return animation/promise for `revertOnComplete` |
+| `revertOnComplete` | `boolean` | `false` | Auto-revert when returned animation completes |
 | `propIndex` | `boolean` | `false` | Add CSS custom properties: `--char-index`, `--word-index`, `--line-index` |
 | `disableKerning` | `boolean` | `false` | Skip kerning compensation (no margin adjustments) |
 | `initialStyles` | `object` | — | Apply initial inline styles to chars/words/lines after split. Values can be objects or `(el, index) => object` functions |
 | `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines. Values are strings |
 
-#### Return Value
-
 ```ts
-{
-  chars: HTMLSpanElement[];   // Character elements
-  words: HTMLSpanElement[];   // Word elements
-  lines: HTMLSpanElement[];   // Line elements
-  revert: () => void;         // Restore original HTML and cleanup
-}
+type SplitType =
+  | "chars"
+  | "words"
+  | "lines"
+  | "chars,words"
+  | "words,lines"
+  | "chars,lines"
+  | "chars,words,lines";
 ```
 
-### `createSplitClones(splitResult, options)` (`fetta/helpers`)
-
-Builds swap/reveal DOM layers (clones + optional wrappers) without coupling to any animation library.
+#### Return Value
 
 ```ts
-import { splitText } from "fetta";
-import { createSplitClones } from "fetta/helpers";
-
-const split = splitText(element, { type: "chars", mask: "chars" });
-const layers = createSplitClones(split, { unit: "chars", wrap: true });
-
-// Animate with Motion, GSAP, WAAPI, or CSS
-// ...
-
-layers.cleanup(); // removes clones/wrappers, keeps split DOM
-// layers.cleanup({ revertSplit: true }) // also calls split.revert()
+interface SplitTextResult {
+  chars: HTMLSpanElement[];
+  words: HTMLSpanElement[];
+  lines: HTMLSpanElement[];
+  revert: () => void;
+}
 ```
 
-#### Behavior
-
-- Clone is always appended to the **current parent** of the original split node.
-- `wrap: false` (default): clone is appended to existing parent (often the mask wrapper).
-- `wrap: true`: original is first moved into a track wrapper, then clone is appended there.
-- Helper never calls `splitText` and never performs animation.
-
-#### Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `unit` | `"chars" \| "words" \| "lines"` | — | Which split nodes to layer |
-| `wrap` | `boolean` | `false` | Wrap each original in a track wrapper (`position: relative`) |
-| `display` | `"auto" \| "inline-block" \| "block"` | `"auto"` | Track display when `wrap: true` (`lines` => `block`, others => `inline-block`) |
-| `cloneOffset.axis` | `"x" \| "y"` | `"y"` | Axis used for initial clone offset |
-| `cloneOffset.direction` | `"start" \| "end"` | `"start"` | Offset direction (`start` => negative) |
-| `cloneOffset.distance` | `string` | `"100%"` | Offset distance |
-| `trackClassName` / `cloneClassName` | `string \| (ctx) => string \| undefined` | — | Class names (static or per-item) |
-| `trackStyle` / `cloneStyle` | `object \| (ctx) => object` | — | Inline styles (static or per-item) |
-
-For reveal/swap effects, use matching `mask` in `splitText` (`"chars"`, `"words"`, or `"lines"`).
-
-### `<SplitText>` (React)
+### `<SplitText>` (`fetta/react`)
 
 ```tsx
-import { SplitText } from 'fetta/react';
+import { SplitText } from "fetta/react";
 ```
 
-`fetta/react` forwards common wrapper DOM props (`id`, `role`, `tabIndex`, `aria-*`, `data-*`, and event handlers like `onClick`) to the wrapper element.
-
-`fetta/react` props:
+`fetta/react` wraps `splitText()` for React with lifecycle hooks, viewport callbacks, and automatic cleanup.
 
 #### React Props
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+|------|------|------|------|
 | `children` | `ReactElement` | — | Single React element to split |
 | `as` | `keyof JSX.IntrinsicElements` | `"div"` | Wrapper element type |
-| `className` | `string` | — | Class name for wrapper element |
-| `style` | `CSSProperties` | — | Additional styles for wrapper element |
-| `ref` | `Ref<HTMLElement>` | — | Ref to container element |
-| `onSplit` | `(result) => CallbackReturn` | — | Called after text is split |
+| `className` | `string` | — | Wrapper class name |
+| `style` | `CSSProperties` | — | Wrapper styles |
+| `ref` | `Ref<HTMLElement>` | — | Ref to wrapper element |
+| `onSplit` | `(result) => CallbackReturn` | — | Called after initial split |
 | `onResplit` | `(result) => void` | — | Called when autoSplit/full-resplit replaces split output elements |
-| `options` | `SplitTextOptions` | — | Split options (type, classes, mask, propIndex, disableKerning) |
+| `options` | `SplitTextOptions` | — | Split options (`type`, classes, mask, debounce, etc.) |
 | `autoSplit` | `boolean` | `false` | Re-split on container resize |
-| `waitForFonts` | `boolean` | `true` | Wait for `document.fonts.ready` before splitting (recommended for stable kerning). Set `false` for immediate split. |
+| `waitForFonts` | `boolean` | `true` | Wait for `document.fonts.ready` before splitting |
 | `revertOnComplete` | `boolean` | `false` | Revert after animation completes |
-| `onRevert` | `() => void` | — | Called when split text is reverted (manual or automatic) |
+| `onRevert` | `() => void` | — | Called when split text reverts |
 | `viewport` | `ViewportOptions` | — | Configure viewport detection |
-| `onViewportEnter` | `(result) => CallbackReturn` | — | Called when element enters viewport |
-| `onViewportLeave` | `(result) => CallbackReturn` | — | Called when element leaves viewport |
-| `initialStyles` | `object` | — | Apply initial inline styles to chars/words/lines. Values can be objects or `(el, index) => object` functions |
-| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines. Values are strings |
-| `resetOnViewportLeave` | `boolean` | `false` | Re-apply initialStyles/initialClasses when leaving viewport |
+| `onViewportEnter` | `(result) => CallbackReturn` | — | Called when entering viewport |
+| `onViewportLeave` | `(result) => CallbackReturn` | — | Called when leaving viewport |
+| `initialStyles` | `object` | — | Apply initial inline styles to chars/words/lines |
+| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines |
+| `resetOnViewportLeave` | `boolean` | `false` | Re-apply initial styles/classes when leaving viewport |
 
-#### Shared `SplitTextOptions` (`options` prop)
-
-| Option | Type | Default | Description |
-|------|------|---------|-------------|
-| `type` | `SplitType` | `"chars,words,lines"` | What to split: `"chars"`, `"words"`, `"lines"`, or combinations |
-| `charClass` | `string` | `"split-char"` | CSS class for character spans |
-| `wordClass` | `string` | `"split-word"` | CSS class for word spans |
-| `lineClass` | `string` | `"split-line"` | CSS class for line spans |
-| `mask` | `"lines" \| "words" \| "chars"` | — | Wrap elements in `overflow: clip` mask containers |
-| `propIndex` | `boolean` | `false` | Add CSS index variables (`--char-index`, `--word-index`, `--line-index`) |
-| `disableKerning` | `boolean` | `false` | Skip kerning compensation (no margin adjustments) |
-
-#### Callback Signature
-
-All callbacks (`onSplit`, `onResplit`, `onViewportEnter`, `onViewportLeave`) receive:
+All callbacks receive:
 
 ```ts
 {
@@ -213,314 +191,118 @@ type CallbackReturn =
   | CallbackReturn[];
 ```
 
-When using `autoSplit` with `lines` in scroll-linked or scroll-triggered animations, re-attach scroll/timeline logic inside `onResplit` so it binds to the new split element references.
-
-`onRevert` is a separate zero-argument callback that fires when a split cycle actually reverts.
-
-#### Viewport Options
-
-```ts
-{
-  amount?: number | "some" | "all"; // Enter threshold, default: 0
-  leave?: number | "some" | "all";  // Leave threshold, default: 0
-  margin?: string;                  // Root margin, default: "0px"
-  once?: boolean;                   // Only trigger once, default: false
-  root?: RefObject<Element>;        // Optional root element
-}
-```
+`fetta/react` and `fetta/motion` both forward common wrapper DOM props (`id`, `role`, `tabIndex`, `aria-*`, `data-*`, event handlers) to the wrapper.
 
-### `<SplitText>` (Motion)
+### `<SplitText>` (`fetta/motion`)
 
 ```tsx
 import { SplitText } from "fetta/motion";
 ```
 
-`fetta/motion` includes all props from `fetta/react`, plus Motion variant props. It also forwards standard Motion/DOM wrapper props (`id`, `role`, `tabIndex`, `layout`, `drag`, `data-*`, etc.) to the wrapper.
-
-Animate on exit with Motion's `AnimatePresence` (make `SplitText` the direct child):
-
-```tsx
-import { AnimatePresence } from "motion/react";
-
-<AnimatePresence>
-  {isVisible && (
-    <SplitText
-      variants={{
-        enter: { opacity: 1, y: 0 },
-        exit: { opacity: 0, y: 12 },
-      }}
-      initial="enter"
-      animate="enter"
-      exit="exit"
-      options={{ type: "words" }}
-    >
-      <h1>Goodbye</h1>
-    </SplitText>
-  )}
-</AnimatePresence>
-```
+Variant-driven component built on Motion. Includes every `fetta/react` prop plus Motion animation/triggers (`initial`, `animate`, `exit`, `whileInView`, `whileScroll`, `whileHover`, etc.).
 
 #### Motion-only Props
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+|------|------|------|------|
 | `variants` | `Record<string, VariantDefinition<TCustom>>` | — | Named variant definitions |
 | `initial` | `string \| VariantDefinition<TCustom> \| false` | — | Initial variant applied instantly after split |
 | `animate` | `string \| VariantDefinition<TCustom>` | — | Base variant |
-| `exit` | `string \| VariantDefinition<TCustom> \| false` | — | Exit variant (AnimatePresence) |
+| `exit` | `string \| VariantDefinition<TCustom> \| false` | — | Exit variant (`AnimatePresence`) |
 | `whileInView` | `string \| VariantDefinition<TCustom>` | — | Variant while element is in view |
 | `whileOutOfView` | `string \| VariantDefinition<TCustom>` | — | Variant after element leaves view |
 | `whileScroll` | `string \| VariantDefinition<TCustom>` | — | Scroll-driven variant (highest trigger priority) |
 | `whileHover` | `string \| VariantDefinition<TCustom>` | — | Variant on hover |
 | `whileTap` | `string \| VariantDefinition<TCustom>` | — | Variant on tap/press |
 | `whileFocus` | `string \| VariantDefinition<TCustom>` | — | Variant on focus |
-| `animateOnResplit` | `boolean` | `false` | Replay initial->animate on autoSplit/full-resplit |
+| `animateOnResplit` | `boolean` | `false` | Replay `initial -> animate` on autoSplit/full-resplit |
 | `scroll` | `{ offset?, axis?, container? }` | — | Scroll tracking options for `whileScroll` |
 | `transition` | `AnimationOptions` | — | Global/default transition for variants |
 | `custom` | `TCustom` | — | Custom data forwarded to function variants |
-| `delayScope` | `"global" \| "local"` | `"global"` | Delay-function index scope (`globalIndex` vs relative `index`) |
-| `reducedMotion` | `"user" \| "always" \| "never"` | — | Reduced-motion behavior for this component |
+| `delayScope` | `"global" \| "local"` | `"global"` | Delay-function index scope (`globalIndex` vs local `index`) |
+| `reducedMotion` | `"user" \| "always" \| "never"` | `"never"` | Reduced-motion behavior for this component |
 | `onHoverStart` | `() => void` | — | Called when hover starts |
 | `onHoverEnd` | `() => void` | — | Called when hover ends |
 
-## Examples
-
-### Vanilla JavaScript
-
-#### Basic
-
-```js
-import { splitText } from 'fetta';
-import { animate, stagger } from 'motion';
-
-const { words } = splitText(document.querySelector('h1'));
-
-animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
-```
-
-#### Masked Line Reveal
-
-```js
-splitText(element, {
-  type: 'lines',
-  mask: 'lines',
-  onSplit: ({ lines }) => {
-    animate(lines, { y: ['100%', '0%'] }, { delay: stagger(0.1) });
-  }
-});
-```
-
-#### With GSAP
-
-```js
-import { splitText } from 'fetta';
-import gsap from 'gsap';
-
-splitText(element, {
-  revertOnComplete: true,
-  onSplit: ({ words }) => {
-    return gsap.from(words, {
-      opacity: 0,
-      y: 20,
-      stagger: 0.05,
-      duration: 0.6,
-    });
-  }
-});
-```
-
-#### CSS-Only with Index Props
-
-```js
-splitText(element, { type: 'chars', propIndex: true });
-```
-
-```css
-.split-char {
-  opacity: 0;
-  animation: fade-in 0.5s forwards;
-  animation-delay: calc(var(--char-index) * 0.03s);
-}
-
-@keyframes fade-in {
-  to { opacity: 1; }
-}
-```
-
-### React
-
-#### Basic
-
-```tsx
-<SplitText
-  onSplit={({ words }) => {
-    animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
-  }}
->
-  <h1>Hello World</h1>
-</SplitText>
-```
-
-#### Masked Line Reveal
-
-```tsx
-<SplitText
-  options={{ type: 'lines', mask: 'lines' }}
-  onSplit={({ lines }) => {
-    animate(lines, { y: ['100%', '0%'] }, { delay: stagger(0.1) });
-  }}
->
-  <p>Each line reveals from below</p>
-</SplitText>
-```
-
-#### Scroll-Triggered with Viewport
+Exit animations use standard Motion behavior (`SplitText` must be a direct child of `AnimatePresence`):
 
 ```tsx
-<SplitText
-  options={{ type: 'words' }}
-  initialStyles={{
-    words: { opacity: '0', transform: 'translateY(20px)' }
-  }}
-  viewport={{ amount: 0.5 }}
-  onViewportEnter={({ words }) => {
-    animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.03) });
-  }}
-  resetOnViewportLeave
->
-  <p>Animates when scrolled into view</p>
-</SplitText>
-```
-
-#### Auto-Revert After Animation
+import { AnimatePresence } from "motion/react";
+import { SplitText } from "fetta/motion";
 
-```tsx
-<SplitText
-  revertOnComplete
-  onSplit={({ chars }) => {
-    return animate(chars, { opacity: [0, 1] }, { delay: stagger(0.02) });
-  }}
->
-  <h1>Reverts to original HTML after animation</h1>
-</SplitText>
+<AnimatePresence>
+  {isVisible && (
+    <SplitText
+      variants={{
+        enter: { opacity: 1, y: 0 },
+        exit: { opacity: 0, y: 12 },
+      }}
+      initial="enter"
+      animate="enter"
+      exit="exit"
+      options={{ type: "words" }}
+    >
+      <h1>Goodbye</h1>
+    </SplitText>
+  )}
+</AnimatePresence>;
 ```
 
-### Motion (`fetta/motion`)
+### `createSplitClones(splitResult, options)` (`fetta/helpers`, optional)
 
-#### Basic Variants
+Helpers are optional utilities for advanced layered reveal/swap effects.
 
-```tsx
-import { SplitText } from 'fetta/motion';
-import { stagger } from 'motion';
-
-<SplitText
-  variants={{
-    hidden: { opacity: 0, y: 20, filter: 'blur(6px)' },
-    visible: { opacity: 1, y: 0, filter: 'blur(0px)' },
-  }}
-  initial="hidden"
-  animate="visible"
-  transition={{ duration: 0.6, delay: stagger(0.04) }}
-  options={{ type: 'words' }}
->
-  <h1>Hello World</h1>
-</SplitText>
-```
-
-#### Line-Aware Stagger
-
-```tsx
-import { SplitText } from 'fetta/motion';
-import { stagger } from 'motion';
+```ts
+import { splitText } from "fetta";
+import { createSplitClones } from "fetta/helpers";
 
-<SplitText
-  delayScope="local"
-  variants={{
-    hidden: { chars: { opacity: 0 } },
-    visible: {
-      chars: ({ lineIndex }) => ({
-        opacity: 1,
-        transition: {
-          duration: 0.3,
-          delay: stagger(0.015, {
-            startDelay: lineIndex * 0.2,
-            from: lineIndex % 2 === 0 ? "first" : "last",
-          }),
-        },
-      }),
-    },
-  }}
-  initial="hidden"
-  animate="visible"
-  options={{ type: "chars,lines" }}
->
-  <p>Line-aware per-character animation</p>
-</SplitText>
+const split = splitText(element, { type: "chars", mask: "chars" });
+const layers = createSplitClones(split, { unit: "chars", wrap: true });
 ```
 
-#### Scroll-Driven Reveal
-
-```tsx
-import { SplitText } from 'fetta/motion';
+#### Helper Options
 
-<SplitText
-  initialStyles={{ chars: { opacity: 0.2 } }}
-  whileScroll={{
-    chars: ({ globalIndex }) => ({
-      opacity: 1,
-      transition: {
-        duration: 0.3,
-        at: globalIndex * 0.025,
-        ease: "linear",
-      },
-    }),
-  }}
-  scroll={{ offset: ["start 90%", "start 10%"] }}
-  options={{ type: "chars" }}
->
-  <p>Characters fade in with scroll progress</p>
-</SplitText>
-```
+| Option | Type | Default | Description |
+|------|------|------|------|
+| `unit` | `"chars" \| "words" \| "lines"` | — | Which split nodes to layer |
+| `wrap` | `boolean` | `false` | Wrap each original in a track wrapper (`position: relative`) |
+| `display` | `"auto" \| "inline-block" \| "block"` | `"auto"` | Track display when `wrap: true` (`lines` => `block`, others => `inline-block`) |
+| `cloneOffset.axis` | `"x" \| "y"` | `"y"` | Axis used for initial clone offset |
+| `cloneOffset.direction` | `"start" \| "end"` | `"start"` | Offset direction (`start` => negative) |
+| `cloneOffset.distance` | `string` | `"100%"` | Offset distance |
+| `trackClassName` / `cloneClassName` | `string \| (ctx) => string \| undefined` | — | Class names (static or per-item) |
+| `trackStyle` / `cloneStyle` | `object \| (ctx) => object` | — | Inline styles (static or per-item) |
 
-#### Hover Interaction
+#### Helper Behavior
 
-```tsx
-import { SplitText } from 'fetta/motion';
-import { stagger } from 'motion';
+- Helper does not call `splitText()`; pass an existing split result.
+- Clone is appended to the current parent of each original split node.
+- `wrap: false` appends clone to existing parent.
+- `wrap: true` moves original into a generated track, then appends clone there.
+- `cleanup()` removes helper-created tracks/clones and is idempotent.
+- `cleanup({ revertSplit: true })` also calls `split.revert()`.
 
-<SplitText
-  variants={{
-    rest: { chars: { opacity: 0.85, y: 0 } },
-    hover: { chars: { opacity: 1, y: -6 } },
-  }}
-  initial="rest"
-  animate="rest"
-  whileHover="hover"
-  transition={{ duration: 0.25, delay: stagger(0.01) }}
-  options={{ type: 'chars' }}
->
-  <p>Hover this text</p>
-</SplitText>
-```
+For reveal/swap effects, match helper `unit` with `splitText` `mask` (`"chars"`, `"words"`, `"lines"`).
 
 ## CSS Classes
 
-Default classes applied to split elements:
+Default classes applied to split output:
 
-| Class | Element | Notes |
-|-------|---------|-------|
-| `.split-char` | Characters | Inline positioning |
-| `.split-word` | Words | Inline positioning |
-| `.split-line` | Lines | Block display |
+| Class | Element |
+|------|------|
+| `.split-char` | Character span |
+| `.split-word` | Word span |
+| `.split-line` | Line span |
 
-Split elements receive typed index attributes:
-- Characters: `data-char-index`
-- Words: `data-word-index`
-- Lines: `data-line-index`
+Split elements receive index attributes:
+
+- `data-char-index`
+- `data-word-index`
+- `data-line-index`
 
 ## Font Loading
 
-For accurate kerning measurements, fonts must be fully loaded before splitting. When using custom fonts in vanilla JS, wait for `document.fonts.ready`:
+For stable kerning measurements in vanilla usage, wait for fonts before splitting:
 
 ```ts
 document.fonts.ready.then(() => {
@@ -529,63 +311,45 @@ document.fonts.ready.then(() => {
 });
 ```
 
-React and Motion components wait for fonts by default (`waitForFonts={true}`), which gives the most stable kerning.
-
-If you notice a visual shift after splitting, keep the default waiting behavior enabled.
-
-If you need immediate splitting (for example, responsiveness-first UI), you can opt out with `waitForFonts={false}`:
-
-```tsx
-<SplitText waitForFonts={false}>
-  <h1>Split Immediately</h1>
-</SplitText>
-```
+React and Motion components wait for fonts by default (`waitForFonts={true}`).
 
 ## Accessibility
 
-Fetta automatically handles accessibility to ensure split text remains readable by screen readers.
-
-**Headings and landmarks** — For elements that support `aria-label` natively (headings, `<section>`, `<nav>`, etc.), Fetta adds `aria-hidden="true"` to each split span and an `aria-label` on the parent:
+Fetta keeps split text readable by screen readers:
 
-```html
-<!-- After splitting <h1>Hello World</h1> -->
-<h1 aria-label="Hello World">
-  <span class="split-word" aria-hidden="true">Hello</span>
-  <span class="split-word" aria-hidden="true">World</span>
-</h1>
-```
-
-**Generic elements and nested content** — For `<span>`, `<div>`, `<p>`, or text containing inline elements like links, Fetta wraps the visual content with `aria-hidden="true"` and adds a screen-reader-only copy that preserves the semantic structure:
-
-```html
-<!-- After splitting <p>Click <a href="/signup">here</a> to start</p> -->
-<p>
-  <span aria-hidden="true" data-fetta-visual="true">
-    <!-- Split visual content -->
-  </span>
-  <span class="fetta-sr-only" data-fetta-sr-copy="true">
-    Click <a href="/signup">here</a> to start
-  </span>
-</p>
-```
-
-Pre-existing `aria-label` attributes are always preserved.
+- Headings/landmarks: split nodes are hidden from assistive tech and parent gets `aria-label`.
+- Generic/nested content: visual split output is hidden and a screen-reader copy preserves semantics.
+- Existing `aria-label` values are preserved.
 
 ## Notes
 
-- **Ligatures are disabled** (`font-variant-ligatures: none`) because ligatures cannot span multiple elements.
-- **Authored hard breaks are preserved** — Explicit `<br>` and block-level descendants are treated as hard boundaries. In `chars`/`words` modes, hard boundaries are normalized to `<br>` in the split output.
+- Ligatures are disabled (`font-variant-ligatures: none`) because ligatures cannot span multiple elements.
+- Authored hard breaks are preserved (`<br>` and block boundaries are kept as hard split boundaries).
+- `autoSplit` width resplits are debounced by default (`100ms`), configurable via `resplitDebounceMs`.
 
 ## Browser Support
 
 All modern browsers: Chrome, Firefox, Safari, Edge.
 
 Requires:
+
 - `ResizeObserver`
 - `IntersectionObserver`
 - `Intl.Segmenter`
 
-**Safari note** — Kerning compensation works but may be slightly less accurate due to Safari's unique font rendering. Differences are typically imperceptible and vary by font, but if you're using `revert()` and notice a subtle shift in some characters, you can bypass compensation with `disableKerning: true`.
+Safari kerning compensation works, but font rendering precision can vary slightly by font. If you notice subtle shifts around `revert()`, use `disableKerning: true`.
+
+## Docs
+
+- https://fetta.dimi.me/
+- https://fetta.dimi.me/installation
+- https://fetta.dimi.me/api/core
+- https://fetta.dimi.me/api/react
+- https://fetta.dimi.me/api/motion
+- https://fetta.dimi.me/api/helpers
+- https://fetta.dimi.me/examples/vanilla
+- https://fetta.dimi.me/examples/react
+- https://fetta.dimi.me/examples/motion
 
 ## License
 

package/dist/{chunk-OUXSJF3P.js → chunk-44MU2I5B.js}

@@ -470,6 +470,13 @@ var ARIA_LABEL_ALLOWED_TAGS = /* @__PURE__ */ new Set([
   "footer",
   "main"
 ]);
+var DEFAULT_RESPLIT_DEBOUNCE_MS = 100;
+function resolveResplitDebounceMs(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return DEFAULT_RESPLIT_DEBOUNCE_MS;
+  }
+  return value;
+}
 function splitTextData(element, rawOptions = {}) {
   const options = rawOptions;
   const {
@@ -1378,6 +1385,7 @@ function splitText(element, rawOptions = {}) {
     lineClass = "split-line",
     mask,
     autoSplit = false,
+    resplitDebounceMs,
     onResplit,
     onSplit,
     revertOnComplete = false,
@@ -1387,6 +1395,7 @@ function splitText(element, rawOptions = {}) {
     initialClasses
   } = options;
   const isolateKerningMeasurement = options.isolateKerningMeasurement !== false;
+  const resolvedResplitDebounceMs = resolveResplitDebounceMs(resplitDebounceMs);
   if (!(element instanceof HTMLElement)) {
     throw new Error("splitText: element must be an HTMLElement");
   }
@@ -1717,8 +1726,16 @@ function splitText(element, rawOptions = {}) {
         lastChangedTarget = changedTarget;
         if (autoSplitDebounceTimer) {
           clearTimeout(autoSplitDebounceTimer);
+          autoSplitDebounceTimer = null;
         }
-        autoSplitDebounceTimer = setTimeout(handleResize, 100);
+        if (resolvedResplitDebounceMs <= 0) {
+          handleResize();
+          return;
+        }
+        autoSplitDebounceTimer = setTimeout(
+          handleResize,
+          resolvedResplitDebounceMs
+        );
       });
       targets.forEach((target) => {
         autoSplitObserver.observe(target);

package/dist/helpers.d.ts

@@ -1,4 +1,4 @@
-import { S as SplitTextResult } from './index-c1UKfWWK.js';
+import { S as SplitTextResult } from './index-Box92Sue.js';
 
 type SplitUnit = "chars" | "words" | "lines";
 type StyleInput = Partial<CSSStyleDeclaration> | ((ctx: {

package/dist/{index-c1UKfWWK.d.ts → index-Box92Sue.d.ts}

@@ -32,6 +32,8 @@ interface SplitTextOptions {
     mask?: "lines" | "words" | "chars";
     /** Auto-split on resize (observes parent element) */
     autoSplit?: boolean;
+    /** Debounce delay for autoSplit/full-resplit width updates in milliseconds (`0` disables debounce). */
+    resplitDebounceMs?: number;
     /** Callback when autoSplit/full-resplit replaces split output elements */
     onResplit?: (result: Omit<SplitTextResult, "revert" | "dispose">) => void;
     /** Callback fired after text is split, receives split elements. Return animation for revertOnComplete. */

package/dist/index.d.ts

@@ -1 +1 @@
-export { a as SplitTextOptions, S as SplitTextResult, s as splitText } from './index-c1UKfWWK.js';
+export { a as SplitTextOptions, S as SplitTextResult, s as splitText } from './index-Box92Sue.js';

package/dist/index.js

@@ -1 +1 @@
-export { splitText } from './chunk-OUXSJF3P.js';
+export { splitText } from './chunk-44MU2I5B.js';

package/dist/motion.d.ts

@@ -2,8 +2,8 @@ import { I as InitialStyles, a as InitialClasses } from './initialStyles-BGuPp5C
 import { DOMKeyframesDefinition, AnimationOptions, scroll } from 'motion';
 import { HTMLMotionProps } from 'motion/react';
 import { ReactElement, RefAttributes } from 'react';
-import { A as AnimationCallbackReturn } from './index-c1UKfWWK.js';
-export { a as CoreSplitTextOptions, S as SplitTextResult } from './index-c1UKfWWK.js';
+import { A as AnimationCallbackReturn } from './index-Box92Sue.js';
+export { a as CoreSplitTextOptions, S as SplitTextResult } from './index-Box92Sue.js';
 
 interface SplitTextOptions {
     type?: "chars" | "words" | "lines" | "chars,words" | "words,lines" | "chars,lines" | "chars,words,lines";
@@ -12,6 +12,8 @@ interface SplitTextOptions {
     lineClass?: string;
     /** Apply overflow mask wrapper to elements for reveal animations */
     mask?: "lines" | "words" | "chars";
+    /** Debounce delay for autoSplit/full-resplit width updates in milliseconds (`0` disables debounce). */
+    resplitDebounceMs?: number;
     propIndex?: boolean;
     /** Skip kerning compensation (no margin adjustments applied).
      * Kerning is naturally lost when splitting into inline-block spans.

package/dist/motion.js

@@ -1,9 +1,16 @@
 import { waitForFontsReady, createViewportObserver, reapplyInitialStyles, reapplyInitialClasses } from './chunk-PA22PLRB.js';
-import { splitTextData, buildLineFingerprintFromData, normalizeToPromise, buildKerningStyleKey, resolveAutoSplitTargets, getObservedWidth, recordWidthChange, resolveAutoSplitWidth, querySplitWords, clearKerningCompensation, applyKerningCompensation } from './chunk-OUXSJF3P.js';
+import { splitTextData, buildLineFingerprintFromData, normalizeToPromise, buildKerningStyleKey, resolveAutoSplitTargets, getObservedWidth, recordWidthChange, resolveAutoSplitWidth, querySplitWords, clearKerningCompensation, applyKerningCompensation } from './chunk-44MU2I5B.js';
 import { scroll, animate } from 'motion';
 import { usePresence, useReducedMotion, MotionConfig, motion } from 'motion/react';
 import { forwardRef, useRef, useState, useCallback, useMemo, useLayoutEffect, isValidElement, useEffect, createElement, cloneElement } from 'react';
 
+var DEFAULT_RESPLIT_DEBOUNCE_MS = 100;
+function resolveResplitDebounceMs(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return DEFAULT_RESPLIT_DEBOUNCE_MS;
+  }
+  return value;
+}
 var ELEMENT_TYPE_KEYS = ["chars", "words", "lines"];
 var VOID_HTML_TAGS = /* @__PURE__ */ new Set(["br", "hr", "img", "input", "meta", "link"]);
 function isPerTypeVariant(v) {
@@ -1097,6 +1104,15 @@ var SplitText = forwardRef(function SplitText2({
     }
     return safeFallbackWidth;
   }, []);
+  const lockCurrentRenderedLines = useCallback((root) => {
+    const lineClass = optionsRef.current?.lineClass ?? "split-line";
+    const classTokens = lineClass.split(/\s+/).filter(Boolean);
+    if (classTokens.length === 0) return;
+    const selector = `.${classTokens.join(".")}`;
+    root.querySelectorAll(selector).forEach((line) => {
+      line.style.whiteSpace = "nowrap";
+    });
+  }, []);
   useEffect(() => {
     if (!childElement) return;
     if (hasSplitRef.current) return;
@@ -1526,6 +1542,7 @@ var SplitText = forwardRef(function SplitText2({
           clearTimeout(resizeTimerRef.current);
           resizeTimerRef.current = null;
         }
+        lockCurrentRenderedLines(currentElement);
         pendingFullResplitRef.current = true;
         let resplitWidth;
         const targets = resolveAutoSplitTargets(currentElement);
@@ -1607,6 +1624,7 @@ var SplitText = forwardRef(function SplitText2({
     autoSplit,
     childTreeVersion,
     data,
+    lockCurrentRenderedLines,
     measureAndSetData,
     resolveLineMeasureWidth
   ]);
@@ -1707,14 +1725,28 @@ var SplitText = forwardRef(function SplitText2({
       }
       if (resizeTimerRef.current) {
         clearTimeout(resizeTimerRef.current);
+        resizeTimerRef.current = null;
+      }
+      const debounceMs = resolveResplitDebounceMs(
+        optionsRef.current?.resplitDebounceMs
+      );
+      if (debounceMs <= 0) {
+        lockCurrentRenderedLines(child2);
+        pendingFullResplitRef.current = true;
+        measureAndSetData(
+          true,
+          splitLines ? lineMeasureWidth : currentWidth
+        );
+        return;
       }
       resizeTimerRef.current = setTimeout(() => {
+        lockCurrentRenderedLines(child2);
         pendingFullResplitRef.current = true;
         measureAndSetData(
           true,
           splitLines ? lineMeasureWidth : currentWidth
         );
-      }, 100);
+      }, debounceMs);
     };
     resizeObserverRef.current = new ResizeObserver((entries) => {
       let changed = false;
@@ -1755,6 +1787,7 @@ var SplitText = forwardRef(function SplitText2({
   }, [
     autoSplit,
     data,
+    lockCurrentRenderedLines,
     measureAndSetData,
     measureLineFingerprintForWidth,
     resolveLineMeasureWidth

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactElement } from 'react';
-import { A as AnimationCallbackReturn } from './index-c1UKfWWK.js';
-export { a as CoreSplitTextOptions, S as SplitTextResult } from './index-c1UKfWWK.js';
+import { A as AnimationCallbackReturn } from './index-Box92Sue.js';
+export { a as CoreSplitTextOptions, S as SplitTextResult } from './index-Box92Sue.js';
 import { I as InitialStyles, a as InitialClasses } from './initialStyles-BGuPp5CS.js';
 
 interface SplitTextOptions {
@@ -11,6 +11,8 @@ interface SplitTextOptions {
     lineClass?: string;
     /** Apply overflow mask wrapper to elements for reveal animations */
     mask?: "lines" | "words" | "chars";
+    /** Debounce delay for autoSplit/full-resplit width updates in milliseconds (`0` disables debounce). */
+    resplitDebounceMs?: number;
     propIndex?: boolean;
     /** Skip kerning compensation (no margin adjustments applied).
      * Kerning is naturally lost when splitting into inline-block spans.

package/dist/react.js

@@ -1,5 +1,5 @@
 import { waitForFontsReady, createViewportObserver, reapplyInitialStyles, reapplyInitialClasses } from './chunk-PA22PLRB.js';
-import { splitText, normalizeToPromise } from './chunk-OUXSJF3P.js';
+import { splitText, normalizeToPromise } from './chunk-44MU2I5B.js';
 import { forwardRef, useRef, useCallback, useState, useLayoutEffect, useEffect, isValidElement, createElement } from 'react';
 
 var SplitText = forwardRef(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fetta",
-  "version": "1.5.3",
+  "version": "1.5.5",
   "description": "Text splitting library with kerning compensation for animations",
   "type": "module",
   "sideEffects": false,