CryptoSmart Momentum Engine

1. Core Concept
The "CryptoSmart Momentum Engine" is an advanced, regime-filtered momentum dashboard. It is designed to solve the single biggest problem with oscillators: false signals during sideways, "chop" markets.

This indicator is not just a MACD and a Stochastic; it's a complete system that combines three elements in one panel:

Momentum (MACD): Measures the primary momentum and trend direction.

Overbought/Oversold (Stochastic): Measures short-term price exhaustion.

Volatility (Bollinger Band Width): Acts as a "Regime Filter" to determine if the market is in a volatile "Trend Mode" or a quiet "Chop Mode".

The indicator's primary function is to visually disable itself—turning the background gray and hiding all signals—during low-volatility chop, forcing you to trade only when the market has enough volatility to be predictable.

2. Key Features
Hybrid Oscillator: A normalized MACD (line, signal, and histogram) and a full Stochastic oscillator (%K and %D) are plotted in a single 0-100 pane.

Volatility "Regime" Filter: Using a Bollinger Band Width (BBW) filter, the indicator automatically detects the difference between a high-volatility Trend Mode (signal-on) and a low-volatility Chop Mode (signal-off).

Filtered Arrow Signals: The primary buy/sell signals (arrows) are only permitted to appear when the indicator is in "Trend Mode." All signals are automatically hidden during "Chop Mode" to prevent you from trading in sideways markets.

Centralized Histogram: The MACD histogram (the difference between the MACD and Signal lines) is visually centered at the 50-line, allowing it to oscillate in the middle of the 0-100 range.

Comprehensive Visuals: The indicator is a full dashboard with fill-shading for the MACD/Signal shadow, the Stochastic K/D spread, and the OB/OS background zones.

3. How It Works: The "Engine" Logic
The indicator's logic is based on its three main components:

Part 1: The Oscillators (MACD & Stochastic)

Normalized MACD: To make the MACD and Stochastic compatible, the MACD's value is "normalized" (mathematically compressed) to fit on the same 0-100 scale as the Stochastic.

Histogram: The histogram is calculated as MACD - Signal but is visually plotted relative to the 50-line (the new "zero").

Stochastic: This is a standard %K and %D oscillator used to identify short-term overbought/oversold levels.

Part 2: The Volatility Filter (The "Brain") This is the most important feature. The indicator calculates the Bollinger Band Width (BBW) and a moving average of that width (bbw_ma).

if bbw > bbw_ma → "Trend Mode" (Current volatility is expanding and higher than average).

if bbw <= bbw_ma → "Chop Mode" (Current volatility is contracting and lower than average).

Part 3: The Filtered Output (The "Result") The indicator's entire visual display is controlled by the Volatility Filter (use_vol_filter):

When in "Chop Mode" (Low Volatility):

All background color fills (for both MACD and Stochastic OB/OS zones) are disabled and replaced by the single, neutral chop_bg_color (Gray).

All arrow signals (longSignal and shortSignal) are disabled.

Meaning: The indicator is visually telling you: "Do not trade. The market is sideways and signals are unreliable."

When in "Trend Mode" (High Volatility):

The indicator "turns on."

The background colors for MACD and Stochastic OB/OS zones become visible.

The arrow signals are enabled and will appear if their conditions are met.

4. How to Read & Use It (Strategy)
The Gray Background (Chop Mode) is the most important signal. It means "Do nothing. Ignore all oscillator crosses. Wait for volatility to return."

The Colored Background (Trend Mode) means the indicator is "armed." You can now look for its signals.

Signal Definitions:

Buy Signal (Up Arrow ⬆️):

The Volatility Filter must be in "Trend Mode" (background is not gray).

The normalized MACD line (blue) crosses UP over the Oversold Level (20).

Interpretation: This is a "recovering from panic" signal. Momentum is returning to the market after an extreme oversold condition, and the market has enough volatility to trend.

Sell Signal (Down Arrow ⬇️):

The Volatility Filter must be in "Trend Mode".

The normalized MACD line (blue) crosses DOWN below the Overbought Level (80).

Interpretation: This is an "exiting from euphoria" signal. Momentum is failing after an extreme overbought condition, and the market has enough volatility to trend downwards.

Secondary Confirmation:

Histogram: Use the histogram (centered at 50) to gauge the speed of momentum. A growing histogram confirms the strength of your signal. A shrinking (diverging) histogram warns that the move is losing strength.

Stochastic: Use the %K and %D lines for faster, shorter-term confirmation or to identify additional entries/exits within the larger trend defined by the MACD and the Volatility Filter.