Custom Modules

This section is the authoring handbook for project-specific modules.

It is not about internal runtime archaeology and it is not a catalog of built-in exports. The goal here is narrower: show how to build your own module on top of the public authoring surface that already ships with StringTune.

What counts as a custom module

A custom module is a class in your own project that extends StringModule and is registered through stringTune.use(...).

Typical reasons to write one:

• a design system needs a behavior that is too project-specific for the package
• you want to compose existing runtime state into a new output channel
• you want one declarative HTML contract shared across several pages

Safe authoring surface

These are the authoring primitives that are exported by the package and are reasonable to rely on when building custom modules:

• StringModule
• StringObject
• StringContext
• ScrollController
• frameDOM
• styleTxn
• DOMBatcher

Everything else in core/managers, objects, or modules should be treated as implementation detail unless it is explicitly exported by the package.

What this section covers

Use the pages in this order:

1. First Custom Module for the smallest working example.
2. Element vs Global Modules to choose the right module shape.
3. Module Contract to understand htmlKey, settings, attribute mapping, and output channels.
4. Lifecycle Hooks to see which hooks actually run in the current runtime.
5. Objects and Attributes for StringObject, mirrored elements, and parsed properties.
6. Context, Tools, and Events for the injected utilities and event patterns.
7. Performance Patterns for read/write separation and rebuild control.
8. Worked Example for a full element module that composes with StringProgress.

Authoring rule

Do not document or ship a project module as if it were a built-in package module.

Every custom module page or code example should make these boundaries explicit:

• where the module lives
• who owns it
• whether it ships with @fiddle-digital/string-tune
• which built-in runtime assumptions it depends on

The practical mindset

Good custom modules in StringTune are usually small.

They do one of these things well:

• read a few attributes and write CSS variables
• react to existing object state such as progress
• subscribe to events and republish a more convenient channel
• bind one DOM-specific behavior behind a stable declarative API

If a module starts needing deep knowledge of ObjectManager, hidden DOM rebuild phases, or private state from another module, that is usually a sign that the design should be simplified.