@labcat2020/p5.audioreactive 0.1.2 → 0.1.3

package/README.md

@@ -21,10 +21,12 @@ pnpm add @labcat2020/p5.audioreactive p5
   "./p5.polygon.js": "./src/p5.polygon.js",
   "./p5.pattern.js": "./src/p5.pattern.js",
   "./p5.randomColor.js": "./src/p5.randomColor.js",
+  "./p5.fps.js": "./src/p5.fps.js",
   "./sacredGeometry.js": "./src/sacredGeometry.js"
 }
 ```
 - `p5.audioReact.js` — `getSongPlaybackTime()`, `scheduleCueSet()`, `loadSong()`/`loadMidi` via `@tonejs/midi` + `p5.sound` boot (`p5.soundBoot.js`, `p5.setGlobalP5.js`).
+- `p5.fps.js` — `p.enableFpsIndicator()` / `disable` / `toggle` / `updateFpsIndicator()` + aliases `showFps`/`hideFps`; bottom-right `lab-label` badge (hidden during capture). See Usage below.
 - `p5.colorGenerator.js` / `p5.randomColor.js` — palette helpers (randomColor port).
 - `p5.Polar.min.js` (Liz Peng) — `polarTriangle`, `polarEllipse`, etc.
 - `p5.polygon.js` — **deprecated re-export** → canonical is `@labcat2020/p5.polygon`.
@@ -45,6 +47,15 @@ await p.loadSong(audioUrl, midiUrl, (data) => {
 p.fft = new p5.FFT();
 ```
 
+FPS indicator (bottom-right badge, shares `lab-label` style from `@labcat2020/animation-lab`):
+```js
+import '@labcat2020/p5.audioreactive/p5.fps.js';
+// in setup(): p.enableFpsIndicator({ decimals: 0, updateInterval: 250 })
+// Toggle: p.toggleFpsIndicator(); aliases: p.showFps(), p.hideFps()
+// Markup auto-created if missing; provide <div id="fps-indicator" class="lab-label lab-label--bottom-right lab-label--fps" hidden>
+// via @labcat2020/animation-lab/components/FpsIndicator.astro or SketchLayout showFps prop. Hidden during capture.
+```
+
 Geometry (prefer new libs for new code):
 ```js
 import '@labcat2020/p5.audioreactive/p5.Polar.min.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@labcat2020/p5.audioreactive",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "p5.js audio-reactive helpers, sound boot, and shared sketch utilities",
   "exports": {
@@ -11,6 +11,7 @@
     "./p5.polygon.js": "./src/p5.polygon.js",
     "./p5.pattern.js": "./src/p5.pattern.js",
     "./p5.randomColor.js": "./src/p5.randomColor.js",
+    "./p5.fps.js": "./src/p5.fps.js",
     "./sacredGeometry.js": "./src/sacredGeometry.js"
   },
   "files": [
@@ -20,7 +21,8 @@
   "sideEffects": [
     "./src/p5.audioReact.js",
     "./src/p5.soundBoot.js",
-    "./src/p5.setGlobalP5.js"
+    "./src/p5.setGlobalP5.js",
+    "./src/p5.fps.js"
   ],
   "publishConfig": {
     "access": "public"
@@ -46,4 +48,4 @@
     "generative",
     "labcat"
   ]
-}
+}

package/src/p5.fps.js

@@ -0,0 +1,164 @@
+import p5 from 'p5';
+
+/**
+ * FPS indicator for audio-reactive sketches.
+ *
+ * Provides p.enableFpsIndicator / p.disableFpsIndicator / p.toggleFpsIndicator
+ * and a DOM badge in the bottom-right corner. Reuses the shared lab-label
+ * styling from @labcat2020/animation-lab (see packages/animation-lab/src/styles/components/lab-label.scss)
+ * with a JS-injected fallback when that stylesheet is absent.
+ *
+ * Usage:
+ *   import '@labcat2020/p5.audioreactive/p5.fps.js';
+ *   // in setup():
+ *   p.enableFpsIndicator(); // shows bottom-right badge
+ *   // options: { elementId, updateInterval, decimals, autoCreate }
+ */
+
+const STYLE_ID = 'lab-label-fallback-style';
+const DEFAULT_ID = 'fps-indicator';
+
+function ensureFallbackStyle() {
+  if (document.getElementById(STYLE_ID)) return;
+  // Only inject if .lab-label not already styled (best-effort detection)
+  // We inject anyway as low-specificity fallback; real lab styles win via cascade order.
+  const css = `
+.lab-label{position:fixed;z-index:1000;padding:8px 12px;background:var(--black,#000);font-family:'Orbitron',monospace;font-weight:700;color:var(--white,#fff);pointer-events:none;line-height:1;font-size:14px}
+.lab-label--top-right{top:10px;right:10px}
+.lab-label--bottom-right{bottom:10px;right:10px}
+.lab-label--fps{min-width:4.5em;text-align:right;font-variant-numeric:tabular-nums}
+.lab-label[hidden]{display:none !important}
+`;
+  const tag = document.createElement('style');
+  tag.id = STYLE_ID;
+  tag.textContent = css;
+  document.head.appendChild(tag);
+}
+
+function resolveElement(elementId, autoCreate) {
+  let el = document.getElementById(elementId);
+  if (!el && autoCreate) {
+    ensureFallbackStyle();
+    el = document.createElement('div');
+    el.id = elementId;
+    el.className = 'lab-label lab-label--bottom-right lab-label--fps';
+    el.setAttribute('aria-live', 'polite');
+    el.hidden = true;
+    document.body.appendChild(el);
+  }
+  return el;
+}
+
+p5.prototype._fpsIndicatorEl = null;
+p5.prototype._fpsIntervalId = null;
+p5.prototype._fpsUpdate = null;
+
+/**
+ * Enable and start updating the FPS badge.
+ * @param {object} [opts]
+ * @param {string} [opts.elementId='fps-indicator']
+ * @param {boolean} [opts.autoCreate=true] - create the div if missing
+ * @param {number} [opts.updateInterval=250] - ms between DOM updates
+ * @param {number} [opts.decimals=0] - decimal places
+ */
+p5.prototype.enableFpsIndicator = function (opts = {}) {
+  const {
+    elementId = DEFAULT_ID,
+    autoCreate = true,
+    updateInterval = 250,
+    decimals = 0,
+  } = opts;
+
+  const el = resolveElement(elementId, autoCreate);
+  if (!el) {
+    console.warn(`enableFpsIndicator: #${elementId} not found and autoCreate disabled`);
+    return;
+  }
+  // Ensure correct classes if element pre-existed but lacked styling
+  if (!el.classList.contains('lab-label')) {
+    el.classList.add('lab-label', 'lab-label--bottom-right', 'lab-label--fps');
+  }
+  el.hidden = false;
+  this._fpsIndicatorEl = el;
+
+  // Clear any previous interval
+  this.disableFpsIndicator();
+
+  // measured FPS via deltaTime (p5.getFrameRate() in p5 v2 returns _targetFrameRate, not actual)
+  this._fpsSmoothed = null;
+  this._fpsWindow = this._fpsWindow || [];
+  if (!this._fpsDrawWrapped && typeof this.draw === 'function') {
+    const orig = this.draw;
+    const self = this;
+    this._fpsOrigDraw = orig;
+    this._fpsDrawWrapped = true;
+    this.draw = function (...args) {
+      const now = performance.now();
+      self._fpsWindow.push(now);
+      if (self._fpsWindow.length > 60) self._fpsWindow.shift();
+      return orig.apply(self, args);
+    };
+  }
+  const update = () => {
+    if (!this._fpsIndicatorEl) return;
+    if (this.captureInProgress) {
+      this._fpsIndicatorEl.hidden = true;
+      return;
+    }
+    this._fpsIndicatorEl.hidden = false;
+    let fps = 0;
+    const dt = this.deltaTime;
+    if (typeof dt === 'number' && dt > 0 && dt < 1000) {
+      const instant = 1000 / dt;
+      if (this._fpsSmoothed == null) this._fpsSmoothed = instant;
+      else this._fpsSmoothed = this._fpsSmoothed * 0.8 + instant * 0.2;
+      fps = this._fpsSmoothed;
+    } else if (this._fpsWindow && this._fpsWindow.length >= 2) {
+      const span = this._fpsWindow[this._fpsWindow.length - 1] - this._fpsWindow[0];
+      if (span > 0) fps = (this._fpsWindow.length - 1) * 1000 / span;
+    }
+    const text = Number.isFinite(fps) && fps > 0 ? `${fps.toFixed(decimals)} FPS` : '-- FPS';
+    this._fpsIndicatorEl.textContent = text;
+  };
+
+  this._fpsUpdate = update;
+  update();
+  this._fpsIntervalId = setInterval(update, updateInterval);
+};
+
+/**
+ * Stop updating (leaves element hidden state as-is; caller may hide).
+ */
+p5.prototype.disableFpsIndicator = function () {
+  if (this._fpsIntervalId != null) {
+    clearInterval(this._fpsIntervalId);
+    this._fpsIntervalId = null;
+  }
+};
+
+/**
+ * Manual tick — useful if you prefer to call from draw() instead of interval.
+ * No-op when not enabled.
+ */
+p5.prototype.updateFpsIndicator = function () {
+  if (typeof this._fpsUpdate === 'function') this._fpsUpdate();
+};
+
+/**
+ * Convenience toggle.
+ */
+p5.prototype.toggleFpsIndicator = function (opts) {
+  if (this._fpsIntervalId != null) {
+    this.disableFpsIndicator();
+    if (this._fpsIndicatorEl) this._fpsIndicatorEl.hidden = true;
+  } else {
+    this.enableFpsIndicator(opts);
+  }
+};
+
+// Aliases for brevity
+p5.prototype.showFps = p5.prototype.enableFpsIndicator;
+p5.prototype.hideFps = function () {
+  this.disableFpsIndicator();
+  if (this._fpsIndicatorEl) this._fpsIndicatorEl.hidden = true;
+};