@bbebee/plugin-visualizer-meters 0.0.0-stage → 0.1.0

package/BBeBee.plugin.json

@@ -0,0 +1,30 @@
+{
+  "author": "BBeBee Team",
+  "capabilities": [],
+  "contributes": {
+    "slots": [
+      "now-playing.visualizer"
+    ]
+  },
+  "dependencies": [
+    "@BBeBee/plugin-visualizer"
+  ],
+  "description": "Example third-party plugin: spectrogram, spectrum and VU meter views driven by the visualizer service.",
+  "displayName": "Visualizer Meters",
+  "effect": null,
+  "enabled": true,
+  "engines": {
+    "BBeBee": "^0.1.0"
+  },
+  "entry": {
+    "main": "./dist/index.js",
+    "ui": {
+      "desktop": "./dist/ui-desktop.js"
+    }
+  },
+  "id": "bbebee-plugin-visualizer-meters",
+  "moduleId": "dsp",
+  "name": "@bbebee/plugin-visualizer-meters",
+  "systemId": "layer-4",
+  "version": "0.1.0"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BBeBeeX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,210 @@
-# Temporary Holding Version
+# Visualizer Meters — a third-party-style BBeBee plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This repository is the home of **`@bbebee/plugin-visualizer-meters`**, a
+complete, publishable BBeBee plugin package written the way a third-party
+author writes one: **one npm package, one `BBeBee.plugin.json`, a headless
+entry and a desktop UI entry**, no monorepo wiring. It started life as the
+reference example in the BBeBee repository (`examples/visualizer-meters/`)
+and is maintained here as its own release repo — copy it as the starting
+point for your own plugin.
+
+It adds three audio meters to the now-playing screen — a **spectrogram**
+(scrolling waterfall), a **spectrum** (log-spaced frequency bars) and a
+**VU meter** (RMS + peak on a dB scale) — all driven by a service it does
+not own: the `visualizer` service of the first-party
+`@BBeBee/plugin-visualizer` plugin (published to npm as
+`@bbebee/plugin-visualizer`).
+
+## What this plugin demonstrates
+
+- **Depending on another plugin's service.** The plugin injects nothing at
+  install time it cannot name: the registry entry declares
+  `services: ["visualizer"]`, the manifest declares
+  `dependencies: ["@BBeBee/plugin-visualizer"]`, and at runtime both halves
+  treat the service as *optional* (`ctx.inject(['visualizer'], …)` in the
+  headless half; per-frame `serviceOf` reads in the UI) — if the visualizer
+  is disabled, the meters idle on a quiet baseline instead of breaking.
+- **The combined package shape.** `entry.main` + `entry.ui.desktop` in one
+  package; the desktop loader composes them into a single plugin (headless
+  first, UI as a child fiber — a broken UI never takes the headless half
+  down with it).
+- **Host-shared React.** The UI bundle keeps `react`, `react-dom`,
+  `react-dom/client`, `react/jsx-runtime` and `react/jsx-dev-runtime`
+  external so the shell's import map resolves them to the host's single
+  React instance; `package.json` declares the matching
+  `peerDependencies` (`^19.0.0`, warn-only at install time). `build.mjs`
+  fails the build if a React implementation ever slips into the bundle.
+- **Zero capabilities.** `capabilities: []` — the plugin touches no fs,
+  network, or database. Its views draw with canvas 2D and host CSS
+  variables only; there is no ui-kit import.
+
+## Layout
+
+```
+package.json            name/version/files + peerDependencies (the npm face)
+BBeBee.plugin.json      the 15-field plugin manifest (name = npm package name, id = unscoped slug)
+registry-entry.json     the registry (schema v2) entry — see "Publishing"
+build.mjs               esbuild: src/index.ts → dist/index.js,
+                        src/ui.tsx → dist/ui-desktop.js, plus the
+                        host-sharing assertions on the UI bundle
+src/
+  config.ts             modes, palettes, defaults, config schema, resolver
+  meters-math.ts        pure frame math (levels, VU ballistics, log bands,
+                        waterfall ring buffer, palette LUTs)
+  index.ts              headless def: config resolution, settings-card
+                        contribution, optional visualizer watch
+  ui.tsx                UI def: view + settings-card registration into the
+                        `now-playing.visualizer` slot; the canvas meters
+test/
+  meters-math.test.ts   node:test unit tests for the pure modules
+```
+
+## How the visualizer service is consumed
+
+The protocol contract (`VisualizerService`) is pull-based — there is no
+frame event:
+
+- `visualizer.getFrequencyData(buf)` fills a `Uint8Array` of
+  `fftSize / 2` byte bins (0 = silence). The service itself fills zeros
+  when no analyser is attached.
+- `visualizer.getTimeDomainData(buf)` fills a `Uint8Array` of `fftSize`
+  bytes centred on 128 (silence).
+- `visualizer.settings.fftSize` (default 128) is the sizing source for
+  both buffers; the view re-allocates when it changes.
+
+The view runs one `requestAnimationFrame` loop, pulls one frame per tick,
+and stops the loop on unmount. With no service (or no audio) the buffers
+stay at their silence values and every meter draws its baseline.
+
+## The three meters
+
+- **Spectrum** — bins are grouped into 48 **logarithmically** spaced bands
+  (`logBandEdges` in `meters-math.ts`; pitch perception is logarithmic, so
+  linear grouping would waste half the width on bass). Each band shows its
+  peak bin, coloured through the active palette.
+- **Spectrogram** — every frame becomes one column of a ring buffer
+  (`WaterfallBuffer`, 240 columns); new frames enter at the right and
+  history scrolls left. Frequencies run bottom (low) to top (high), values
+  map through a pseudocolor LUT: `ember` is black → purple → orange →
+  yellow, alongside `ice` and `mono`. Rendering goes through an offscreen
+  `ImageData` strip scaled up to the canvas.
+- **VU** — RMS and peak are computed from the time-domain frame and shown
+  on a −60…0 dB scale. Ballistics (`stepVu`, a pure function): the level
+  bar attacks instantly and releases at 0.9 dB/frame; the peak marker jumps
+  to a new peak, holds ≈45 frames, then falls at 0.35 dB/frame and never
+  below the current frame's peak.
+
+Mode and palette can be switched from the segmented control on the view
+itself and from the settings card (Settings → Playback → *Visualizer
+Meters*); both write to one small store inside the UI bundle.
+
+## Configuration
+
+The plugin accepts a config object (from its registry entry / install
+record) of the shape declared in `src/config.ts` (`METERS_CONFIG_SCHEMA`):
+
+```json
+{ "mode": "spectrum" | "spectrogram" | "vu", "palette": "ember" | "ice" | "mono" }
+```
+
+The headless half resolves the loader-passed config against the defaults
+and logs the result. The composed UI def is registered without a config
+argument (that is how the loader's composition works today), so the UI
+seeds its session state from the same defaults and in-view changes are
+session-local. Persisting them across restarts would require a host
+storage capability (`db:own`), which this plugin deliberately does not
+request.
+
+## Build & test
+
+```bash
+npm install   # once — esbuild + type packages from devDependencies
+npm run build # → dist/index.js + dist/ui-desktop.js, with assertions
+npm test      # node --test over the pure modules — no framework needed
+```
+
+`dist/` is a build product (gitignored); `package.json`'s `files` ships
+exactly `BBeBee.plugin.json` + `dist`, which is what `npm publish` would
+upload.
+
+## Trying it locally
+
+1. `npm install && npm run build` here.
+2. Either publish to npm (see below) and install it from the in-app plugin
+   market like any registry plugin, or sideload: copy this package
+   directory (with its built `dist/`) into the desktop app's
+   `installed-plugins/` directory and restart — the loader picks up
+   external packages from there, checks the manifest, and composes
+   `entry.main` + `entry.ui.desktop`.
+3. Play something and open the now-playing screen: the meters view appears
+   in the visualizer slot, after the built-in visualizer canvas. (The
+   visualizer plugin must be enabled for live data; without it the meters
+   draw their idle baseline.)
+
+## Publishing
+
+### 1. Publish the package to npm
+
+```bash
+npm run build
+npm publish
+```
+
+The npm package name and the registry entry's `npm` field are the same
+string — `@bbebee/plugin-visualizer-meters` — while the manifest `id`
+(and the registry entry's `id`) is the unscoped slug
+`bbebee-plugin-visualizer-meters`. The install-time anti-spoofing checks
+compare the pairs separately: the published package's name against the
+entry's `npm`, its manifest `id` against the entry's `id`.
+
+### 2. Register it in B_Be_Bee-registry
+
+`registry-entry.json` in this repo is the schema-v2 entry for the
+community registry. To list the plugin:
+
+1. Copy it into the
+   [B_Be_Bee-registry](https://github.com/BBeBeeX/B_Be_Bee-registry) repo
+   as `plugins/bbebeex-visualizer-meters.json` (entry filenames are
+   `{github-owner}-{name}.json`, a convention separate from the entry
+   `id` inside) and open a PR there.
+2. Registry CI validates the entry: field shape, the `services`
+   whitelist, and — by fetching the npm packument — that the package in
+   the `npm` field exists and that its published manifest id and package
+   name match the entry. **Publish to npm first** (step 1); before the
+   first publish, validation reports, verbatim:
+   `npm package "@bbebee/plugin-visualizer-meters" does not exist on the public npm registry (HTTP 404) — publish it before submitting, or fix the "npm" field`.
+
+Two details of the entry are easy to get wrong:
+
+- **`services: ["visualizer"]`** — passes the registry whitelist because
+  `visualizer` is in the registry's core service-key list
+  (`scripts/lib/service-keys.ts` in B_Be_Bee-registry); service keys that
+  are *not* core keys are covered by the providing entry's `provides`.
+- **The dependency names the visualizer's *registry* id.**
+  `dependencies: ["bbebeex-visualizer@^0.1.0"]` — a lowercase slug, a
+  different namespace from the manifest id (`@BBeBee/plugin-visualizer`)
+  that this package's own `BBeBee.plugin.json` `dependencies` uses. The
+  registry's dependency grammar (and the client's `parseDepSpecifier`)
+  accepts slugs only; writing the manifest-id form here is rejected
+  outright (`invalid dependency … — expected "<id>" or
+  "<id>@<semver-range>"`). The slug form works because a published
+  package's in-package manifest id is stamped to the registry id at
+  packaging time, which is exactly what the install-time anti-spoofing
+  check compares the entry id against. The dependency is also what makes
+  the `services` requirement satisfiable on a fresh install: the
+  installer resolves the closure, counts the visualizer entry's declared
+  `provides` in its plan-stage availability estimate, and re-verifies the
+  downloaded package's manifest `contributes.services` before activating
+  anything.
+
+## Notes for authors copying this plugin
+
+- Keep the two halves' shared code inside this package (`src/config.ts`,
+  `src/meters-math.ts` are bundled into each entry that imports them).
+  Cross-package value imports are not part of the third-party contract.
+- If you need the host's exact shared-module list, the single source of
+  truth is `apps/desktop/renderer/host-modules.manifest.ts` in the BBeBee
+  repo; `build.mjs` mirrors it and says so.
+- Log through `ctx.logger`, register cleanup through the fiber/effect
+  being disposed, and keep entry points `async` — the loader discards
+  disposers returned by plain non-async functions.

package/dist/index.js

@@ -0,0 +1,84 @@
+// src/config.ts
+var METERS_MODES = ["spectrum", "spectrogram", "vu"];
+var METERS_PALETTES = ["ember", "ice", "mono"];
+var DEFAULT_METERS_CONFIG = {
+  mode: "spectrum",
+  palette: "ember"
+};
+var METERS_CONFIG_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    mode: {
+      type: "string",
+      enum: [...METERS_MODES],
+      default: DEFAULT_METERS_CONFIG.mode,
+      description: "Meter shown by default: spectrum bars, spectrogram waterfall, or VU meter."
+    },
+    palette: {
+      type: "string",
+      enum: [...METERS_PALETTES],
+      default: DEFAULT_METERS_CONFIG.palette,
+      description: "Pseudocolor palette used to render levels."
+    }
+  }
+};
+function resolveMetersConfig(input) {
+  if (input === null || typeof input !== "object") {
+    return { ...DEFAULT_METERS_CONFIG };
+  }
+  const raw = input;
+  return {
+    mode: isMode(raw.mode) ? raw.mode : DEFAULT_METERS_CONFIG.mode,
+    palette: isPalette(raw.palette) ? raw.palette : DEFAULT_METERS_CONFIG.palette
+  };
+}
+function isMode(value) {
+  return typeof value === "string" && METERS_MODES.includes(value);
+}
+function isPalette(value) {
+  return typeof value === "string" && METERS_PALETTES.includes(value);
+}
+
+// src/index.ts
+var name = "bbebee-plugin-visualizer-meters";
+var inject = [];
+var configSchema = METERS_CONFIG_SCHEMA;
+async function apply(ctx, config) {
+  const resolved = resolveMetersConfig(config);
+  ctx.logger.info(
+    `visualizer-meters: loaded (default mode=${resolved.mode}, palette=${resolved.palette})`
+  );
+  ctx.inject(["visualizer"], (scoped) => {
+    const fftSize = scoped.visualizer?.settings?.fftSize;
+    scoped.logger.info(
+      `visualizer-meters: visualizer service available${fftSize ? ` (fftSize=${fftSize})` : ""}`
+    );
+  });
+  ctx.inject(
+    ["ui"],
+    (scoped) => scoped.effect(function* () {
+      yield scoped.ui?.contribute({
+        kind: "settings",
+        id: "visualizer-meters.settings",
+        section: "playback",
+        title: "Visualizer Meters",
+        description: "Default mode and palette for the spectrogram / spectrum / VU meter views",
+        display: "card",
+        order: 90
+      });
+    }, "visualizer-meters-settings-contribution")
+  );
+  return () => {
+    ctx.logger.info("visualizer-meters: disposed");
+  };
+}
+var index_default = { name, inject, apply };
+export {
+  DEFAULT_METERS_CONFIG,
+  apply,
+  configSchema,
+  index_default as default,
+  inject,
+  name
+};

package/dist/ui-desktop.js

@@ -0,0 +1,538 @@
+// src/ui.tsx
+import {
+  createElement as h,
+  useEffect,
+  useRef,
+  useSyncExternalStore
+} from "react";
+
+// src/config.ts
+var METERS_MODES = ["spectrum", "spectrogram", "vu"];
+var METERS_PALETTES = ["ember", "ice", "mono"];
+var DEFAULT_METERS_CONFIG = {
+  mode: "spectrum",
+  palette: "ember"
+};
+var METERS_CONFIG_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    mode: {
+      type: "string",
+      enum: [...METERS_MODES],
+      default: DEFAULT_METERS_CONFIG.mode,
+      description: "Meter shown by default: spectrum bars, spectrogram waterfall, or VU meter."
+    },
+    palette: {
+      type: "string",
+      enum: [...METERS_PALETTES],
+      default: DEFAULT_METERS_CONFIG.palette,
+      description: "Pseudocolor palette used to render levels."
+    }
+  }
+};
+
+// src/meters-math.ts
+var DB_FLOOR = -60;
+var clamp = (value, lo, hi) => Math.min(hi, Math.max(lo, value));
+function byteToSample(byte) {
+  return clamp((byte - 128) / 128, -1, 1);
+}
+function computeRms(timeDomain) {
+  if (timeDomain.length === 0) return 0;
+  let sumSquares = 0;
+  for (let i = 0; i < timeDomain.length; i++) {
+    const sample = byteToSample(timeDomain[i]);
+    sumSquares += sample * sample;
+  }
+  return Math.sqrt(sumSquares / timeDomain.length);
+}
+function computePeak(timeDomain) {
+  let peak = 0;
+  for (let i = 0; i < timeDomain.length; i++) {
+    const magnitude = Math.abs(byteToSample(timeDomain[i]));
+    if (magnitude > peak) peak = magnitude;
+  }
+  return peak;
+}
+function levelToDb(level, floorDb = DB_FLOOR) {
+  if (!(level > 0)) return floorDb;
+  return clamp(20 * Math.log10(level), floorDb, 0);
+}
+function dbToFraction(db, floorDb = DB_FLOOR) {
+  return clamp((db - floorDb) / (0 - floorDb), 0, 1);
+}
+var DEFAULT_VU_OPTIONS = {
+  releaseDbPerFrame: 0.9,
+  peakFallDbPerFrame: 0.35,
+  peakHoldFrames: 45
+};
+function createVuState(floorDb = DB_FLOOR) {
+  return { levelDb: floorDb, peakDb: floorDb, peakHoldFramesLeft: 0 };
+}
+function stepVu(state, rmsDb, peakDb, options = DEFAULT_VU_OPTIONS, floorDb = DB_FLOOR) {
+  const nextRms = clamp(rmsDb, floorDb, 0);
+  const nextPeakIn = clamp(peakDb, floorDb, 0);
+  const levelDb = nextRms >= state.levelDb ? nextRms : Math.max(nextRms, state.levelDb - options.releaseDbPerFrame);
+  let nextPeakDb = state.peakDb;
+  let holdLeft = state.peakHoldFramesLeft;
+  if (nextPeakIn >= state.peakDb) {
+    nextPeakDb = nextPeakIn;
+    holdLeft = options.peakHoldFrames;
+  } else if (holdLeft > 0) {
+    holdLeft -= 1;
+  } else {
+    nextPeakDb = Math.max(nextPeakIn, state.peakDb - options.peakFallDbPerFrame);
+  }
+  return { levelDb, peakDb: clamp(nextPeakDb, floorDb, 0), peakHoldFramesLeft: holdLeft };
+}
+function logBandEdges(binCount, bandCount) {
+  const usable = Math.max(0, binCount - 1);
+  const bands = Math.max(1, Math.min(bandCount, Math.max(1, usable)));
+  const edges = [];
+  let start = 1;
+  for (let i = 0; i < bands; i++) {
+    const t = (i + 1) / bands;
+    const end = i === bands - 1 ? binCount : Math.round(Math.exp(Math.log(1) + Math.log(binCount) * t));
+    const clampedEnd = Math.min(binCount, Math.max(start + 1, end));
+    edges.push([start, clampedEnd]);
+    start = clampedEnd;
+  }
+  return edges;
+}
+function aggregateBands(frequencyData, edges) {
+  const out = new Float32Array(edges.length);
+  for (let b = 0; b < edges.length; b++) {
+    const [start, end] = edges[b];
+    let max = 0;
+    const stop = Math.min(end, frequencyData.length);
+    for (let i = start; i < stop; i++) {
+      const value = frequencyData[i];
+      if (value > max) max = value;
+    }
+    out[b] = max / 255;
+  }
+  return out;
+}
+var WaterfallBuffer = class {
+  width;
+  height;
+  columns;
+  head = 0;
+  filled = 0;
+  constructor(width, height) {
+    this.width = Math.max(1, Math.floor(width));
+    this.height = Math.max(1, Math.floor(height));
+    this.columns = Array.from({ length: this.width }, () => new Uint8Array(this.height));
+  }
+  /** Number of frames currently stored (≤ width). */
+  get size() {
+    return this.filled;
+  }
+  /** Stores one frame (a column of `height` byte values; extra values are dropped). */
+  push(frame) {
+    const column = this.columns[this.head];
+    const n = Math.min(this.height, frame.length);
+    for (let i = 0; i < n; i++) column[i] = frame[i];
+    for (let i = n; i < this.height; i++) column[i] = 0;
+    this.head = (this.head + 1) % this.width;
+    if (this.filled < this.width) this.filled += 1;
+  }
+  /** Returns the frame `age` pushes ago (0 = newest), or undefined if not stored yet. */
+  columnAtAge(age) {
+    if (age < 0 || age >= this.filled) return void 0;
+    const index = (this.head - 1 - age + this.width * 2) % this.width;
+    return this.columns[index];
+  }
+  clear() {
+    this.head = 0;
+    this.filled = 0;
+    for (const column of this.columns) column.fill(0);
+  }
+};
+var PALETTE_STOPS = {
+  ember: [
+    [0, 0, 0],
+    [64, 0, 128],
+    [255, 96, 0],
+    [255, 224, 64]
+  ],
+  ice: [
+    [0, 0, 0],
+    [0, 32, 96],
+    [0, 160, 200],
+    [235, 250, 255]
+  ],
+  mono: [
+    [0, 0, 0],
+    [96, 96, 96],
+    [192, 192, 192],
+    [255, 255, 255]
+  ]
+};
+function buildPaletteLut(stops) {
+  const lut = new Uint8Array(256 * 3);
+  if (stops.length === 0) return lut;
+  if (stops.length === 1) {
+    const [r, g, b] = stops[0];
+    for (let i = 0; i < 256; i++) {
+      lut[i * 3] = r;
+      lut[i * 3 + 1] = g;
+      lut[i * 3 + 2] = b;
+    }
+    return lut;
+  }
+  const segments = stops.length - 1;
+  for (let i = 0; i < 256; i++) {
+    const t = i / 255 * segments;
+    const segment = Math.min(segments - 1, Math.floor(t));
+    const local = t - segment;
+    const a = stops[segment];
+    const b = stops[segment + 1];
+    lut[i * 3] = Math.round(a[0] + (b[0] - a[0]) * local);
+    lut[i * 3 + 1] = Math.round(a[1] + (b[1] - a[1]) * local);
+    lut[i * 3 + 2] = Math.round(a[2] + (b[2] - a[2]) * local);
+  }
+  return lut;
+}
+function lutColor(lut, byteValue) {
+  const index = clamp(Math.round(byteValue), 0, 255) * 3;
+  return [lut[index], lut[index + 1], lut[index + 2]];
+}
+
+// src/ui.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function serviceOf(ctx, key) {
+  try {
+    const fromReflect = ctx.reflect?.get(key, false);
+    if (fromReflect !== void 0 && fromReflect !== null) return fromReflect;
+  } catch {
+  }
+  const value = ctx[key];
+  return value === void 0 || value === null ? void 0 : value;
+}
+var uiSnapshot = { ...DEFAULT_METERS_CONFIG };
+var uiListeners = /* @__PURE__ */ new Set();
+function setUiState(patch) {
+  uiSnapshot = { ...uiSnapshot, ...patch };
+  for (const listener of uiListeners) listener();
+}
+function subscribeUi(listener) {
+  uiListeners.add(listener);
+  return () => {
+    uiListeners.delete(listener);
+  };
+}
+function useMetersUiState() {
+  return useSyncExternalStore(subscribeUi, () => uiSnapshot, () => uiSnapshot);
+}
+var MODE_LABELS = {
+  spectrum: "Spectrum",
+  spectrogram: "Spectrogram",
+  vu: "VU"
+};
+function ModeSwitch({ value, onChange }) {
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      role: "tablist",
+      "aria-label": "Meter mode",
+      style: { display: "inline-flex", gap: 2, padding: 2, borderRadius: 6, border: "1px solid var(--border-subtle, rgba(127, 127, 127, 0.35))" },
+      children: METERS_MODES.map((mode) => /* @__PURE__ */ jsx(
+        "button",
+        {
+          role: "tab",
+          "aria-selected": mode === value,
+          onClick: () => onChange(mode),
+          style: {
+            border: "none",
+            borderRadius: 4,
+            padding: "2px 8px",
+            fontSize: 12,
+            cursor: "pointer",
+            color: "var(--color-text-primary, inherit)",
+            background: mode === value ? "var(--color-primary, #5f87ff)" : "transparent"
+          },
+          children: MODE_LABELS[mode]
+        },
+        mode
+      ))
+    }
+  );
+}
+function PaletteSwitch({
+  value,
+  onChange
+}) {
+  return /* @__PURE__ */ jsxs("label", { style: { display: "inline-flex", alignItems: "center", gap: 6, fontSize: 12 }, children: [
+    "Palette",
+    /* @__PURE__ */ jsx(
+      "select",
+      {
+        value,
+        onChange: (event) => onChange(event.target.value),
+        style: {
+          fontSize: 12,
+          color: "var(--color-text-primary, inherit)",
+          background: "transparent",
+          border: "1px solid var(--border-subtle, rgba(127, 127, 127, 0.35))",
+          borderRadius: 4,
+          padding: "2px 4px"
+        },
+        children: METERS_PALETTES.map((palette) => /* @__PURE__ */ jsx("option", { value: palette, children: palette }, palette))
+      }
+    )
+  ] });
+}
+var SPECTRUM_BANDS = 48;
+var WATERFALL_COLUMNS = 240;
+var DB_TICKS = [-40, -30, -20, -12, -9, -6, -3, 0];
+function MetersView({ ctx, height = 132 }) {
+  const canvasRef = useRef(null);
+  const uiState = useMetersUiState();
+  const uiStateRef = useRef(uiState);
+  uiStateRef.current = uiState;
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const g = canvas.getContext("2d");
+    if (!g) return;
+    const dpr = typeof window !== "undefined" ? window.devicePixelRatio || 1 : 1;
+    let cssWidth = 320;
+    let cssHeight = height;
+    const resize = () => {
+      const rect = canvas.getBoundingClientRect();
+      cssWidth = rect.width || 320;
+      cssHeight = rect.height || height;
+      canvas.width = Math.max(1, Math.floor(cssWidth * dpr));
+      canvas.height = Math.max(1, Math.floor(cssHeight * dpr));
+    };
+    resize();
+    const observer = typeof ResizeObserver !== "undefined" ? new ResizeObserver(() => resize()) : null;
+    observer?.observe(canvas);
+    let fftSize = 0;
+    let freq = new Uint8Array(0);
+    let time = new Uint8Array(0);
+    let waterfall = null;
+    let waterfallBins = 0;
+    let vu = createVuState();
+    const lutCache = /* @__PURE__ */ new Map();
+    const lutFor = (palette) => {
+      let lut = lutCache.get(palette);
+      if (!lut) {
+        lut = buildPaletteLut(PALETTE_STOPS[palette] ?? PALETTE_STOPS.ember);
+        lutCache.set(palette, lut);
+      }
+      return lut;
+    };
+    const strip = document.createElement("canvas");
+    const stripCtx = strip.getContext("2d");
+    const drawBaseline = (w, hgt) => {
+      g.strokeStyle = "rgba(127, 127, 127, 0.45)";
+      g.lineWidth = 1;
+      g.beginPath();
+      g.moveTo(0, hgt - 0.5);
+      g.lineTo(w, hgt - 0.5);
+      g.stroke();
+    };
+    const drawSpectrum = (w, hgt, lut) => {
+      const edges = logBandEdges(freq.length, SPECTRUM_BANDS);
+      const bands = aggregateBands(freq, edges);
+      const gap = 2;
+      const barWidth = Math.max(1, (w - (bands.length - 1) * gap) / bands.length);
+      for (let i = 0; i < bands.length; i++) {
+        const value = bands[i];
+        const barHeight = Math.max(value > 0 ? 2 : 0, value * (hgt - 4));
+        if (barHeight <= 0) continue;
+        const [r, gg, b] = lutColor(lut, value * 255);
+        g.fillStyle = `rgb(${r}, ${gg}, ${b})`;
+        g.fillRect(i * (barWidth + gap), hgt - barHeight, barWidth, barHeight);
+      }
+      drawBaseline(w, hgt);
+    };
+    const drawSpectrogram = (w, hgt, lut) => {
+      if (!waterfall || !stripCtx) {
+        drawBaseline(w, hgt);
+        return;
+      }
+      const bins = waterfallBins;
+      if (strip.width !== WATERFALL_COLUMNS || strip.height !== bins) {
+        strip.width = WATERFALL_COLUMNS;
+        strip.height = Math.max(1, bins);
+      }
+      const image = stripCtx.createImageData(strip.width, strip.height);
+      for (let x = 0; x < strip.width; x++) {
+        const column = waterfall.columnAtAge(strip.width - 1 - x);
+        for (let bin = 0; bin < bins; bin++) {
+          const row = bins - 1 - bin;
+          const offset = (row * strip.width + x) * 4;
+          const value = column ? column[bin] ?? 0 : 0;
+          const [r, gg, b] = lutColor(lut, value);
+          image.data[offset] = r;
+          image.data[offset + 1] = gg;
+          image.data[offset + 2] = b;
+          image.data[offset + 3] = 255;
+        }
+      }
+      stripCtx.putImageData(image, 0, 0);
+      g.imageSmoothingEnabled = true;
+      g.clearRect(0, 0, w, hgt);
+      g.drawImage(strip, 0, 0, w, hgt);
+    };
+    const drawVu = (w, hgt, lut) => {
+      const midY = Math.floor(hgt / 2);
+      const trackY = midY - 7;
+      const trackHeight = 14;
+      g.fillStyle = "rgba(127, 127, 127, 0.25)";
+      g.fillRect(0, trackY, w, trackHeight);
+      g.fillStyle = "rgba(127, 127, 127, 0.8)";
+      g.font = "10px sans-serif";
+      for (const db of DB_TICKS) {
+        const x = dbToFraction(db) * w;
+        g.fillRect(x, trackY + trackHeight + 2, 1, 4);
+        g.fillText(`${db}`, x + 2, trackY + trackHeight + 14);
+      }
+      const levelFraction = dbToFraction(vu.levelDb);
+      if (levelFraction > 0) {
+        const [r, gg, b] = lutColor(lut, levelFraction * 255);
+        g.fillStyle = `rgb(${r}, ${gg}, ${b})`;
+        g.fillRect(0, trackY, levelFraction * w, trackHeight);
+      }
+      const peakX = dbToFraction(vu.peakDb) * w;
+      g.fillStyle = "rgba(255, 80, 80, 0.95)";
+      g.fillRect(Math.max(0, peakX - 1), trackY - 3, 2, trackHeight + 6);
+      g.fillStyle = "rgba(127, 127, 127, 0.9)";
+      const label = (db) => db <= DB_FLOOR ? "-\u221E dB" : `${db.toFixed(1)} dB`;
+      g.fillText(`RMS ${label(vu.levelDb)}   peak ${label(vu.peakDb)}`, 0, 12);
+      if (vu.levelDb <= DB_FLOOR && vu.peakDb <= DB_FLOOR) drawBaseline(w, hgt);
+    };
+    let animId = 0;
+    const render = () => {
+      animId = requestAnimationFrame(render);
+      const { mode, palette } = uiStateRef.current;
+      const lut = lutFor(palette);
+      const visualizer = serviceOf(ctx, "visualizer");
+      const targetFft = clampFftSize(visualizer?.settings?.fftSize ?? 128);
+      if (targetFft !== fftSize) {
+        fftSize = targetFft;
+        freq = new Uint8Array(fftSize / 2);
+        time = new Uint8Array(fftSize);
+        waterfall = null;
+        waterfallBins = 0;
+      }
+      if (visualizer) {
+        visualizer.getFrequencyData(freq);
+        visualizer.getTimeDomainData(time);
+      } else {
+        freq.fill(0);
+        time.fill(128);
+      }
+      g.setTransform(dpr, 0, 0, dpr, 0, 0);
+      g.clearRect(0, 0, cssWidth, cssHeight);
+      if (mode === "spectrum") {
+        drawSpectrum(cssWidth, cssHeight, lut);
+      } else if (mode === "spectrogram") {
+        if (!waterfall || waterfallBins !== freq.length) {
+          waterfall = new WaterfallBuffer(WATERFALL_COLUMNS, freq.length);
+          waterfallBins = freq.length;
+        }
+        waterfall.push(freq);
+        drawSpectrogram(cssWidth, cssHeight, lut);
+      } else {
+        vu = stepVu(vu, levelToDb(computeRms(time)), levelToDb(computePeak(time)));
+        drawVu(cssWidth, cssHeight, lut);
+      }
+    };
+    animId = requestAnimationFrame(render);
+    return () => {
+      if (animId) cancelAnimationFrame(animId);
+      observer?.disconnect();
+    };
+  }, [ctx, height]);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      style: {
+        display: "flex",
+        flexDirection: "column",
+        gap: 6,
+        width: "100%",
+        maxWidth: 560,
+        color: "var(--color-text-primary, inherit)"
+      },
+      children: [
+        /* @__PURE__ */ jsxs("div", { style: { display: "flex", alignItems: "center", gap: 12, flexWrap: "wrap" }, children: [
+          /* @__PURE__ */ jsx(ModeSwitch, { value: uiState.mode, onChange: (mode) => setUiState({ mode }) }),
+          /* @__PURE__ */ jsx(PaletteSwitch, { value: uiState.palette, onChange: (palette) => setUiState({ palette }) })
+        ] }),
+        /* @__PURE__ */ jsx(
+          "canvas",
+          {
+            ref: canvasRef,
+            style: {
+              width: "100%",
+              height,
+              display: "block",
+              borderRadius: 6,
+              border: "1px solid var(--border-subtle, rgba(127, 127, 127, 0.35))",
+              background: "var(--color-bg-app, transparent)"
+            }
+          }
+        )
+      ]
+    }
+  );
+}
+function clampFftSize(value) {
+  if (!Number.isFinite(value) || value <= 0) return 128;
+  const power = Math.round(Math.log2(value));
+  return Math.min(2048, Math.max(32, 2 ** power));
+}
+function MetersSettingsCard({ ctx }) {
+  const uiState = useMetersUiState();
+  const visualizer = serviceOf(ctx, "visualizer");
+  return /* @__PURE__ */ jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 10, maxWidth: 560 }, children: [
+    /* @__PURE__ */ jsxs("div", { style: { display: "flex", alignItems: "center", gap: 12, flexWrap: "wrap" }, children: [
+      /* @__PURE__ */ jsx(ModeSwitch, { value: uiState.mode, onChange: (mode) => setUiState({ mode }) }),
+      /* @__PURE__ */ jsx(PaletteSwitch, { value: uiState.palette, onChange: (palette) => setUiState({ palette }) })
+    ] }),
+    /* @__PURE__ */ jsxs("p", { style: { margin: 0, fontSize: 12, opacity: 0.75 }, children: [
+      "These defaults seed the Visualizer Meters view in the now-playing screen. The",
+      " ",
+      /* @__PURE__ */ jsx("code", { children: "visualizer" }),
+      " service is",
+      " ",
+      visualizer ? "available" : "not available \u2014 the meters will show a quiet baseline",
+      ". Changes are session-local in this example (see the package README)."
+    ] })
+  ] });
+}
+var name = "bbebee-plugin-visualizer-meters-ui";
+var inject = ["ui"];
+function bound(ctx, Screen) {
+  return function Bound(props) {
+    return h(Screen, { ...props, ctx });
+  };
+}
+async function apply(ctx) {
+  ctx.logger.info("visualizer-meters ui: loaded");
+  return ctx.effect(function* () {
+    yield ctx.ui.registerView("visualizer-meters.canvas", bound(ctx, MetersView));
+    yield ctx.ui.registerView("visualizer-meters.settings", bound(ctx, MetersSettingsCard));
+    yield ctx.ui.contribute({
+      kind: "slot",
+      id: "visualizer-meters.canvas",
+      slot: "now-playing.visualizer",
+      order: 20
+    });
+  }, "visualizer-meters-ui");
+}
+var ui_default = { name, inject, apply };
+export {
+  MetersSettingsCard,
+  MetersView,
+  apply,
+  ui_default as default,
+  inject,
+  name
+};

package/package.json

@@ -1,6 +1,28 @@
 {
+  "author": "BBeBee Team",
+  "description": "BBeBee example plugin (third-party style): spectrogram, spectrum and VU meters powered by the visualizer service.",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "esbuild": "^0.28.0",
+    "typescript": "^5.9.0"
+  },
+  "files": [
+    "BBeBee.plugin.json",
+    "dist"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
   "name": "@bbebee/plugin-visualizer-meters",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node --test test/meters-math.test.ts"
+  },
+  "type": "module",
+  "version": "0.1.0"
+}