StringPositionTracker

StringPositionTracker is a diagnostics module for the active global scroll state. On every scroll update it exposes three public values:

• current scroll position in pixels
• current scroll position as a percentage
• current direction marker

It can write those values into DOM attributes, emit them as one shared event, and optionally show a floating overlay.

Public API

Attributes

StringPositionTracker does not read any string-* activation attributes. It is a global module registered through use().

The DOM hooks it watches are:

• data-val
• data-val-pct
• data-dir

CSS Variables and DOM Output

The module writes these attributes:

• data-val
• data-val-pct
• data-dir

Meaning:

• data-val is the rounded current scroll position in pixels
• data-val-pct is the rounded progress percentage of the global scroll range
• data-dir is one of ↓, ↑, or •

If stringTune.PositionTrackerVisible = true, the runtime also creates one floating overlay in the bottom-left corner and writes the same attributes there.

Events

stringTune.on('scroll-position', ({ val, valPct, direction }) => {
  console.log(val, valPct, direction);
});

Mirror Behavior

This module has no mirror output contract.

Quick Example

<div class="scroll-debug">
  <div class="debug-row">
    <span>Direction</span>
    <strong data-dir></strong>
  </div>
  <div class="debug-row">
    <span>Pixels</span>
    <strong data-val></strong>
  </div>
  <div class="debug-row">
    <span>Progress</span>
    <strong data-val-pct></strong>
  </div>
</div>

.scroll-debug {
  position: fixed;
  bottom: 24px;
  left: 24px;
  background: black;
  color: white;
  padding: 1.25rem;
  border: 1px solid #333;
  font-family: ui-monospace, SFMono-Regular, monospace;
  font-size: 0.875rem;
  display: grid;
  gap: 0.75rem;
  min-width: 180px;
}

.debug-row {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.debug-row span {
  color: #999;
  text-transform: uppercase;
  font-size: 0.75rem;
  letter-spacing: 0.05em;
}

[data-dir]::before { content: attr(data-dir); }
[data-val]::before { content: attr(data-val) "px"; }
[data-val-pct]::before { content: attr(data-val-pct) "%"; }

Registration

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

const stringTune = StringTune.getInstance();
stringTune.use(StringPositionTracker);
stringTune.start(60);

If you want the built-in floating overlay, enable it explicitly:

stringTune.PositionTrackerVisible = true;

Detailed Behavior

• The tracker watches the whole document for the three diagnostic attributes and refreshes its cache through a MutationObserver.
• Percentage is computed from current / (contentHeight - windowHeight) and rounded to an integer.
• Direction is derived from scroll motion. When movement stops, the module resets the marker to • after about 150ms.
• Without the built-in overlay, your own [data-val], [data-val-pct], and [data-dir] elements still receive updates, but you control their visual presentation.