feat: optional input-smoothing utility (./smoothing)

[jonathanKingston]

Closes #84.

An opt-in reveal-smoothing utility behind a new ./smoothing subpath — off by default, zero bytes in the main bundle unless imported, and the incremental DOM emitter's default behavior is byte-for-byte unchanged.

Approach: input-smoothing, not output-animation

The smoother throttles the input string fed to renderer.update() — releasing a growing prefix a few characters per frame via requestAnimationFrame — rather than animating newly-added DOM nodes. Every released value is a prefix of the accumulated text, i.e. exactly the streaming contract the existing pending-state machinery and DOM morph already converge on, so it composes with them instead of introducing a second animation system that could fight the morph. Lower-risk and framework-/theme-agnostic.

CSS entrance animations are deliberately left to the host (documented): style the emitter's existing .stream-pending / .stream-complete hooks with your own transitions.

API

import { createInputSmoother } from '@copse/streaming-markdown/smoothing'

const smoother = createInputSmoother({ update: (t) => renderer.update(t), charsPerSecond: 600 })
for await (const chunk of stream) { accumulated += chunk; smoother.push(accumulated) }
smoother.flush() // release everything immediately on stream end

createInputSmoother({ update, charsPerSecond=600, disabled, respectReducedMotion=true, + injectable now/requestFrame/cancelFrame/matchMedia seams }) → { push, flush, dispose, enabled }.

Guarantees

• Off by default; zero main-bundle bytes (asserted via an esbuild bundle-of-index test).
• prefers-reduced-motion → smoothing disabled, immediate pass-through.
• Post-flush() DOM equals a single un-smoothed update(fullText) (asserted against a direct full-string render) — convergence preserved.
• All environment globals read through defaulted injectable seams, so it runs and unit-tests under node/jsdom.
• UTF-16-surrogate-safe: intermediate frames never emit a lone surrogate half.

Verification

• npm run typecheck, npm run build (dist/smoothing.* emitted) — pass
• npm test — 786 pass / 0 fail / 1 pre-existing skip (incl. 19 new smoothing tests)
• npm run check:conformance / npm run check:gfm-conformance — pass
• npm run coverage:ci — gate passes; smoothing.ts 100% lines/funcs; baseline ratcheted 99.75 → 99.76

Caveats

• prefers-reduced-motion is evaluated once at creation (documented).
• The c8-instrumented full run took a late SIGKILL in the sandbox after flushing a complete coverage summary (which the gate passed against, +0.01%); the uninstrumented suite completed cleanly green. A clean CI run can only match or exceed this. Worth a glance at the CI coverage job.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ehmok4AzyTQDNkRzW3g8z8

---

Generated by Claude Code