StringFPSTracker

StringFPSTracker is a diagnostics module. It counts rendered frames once per second and exposes that number through two public surfaces:

• elements with data-fps
• the global fps event

It can also render its own floating debug overlay, but that overlay is optional and disabled by default.

Public API

Attributes

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

The only DOM hook it watches is:

• data-fps

CSS Variables and DOM Output

The module writes:

• data-fps="<integer>"

on every tracked element in the document.

If stringTune.FPSTrackerVisible = true, it also creates one floating overlay element in the bottom-right corner and updates the same data-fps attribute on that overlay.

Events

stringTune.on('fps', (fps) => {
  console.log(fps);
});

Mirror Behavior

This module has no mirror output contract.

Quick Example

<div class="debug-panel">
  <div class="debug-label">Performance</div>
  <div data-fps class="fps-value"></div>
</div>

.debug-panel {
  position: fixed;
  bottom: 24px;
  right: 24px;
  background: black;
  color: white;
  padding: 1rem;
  border: 1px solid #333;
  display: flex;
  gap: 1rem;
  align-items: center;
  font-family: ui-monospace, SFMono-Regular, monospace;
  font-size: 0.875rem;
}

.debug-label {
  text-transform: uppercase;
  color: #999;
}

.fps-value {
  font-weight: bold;
}

.fps-value::before {
  content: attr(data-fps) " FPS";
}

Registration

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

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

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

stringTune.FPSTrackerVisible = true;

Detailed Behavior

• The tracker scans the whole document for [data-fps] and keeps that list fresh with a MutationObserver.
• The public value is an integer frame count over the last one-second window, not an averaged moving metric.
• The built-in overlay injects a small helper style that renders FPS: <value> through ::before.
• Without the built-in overlay, your own [data-fps] elements still receive attribute updates, but you are responsible for presenting that value in CSS or JavaScript.