StringTune

StringTune is a modular runtime for scroll-driven motion, cursor interaction, responsive visibility, media helpers, and diagnostics.

This docs site treats the library source and package exports as the only source of truth. If an older snippet, copied example, or internal project module disagrees with the current package, the package wins.

What matters first

• The public surface comes from the package exports, not from internal runtime folders.
• Built-in modules and custom modules are documented separately on purpose.
• Most user-facing behavior is one of four things:
  • instance API on StringTune
  • module registration through stringTune.use(...)
  • declarative attributes in HTML
  • outputs written as CSS variables, classes, inline styles, or emitted events

Runtime model

StringTune is not a bag of unrelated effects. It is one runtime instance that:

• registers modules
• scans the DOM for matching objects
• calculates geometry and state on frame updates
• writes outputs back to the DOM

In practice, a module usually follows this contract:

1. You activate it with stringTune.use(...).
2. You configure an element through string="..." and related attributes.
3. The runtime computes state from scroll, cursor, viewport, or form input.
4. The module publishes that state as CSS variables, classes, inline transforms, helper nodes, or events.

Documentation model

Use the docs in this order:

1. Read Installation and Quick Start if you are integrating the package.
2. Read Configuration and the rest of Concepts if you need to understand object ids, offsets, events, or scroll modes.
3. Go to Built-in Modules Overview for the official module catalog and the per-module public API.
4. Use API Overview when you need exact exports, shared attributes, settings, and event names.

Package boundaries

Built-in modules

These are official exports from the package and belong in the main module catalog. They are the supported integration surface of StringTune.

Examples:

• StringProgress
• StringCursor
• StringResponsive
• StringLoading

Custom modules

These are project-specific extensions built on top of StringTune. They can be valid for a product codebase, but they are not part of the package contract unless they are exported by the package itself.

Internal runtime

Internal managers and helpers exist to run the system, but they are not a supported integration surface. The docs may reference them conceptually to explain behavior, but they are not documented as public API.

Core integration pattern

import StringTune, { StringProgress, StringCursor } from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();

stringTune.use(StringProgress);
stringTune.use(StringCursor, { lerp: 0.8 });
stringTune.start(60);

<div string="progress" string-id="hero"></div>

That pattern stays the same across the library:

• register the modules you need
• attach declarative attributes in markup
• consume the module output in CSS or JavaScript

What this docs site optimizes for

• fast lookup over long narrative
• accurate API and runtime behavior
• examples that match the real code
• explicit boundaries between official, custom, and internal behavior