slot-text 0.3.2 → 0.3.3

package/README.md

@@ -55,6 +55,17 @@ label.flash("Copied", { enter: { color: chromatic() } });
 
 That's it — import the CSS once, attach to an element, roll text.
 
+## 🧪 Try it locally
+
+The included playground has one button that flashes `Copy` → `Copied` → `Copy`.
+
+```bash
+npm run build
+python3 -m http.server
+```
+
+Open [http://localhost:8000/examples/basic/](http://localhost:8000/examples/basic/).
+
 ## 🧩 API
 
 | Method | What it does |
@@ -176,7 +187,8 @@ font, so widths are always correct.
 - Kerning is lost — pairs like `AV` sit slightly looser (invisible at label sizes).
 - Ligatures won't form (`fi`, `fl`, coding ligatures).
 - Joined scripts (Arabic, Devanagari) render as isolated forms.
-- ZWJ emoji sequences (👨‍👩‍👧) split into cells; single emoji are fine.
+- Grapheme clusters such as combining marks and ZWJ emoji stay together when
+  `Intl.Segmenter` is available; older browsers fall back to Unicode code points.
 - Very tall display fonts may clip at the roll mask (`line-height: 1.3`).
 
 **In short:** ideal for short labels, numbers, statuses and commands — in
@@ -188,4 +200,6 @@ essentially any font you'd use for those.
 - React, Vue, Solid, and Svelte are optional peer dependencies — plain JS users
   don't need them.
 - Import the CSS once before using the animation.
+- If the stylesheet loads late, labels stay as plain readable text and upgrade
+  to slot animation once the required layout styles become available.
 - Low-level helpers also exported: `buildSlotText`, `animateSlotText`, `chromatic`.

package/dist/constants.d.ts

@@ -0,0 +1,56 @@
+export declare const TUNING: {
+    readonly animation: {
+        readonly direction: "down";
+        readonly stagger: 45;
+        readonly duration: 300;
+        readonly exitOffset: 50;
+        readonly easing: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+        readonly bounce: 0.6;
+        readonly colorFade: 280;
+        readonly skipUnchanged: true;
+        readonly interrupt: true;
+    };
+    readonly variation: {
+        readonly indexFrequency: 12.9898;
+        readonly channelFrequency: 78.233;
+        readonly seedScale: 43758.5453;
+        readonly durationChannel: 1;
+        readonly staggerChannel: 2;
+        readonly tiltChannel: 3;
+    };
+    readonly glyph: {
+        readonly tailDurationMultiplier: 0.75;
+        readonly durationVariationStrength: 0.45;
+        readonly tailStaggerStartMultiplier: 0.5;
+        readonly tailStaggerStepMultiplier: 0.25;
+        readonly staggerVariationStrength: 0.25;
+        readonly maximumTiltDegrees: 5;
+        readonly tiltDecimalPlaces: 2;
+    };
+    readonly width: {
+        readonly tailCollapseDelayMultiplier: 0.55;
+        readonly tailCollapseDurationMultiplier: 0.6;
+        readonly newSlotExpansionDurationMultiplier: 0.45;
+        readonly minimumTransitionMs: 140;
+        readonly resizeEasing: "cubic-bezier(0.2, 0, 0, 1)";
+        readonly minimumVisibleChangePx: 0.5;
+    };
+    readonly layout: {
+        readonly probeOffscreenPositionPx: -9999;
+        readonly fallbackLineHeightMultiplier: 1.3;
+        readonly fallbackCharacterHeightPx: 18;
+        readonly characterTransformOrigin: "50% 50%";
+        readonly characterRestTransform: "translateY(0) rotate(0deg)";
+    };
+    readonly chromatic: {
+        readonly hueStartDegrees: 0;
+        readonly hueSpreadDegrees: 320;
+        readonly saturationPercent: 92;
+        readonly lightnessPercent: 60;
+        readonly fullHueRotationDegrees: 360;
+    };
+    readonly lifecycle: {
+        readonly completionBufferMs: 80;
+        readonly flashRevertDelayMs: 1400;
+    };
+};

package/dist/constants.js

@@ -0,0 +1,56 @@
+export const TUNING = {
+    animation: {
+        direction: "down",
+        stagger: 45,
+        duration: 300,
+        exitOffset: 50,
+        easing: "cubic-bezier(0.34, 1.56, 0.64, 1)",
+        bounce: 0.6,
+        colorFade: 280,
+        skipUnchanged: true,
+        interrupt: true,
+    },
+    variation: {
+        indexFrequency: 12.9898,
+        channelFrequency: 78.233,
+        seedScale: 43758.5453,
+        durationChannel: 1,
+        staggerChannel: 2,
+        tiltChannel: 3,
+    },
+    glyph: {
+        tailDurationMultiplier: 0.75,
+        durationVariationStrength: 0.45,
+        tailStaggerStartMultiplier: 0.5,
+        tailStaggerStepMultiplier: 0.25,
+        staggerVariationStrength: 0.25,
+        maximumTiltDegrees: 5,
+        tiltDecimalPlaces: 2,
+    },
+    width: {
+        tailCollapseDelayMultiplier: 0.55,
+        tailCollapseDurationMultiplier: 0.6,
+        newSlotExpansionDurationMultiplier: 0.45,
+        minimumTransitionMs: 140,
+        resizeEasing: "cubic-bezier(0.2, 0, 0, 1)",
+        minimumVisibleChangePx: 0.5,
+    },
+    layout: {
+        probeOffscreenPositionPx: -9999,
+        fallbackLineHeightMultiplier: 1.3,
+        fallbackCharacterHeightPx: 18,
+        characterTransformOrigin: "50% 50%",
+        characterRestTransform: "translateY(0) rotate(0deg)",
+    },
+    chromatic: {
+        hueStartDegrees: 0,
+        hueSpreadDegrees: 320,
+        saturationPercent: 92,
+        lightnessPercent: 60,
+        fullHueRotationDegrees: 360,
+    },
+    lifecycle: {
+        completionBufferMs: 80,
+        flashRevertDelayMs: 1400,
+    },
+};

package/dist/dom.d.ts

@@ -0,0 +1,40 @@
+import { type ResolvedSlotOptions } from "./timing.js";
+/** Internal test seam; not re-exported from the package. */
+export declare function resetSlotLayoutCache(): void;
+interface CharacterSlotElements {
+    slot: HTMLElement;
+    sizer: HTMLElement;
+    previousFace: HTMLElement | null;
+}
+interface SlotMeasurement extends CharacterSlotElements {
+    index: number;
+    currentSegment: string;
+    targetSegment: string;
+    currentWidth: number;
+    targetWidth: number;
+    widthWillChange: boolean;
+}
+/** Render slot markup without touching animation lifecycle state. */
+export declare function renderCharacterSlots(container: HTMLElement, text: string): void;
+export declare function renderPlainText(container: HTMLElement, text: string): void;
+export declare function getCharacterSlots(container: HTMLElement): HTMLElement[];
+export declare function isSlotLayoutReady(slot: HTMLElement | undefined): boolean;
+/**
+ * Check the globally imported stylesheet contract. A successful check is
+ * cached because an applied stylesheet does not normally disappear. A failed
+ * check is retried so asynchronously loaded CSS can upgrade plain text later.
+ */
+export declare function canRenderSlotLayout(): boolean;
+export declare function addMissingCharacterSlots(container: HTMLElement, characterSlots: HTMLElement[], requiredSlotCount: number): void;
+export declare function measureCharacterHeight(container: HTMLElement, characterSlots: HTMLElement[], containerStyle: CSSStyleDeclaration): number;
+/** Measure all old widths, apply all target sizers, then read all new widths. */
+export declare function measureChangedSlots(characterSlots: HTMLElement[], currentSegments: string[], targetSegments: string[], skipUnchanged: boolean): SlotMeasurement[];
+export declare function prepareSlotAnimation(measurement: SlotMeasurement, targetSegmentCount: number, characterHeight: number, options: ResolvedSlotOptions): {
+    measurement: SlotMeasurement;
+    timing: import("./timing.js").GlyphTiming;
+    widthTiming: import("./timing.js").WidthTiming;
+    incomingFace: HTMLSpanElement;
+    completionTimeMs: number;
+};
+export declare function scheduleSlotAnimation(preparedAnimation: ReturnType<typeof prepareSlotAnimation>, characterHeight: number, restingColor: string, options: ResolvedSlotOptions, scheduleTask: (callback: () => void, delayMs: number) => void): void;
+export {};

package/dist/dom.js

@@ -0,0 +1,209 @@
+import { TUNING } from "./constants.js";
+import { getVisibleSegmentText, segmentTextIntoGraphemes, } from "./text.js";
+import { calculateGlyphTiming, calculateWidthTiming, } from "./timing.js";
+const CSS_PROBE_TEXT = "x";
+const { layout, width } = TUNING;
+let cachedSlotLayoutReady = false;
+/** Internal test seam; not re-exported from the package. */
+export function resetSlotLayoutCache() {
+    cachedSlotLayoutReady = false;
+}
+function createCharacterFace(segment) {
+    const face = document.createElement("span");
+    face.className = "char-face";
+    face.textContent = getVisibleSegmentText(segment);
+    return face;
+}
+function createCharacterSlot(segment) {
+    const slot = document.createElement("span");
+    slot.className = "char-slot";
+    slot.dataset.char = segment;
+    const sizer = document.createElement("span");
+    sizer.className = "char-sizer";
+    sizer.textContent = getVisibleSegmentText(segment);
+    slot.append(sizer, createCharacterFace(segment));
+    return slot;
+}
+/** Render slot markup without touching animation lifecycle state. */
+export function renderCharacterSlots(container, text) {
+    container.classList.add("slot-text");
+    container.replaceChildren(...segmentTextIntoGraphemes(text).map(createCharacterSlot));
+}
+export function renderPlainText(container, text) {
+    container.classList.remove("slot-text");
+    container.textContent = text;
+}
+export function getCharacterSlots(container) {
+    return Array.from(container.querySelectorAll(".char-slot"));
+}
+export function isSlotLayoutReady(slot) {
+    if (!slot)
+        return false;
+    const face = slot.querySelector(".char-face");
+    if (!face)
+        return false;
+    const slotStyle = getComputedStyle(slot);
+    const faceStyle = getComputedStyle(face);
+    const slotIsFlex = slotStyle.display === "inline-flex" || slotStyle.display === "flex";
+    return (slotStyle.position === "relative" &&
+        slotIsFlex &&
+        faceStyle.position === "absolute");
+}
+/**
+ * Check the globally imported stylesheet contract. A successful check is
+ * cached because an applied stylesheet does not normally disappear. A failed
+ * check is retried so asynchronously loaded CSS can upgrade plain text later.
+ */
+export function canRenderSlotLayout() {
+    if (cachedSlotLayoutReady)
+        return true;
+    if (!document.body)
+        return false;
+    const cssProbe = document.createElement("span");
+    cssProbe.setAttribute("aria-hidden", "true");
+    cssProbe.style.cssText =
+        `position:absolute;left:${layout.probeOffscreenPositionPx}px;` +
+            `top:${layout.probeOffscreenPositionPx}px;visibility:hidden;pointer-events:none;`;
+    renderCharacterSlots(cssProbe, CSS_PROBE_TEXT);
+    document.body.appendChild(cssProbe);
+    const firstProbeSlot = getCharacterSlots(cssProbe)[0];
+    cachedSlotLayoutReady = isSlotLayoutReady(firstProbeSlot);
+    cssProbe.remove();
+    return cachedSlotLayoutReady;
+}
+export function addMissingCharacterSlots(container, characterSlots, requiredSlotCount) {
+    for (let index = characterSlots.length; index < requiredSlotCount; index++) {
+        const slot = createCharacterSlot("");
+        container.appendChild(slot);
+        characterSlots.push(slot);
+    }
+}
+export function measureCharacterHeight(container, characterSlots, containerStyle) {
+    const firstCharacterSlot = characterSlots[0];
+    const sampleSlot = characterSlots.find((slot) => (slot.dataset.char ?? "") !== "") ??
+        firstCharacterSlot;
+    return (Math.ceil(sampleSlot?.getBoundingClientRect().height ||
+        sampleSlot?.offsetHeight ||
+        container.getBoundingClientRect().height ||
+        parseFloat(containerStyle.lineHeight) ||
+        0) ||
+        Math.ceil(parseFloat(containerStyle.fontSize) *
+            layout.fallbackLineHeightMultiplier) ||
+        layout.fallbackCharacterHeightPx);
+}
+/** Measure all old widths, apply all target sizers, then read all new widths. */
+export function measureChangedSlots(characterSlots, currentSegments, targetSegments, skipUnchanged) {
+    const changedSlots = [];
+    for (let index = 0; index < characterSlots.length; index++) {
+        const currentSegment = currentSegments[index] ?? "";
+        const targetSegment = targetSegments[index] ?? "";
+        if (currentSegment === targetSegment &&
+            (skipUnchanged || currentSegment === "")) {
+            continue;
+        }
+        const slot = characterSlots[index];
+        const sizer = slot.querySelector(".char-sizer");
+        changedSlots.push({
+            index,
+            slot,
+            sizer,
+            previousFace: slot.querySelector(".char-face"),
+            currentSegment,
+            targetSegment,
+            currentWidth: slot.getBoundingClientRect().width,
+        });
+    }
+    changedSlots.forEach(({ sizer, targetSegment }) => {
+        sizer.textContent = getVisibleSegmentText(targetSegment);
+    });
+    return changedSlots.map((changedSlot) => {
+        const targetWidth = changedSlot.sizer.getBoundingClientRect().width;
+        return {
+            ...changedSlot,
+            targetWidth,
+            widthWillChange: Math.abs(targetWidth - changedSlot.currentWidth) >
+                width.minimumVisibleChangePx,
+        };
+    });
+}
+export function prepareSlotAnimation(measurement, targetSegmentCount, characterHeight, options) {
+    const { index, slot, currentSegment, targetSegment } = measurement;
+    const { currentWidth, widthWillChange } = measurement;
+    const timing = calculateGlyphTiming(index, targetSegmentCount, targetSegment === "", options);
+    const widthTiming = calculateWidthTiming(currentSegment, targetSegment, timing);
+    const incomingOffsetY = options.direction === "down" ? -characterHeight : characterHeight;
+    const incomingColor = typeof options.color === "function"
+        ? options.color(index, targetSegmentCount)
+        : options.color;
+    if (widthWillChange)
+        slot.style.width = `${currentWidth}px`;
+    if (currentSegment === "" || targetSegment === "") {
+        slot.classList.add("is-resizing");
+    }
+    const incomingFace = createCharacterFace(targetSegment);
+    incomingFace.style.transformOrigin = layout.characterTransformOrigin;
+    incomingFace.style.transform =
+        `translateY(${incomingOffsetY}px) ` +
+            `rotate(${timing.startingTiltDegrees}deg)`;
+    if (incomingColor)
+        incomingFace.style.color = incomingColor;
+    slot.appendChild(incomingFace);
+    const widthCompletionTimeMs = widthWillChange
+        ? widthTiming.startDelayMs + widthTiming.durationMs
+        : 0;
+    const glyphCompletionTimeMs = timing.startDelayMs +
+        options.exitOffset +
+        timing.durationMs +
+        (options.color ? options.colorFade : 0);
+    return {
+        measurement,
+        timing,
+        widthTiming,
+        incomingFace,
+        completionTimeMs: Math.max(widthCompletionTimeMs, glyphCompletionTimeMs),
+    };
+}
+export function scheduleSlotAnimation(preparedAnimation, characterHeight, restingColor, options, scheduleTask) {
+    const { measurement, timing, widthTiming, incomingFace } = preparedAnimation;
+    const { slot, previousFace, targetWidth, widthWillChange } = measurement;
+    const outgoingOffsetY = options.direction === "down" ? characterHeight : -characterHeight;
+    const rollTransition = `transform ${timing.durationMs}ms ${options.easing}`;
+    const incomingTransition = options.color
+        ? `${rollTransition}, color ${options.colorFade}ms linear ${timing.durationMs}ms`
+        : rollTransition;
+    if (widthWillChange) {
+        scheduleTask(() => {
+            slot.style.transition =
+                `width ${widthTiming.durationMs}ms ${width.resizeEasing}`;
+            slot.style.width = `${targetWidth}px`;
+        }, widthTiming.startDelayMs);
+    }
+    if (previousFace) {
+        scheduleTask(() => {
+            previousFace.style.transition = rollTransition;
+            previousFace.style.transform =
+                `translateY(${outgoingOffsetY}px) ` +
+                    `rotate(${-timing.startingTiltDegrees}deg)`;
+        }, timing.startDelayMs);
+    }
+    scheduleTask(() => {
+        incomingFace.style.transition = incomingTransition;
+        incomingFace.style.transform = layout.characterRestTransform;
+        if (options.color)
+            incomingFace.style.color = restingColor;
+        const finishOnTransformEnd = (event) => {
+            if (event.propertyName !== "transform")
+                return;
+            incomingFace.removeEventListener("transitionend", finishOnTransformEnd);
+            slot.dataset.char = measurement.targetSegment;
+            slot.style.removeProperty("transition");
+            slot.style.removeProperty("width");
+            slot.classList.remove("is-resizing");
+            slot.querySelectorAll(".char-face").forEach((face) => {
+                if (face !== incomingFace)
+                    face.remove();
+            });
+        };
+        incomingFace.addEventListener("transitionend", finishOnTransformEnd);
+    }, timing.startDelayMs + options.exitOffset);
+}

package/dist/index.d.ts

@@ -31,4 +31,4 @@ export interface SlotTextController {
  *   label.set("Copied", { direction: "up" });
  *   label.flash("Copied", { revertAfter: 1400 }); // auto-reverts to "Copy"
  */
-export declare function slotText(element: HTMLElement, initialText: string, options?: SlotOptions): SlotTextController;
+export declare function slotText(element: HTMLElement, initialText: string, defaultOptions?: SlotOptions): SlotTextController;

package/dist/index.js

@@ -1,5 +1,6 @@
 export { animateSlotText, buildSlotText, chromatic, clearSlotText, } from "./slotText.js";
-import { animateSlotText, buildSlotText, clearSlotText } from "./slotText.js";
+import { TUNING } from "./constants.js";
+import { animateSlotText, clearSlotText, renderTextWithCssFallback, } from "./slotText.js";
 /**
  * Create a text-roll controller for one element.
  *
@@ -9,54 +10,54 @@ import { animateSlotText, buildSlotText, clearSlotText } from "./slotText.js";
  *   label.set("Copied", { direction: "up" });
  *   label.flash("Copied", { revertAfter: 1400 }); // auto-reverts to "Copy"
  */
-export function slotText(element, initialText, options = {}) {
-    let value = initialText;
-    let revertTimeout;
+export function slotText(element, initialText, defaultOptions = {}) {
+    let currentValue = initialText;
+    let revertTimerId;
     let restingText;
-    buildSlotText(element, initialText);
+    renderTextWithCssFallback(element, initialText);
+    const animateWithoutInterrupt = (text, overrides) => animateSlotText(element, text, {
+        ...defaultOptions,
+        interrupt: false,
+        ...overrides,
+    });
     return {
         element,
         get value() {
-            return value;
+            return currentValue;
         },
-        set(text, nextOptions = {}) {
+        set(text, optionOverrides = {}) {
             // An explicit set wins over a pending flash revert.
-            clearTimeout(revertTimeout);
+            clearTimeout(revertTimerId);
             restingText = undefined;
-            value = text;
-            animateSlotText(element, text, { ...options, ...nextOptions });
+            currentValue = text;
+            animateSlotText(element, text, {
+                ...defaultOptions,
+                ...optionOverrides,
+            });
         },
-        flash(text, { revertAfter = 1400, enter, exit } = {}) {
+        flash(text, { revertAfter = TUNING.lifecycle.flashRevertDelayMs, enter: enterOptions, exit: exitOptions, } = {}) {
             // Capture the resting text only on the first flash of a burst, so a
             // flash-during-flash still reverts to the original label.
             if (restingText === undefined) {
-                restingText = value;
+                restingText = currentValue;
             }
             // Flashes default to non-interrupting rolls: spam-friendly, no mid-roll
             // cutoffs. Callers can still override via `enter`/`exit`.
-            value = text;
-            animateSlotText(element, text, {
-                ...options,
-                interrupt: false,
-                ...enter,
-            });
+            currentValue = text;
+            animateWithoutInterrupt(text, enterOptions);
             // Restart the revert timer: one revert per burst, after the last flash.
-            clearTimeout(revertTimeout);
-            revertTimeout = window.setTimeout(() => {
-                const back = restingText;
+            clearTimeout(revertTimerId);
+            revertTimerId = window.setTimeout(() => {
+                const originalText = restingText;
                 restingText = undefined;
-                revertTimeout = undefined;
-                value = back;
-                animateSlotText(element, back, {
-                    ...options,
-                    interrupt: false,
-                    ...exit,
-                });
+                revertTimerId = undefined;
+                currentValue = originalText;
+                animateWithoutInterrupt(originalText, exitOptions);
             }, revertAfter);
         },
         destroy() {
-            clearTimeout(revertTimeout);
-            clearSlotText(element, value);
+            clearTimeout(revertTimerId);
+            clearSlotText(element, currentValue);
         },
     };
 }

package/dist/react.js

@@ -1,5 +1,5 @@
 import { createElement, forwardRef, useEffect, useImperativeHandle, useRef, } from "react";
-import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText.js";
+import { animateSlotText, clearSlotText, renderTextWithCssFallback, } from "./slotText.js";
 export const SlotText = forwardRef(({ text, options, "aria-label": ariaLabel, ...props }, forwardedRef) => {
     const elementRef = useRef(null);
     const mountedRef = useRef(false);
@@ -13,7 +13,7 @@ export const SlotText = forwardRef(({ text, options, "aria-label": ariaLabel, ..
         const element = elementRef.current;
         if (!element)
             return;
-        buildSlotText(element, text);
+        renderTextWithCssFallback(element, text);
         mountedRef.current = true;
         return () => {
             clearSlotText(element);

package/dist/slotText.d.ts

@@ -1,16 +1,8 @@
 /**
- * slotText - a dependency-free "text roll" animation.
- *
- * Adapted from motion-primitives' TextRoll (vertical-slide variant): each
- * character sits in its own clipped cell and changes by sliding. The new
- * glyph enters from one side while the old glyph slides out the other, with
- * the incoming glyph chasing the outgoing one by a stagger step. Pure
- * transform/transition, GPU-composited, with a springy overshoot easing, so
- * every letter lands with a little bounce.
- *
- *   buildSlotText(el, "Copy");                       // initialise
- *   animateSlotText(el, "Copied", { direction: "up" }); // animate to new text
+ * Browser-only text-roll animation. Each grapheme owns one clipped slot; the
+ * previous face rolls out while the next face rolls in.
  */
+/** Options shared by the low-level animation and all framework adapters. */
 export interface SlotOptions {
     /** "down" rolls glyphs downward (enter from top); "up" rolls upward. */
     direction?: "up" | "down";
@@ -23,49 +15,43 @@ export interface SlotOptions {
     /** Easing — defaults to a springy, overshooting "back" curve. */
     easing?: string;
     /**
-     * Per-letter personality: 0 = every glyph lands identically, 1 = lots of
-     * individual variation in speed and a little tilt-wobble as each settles.
-     * Default 0.6.
+     * Per-letter personality: 0 makes every glyph move identically; 1 adds the
+     * strongest timing variation and tilt. Default 0.6.
      */
     bounce?: number;
     /**
-     * Chromatic flash: each incoming glyph rolls in tinted, then fades to its
-     * resting color once it lands. Pass a single CSS color for a flat tint, or a
-     * function `(index, total) => color` to give every glyph its own hue. That's
-     * what produces the spectrum/rainbow sweep across the line. Omit for no flash.
+     * Incoming glyph tint. Pass one CSS color, or return a color for each
+     * `(segmentIndex, segmentCount)` pair.
      */
-    color?: string | ((index: number, total: number) => string);
-    /** How long the chromatic tint takes to fade back to rest, in ms (default 280). */
+    color?: string | ((segmentIndex: number, segmentCount: number) => string);
+    /** Tint fade duration in ms (default 280). */
     colorFade?: number;
     /**
-     * Keep characters that are identical at the same index static. Ideal for
-     * short aligned labels (Copy to Copied). Turn off when the shared parts of the
-     * two strings are misaligned (different lengths) so the whole line rolls
-     * uniformly instead of leaving stray letters frozen.
+     * Keep graphemes that are identical at the same index static. Disable this
+     * when differently sized strings are not positionally aligned.
      */
     skipUnchanged?: boolean;
     /**
-     * true (default): a new call interrupts any roll in flight, snapping it to
-     * its target before starting fresh. false: the current roll finishes and the
-     * latest call made mid-roll plays after it lands; calls targeting the text
-     * already displayed are dropped. Ideal for spam-prone triggers like buttons.
+     * true interrupts the running roll. false lets it finish, then plays only
+     * the latest queued target. Default true.
      */
     interrupt?: boolean;
 }
 export interface ChromaticOptions {
+    /** Starting hue in degrees. Default 0. */
     from?: number;
+    /** Hue distance from first to last grapheme. Default 320 degrees. */
     spread?: number;
+    /** HSL saturation percentage. Default 92. */
     saturation?: number;
+    /** HSL lightness percentage. Default 60. */
     lightness?: number;
 }
-/**
- * Build a `color` function that sweeps the hue across the line, giving every
- * glyph its own color so the roll lands as a chromatic spectrum.
- *
- *   animateSlotText(el, txt, { color: chromatic() });            // full rainbow
- *   animateSlotText(el, txt, { color: chromatic({ from: 18 }) }); // start gold
- */
-export declare function chromatic({ from, spread, saturation, lightness, }?: ChromaticOptions): (index: number, total: number) => string;
+/** Build a color function that sweeps a hue range across the text. */
+export declare function chromatic({ from, spread, saturation, lightness, }?: ChromaticOptions): (segmentIndex: number, segmentCount: number) => string;
+/** Render settled text, falling back to plain text until the CSS is ready. */
+export declare function renderTextWithCssFallback(container: HTMLElement, text: string): void;
+/** Build slot markup immediately and cancel any animation that owns it. */
 export declare function buildSlotText(container: HTMLElement, text: string): void;
-export declare function animateSlotText(container: HTMLElement, toText: string, options?: SlotOptions): void;
+export declare function animateSlotText(container: HTMLElement, targetText: string, options?: SlotOptions): void;
 export declare function clearSlotText(container: HTMLElement, text?: string): void;

package/dist/slotText.js

@@ -1,266 +1,118 @@
-/**
- * slotText - a dependency-free "text roll" animation.
- *
- * Adapted from motion-primitives' TextRoll (vertical-slide variant): each
- * character sits in its own clipped cell and changes by sliding. The new
- * glyph enters from one side while the old glyph slides out the other, with
- * the incoming glyph chasing the outgoing one by a stagger step. Pure
- * transform/transition, GPU-composited, with a springy overshoot easing, so
- * every letter lands with a little bounce.
- *
- *   buildSlotText(el, "Copy");                       // initialise
- *   animateSlotText(el, "Copied", { direction: "up" }); // animate to new text
- */
-const DEFAULTS = {
-    direction: "down",
-    stagger: 45,
-    duration: 300,
-    exitOffset: 50,
-    easing: "cubic-bezier(0.34, 1.56, 0.64, 1)",
-    bounce: 0.6,
-    colorFade: 280,
-    skipUnchanged: true,
-    interrupt: true,
-};
-const NBSP = "\u00A0";
-const glyph = (char) => (char === " " ? NBSP : char);
-/**
- * Build a `color` function that sweeps the hue across the line, giving every
- * glyph its own color so the roll lands as a chromatic spectrum.
- *
- *   animateSlotText(el, txt, { color: chromatic() });            // full rainbow
- *   animateSlotText(el, txt, { color: chromatic({ from: 18 }) }); // start gold
- */
-export function chromatic({ from = 0, spread = 320, saturation = 92, lightness = 60, } = {}) {
-    return (index, total) => {
-        const t = total <= 1 ? 0 : index / (total - 1);
-        return `hsl(${(from + t * spread) % 360} ${saturation}% ${lightness}%)`;
+import { TUNING } from "./constants.js";
+import { addMissingCharacterSlots, canRenderSlotLayout, getCharacterSlots, isSlotLayoutReady, measureChangedSlots, measureCharacterHeight, prepareSlotAnimation, renderPlainText, renderCharacterSlots, scheduleSlotAnimation, } from "./dom.js";
+import { segmentTextIntoGraphemes } from "./text.js";
+import { resolveAnimationOptions } from "./timing.js";
+const { chromatic: chromaticTuning, lifecycle } = TUNING;
+/** Build a color function that sweeps a hue range across the text. */
+export function chromatic({ from = chromaticTuning.hueStartDegrees, spread = chromaticTuning.hueSpreadDegrees, saturation = chromaticTuning.saturationPercent, lightness = chromaticTuning.lightnessPercent, } = {}) {
+    return (segmentIndex, segmentCount) => {
+        const lastSegmentIndex = segmentCount - 1;
+        const progress = segmentCount <= 1 ? 0 : segmentIndex / lastSegmentIndex;
+        const hueDegrees = (from + progress * spread) % chromaticTuning.fullHueRotationDegrees;
+        return `hsl(${hueDegrees} ${saturation}% ${lightness}%)`;
     };
 }
-const states = new WeakMap();
-/** Cancel any running animation on a container and snap it to its target text. */
-function settle(container) {
-    const state = states.get(container);
-    if (!state)
-        return;
-    state.timers.forEach((t) => window.clearTimeout(t));
-    states.delete(container);
-    // Rebuild a pristine DOM at the text the interrupted roll was heading toward,
-    // so the next animation starts from a clean, non-overlapping baseline.
-    buildSlotText(container, state.target);
+const animationStates = new WeakMap();
+const initializedContainers = new WeakSet();
+function cancelRunningAnimation(container) {
+    const animationState = animationStates.get(container);
+    if (!animationState)
+        return undefined;
+    animationState.timerIds.forEach((timerId) => window.clearTimeout(timerId));
+    animationStates.delete(container);
+    return animationState;
 }
-function makeFace(char) {
-    const face = document.createElement("span");
-    face.className = "char-face";
-    face.textContent = glyph(char);
-    return face;
+/** Render settled text, falling back to plain text until the CSS is ready. */
+export function renderTextWithCssFallback(container, text) {
+    initializedContainers.add(container);
+    if (canRenderSlotLayout())
+        renderCharacterSlots(container, text);
+    else
+        renderPlainText(container, text);
 }
-function buildSlot(char) {
-    const slot = document.createElement("span");
-    slot.className = "char-slot";
-    slot.dataset.char = char;
-    // Invisible sizer keeps the cell exactly the width/height of its glyph, so
-    // the absolutely-positioned animating faces never reflow the line.
-    const sizer = document.createElement("span");
-    sizer.className = "char-sizer";
-    sizer.textContent = glyph(char);
-    slot.append(sizer, makeFace(char));
-    return slot;
+function finishRunningAnimationImmediately(container) {
+    const animationState = cancelRunningAnimation(container);
+    if (animationState) {
+        renderTextWithCssFallback(container, animationState.targetText);
+    }
 }
+/** Build slot markup immediately and cancel any animation that owns it. */
 export function buildSlotText(container, text) {
-    container.classList.add("slot-text");
-    container.replaceChildren(...Array.from(text, buildSlot));
+    cancelRunningAnimation(container);
+    initializedContainers.add(container);
+    renderCharacterSlots(container, text);
 }
-export function animateSlotText(container, toText, options = {}) {
-    const { direction, stagger, duration, exitOffset, easing, bounce, color, colorFade, skipUnchanged, interrupt, } = {
-        ...DEFAULTS,
-        ...options,
-    };
-    // Non-interrupting mode: if a roll is already in flight, let it finish and
-    // remember this request instead. Only the latest request survives, so spam
-    // taps coalesce into a single follow-up roll once the current one lands.
-    const running = states.get(container);
-    if (running && !interrupt) {
-        if (toText !== running.target) {
-            running.pending = { text: toText, options };
-        }
+function scheduleAnimationTask(animationState, callback, delayMs) {
+    const timerId = window.setTimeout(callback, delayMs);
+    animationState.timerIds.push(timerId);
+}
+export function animateSlotText(container, targetText, options = {}) {
+    const resolvedOptions = resolveAnimationOptions(options);
+    const runningAnimation = animationStates.get(container);
+    if (runningAnimation && !resolvedOptions.interrupt) {
+        runningAnimation.pendingAnimation =
+            targetText === runningAnimation.targetText
+                ? undefined
+                : { text: targetText, options };
         return;
     }
-    // Interrupt: if a previous roll is still running, fast-forward it to its
-    // target and tear down its timers before we start fresh. This is what kills
-    // the "switch bun→npm mid-animation" glitch.
-    settle(container);
-    // First run / empty container → just build it.
-    if (!container.querySelector(".char-slot")) {
-        buildSlotText(container, toText);
+    finishRunningAnimationImmediately(container);
+    let characterSlots = getCharacterSlots(container);
+    if (characterSlots.length === 0) {
+        if (!initializedContainers.has(container)) {
+            renderTextWithCssFallback(container, targetText);
+            return;
+        }
+        if (!canRenderSlotLayout()) {
+            renderPlainText(container, targetText);
+            return;
+        }
+        renderCharacterSlots(container, container.textContent ?? "");
+        characterSlots = getCharacterSlots(container);
+    }
+    const firstCharacterSlot = characterSlots[0];
+    if (firstCharacterSlot && !isSlotLayoutReady(firstCharacterSlot)) {
+        renderPlainText(container, targetText);
         return;
     }
-    const slots = Array.from(container.querySelectorAll(".char-slot"));
-    const fromText = slots.map((s) => s.dataset.char ?? "").join("");
-    // Non-interrupting mode also drops rolls to the text already on screen, so
-    // repeated triggers do not visibly re-roll an unchanged label.
-    if (!interrupt && fromText === toText)
+    const currentSegments = characterSlots.map((slot) => slot.dataset.char ?? "");
+    const targetSegments = segmentTextIntoGraphemes(targetText);
+    if (!resolvedOptions.interrupt &&
+        currentSegments.length === targetSegments.length &&
+        currentSegments.every((segment, index) => segment === targetSegments[index])) {
         return;
-    const maxLen = Math.max(fromText.length, toText.length);
-    // Whole-pixel slide distance = one cell height, so glyphs clip cleanly.
-    // If layout has not produced dimensions yet, fall back to line-height/font-size
-    // so the text still rolls instead of swapping in place.
-    const sample = slots.find((s) => (s.dataset.char ?? "") !== "") ?? slots[0];
-    const cs = getComputedStyle(container);
-    // Ceil, not round: if the slide distance is even half a pixel short of the
-    // cell height, a sliver of the outgoing glyph stays visible at the clip edge.
-    const H = Math.ceil(sample?.getBoundingClientRect().height ||
-        sample?.offsetHeight ||
-        container.getBoundingClientRect().height ||
-        parseFloat(cs.lineHeight) ||
-        0) ||
-        Math.ceil(parseFloat(cs.fontSize) * 1.3) ||
-        18;
-    // Resting color to settle the chromatic flash back to.
-    const restColor = color ? cs.color : "";
-    // Pre-create any extra cells up front so the row never reflows mid-roll.
-    for (let i = slots.length; i < maxLen; i++) {
-        const slot = buildSlot("");
-        container.appendChild(slot);
-        slots.push(slot);
     }
-    const timers = [];
-    const state = { timers, target: toText };
-    states.set(container, state);
-    // down: new enters from above (-H to 0), old exits below (0 to +H)
-    // up:   new enters from below (+H to 0), old exits above (0 to -H)
-    const outY = direction === "down" ? H : -H;
-    const inStart = direction === "down" ? -H : H;
-    // A tiny deterministic-feeling jitter in [-1, 1] per character. Scaled by
-    // `bounce` it gives each glyph its own speed and a little tilt-wobble, so the
-    // line does not land as one rigid block. Every letter has some personality.
-    const wobble = (i, salt) => {
-        const n = Math.sin((i + 1) * 12.9898 + salt * 78.233) * 43758.5453;
-        return (n - Math.floor(n)) * 2 - 1;
-    };
-    // Track the slowest letter so the safety-net snap waits for everyone.
-    let maxEnd = 0;
-    for (let i = 0; i < maxLen; i++) {
-        const fromChar = fromText[i] || "";
-        const toChar = toText[i] || "";
-        if (fromChar === toChar && (skipUnchanged || fromChar === ""))
-            continue;
-        const slot = slots[i];
-        const sizer = slot.querySelector(".char-sizer");
-        const oldFace = slot.querySelector(".char-face");
-        // Resize the cell to the new glyph — but ease the width instead of
-        // snapping it, so a wide outgoing glyph (W → i) is never cropped by a
-        // suddenly-narrow cell and neighbouring letters glide rather than jump.
-        const oldW = slot.getBoundingClientRect().width;
-        sizer.textContent = glyph(toChar);
-        const newW = sizer.getBoundingClientRect().width;
-        const widthChanges = Math.abs(newW - oldW) > 0.5;
-        if (widthChanges)
-            slot.style.width = `${oldW}px`;
-        // A cell growing from or collapsing to empty changes width drastically —
-        // clip it horizontally while it resizes so its glyph wipes in/out with the
-        // cell instead of spilling over and stacking onto the neighbours.
-        if (fromChar === "" || toChar === "")
-            slot.classList.add("is-resizing");
-        const tint = typeof color === "function" ? color(i, maxLen) : color;
-        // Per-letter personality: vary the speed, the stagger and a starting tilt
-        // that springs back to upright as the glyph settles. Tilt is kept small so
-        // rotated corners never swing into the neighbouring cells.
-        // Tail cells (rolling out to nothing) join the same wave instead of
-        // queuing behind it: they start mid-wave, roll a little faster, and are
-        // gone before the new word finishes landing — so nothing trails.
-        const isTail = toChar === "";
-        const d = Math.round(duration * (isTail ? 0.75 : 1) * (1 + bounce * 0.45 * wobble(i, 1)));
-        const staggerIndex = isTail
-            ? toText.length * 0.5 + (i - toText.length) * 0.25
-            : i;
-        const base = Math.round(staggerIndex * stagger * (1 + bounce * 0.25 * wobble(i, 2)));
-        const tilt = (bounce * 5 * wobble(i, 3)).toFixed(2);
-        const rollTrans = `transform ${d}ms ${easing}`;
-        const trans = color
-            ? `${rollTrans}, color ${colorFade}ms linear ${d}ms`
-            : rollTrans;
-        const newFace = makeFace(toChar);
-        newFace.style.transformOrigin = "50% 50%";
-        newFace.style.transform = `translateY(${inStart}px) rotate(${tilt}deg)`;
-        if (tint)
-            newFace.style.color = tint;
-        slot.appendChild(newFace);
-        void slot.offsetWidth; // commit start transforms
-        // Glide the cell to its new width with a clean ease-out (no overshoot) so
-        // it never pinches narrower than either glyph. Timing depends on the kind
-        // of change:
-        //  - glyph → glyph: resize alongside the roll.
-        //  - glyph → empty: let the glyph roll out vertically at full width FIRST,
-        //    then snap the empty cell closed quickly — so the exit reads as a roll,
-        //    not a horizontal crush.
-        //  - empty → glyph: open the cell quickly BEFORE the glyph rolls in, so it
-        //    arrives into a full-width cell.
-        if (widthChanges) {
-            let wDelay = base;
-            let wDur = d;
-            if (isTail) {
-                // Keep full width while the glyph is visibly rolling (first ~55%),
-                // then close just behind it — the exit reads as a roll, and the line
-                // has fully contracted by the time the new word lands.
-                wDelay = base + Math.round(d * 0.55);
-                wDur = Math.max(140, Math.round(d * 0.6));
-            }
-            else if (fromChar === "") {
-                wDur = Math.max(140, Math.round(d * 0.45));
-            }
-            timers.push(window.setTimeout(() => {
-                slot.style.transition = `width ${wDur}ms cubic-bezier(0.2, 0, 0, 1)`;
-                slot.style.width = `${newW}px`;
-            }, wDelay));
-            maxEnd = Math.max(maxEnd, wDelay + wDur);
-        }
-        maxEnd = Math.max(maxEnd, base + exitOffset + d + (color ? colorFade : 0));
-        // Outgoing glyph slides away first (with its own little counter-tilt).
-        if (oldFace) {
-            timers.push(window.setTimeout(() => {
-                oldFace.style.transition = rollTrans;
-                oldFace.style.transform = `translateY(${outY}px) rotate(${-Number(tilt)}deg)`;
-            }, base));
-        }
-        // Incoming glyph chases it in (and, if tinted, fades to rest afterwards).
-        timers.push(window.setTimeout(() => {
-            newFace.style.transition = trans;
-            newFace.style.transform = "translateY(0) rotate(0deg)";
-            if (color)
-                newFace.style.color = restColor;
-            const done = (e) => {
-                if (e.propertyName !== "transform")
-                    return; // ignore the colour fade
-                newFace.removeEventListener("transitionend", done);
-                slot.dataset.char = toChar;
-                // Hand sizing back to the sizer (same px, so nothing visibly moves).
-                slot.style.removeProperty("transition");
-                slot.style.removeProperty("width");
-                slot.classList.remove("is-resizing");
-                slot.querySelectorAll(".char-face").forEach((f) => {
-                    if (f !== newFace)
-                        f.remove();
-                });
-            };
-            newFace.addEventListener("transitionend", done);
-        }, base + exitOffset));
+    const requiredSlotCount = Math.max(currentSegments.length, targetSegments.length);
+    addMissingCharacterSlots(container, characterSlots, requiredSlotCount);
+    const containerStyle = getComputedStyle(container);
+    const characterHeight = measureCharacterHeight(container, characterSlots, containerStyle);
+    const restingColor = resolvedOptions.color ? containerStyle.color : "";
+    const changedSlotMeasurements = measureChangedSlots(characterSlots, currentSegments, targetSegments, resolvedOptions.skipUnchanged);
+    if (changedSlotMeasurements.length === 0) {
+        renderCharacterSlots(container, targetText);
+        return;
     }
-    // Safety net: snap to a pristine DOM once the slowest letter has settled.
-    // If a non-interrupting call was deferred mid-roll, replay it now — it runs
-    // as a fresh roll from this clean baseline.
-    const total = maxEnd + 80;
-    timers.push(window.setTimeout(() => {
-        const pending = state.pending;
-        states.delete(container);
-        buildSlotText(container, toText);
-        if (pending) {
-            animateSlotText(container, pending.text, pending.options);
+    const animationState = { timerIds: [], targetText };
+    animationStates.set(container, animationState);
+    const preparedSlotAnimations = changedSlotMeasurements.map((measurement) => prepareSlotAnimation(measurement, targetSegments.length, characterHeight, resolvedOptions));
+    // Commit every start style with one layout flush instead of one per glyph.
+    void container.offsetWidth;
+    preparedSlotAnimations.forEach((preparedSlotAnimation) => scheduleSlotAnimation(preparedSlotAnimation, characterHeight, restingColor, resolvedOptions, (callback, delayMs) => scheduleAnimationTask(animationState, callback, delayMs)));
+    const completionDelayMs = Math.max(...preparedSlotAnimations.map(({ completionTimeMs }) => completionTimeMs)) +
+        lifecycle.completionBufferMs;
+    scheduleAnimationTask(animationState, () => {
+        if (animationStates.get(container) !== animationState)
+            return;
+        const pendingAnimation = animationState.pendingAnimation;
+        animationStates.delete(container);
+        renderTextWithCssFallback(container, targetText);
+        if (pendingAnimation) {
+            animateSlotText(container, pendingAnimation.text, pendingAnimation.options);
         }
-    }, total));
+    }, completionDelayMs);
 }
 export function clearSlotText(container, text = "") {
-    settle(container);
-    container.classList.remove("slot-text");
-    container.textContent = text;
+    cancelRunningAnimation(container);
+    initializedContainers.delete(container);
+    renderPlainText(container, text);
 }

package/dist/text.d.ts

@@ -0,0 +1,4 @@
+/** Split text into user-perceived characters, with code-point fallback. */
+export declare function segmentTextIntoGraphemes(text: string): string[];
+/** Preserve regular spaces inside individually measured glyph cells. */
+export declare function getVisibleSegmentText(segment: string): string;

package/dist/text.js

@@ -0,0 +1,14 @@
+const NBSP = "\u00A0";
+const graphemeSegmenter = Intl.Segmenter
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : undefined;
+/** Split text into user-perceived characters, with code-point fallback. */
+export function segmentTextIntoGraphemes(text) {
+    if (!graphemeSegmenter)
+        return Array.from(text);
+    return Array.from(graphemeSegmenter.segment(text), ({ segment }) => segment);
+}
+/** Preserve regular spaces inside individually measured glyph cells. */
+export function getVisibleSegmentText(segment) {
+    return segment === " " ? NBSP : segment;
+}

package/dist/timing.d.ts

@@ -0,0 +1,25 @@
+import type { SlotOptions } from "./slotText.js";
+export interface ResolvedSlotOptions {
+    direction: "up" | "down";
+    stagger: number;
+    duration: number;
+    exitOffset: number;
+    easing: string;
+    bounce: number;
+    color?: string | ((segmentIndex: number, segmentCount: number) => string);
+    colorFade: number;
+    skipUnchanged: boolean;
+    interrupt: boolean;
+}
+export interface GlyphTiming {
+    durationMs: number;
+    startDelayMs: number;
+    startingTiltDegrees: number;
+}
+export interface WidthTiming {
+    durationMs: number;
+    startDelayMs: number;
+}
+export declare function resolveAnimationOptions(options: SlotOptions): ResolvedSlotOptions;
+export declare function calculateGlyphTiming(segmentIndex: number, targetSegmentCount: number, isTrailingSlot: boolean, options: Pick<ResolvedSlotOptions, "duration" | "stagger" | "bounce">): GlyphTiming;
+export declare function calculateWidthTiming(currentSegment: string, targetSegment: string, timing: GlyphTiming): WidthTiming;

package/dist/timing.js

@@ -0,0 +1,68 @@
+import { TUNING } from "./constants.js";
+const { animation, glyph, variation, width } = TUNING;
+export function resolveAnimationOptions(options) {
+    return {
+        direction: options.direction ?? animation.direction,
+        stagger: options.stagger ?? animation.stagger,
+        duration: options.duration ?? animation.duration,
+        exitOffset: options.exitOffset ?? animation.exitOffset,
+        easing: options.easing ?? animation.easing,
+        bounce: options.bounce ?? animation.bounce,
+        color: options.color,
+        colorFade: options.colorFade ?? animation.colorFade,
+        skipUnchanged: options.skipUnchanged ?? animation.skipUnchanged,
+        interrupt: options.interrupt ?? animation.interrupt,
+    };
+}
+/** Return stable pseudo-random variation in the range -1 to 1. */
+function getDeterministicVariation(segmentIndex, variationChannel) {
+    // Start at one so the first grapheme never uses a zero seed.
+    const oneBasedSegmentIndex = segmentIndex + 1;
+    const pseudoRandomSeed = Math.sin(oneBasedSegmentIndex * variation.indexFrequency +
+        variationChannel * variation.channelFrequency) * variation.seedScale;
+    const zeroToOne = pseudoRandomSeed - Math.floor(pseudoRandomSeed);
+    // Stretch 0..1 to 0..2, then center it around zero to get -1..1.
+    return zeroToOne * 2 - 1;
+}
+export function calculateGlyphTiming(segmentIndex, targetSegmentCount, isTrailingSlot, options) {
+    const { duration, stagger, bounce } = options;
+    const variationMultiplier = (strength, channel) => 1 + bounce * strength * getDeterministicVariation(segmentIndex, channel);
+    const durationMs = Math.round(duration *
+        (isTrailingSlot ? glyph.tailDurationMultiplier : 1) *
+        variationMultiplier(glyph.durationVariationStrength, variation.durationChannel));
+    const staggerPosition = isTrailingSlot
+        ? targetSegmentCount * glyph.tailStaggerStartMultiplier +
+            (segmentIndex - targetSegmentCount) *
+                glyph.tailStaggerStepMultiplier
+        : segmentIndex;
+    const startingTiltDegrees = Number((bounce *
+        glyph.maximumTiltDegrees *
+        getDeterministicVariation(segmentIndex, variation.tiltChannel)).toFixed(glyph.tiltDecimalPlaces));
+    return {
+        durationMs,
+        startDelayMs: Math.round(staggerPosition *
+            stagger *
+            variationMultiplier(glyph.staggerVariationStrength, variation.staggerChannel)),
+        startingTiltDegrees,
+    };
+}
+export function calculateWidthTiming(currentSegment, targetSegment, timing) {
+    const scaledDuration = (multiplier) => Math.max(width.minimumTransitionMs, Math.round(timing.durationMs * multiplier));
+    if (targetSegment === "") {
+        return {
+            startDelayMs: timing.startDelayMs +
+                Math.round(timing.durationMs * width.tailCollapseDelayMultiplier),
+            durationMs: scaledDuration(width.tailCollapseDurationMultiplier),
+        };
+    }
+    if (currentSegment === "") {
+        return {
+            startDelayMs: timing.startDelayMs,
+            durationMs: scaledDuration(width.newSlotExpansionDurationMultiplier),
+        };
+    }
+    return {
+        startDelayMs: timing.startDelayMs,
+        durationMs: timing.durationMs,
+    };
+}

package/dist/vue.js

@@ -1,5 +1,5 @@
 import { defineComponent, h, onBeforeUnmount, onMounted, ref, watch, } from "vue";
-import { animateSlotText, buildSlotText, clearSlotText, } from "./slotText.js";
+import { animateSlotText, clearSlotText, renderTextWithCssFallback, } from "./slotText.js";
 export const SlotText = defineComponent({
     name: "SlotText",
     inheritAttrs: false,
@@ -19,7 +19,7 @@ export const SlotText = defineComponent({
         onMounted(() => {
             if (!element.value)
                 return;
-            buildSlotText(element.value, props.text);
+            renderTextWithCssFallback(element.value, props.text);
             mounted = true;
         });
         watch(() => props.text, (text) => {

package/examples/basic/index.html

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>slot-text example</title>
+    <title>slot-text playground</title>
     <link rel="stylesheet" href="../../style.css" />
     <style>
       body {
@@ -11,24 +11,63 @@
         margin: 0;
         display: grid;
         place-items: center;
-        font: 600 18px/1.2 ui-sans-serif, system-ui, sans-serif;
+        font:
+          600 16px/1.2 ui-sans-serif,
+          system-ui,
+          sans-serif;
         background: #0e1116;
         color: #edf2f7;
+        -webkit-font-smoothing: antialiased;
+      }
+
+      main {
+        display: grid;
+        gap: 16px;
+        justify-items: center;
+      }
+
+      p {
+        margin: 0;
+        color: #9ca3af;
+        font-size: 13px;
+        font-weight: 500;
+        letter-spacing: 0.02em;
       }
 
       button {
-        border: 1px solid #2a3342;
-        border-radius: 10px;
+        --button-text-color: #0c50c6;
+        min-width: 112px;
+        min-height: 44px;
+        border: 0;
+        border-radius: 12px;
         padding: 12px 18px;
-        background: #151a22;
-        color: inherit;
+        background: #edf2f7;
+        color: var(--button-text-color);
         font: inherit;
         cursor: pointer;
+        box-shadow: 0 1px 1px rgb(0 0 0 / 20%);
+        transition: transform 160ms cubic-bezier(0.2, 0, 0, 1);
+      }
+
+      button:hover {
+        transform: translateY(-1px);
+      }
+
+      button:active {
+        transform: scale(0.96);
+      }
+
+      #copy-label,
+      #copy-label .char-face {
+        color: var(--button-text-color);
       }
     </style>
   </head>
   <body>
-    <button type="button"><span id="copy-label"></span></button>
+    <main>
+      <p>Click the button to test slot-text.</p>
+      <button type="button"><span id="copy-label"></span></button>
+    </main>
 
     <script type="module">
       import { slotText, chromatic } from "../../dist/index.js";

package/examples/css-race/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>slot-text delayed CSS example</title>
+    <style>
+      body {
+        min-height: 100vh;
+        margin: 0;
+        display: grid;
+        place-items: center;
+        font: 800 48px/1.1 ui-sans-serif, system-ui, sans-serif;
+      }
+    </style>
+  </head>
+  <body>
+    <button type="button"><span id="label">Take the next step</span></button>
+
+    <script type="module">
+      import { slotText } from "../../dist/index.js";
+
+      const STYLESHEET_DELAY_MS = 900;
+
+      const label = slotText(
+        document.querySelector("#label"),
+        "Take the next step",
+      );
+      label.set("Continue");
+
+      window.setTimeout(() => {
+        const stylesheet = document.createElement("link");
+        stylesheet.rel = "stylesheet";
+        stylesheet.href = "../../style.css";
+        document.head.appendChild(stylesheet);
+      }, STYLESHEET_DELAY_MS);
+    </script>
+  </body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slot-text",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Dependency-free text roll animation for tiny, tactile UI labels.",
   "type": "module",
   "license": "MIT",