Event Channels

StringTune exposes one global event bus through:

TypeScript

stringTune.on(eventName, callback);
stringTune.off(eventName, callback);

This page lists channels that are reasonable to treat as public integration surface.

Important Boundary

Some events in the runtime exist only for internal orchestration.

Examples:

Those channels are used by controllers and modules internally. They should not be documented as normal app-facing API.

Channel	Payload	Fired when
`start`	`null`	`stringTune.start()` finishes initialization
`update`	`null`	End of each update frame
`scroll`	`number`	Scroll position changes
`lerp`	`number`	Shared scroll lerp value changes
`scroll:start`	`null`	Scrolling begins
`scroll:stop`	`null`	Scrolling stops
`dom:changed`	`null`	Object manager detects relevant DOM additions or removals

Channel	Payload	Fired when
`screen:mobile`	`boolean`	Responsive mobile match changes
`screen:tablet`	`boolean`	Responsive tablet match changes
`screen:laptop`	`boolean`	Responsive laptop match changes
`screen:desktop`	`boolean`	Responsive desktop match changes
`cursor`	`{ x, y, stepX, stepY }`	Cursor portal state changes
`fps`	`number`	FPS tracker measures a new FPS value
`scroll-position`	`{ val, valPct, direction }`	Position tracker updates
`tracker:fps:visible`	`boolean`	`stringTune.FPSTrackerVisible` changes
`tracker:position:visible`	`boolean`	`stringTune.PositionTrackerVisible` changes
`masonry:shuffle:start`	`{ object }`	Masonry shuffle starts
`masonry:shuffle:end`	`{ object }`	Masonry shuffle ends

These are keyed by object ID, so they depend on string-id.

Channel	Payload	Fired when
`object:activate:<id>`	`boolean`	Activation observer toggles the object
`object:inview:<id>`	`{ inView, direction }`	In-view window changes

direction is one of:

Channel	Payload	Fired when
`object:progress:<id>`	`number`	`StringProgress` updates eased progress
`object:progress-slice:<id>`	`number`	`StringProgressPart` updates remapped slice progress
`object:parallax:<id>`	`number`	`StringParallax` recomputes translation
`object:lerp:<id>`	`number`	`StringLerp` applies a new lerp value
`object:glide:<id>`	`number`	`StringGlide` recomputes the pixel translation

Important:

Channel	Payload	Fired when
`cursor:start:<id>`	`null`	Cursor target tracking becomes active
`cursor:move:<id>`	`{ x, y }`	Target-local cursor coordinates change
`cursor:pixel:<id>`	`{ x, y }`	Target-local pixel coordinates change
`cursor:end:<id>`	`null`	Cursor target tracking ends
`magnetic:move:<id>`	`{ x, y }`	Magnetic offset changes
`spotlight:update:<id>`	`{ angleDeg, distance }`	Spotlight values change
`object:impulse:<id>:move`	`{ x, y }`	Impulse translation output changes
`object:impulse:<id>:rotate`	`{ rotation }`	Impulse rotation output changes
`object:impulse:<id>:side`	`{ value }`	Pointer side position across the element changes

The order for suffixed impulse channels is important:

Channel	Payload	Fired when
`form:submit:<id>`	`Record<string, any>`	Submit passes validation
`form:invalid:<id>`	`void`	Submit fails validation
`form:field:valid:<key>`	`{ key, field, errors, phase, valid }`	Field becomes valid
`form:field:invalid:<key>`	`{ key, field, errors, phase, valid }`	Field fails live validation
`form:field:error:<key>`	`{ key, field, errors, phase, valid }`	Field fails submit validation

Form field channels are keyed by field key, not by form ID.

Some behavior in the runtime is local to StringObject.events, not the global bus.

Examples:

StringVideoAutoplay uses those local object events internally. They are not consumed through stringTune.on(...).