feat(core): B4 price oscillators (TsfOscillator, MacdHistogram, PpoHistogram) (#184)

Adds three **Price Oscillators** family indicators (420 → 423).

## Indicators

- **TsfOscillator** — `100·(close − TSF)/close`, the percentage gap of the close to the **one-bar-ahead** time-series forecast. Close-relative companion to `Cfo`, which measures the same gap against the regression value at the *current* bar; the two differ by exactly the slope term `100·b/close`.
- **MacdHistogram** — the standalone `macd − signal` bar of MACD exposed as a plain `f64` series.
- **PpoHistogram** — the Percentage Price Oscillator with its 9-period signal EMA and the resulting scale-free, zero-centered histogram (PPO itself only emits the line).

All three are scalar `f64` indicators wrapping existing, already-tested building blocks (`MacdIndicator`, `Ppo` + `Ema`, `Tsf`).

## Scope notes (VORAB-CHECK)

The B4 roadmap listed six items; three were dropped to avoid duplicates:
- *Forecast Oscillator* already ships as `Cfo`.
- *Derivative Oscillator* already ships (`DerivativeOscillator`, B2).
- *Detrended Synthetic Price* deferred — no citable formula distinct from the existing `Apo`/`Dpo`.

## Touchpoints

Core (`tsf_oscillator.rs`, `macd_histogram.rs`, `ppo_histogram.rs`) with full per-branch unit tests, `mod.rs`/`lib.rs`, python/node/wasm bindings (wasm via typed-arg macro, python/node hand-written for the multi-arg histograms), fuzz drivers, python reference + streaming-vs-batch tests, node factories, README family row + counter, CHANGELOG.

Local verify: `cargo test --workspace` green, `clippy -D warnings` clean, node 498 tests, full python suite green.

bindings/node/__tests__/indicators.test.js

@@ -28,6 +28,9 @@ function num(v) {
 // --- Scalar indicators: update(value) vs batch(prices) ---
 
 const scalarFactories = {
+  PpoHistogram: () => new wickra.PpoHistogram(3, 6, 3),
+  MacdHistogram: () => new wickra.MacdHistogram(3, 6, 3),
+  TsfOscillator: () => new wickra.TsfOscillator(3),
   WAVE_PM: () => new wickra.WAVE_PM(32, 3),
   POLARIZED_FRACTAL_EFFICIENCY: () => new wickra.POLARIZED_FRACTAL_EFFICIENCY(10, 5),
   TREND_STRENGTH_INDEX: () => new wickra.TREND_STRENGTH_INDEX(20),

bindings/node/index.d.ts

@@ -978,6 +978,15 @@ export declare class TREND_STRENGTH_INDEX {
   isReady(): boolean
   warmupPeriod(): number
 }
+export type TsfOscillatorNode = TsfOscillator
+export declare class TsfOscillator {
+  constructor(period: number)
+  update(value: number): number | null
+  batch(prices: Array<number>): Array<number>
+  reset(): void
+  isReady(): boolean
+  warmupPeriod(): number
+}
 export type JumpIndicatorNode = JumpIndicator
 export declare class JumpIndicator {
   constructor(period: number, threshold: number)
@@ -1909,6 +1918,24 @@ export declare class DerivativeOscillator {
   isReady(): boolean
   warmupPeriod(): number
 }
+export type MacdHistogramNode = MacdHistogram
+export declare class MacdHistogram {
+  constructor(fast: number, slow: number, signal: number)
+  update(value: number): number | null
+  batch(prices: Array<number>): Array<number>
+  reset(): void
+  isReady(): boolean
+  warmupPeriod(): number
+}
+export type PpoHistogramNode = PpoHistogram
+export declare class PpoHistogram {
+  constructor(fast: number, slow: number, signal: number)
+  update(value: number): number | null
+  batch(prices: Array<number>): Array<number>
+  reset(): void
+  isReady(): boolean
+  warmupPeriod(): number
+}
 export type TsiNode = TSI
 export declare class TSI {
   constructor(long: number, short: number)

bindings/node/src/lib.rs

@@ -219,6 +219,7 @@ node_scalar_indicator!(
     "TREND_STRENGTH_INDEX",
     wc::TrendStrengthIndex
 );
+node_scalar_indicator!(TsfOscillatorNode, "TsfOscillator", wc::TsfOscillator);
 #[napi(js_name = "JumpIndicator")]
 pub struct JumpIndicatorNode {
     inner: wc::JumpIndicator,
@@ -4533,6 +4534,82 @@ impl DerivativeOscillatorNode {
     }
 }
 
+// ============================== MacdHistogram ==============================
+
+#[napi(js_name = "MacdHistogram")]
+pub struct MacdHistogramNode {
+    inner: wc::MacdHistogram,
+}
+
+#[napi]
+impl MacdHistogramNode {
+    #[napi(constructor)]
+    pub fn new(fast: u32, slow: u32, signal: u32) -> napi::Result<Self> {
+        Ok(Self {
+            inner: wc::MacdHistogram::new(fast as usize, slow as usize, signal as usize)
+                .map_err(map_err)?,
+        })
+    }
+    #[napi]
+    pub fn update(&mut self, value: f64) -> Option<f64> {
+        self.inner.update(value)
+    }
+    #[napi]
+    pub fn batch(&mut self, prices: Vec<f64>) -> Vec<f64> {
+        flatten(self.inner.batch(&prices))
+    }
+    #[napi]
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[napi(js_name = "isReady")]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[napi(js_name = "warmupPeriod")]
+    pub fn warmup_period(&self) -> u32 {
+        self.inner.warmup_period() as u32
+    }
+}
+
+// ============================== PpoHistogram ==============================
+
+#[napi(js_name = "PpoHistogram")]
+pub struct PpoHistogramNode {
+    inner: wc::PpoHistogram,
+}
+
+#[napi]
+impl PpoHistogramNode {
+    #[napi(constructor)]
+    pub fn new(fast: u32, slow: u32, signal: u32) -> napi::Result<Self> {
+        Ok(Self {
+            inner: wc::PpoHistogram::new(fast as usize, slow as usize, signal as usize)
+                .map_err(map_err)?,
+        })
+    }
+    #[napi]
+    pub fn update(&mut self, value: f64) -> Option<f64> {
+        self.inner.update(value)
+    }
+    #[napi]
+    pub fn batch(&mut self, prices: Vec<f64>) -> Vec<f64> {
+        flatten(self.inner.batch(&prices))
+    }
+    #[napi]
+    pub fn reset(&mut self) {
+        self.inner.reset();
+    }
+    #[napi(js_name = "isReady")]
+    pub fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    #[napi(js_name = "warmupPeriod")]
+    pub fn warmup_period(&self) -> u32 {
+        self.inner.warmup_period() as u32
+    }
+}
+
 // ============================== TSI ==============================
 
 #[napi(js_name = "TSI")]

bindings/python/python/wickra/__init__.py

@@ -25,6 +25,9 @@ from __future__ import annotations
 
 from ._wickra import (
     __version__,
+    PpoHistogram,
+    MacdHistogram,
+    TsfOscillator,
     Qstick,
     GatorOscillator,
     KasePermissionStochastic,
@@ -473,6 +476,9 @@ from ._wickra import (
 )
 
 __all__ = [
+    "PpoHistogram",
+    "MacdHistogram",
+    "TsfOscillator",
     "Qstick",
     "GatorOscillator",
     "KasePermissionStochastic",

bindings/python/src/lib.rs

@@ -3295,6 +3295,144 @@ impl PyKasePermissionStochastic {
     }
 }
 
+// ============================== TsfOscillator ==============================
+
+#[pyclass(name = "TsfOscillator", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyTsfOscillator {
+    inner: wc::TsfOscillator,
+}
+
+#[pymethods]
+impl PyTsfOscillator {
+    #[new]
+    #[pyo3(signature = (period=14))]
+    fn new(period: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::TsfOscillator::new(period).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, value: f64) -> Option<f64> {
+        self.inner.update(value)
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        prices: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        let s = prices
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        Ok(flatten(self.inner.batch(s)).into_pyarray(py))
+    }
+    #[getter]
+    fn period(&self) -> usize {
+        self.inner.period()
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        format!("TsfOscillator(period={})", self.inner.period())
+    }
+}
+
+// ============================== MacdHistogram ==============================
+
+#[pyclass(name = "MacdHistogram", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyMacdHistogram {
+    inner: wc::MacdHistogram,
+}
+
+#[pymethods]
+impl PyMacdHistogram {
+    #[new]
+    #[pyo3(signature = (fast=12, slow=26, signal=9))]
+    fn new(fast: usize, slow: usize, signal: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::MacdHistogram::new(fast, slow, signal).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, value: f64) -> Option<f64> {
+        self.inner.update(value)
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        prices: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        let s = prices
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        Ok(flatten(self.inner.batch(s)).into_pyarray(py))
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        let (fast, slow, signal) = self.inner.periods();
+        format!("MacdHistogram(fast={fast}, slow={slow}, signal={signal})")
+    }
+}
+
+// ============================== PpoHistogram ==============================
+
+#[pyclass(name = "PpoHistogram", module = "wickra._wickra", skip_from_py_object)]
+#[derive(Clone)]
+struct PyPpoHistogram {
+    inner: wc::PpoHistogram,
+}
+
+#[pymethods]
+impl PyPpoHistogram {
+    #[new]
+    #[pyo3(signature = (fast=12, slow=26, signal=9))]
+    fn new(fast: usize, slow: usize, signal: usize) -> PyResult<Self> {
+        Ok(Self {
+            inner: wc::PpoHistogram::new(fast, slow, signal).map_err(map_err)?,
+        })
+    }
+    fn update(&mut self, value: f64) -> Option<f64> {
+        self.inner.update(value)
+    }
+    fn batch<'py>(
+        &mut self,
+        py: Python<'py>,
+        prices: PyReadonlyArray1<'py, f64>,
+    ) -> PyResult<Bound<'py, PyArray1<f64>>> {
+        let s = prices
+            .as_slice()
+            .map_err(|_| PyValueError::new_err(NON_CONTIGUOUS))?;
+        Ok(flatten(self.inner.batch(s)).into_pyarray(py))
+    }
+    fn reset(&mut self) {
+        self.inner.reset();
+    }
+    fn is_ready(&self) -> bool {
+        self.inner.is_ready()
+    }
+    fn warmup_period(&self) -> usize {
+        self.inner.warmup_period()
+    }
+    fn __repr__(&self) -> String {
+        let (fast, slow, signal) = self.inner.periods();
+        format!("PpoHistogram(fast={fast}, slow={slow}, signal={signal})")
+    }
+}
+
 // ============================== Stochastic ==============================
 
 #[pyclass(name = "IMI", module = "wickra._wickra", skip_from_py_object)]
@@ -21422,5 +21560,8 @@ fn _wickra(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyWavePm>()?;
     m.add_class::<PyGatorOscillator>()?;
     m.add_class::<PyKasePermissionStochastic>()?;
+    m.add_class::<PyTsfOscillator>()?;
+    m.add_class::<PyMacdHistogram>()?;
+    m.add_class::<PyPpoHistogram>()?;
     Ok(())
 }

bindings/python/tests/test_new_indicators.py

@@ -45,6 +45,9 @@ def ohlcv() -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
 # --- Scalar (f64 -> f64) indicators ---------------------------------------
 
 SCALAR = [
+    (ta.PpoHistogram, (3, 6, 3)),
+    (ta.MacdHistogram, (3, 6, 3)),
+    (ta.TsfOscillator, (3,)),
     (ta.WAVE_PM, (32, 3)),
     (ta.POLARIZED_FRACTAL_EFFICIENCY, (10, 5)),
     (ta.TREND_STRENGTH_INDEX, (20,)),
@@ -2862,6 +2865,31 @@ def test_kase_permission_stochastic_reference():
     assert out[-1][0] == pytest.approx(50.0)
     assert out[-1][1] == pytest.approx(50.0)
 
+
+def test_tsf_oscillator_reference():
+    t = ta.TsfOscillator(3)
+    assert t.update(1.0) is None
+    assert t.update(2.0) is None
+    assert t.update(9.0) == pytest.approx(-33.33333333333333)
+
+
+def test_macd_histogram_reference():
+    # On a constant-slope ramp the MACD line is flat once seeded, so the
+    # signal EMA catches up and the histogram collapses to 0.
+    t = ta.MacdHistogram(3, 6, 3)
+    for i in range(7):
+        assert t.update(100.0 + i * 2.0) is None
+    assert t.update(100.0 + 7 * 2.0) == pytest.approx(0.0, abs=1e-9)
+
+
+def test_ppo_histogram_reference():
+    # PPO divides the EMA gap by the slow EMA, so on the same ramp the ratio
+    # keeps drifting and the histogram stays non-zero.
+    t = ta.PpoHistogram(3, 6, 3)
+    for i in range(7):
+        assert t.update(100.0 + i * 2.0) is None
+    assert t.update(100.0 + 7 * 2.0) == pytest.approx(-0.052098, abs=1e-6)
+
 # --- Lifecycle ------------------------------------------------------------
 
 

bindings/wasm/src/lib.rs

@@ -10653,6 +10653,9 @@ wasm_scalar_indicator!(WasmDynamicMomentumIndex, "DynamicMomentumIndex", wc::Dyn
 wasm_scalar_indicator!(WasmRmi, "RMI", wc::Rmi, period: usize, momentum: usize);
 wasm_scalar_indicator!(WasmDerivativeOscillator, "DerivativeOscillator", wc::DerivativeOscillator, rsi_period: usize, smooth1: usize, smooth2: usize, signal_period: usize);
 wasm_scalar_indicator!(WasmTrendStrengthIndex, "TREND_STRENGTH_INDEX", wc::TrendStrengthIndex, period: usize);
+wasm_scalar_indicator!(WasmTsfOscillator, "TsfOscillator", wc::TsfOscillator, period: usize);
+wasm_scalar_indicator!(WasmMacdHistogram, "MacdHistogram", wc::MacdHistogram, fast: usize, slow: usize, signal: usize);
+wasm_scalar_indicator!(WasmPpoHistogram, "PpoHistogram", wc::PpoHistogram, fast: usize, slow: usize, signal: usize);
 
 // --- DrawdownDuration: u32 output, no constructor args ---