@overpunch/speechtype 1.0.11

package/README.md

@@ -0,0 +1,258 @@
+# speechType
+
+[![npm](https://img.shields.io/npm/v/%40overpunch%2Fspeechtype.svg)](https://www.npmjs.com/package/@overpunch/speechtype) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![part of liiift type-tools](https://img.shields.io/badge/liiift-type--tools-blueviolet)](https://github.com/over-punch/type-tools)
+
+Typography that follows your voice — per-word typographic emphasis synced to Web Speech API boundary events. Each spoken word gets wider tracking, heavier weight, and larger optical size; the rest of the text recedes. A read-along effect grounded in typographic logic, not arbitrary highlight colours.
+
+![speechType emphasising each word of a paragraph in turn as it is spoken aloud — the active word grows bolder, wider-tracked, and larger in optical size while the surrounding text fades back](https://raw.githubusercontent.com/over-punch/speechType/main/assets/speechtype-demo.gif?v=1)
+
+**[speechtype.vercel.app](https://speechtype.vercel.app)** · [npm](https://www.npmjs.com/package/@overpunch/speechtype) · [GitHub](https://github.com/over-punch/speechType)
+
+TypeScript · Zero dependencies · React + Vanilla JS
+
+**Good for** read-along reading aids, language-learning apps, teleprompters, and any interface where a spoken voice and on-screen text need to stay visibly in sync.
+
+> **Requires a variable font** with `wght` and `opsz` axes (e.g. Merriweather, Inter, Source Serif). The weight and optical-size emphasis are written via `font-variation-settings`; with a static font only the tracking and opacity changes apply.
+
+---
+
+## Install
+
+```bash
+npm install @overpunch/speechtype
+```
+
+---
+
+## Usage
+
+> **Next.js App Router:** this library uses browser APIs. Add `"use client"` to any component file that imports from it.
+
+### React component (controlled)
+
+`SpeechTypeText` is a controlled component — you manage a `SpeechSynthesisUtterance` yourself, track which word is active in state, and pass the index as a prop. This pattern gives you full control over voice, timing, and UI.
+
+> **Note:** the controlled component and the `useSpeechType` hook only apply the *visual* options (`activeTracking`, `activeWeight`, `activeOpsz`, `inactiveOpacity`, `transitionMs`). The *speech* options (`rate`, `pitch`, `volume`, `onUnsupported`, `onError`) are only read by `startSpeechType`, since in the controlled pattern you own the `SpeechSynthesisUtterance`. `SpeechTypeText` also takes an `as` prop (default `"p"`) and forwards any `aria-*`, `data-*`, `role`, and `lang` attributes to the rendered element.
+
+```tsx
+"use client"
+import { SpeechTypeText } from '@overpunch/speechtype'
+import { useState, useCallback } from 'react'
+
+const TEXT = 'The quick brown fox jumps over the lazy dog.'
+
+export default function Demo() {
+  const [activeWordIndex, setActiveWordIndex] = useState(-1)
+
+  const handleSpeak = useCallback(() => {
+    const utterance = new SpeechSynthesisUtterance(TEXT)
+    utterance.onboundary = (e) => {
+      if (e.name === 'word') {
+        const wordIndex = TEXT.slice(0, e.charIndex).trim().split(/\s+/).filter(Boolean).length
+        setActiveWordIndex(wordIndex)
+      }
+    }
+    utterance.onend = () => setActiveWordIndex(-1)
+    speechSynthesis.speak(utterance)
+  }, [])
+
+  return (
+    <>
+      <SpeechTypeText activeWordIndex={activeWordIndex} activeWeight={700} inactiveOpacity={0.45}>
+        {TEXT}
+      </SpeechTypeText>
+      <button onClick={handleSpeak}>Speak</button>
+    </>
+  )
+}
+```
+
+### React — imperative (startSpeechType)
+
+For a simpler setup, skip `SpeechTypeText` and let `startSpeechType` manage everything directly on a plain element ref:
+
+```tsx
+"use client"
+import { useRef } from 'react'
+import { startSpeechType, removeSpeechType } from '@overpunch/speechtype'
+
+export default function Demo() {
+  const ref = useRef<HTMLParagraphElement>(null)
+  // stop() cancels speech and resets emphasis but keeps spans in place.
+  // removeSpeechType() does a full teardown — cancels speech AND restores original HTML.
+  // Call stop() for pause/stop controls; call removeSpeechType() only on unmount or full reset.
+  const stopRef = useRef<(() => void) | null>(null)
+
+  function handleSpeak() {
+    if (!ref.current) return
+    stopRef.current?.()  // cancel any in-progress speech first
+    stopRef.current = startSpeechType(ref.current, { activeWeight: 700, rate: 0.9 })
+  }
+
+  function handleStop() {
+    stopRef.current?.()
+    stopRef.current = null
+  }
+
+  return (
+    <>
+      <p ref={ref}>The quick brown fox jumps over the lazy dog.</p>
+      <button onClick={handleSpeak}>Speak</button>
+      <button onClick={handleStop}>Stop</button>
+    </>
+  )
+}
+```
+
+### React hook
+
+`useSpeechType` is the low-level hook behind `SpeechTypeText`. Use it when you need the controlled pattern but want to render your own element:
+
+```tsx
+"use client"
+import { useSpeechType } from '@overpunch/speechtype'
+import { useRef, useState, useCallback } from 'react'
+
+export default function Demo() {
+  const ref = useRef<HTMLParagraphElement>(null)
+  const [activeWordIndex, setActiveWordIndex] = useState(-1)
+
+  useSpeechType(ref, activeWordIndex, { activeWeight: 700 })
+
+  return <p ref={ref}>The quick brown fox jumps over the lazy dog.</p>
+}
+```
+
+### Vanilla JS
+
+`startSpeechType` is the all-in-one entry point for vanilla use. It wraps the words in spans, starts the Web Speech API, updates the emphasis on each boundary event, and returns a `stop` function.
+
+```ts
+import { startSpeechType, removeSpeechType } from '@overpunch/speechtype'
+
+const el = document.querySelector('p')
+const stop = startSpeechType(el, {
+  activeWeight: 700,
+  activeTracking: 0.06,
+  rate: 0.9,
+})
+
+// Later — stop speech and restore original HTML:
+stop()
+removeSpeechType(el)
+```
+
+For more control, use the lower-level functions:
+
+```ts
+import { prepareSpeechType, applySpeechType, removeSpeechType } from '@overpunch/speechtype'
+
+const el = document.querySelector('p')
+prepareSpeechType(el)               // wraps each word in a span
+
+applySpeechType(el, 3)              // emphasise word at index 3
+applySpeechType(el, -1)             // clear emphasis
+
+removeSpeechType(el)                // restore original HTML
+```
+
+### TypeScript
+
+```ts
+import type { SpeechTypeOptions } from '@overpunch/speechtype'
+
+const opts: SpeechTypeOptions = {
+  activeTracking: 0.08,
+  activeWeight: 800,
+  inactiveOpacity: 0.3,
+  rate: 0.85,
+}
+```
+
+---
+
+## Options
+
+Visual options apply everywhere; speech options are only read by `startSpeechType` (see the note under [React component](#react-component-controlled)).
+
+| Option | Type | Default | Scope | Description |
+|--------|------|---------|-------|-------------|
+| `activeTracking` | `number` | `0.06` | visual | Letter-spacing on the active (currently spoken) word, in em |
+| `activeWeight` | `number` | `700` | visual | `wght` axis value on the active word. Must sit within the font's `wght` axis range |
+| `activeOpsz` | `number` | `24` | visual | `opsz` axis value on the active word. Must sit within the font's `opsz` axis range |
+| `inactiveOpacity` | `number` | `0.45` | visual | Opacity of inactive (not currently spoken) words. Keep ≥ 0.3 for legibility — values below ~0.5 may drop contrast under WCAG AA depending on your colours |
+| `transitionMs` | `number` | `80` | visual | CSS transition duration in ms for style changes |
+| `rate` | `number` | `0.9` | speech | Speech rate (0.1–10). Passed to `SpeechSynthesisUtterance` |
+| `pitch` | `number` | `1` | speech | Speech pitch (0–2). Passed to `SpeechSynthesisUtterance` |
+| `volume` | `number` | `1` | speech | Speech volume (0–1). Passed to `SpeechSynthesisUtterance` |
+| `onUnsupported` | `() => void` | — | speech | Called when the browser has no `speechSynthesis`. Use it to surface a fallback (e.g. show the text statically or a manual stepper) |
+| `onError` | `(e: SpeechSynthesisErrorEvent) => void` | — | speech | Called on a real speech error. The normal `"interrupted"` cancellation is filtered out for you |
+
+---
+
+## How it works
+
+`prepareSpeechType` reads the element's text content and wraps each word in a `<span class="st-word">` — without changing visual layout. Note: inline child elements (`<em>`, `<strong>`, `<a>`, etc.) are flattened to plain text during wrapping. `applySpeechType` then writes `font-variation-settings`, `letter-spacing`, and `opacity` as inline styles directly on each span (no CSS class toggles). The active span gets wider tracking, heavier weight, and larger optical size; inactive spans get reduced opacity. CSS transitions on those properties are set once by `prepareSpeechType`.
+
+`startSpeechType` wires a `SpeechSynthesisUtterance` to the browser's Web Speech API, listens for `boundary` events, maps the character offset to a word index, and calls `applySpeechType` on each event. It returns a `stop` function that cancels synthesis and removes all emphasis.
+
+**Browser support:** Web Speech API is supported in Chrome, Edge, and Safari. Firefox requires a flag. Note that Safari fires `boundary` events sparsely, so word-level sync is most reliable in Chromium-based browsers; where boundaries don't fire, the text simply stays un-emphasised. `startSpeechType` falls back silently in environments without `speechSynthesis` — pass `onUnsupported` to detect that case and render your own fallback:
+
+```ts
+startSpeechType(el, {
+  onUnsupported: () => showManualStepper(),     // no Web Speech API here
+  onError: (e) => console.warn('Speech failed', e.error),
+})
+```
+
+---
+
+## Accessibility
+
+speechType is built for read-along contexts, so it ships screen-reader support rather than leaving it to you:
+
+- Each word span is marked `aria-hidden="true"` and the active word also gets `aria-current="true"`, so assistive tech reads continuous text instead of 27 separate spans.
+- An off-screen `aria-live="polite"` region announces the active word as emphasis moves, keeping non-visual users in sync with the highlight.
+- All emphasis is plain CSS (`font-variation-settings`, `letter-spacing`, `opacity`) — no content is duplicated or reordered.
+
+Two trade-offs to design around:
+
+- **Contrast.** Inactive words fade to `inactiveOpacity` (default `0.45`), which *reduces* contrast. Keep it at `0.3` or higher and verify the result still meets WCAG AA (4.5:1) against your background — or raise it toward `1` if your audience needs maximum legibility.
+- **Inline markup is flattened.** `prepareSpeechType` reads `textContent`, so inline children (`<em>`, `<strong>`, `<a>`, …) inside the target element are replaced by plain text when words are wrapped. Apply speechType to elements whose formatting you don't need to preserve, and use `getCleanHTML(el)` to recover the unwrapped markup if needed.
+
+---
+
+## API reference
+
+| Export | Description |
+|--------|-------------|
+| `prepareSpeechType(el, options?)` | Wraps each word in a span. Call once before `applySpeechType`. |
+| `applySpeechType(el, activeIndex, options?)` | Emphasises word at `activeIndex`. Pass `-1` to clear. |
+| `startSpeechType(el, options?)` | All-in-one: prepares spans, starts Web Speech API, returns `stop()`. |
+| `removeSpeechType(el)` | Cancels synthesis and restores original HTML. |
+| `getCleanHTML(el)` | Returns element HTML with all injected spans removed. |
+| `useSpeechType` | React hook: `(ref, activeWordIndex, options?)` |
+| `SpeechTypeText` | React component. Controlled via `activeWordIndex` prop. Forwards ref. |
+| `SpeechTypeOptions` | TypeScript interface for all options. |
+| `SPEECH_CLASSES` | CSS class names injected by the algorithm (`st-word`). |
+
+---
+
+## Next.js
+
+`SpeechTypeText`, `useSpeechType`, and `startSpeechType` all require a browser environment. Add `"use client"` to any component that imports them:
+
+```tsx
+"use client"
+import { SpeechTypeText } from '@overpunch/speechtype'
+```
+
+---
+
+## Dev notes
+
+### `next` in root devDependencies
+
+`package.json` at the repo root lists `next` as a devDependency. This is a **Vercel detection workaround** — not a real dependency of the npm package. Vercel's build system inspects the root `package.json` to detect the framework; without `next` present it falls back to a static build and skips the Next.js pipeline, breaking the `/site` subdirectory deploy.
+
+The package itself has zero runtime dependencies. Do not remove this entry.

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("react"),b=require("react/jsx-runtime"),v={word:"st-word"},w=new WeakMap;function C(t,e={}){if(typeof window>"u")return[];const r=window.scrollY,n=w.get(t),l=(n==null?void 0:n.originalHTML)??t.innerHTML;t.innerHTML=l;const d=(t.textContent??"").split(/(\s+)/);t.innerHTML=d.map(i=>!i||/^\s+$/.test(i)?i:`<span class="${v.word}" aria-hidden="true">${i}</span>`).join("");const u=Array.from(t.querySelectorAll(`.${v.word}`)),o=e.transitionMs??80;u.forEach(i=>{i.style.display="inline",i.style.transition=[`font-variation-settings ${o}ms ease`,`letter-spacing ${o}ms ease`,`opacity ${o}ms ease`].join(", ")});let c=t.querySelector("[data-st-live]");return c||(c=document.createElement("span"),c.setAttribute("data-st-live",""),c.setAttribute("aria-live","polite"),c.setAttribute("aria-atomic","true"),c.style.cssText="position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0",t.appendChild(c)),w.set(t,{originalHTML:l,wordSpans:u,utterance:null,activeIndex:-1}),requestAnimationFrame(()=>{Math.abs(window.scrollY-r)>2&&window.scrollTo({top:r,behavior:"instant"})}),u}function y(t,e,r={}){var c;if(typeof window>"u")return;const n=w.get(t);if(!n)return;const l=r.activeTracking??.06,s=r.activeWeight??700,d=r.activeOpsz??24,u=r.inactiveOpacity??.45;n.activeIndex=e;const o=t.querySelector("[data-st-live]");o&&(o.textContent=e>=0?((c=n.wordSpans[e])==null?void 0:c.textContent)??"":""),n.wordSpans.forEach((i,S)=>{S===e?(i.setAttribute("aria-current","true"),i.style.fontVariationSettings=`"wght" ${s}, "opsz" ${d}`,i.style.letterSpacing=`${l}em`,i.style.opacity="1"):(i.removeAttribute("aria-current"),i.style.fontVariationSettings="",i.style.letterSpacing="",i.style.opacity=e===-1?"1":String(u))})}function L(t,e={}){var m;if(typeof window>"u"||!("speechSynthesis"in window))return(m=e.onUnsupported)==null||m.call(e),()=>{};const r=C(t,e),n=w.get(t);if(!n)return()=>{};window.speechSynthesis.cancel();const l=r.map(a=>a.textContent??"").join(" "),s=new SpeechSynthesisUtterance(l);s.rate=e.rate??.9,s.pitch=e.pitch??1,s.volume=e.volume??1;const d=e.activeTracking??.06,u=e.activeWeight??700,o=e.activeOpsz??24,c={...e,activeTracking:d,activeWeight:u,activeOpsz:o};let i=0;const S=r.map(a=>{var h;const p=i;return i+=(((h=a.textContent)==null?void 0:h.length)??0)+1,p});let f=!1;return s.onboundary=a=>{if(f||a.name!=="word")return;const p=S.findIndex((h,x)=>{const T=S[x+1]??1/0;return a.charIndex>=h&&a.charIndex<T});p!==-1&&y(t,p,c)},s.onend=()=>{f||(y(t,-1,c),n.utterance=null)},s.onerror=a=>{var p;a.error!=="interrupted"&&((p=e.onError)==null||p.call(e,a)),f||(y(t,-1,c),n.utterance=null)},n.utterance=s,window.speechSynthesis.speak(s),()=>{f||(f=!0,window.speechSynthesis.cancel(),y(t,-1,c),n.utterance=null)}}function M(t){const e=w.get(t);e&&(typeof window<"u"&&"speechSynthesis"in window&&window.speechSynthesis.cancel(),t.innerHTML=e.originalHTML,w.delete(t))}function A(t){const e=t.cloneNode(!0);return e.querySelectorAll(`.${v.word}`).forEach(r=>{const n=r.parentNode;if(n){for(;r.firstChild;)n.insertBefore(r.firstChild,r);n.removeChild(r)}}),e.innerHTML}function E(t,e,r){g.useEffect(()=>{const n=t.current;if(n)return C(n,r),()=>M(n)},[r==null?void 0:r.transitionMs]),g.useEffect(()=>{const n=t.current;n&&y(n,e,r)},[e])}const $=g.forwardRef(function({activeWordIndex:e,as:r="p",children:n,style:l,className:s,activeTracking:d,activeWeight:u,activeOpsz:o,inactiveOpacity:c,transitionMs:i,rate:S,pitch:f,volume:m,onUnsupported:a,onError:p,...h},x){const T=g.useRef(null);g.useImperativeHandle(x,()=>T.current),E(T,e,{activeTracking:d,activeWeight:u,activeOpsz:o,inactiveOpacity:c,transitionMs:i});const H=r;return b.jsx(H,{ref:T,style:l,className:s,...h,children:n})});exports.SPEECH_CLASSES=v;exports.SpeechTypeText=$;exports.applySpeechType=y;exports.getCleanHTML=A;exports.prepareSpeechType=C;exports.removeSpeechType=M;exports.startSpeechType=L;exports.useSpeechType=E;

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+import { ElementType } from 'react';
+import { ForwardRefExoticComponent } from 'react';
+import { RefAttributes } from 'react';
+import { RefObject } from 'react';
+
+/**
+ * Apply typographic emphasis to the word at activeIndex.
+ * All other words receive the inactive style. Pass -1 to reset all words to neutral.
+ *
+ * @param el          - Element previously prepared by prepareSpeechType
+ * @param activeIndex - Index of the word to emphasise, -1 for none
+ * @param options     - SpeechTypeOptions (merged with defaults)
+ */
+export declare function applySpeechType(el: HTMLElement, activeIndex: number, options?: SpeechTypeOptions): void;
+
+/**
+ * Return a clean copy of el's innerHTML with all speechType spans unwrapped.
+ * Does not modify el itself.
+ *
+ * @param el - Element to read clean HTML from
+ */
+export declare function getCleanHTML(el: HTMLElement): string;
+
+declare type HTMLForwardProps = Omit<React.HTMLAttributes<HTMLElement>, keyof SpeechTypeOptions | 'children' | 'style' | 'className'>;
+
+/**
+ * Wrap the text content of el in per-word <span> elements with the SPEECH_CLASSES.word
+ * class. Saves the original innerHTML for cleanup. Idempotent — calling again re-wraps
+ * from the saved original. Returns the array of word span elements.
+ *
+ * @param el      - Element whose text will be wrapped
+ * @param options - SpeechTypeOptions (merged with defaults)
+ */
+export declare function prepareSpeechType(el: HTMLElement, options?: SpeechTypeOptions): HTMLElement[];
+
+/**
+ * Remove speechType from el — cancel any active speech, restore original innerHTML,
+ * and delete all saved state. No-op if prepareSpeechType was never called.
+ *
+ * @param el - The element previously prepared by prepareSpeechType
+ */
+export declare function removeSpeechType(el: HTMLElement): void;
+
+/**
+ * CSS class names injected by speechType.
+ * Only `word` ('st-word') is used — there are no st-active or st-inactive classes.
+ * Emphasis is applied via inline styles (fontVariationSettings, letterSpacing, opacity),
+ * not via class toggles.
+ */
+export declare const SPEECH_CLASSES: {
+    readonly word: "st-word";
+};
+
+/**
+ * Options controlling how speechType emphasises spoken words.
+ *
+ * @remarks
+ * Visual options (activeTracking, activeWeight, activeOpsz, inactiveOpacity, transitionMs)
+ * are used by prepareSpeechType and applySpeechType.
+ * Speech options (rate, pitch, volume) are only used by startSpeechType and are ignored
+ * by applySpeechType, useSpeechType, and SpeechTypeText.
+ *
+ * activeWeight and activeOpsz are written directly into font-variation-settings. Ensure
+ * the values are within the wght/opsz axis ranges supported by your font — out-of-range
+ * values may cause some engines to silently ignore the entire declaration.
+ *
+ * inactiveOpacity: ensure the resulting contrast ratio remains at least 4.5:1 against
+ * your background colour to meet WCAG AA. The default of 0.45 may fail this threshold
+ * depending on your foreground/background pairing.
+ */
+export declare interface SpeechTypeOptions {
+    /** Letter-spacing on the active (currently spoken) word in em. Default: 0.06 */
+    activeTracking?: number;
+    /**
+     * wght axis value on the active word. Default: 700.
+     * Must be within the font's supported wght axis range (e.g. 100–900 for most variable fonts).
+     */
+    activeWeight?: number;
+    /**
+     * opsz axis value on the active word. Default: 24.
+     * Must be within the font's supported opsz axis range (e.g. 6–72 for many variable fonts).
+     */
+    activeOpsz?: number;
+    /**
+     * Opacity of inactive (not currently spoken) words. Default: 0.45.
+     * Values below ~0.5 may reduce contrast below WCAG AA (4.5:1) depending on your colours.
+     * Minimum recommended value: 0.3.
+     */
+    inactiveOpacity?: number;
+    /** CSS transition duration in ms for style changes. Default: 80 */
+    transitionMs?: number;
+    /** Speech rate (0.1–10). Used only by startSpeechType. Default: 0.9 */
+    rate?: number;
+    /** Speech pitch (0–2). Used only by startSpeechType. Default: 1 */
+    pitch?: number;
+    /** Speech volume (0–1). Used only by startSpeechType. Default: 1 */
+    volume?: number;
+    /**
+     * Called when speech synthesis is unavailable in the current browser.
+     * Used only by startSpeechType.
+     */
+    onUnsupported?: () => void;
+    /**
+     * Called when a real speech error occurs (any error code other than "interrupted",
+     * which is a normal cancellation). Receives the SpeechSynthesisErrorEvent.
+     * Used only by startSpeechType.
+     */
+    onError?: (event: SpeechSynthesisErrorEvent) => void;
+}
+
+/**
+ * Renders children inside the given tag, wraps words in spans, and emphasises
+ * the word at activeWordIndex with wider tracking, heavier weight, and larger opsz.
+ * Forwards a ref to the underlying DOM element for imperative startSpeechType access.
+ * All aria-*, data-*, role, lang, and other HTML attributes are forwarded to the DOM element.
+ */
+export declare const SpeechTypeText: ForwardRefExoticComponent<SpeechTypeTextProps & RefAttributes<HTMLElement>>;
+
+/** Props accepted by SpeechTypeText */
+declare interface SpeechTypeTextProps extends SpeechTypeOptions, HTMLForwardProps {
+    /** Index of the word currently being spoken (-1 = no active word). Default: -1 */
+    activeWordIndex: number;
+    /** HTML element tag to render. Default: 'p' */
+    as?: ElementType;
+    /** React children (text content to highlight) */
+    children: React.ReactNode;
+    /** Inline styles forwarded to the rendered element */
+    style?: React.CSSProperties;
+    /** Class name forwarded to the rendered element */
+    className?: string;
+}
+
+/**
+ * Start speech synthesis on el's text content, syncing word emphasis to Web Speech API
+ * boundary events. Calls prepareSpeechType first. Cancels any existing speech.
+ * Returns a stop() function that cancels speech and resets all styles.
+ *
+ * @param el      - Element to speak and highlight
+ * @param options - SpeechTypeOptions (merged with defaults)
+ */
+export declare function startSpeechType(el: HTMLElement, options?: SpeechTypeOptions): () => void;
+
+/**
+ * Prepare word spans on mount and apply emphasis when activeWordIndex changes.
+ * Cleans up by restoring original innerHTML on unmount.
+ *
+ * @param ref             - Ref to the element containing text to highlight
+ * @param activeWordIndex - Index of the currently active word (-1 = none)
+ * @param options         - SpeechTypeOptions (merged with defaults)
+ */
+export declare function useSpeechType(ref: RefObject<HTMLElement | null>, activeWordIndex: number, options?: SpeechTypeOptions): void;
+
+export { }

package/dist/index.js

@@ -0,0 +1,136 @@
+import { useEffect as x, forwardRef as C, useRef as E, useImperativeHandle as H } from "react";
+import { jsx as $ } from "react/jsx-runtime";
+const T = {
+  word: "st-word"
+}, w = /* @__PURE__ */ new WeakMap();
+function M(t, e = {}) {
+  if (typeof window > "u") return [];
+  const r = window.scrollY, n = w.get(t), l = (n == null ? void 0 : n.originalHTML) ?? t.innerHTML;
+  t.innerHTML = l;
+  const f = (t.textContent ?? "").split(/(\s+)/);
+  t.innerHTML = f.map((i) => !i || /^\s+$/.test(i) ? i : `<span class="${T.word}" aria-hidden="true">${i}</span>`).join("");
+  const u = Array.from(t.querySelectorAll(`.${T.word}`)), o = e.transitionMs ?? 80;
+  u.forEach((i) => {
+    i.style.display = "inline", i.style.transition = [
+      `font-variation-settings ${o}ms ease`,
+      `letter-spacing ${o}ms ease`,
+      `opacity ${o}ms ease`
+    ].join(", ");
+  });
+  let c = t.querySelector("[data-st-live]");
+  return c || (c = document.createElement("span"), c.setAttribute("data-st-live", ""), c.setAttribute("aria-live", "polite"), c.setAttribute("aria-atomic", "true"), c.style.cssText = "position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0", t.appendChild(c)), w.set(t, { originalHTML: l, wordSpans: u, utterance: null, activeIndex: -1 }), requestAnimationFrame(() => {
+    Math.abs(window.scrollY - r) > 2 && window.scrollTo({ top: r, behavior: "instant" });
+  }), u;
+}
+function v(t, e, r = {}) {
+  var c;
+  if (typeof window > "u") return;
+  const n = w.get(t);
+  if (!n) return;
+  const l = r.activeTracking ?? 0.06, s = r.activeWeight ?? 700, f = r.activeOpsz ?? 24, u = r.inactiveOpacity ?? 0.45;
+  n.activeIndex = e;
+  const o = t.querySelector("[data-st-live]");
+  o && (o.textContent = e >= 0 ? ((c = n.wordSpans[e]) == null ? void 0 : c.textContent) ?? "" : ""), n.wordSpans.forEach((i, y) => {
+    y === e ? (i.setAttribute("aria-current", "true"), i.style.fontVariationSettings = `"wght" ${s}, "opsz" ${f}`, i.style.letterSpacing = `${l}em`, i.style.opacity = "1") : (i.removeAttribute("aria-current"), i.style.fontVariationSettings = "", i.style.letterSpacing = "", i.style.opacity = e === -1 ? "1" : String(u));
+  });
+}
+function R(t, e = {}) {
+  var g;
+  if (typeof window > "u" || !("speechSynthesis" in window))
+    return (g = e.onUnsupported) == null || g.call(e), () => {
+    };
+  const r = M(t, e), n = w.get(t);
+  if (!n) return () => {
+  };
+  window.speechSynthesis.cancel();
+  const l = r.map((a) => a.textContent ?? "").join(" "), s = new SpeechSynthesisUtterance(l);
+  s.rate = e.rate ?? 0.9, s.pitch = e.pitch ?? 1, s.volume = e.volume ?? 1;
+  const f = e.activeTracking ?? 0.06, u = e.activeWeight ?? 700, o = e.activeOpsz ?? 24, c = { ...e, activeTracking: f, activeWeight: u, activeOpsz: o };
+  let i = 0;
+  const y = r.map((a) => {
+    var h;
+    const d = i;
+    return i += (((h = a.textContent) == null ? void 0 : h.length) ?? 0) + 1, d;
+  });
+  let p = !1;
+  return s.onboundary = (a) => {
+    if (p || a.name !== "word") return;
+    const d = y.findIndex((h, m) => {
+      const S = y[m + 1] ?? 1 / 0;
+      return a.charIndex >= h && a.charIndex < S;
+    });
+    d !== -1 && v(t, d, c);
+  }, s.onend = () => {
+    p || (v(t, -1, c), n.utterance = null);
+  }, s.onerror = (a) => {
+    var d;
+    a.error !== "interrupted" && ((d = e.onError) == null || d.call(e, a)), p || (v(t, -1, c), n.utterance = null);
+  }, n.utterance = s, window.speechSynthesis.speak(s), () => {
+    p || (p = !0, window.speechSynthesis.cancel(), v(t, -1, c), n.utterance = null);
+  };
+}
+function b(t) {
+  const e = w.get(t);
+  e && (typeof window < "u" && "speechSynthesis" in window && window.speechSynthesis.cancel(), t.innerHTML = e.originalHTML, w.delete(t));
+}
+function j(t) {
+  const e = t.cloneNode(!0);
+  return e.querySelectorAll(`.${T.word}`).forEach((r) => {
+    const n = r.parentNode;
+    if (n) {
+      for (; r.firstChild; ) n.insertBefore(r.firstChild, r);
+      n.removeChild(r);
+    }
+  }), e.innerHTML;
+}
+function A(t, e, r) {
+  x(() => {
+    const n = t.current;
+    if (n)
+      return M(n, r), () => b(n);
+  }, [r == null ? void 0 : r.transitionMs]), x(() => {
+    const n = t.current;
+    n && v(n, e, r);
+  }, [e]);
+}
+const k = C(
+  function({
+    activeWordIndex: e,
+    as: r = "p",
+    children: n,
+    style: l,
+    className: s,
+    // Extract SpeechTypeOptions fields explicitly so they are NOT forwarded to the DOM
+    activeTracking: f,
+    activeWeight: u,
+    activeOpsz: o,
+    inactiveOpacity: c,
+    transitionMs: i,
+    rate: y,
+    pitch: p,
+    volume: g,
+    onUnsupported: a,
+    onError: d,
+    // Remaining props (aria-*, data-*, role, lang, etc.) are forwarded to the DOM element
+    ...h
+  }, m) {
+    const S = E(null);
+    return H(m, () => S.current), A(S, e, {
+      activeTracking: f,
+      activeWeight: u,
+      activeOpsz: o,
+      inactiveOpacity: c,
+      transitionMs: i
+    }), /* @__PURE__ */ $(r, { ref: S, style: l, className: s, ...h, children: n });
+  }
+);
+export {
+  T as SPEECH_CLASSES,
+  k as SpeechTypeText,
+  v as applySpeechType,
+  j as getCleanHTML,
+  M as prepareSpeechType,
+  b as removeSpeechType,
+  R as startSpeechType,
+  A as useSpeechType
+};

package/dist/speechtype.webflow.min.js

@@ -0,0 +1 @@
+var SpeechType=(function(d){"use strict";const k={word:"st-word"},f=new WeakMap;function O(e,t={}){if(typeof window>"u")return[];const i=window.scrollY,n=f.get(e),p=(n==null?void 0:n.originalHTML)??e.innerHTML;e.innerHTML=p;const y=(e.textContent??"").split(/(\s+)/);e.innerHTML=y.map(s=>!s||/^\s+$/.test(s)?s:`<span class="${k.word}" aria-hidden="true">${s}</span>`).join("");const u=Array.from(e.querySelectorAll(`.${k.word}`)),o=t.transitionMs??80;u.forEach(s=>{s.style.display="inline",s.style.transition=[`font-variation-settings ${o}ms ease`,`letter-spacing ${o}ms ease`,`opacity ${o}ms ease`].join(", ")});let r=e.querySelector("[data-st-live]");return r||(r=document.createElement("span"),r.setAttribute("data-st-live",""),r.setAttribute("aria-live","polite"),r.setAttribute("aria-atomic","true"),r.style.cssText="position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0",e.appendChild(r)),f.set(e,{originalHTML:p,wordSpans:u,utterance:null,activeIndex:-1}),requestAnimationFrame(()=>{Math.abs(window.scrollY-i)>2&&window.scrollTo({top:i,behavior:"instant"})}),u}function w(e,t,i={}){var r;if(typeof window>"u")return;const n=f.get(e);if(!n)return;const p=i.activeTracking??.06,a=i.activeWeight??700,y=i.activeOpsz??24,u=i.inactiveOpacity??.45;n.activeIndex=t;const o=e.querySelector("[data-st-live]");o&&(o.textContent=t>=0?((r=n.wordSpans[t])==null?void 0:r.textContent)??"":""),n.wordSpans.forEach((s,S)=>{S===t?(s.setAttribute("aria-current","true"),s.style.fontVariationSettings=`"wght" ${a}, "opsz" ${y}`,s.style.letterSpacing=`${p}em`,s.style.opacity="1"):(s.removeAttribute("aria-current"),s.style.fontVariationSettings="",s.style.letterSpacing="",s.style.opacity=t===-1?"1":String(u))})}function C(e,t={}){var A;if(typeof window>"u"||!("speechSynthesis"in window))return(A=t.onUnsupported)==null||A.call(t),()=>{};const i=O(e,t),n=f.get(e);if(!n)return()=>{};window.speechSynthesis.cancel();const p=i.map(c=>c.textContent??"").join(" "),a=new SpeechSynthesisUtterance(p);a.rate=t.rate??.9,a.pitch=t.pitch??1,a.volume=t.volume??1;const y=t.activeTracking??.06,u=t.activeWeight??700,o=t.activeOpsz??24,r={...t,activeTracking:y,activeWeight:u,activeOpsz:o};let s=0;const S=i.map(c=>{var m;const l=s;return s+=(((m=c.textContent)==null?void 0:m.length)??0)+1,l});let v=!1;return a.onboundary=c=>{if(v||c.name!=="word")return;const l=S.findIndex((m,F)=>{const P=S[F+1]??1/0;return c.charIndex>=m&&c.charIndex<P});l!==-1&&w(e,l,r)},a.onend=()=>{v||(w(e,-1,r),n.utterance=null)},a.onerror=c=>{var l;c.error!=="interrupted"&&((l=t.onError)==null||l.call(t,c)),v||(w(e,-1,r),n.utterance=null)},n.utterance=a,window.speechSynthesis.speak(a),()=>{v||(v=!0,window.speechSynthesis.cancel(),w(e,-1,r),n.utterance=null)}}function E(e){const t=f.get(e);t&&(typeof window<"u"&&"speechSynthesis"in window&&window.speechSynthesis.cancel(),e.innerHTML=t.originalHTML,f.delete(e))}const L="data-speechtype",H="false",h=new WeakMap;function b(e){const t=e.dataset,i={};if(t.stTracking!==void 0){const n=parseFloat(t.stTracking);isNaN(n)||(i.activeTracking=n)}if(t.stWeight!==void 0){const n=parseFloat(t.stWeight);isNaN(n)||(i.activeWeight=n)}if(t.stOpsz!==void 0){const n=parseFloat(t.stOpsz);isNaN(n)||(i.activeOpsz=n)}if(t.stInactiveOpacity!==void 0){const n=parseFloat(t.stInactiveOpacity);isNaN(n)||(i.inactiveOpacity=n)}if(t.stTransition!==void 0){const n=parseFloat(t.stTransition);isNaN(n)||(i.transitionMs=n)}if(t.stRate!==void 0){const n=parseFloat(t.stRate);isNaN(n)||(i.rate=n)}if(t.stPitch!==void 0){const n=parseFloat(t.stPitch);isNaN(n)||(i.pitch=n)}if(t.stVolume!==void 0){const n=parseFloat(t.stVolume);isNaN(n)||(i.volume=n)}return i.onUnsupported=()=>{console.warn("SpeechType: this browser does not support the Web Speech API — nothing will be spoken.")},i}function T(e){const t=h.get(e);if(t){if(t.stop){N(e);return}t.stop=C(e,b(e))}}function N(e){const t=h.get(e);!t||!t.stop||(t.stop(),t.stop=null)}function $(e){N(e),T(e)}function I(e){M(e),O(e,b(e));let t=null;e.dataset.stClick!==H&&(t=()=>T(e),e.addEventListener("click",t),e.style.cursor="pointer"),h.set(e,{stop:null,clickHandler:t})}function M(e){const t=h.get(e);t&&(t.stop&&t.stop(),t.clickHandler&&(e.removeEventListener("click",t.clickHandler),e.style.cursor=""),E(e),h.delete(e))}function g(e=document){e.querySelectorAll(`[${L}]`).forEach(I)}function W(){const e=()=>{var t;(t=document.fonts)!=null&&t.ready?document.fonts.ready.then(()=>g()).catch(()=>g()):g()};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",e,{once:!0}):e()}return W(),d.destroy=M,d.init=g,d.restart=$,d.speak=T,d.stop=N,Object.defineProperty(d,Symbol.toStringTag,{value:"Module"}),d})({});

package/package.json

@@ -0,0 +1,91 @@
+{
+	"name": "@overpunch/speechtype",
+	"version": "1.0.11",
+	"description": "Typography that follows your voice — per-word typographic emphasis synced to Web Speech API boundary events",
+	"type": "module",
+	"main": "dist/index.cjs",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "vite build",
+		"build:webflow": "vite build --config vite.webflow.config.ts",
+		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
+		"prepublishOnly": "npm run test && npm run build && npm run build:webflow"
+	},
+	"peerDependencies": {
+		"react": ">=17",
+		"react-dom": ">=17"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		},
+		"react-dom": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@testing-library/react": "^16.3.2",
+		"@testing-library/user-event": "^14.6.1",
+		"@types/react": "^19.0.0",
+		"@vitejs/plugin-react": "^4.0.0",
+		"happy-dom": "^20.10.6",
+		"next": "16.2.2",
+		"react": "^19.0.0",
+		"typescript": "^5.0.0",
+		"vite": "^6.0.0",
+		"vite-plugin-dts": "^4.0.0",
+		"vitest": "^3.0.0"
+	},
+	"keywords": [
+		"typography",
+		"web-typography",
+		"frontend",
+		"liiift-studio",
+		"speech-synthesis",
+		"web-speech-api",
+		"tts",
+		"text-to-speech",
+		"voice",
+		"karaoke",
+		"word-highlight",
+		"accessibility",
+		"a11y",
+		"language-learning",
+		"teleprompter",
+		"variable-font",
+		"font-variation-settings",
+		"wght",
+		"opsz",
+		"letter-spacing",
+		"zero-dependencies",
+		"react",
+		"typescript",
+		"css"
+	],
+	"author": "Quinn Keaveney <quinn@liiift.studio>",
+	"license": "MIT",
+	"homepage": "https://speechtype.vercel.app",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/over-punch/speechType.git"
+	},
+	"bugs": {
+		"url": "https://github.com/over-punch/speechType/issues"
+	},
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}