Visuals and Logic

This page is for the reader who wants a working mental model of what is on the pane and what makes each piece move. It is longer than the Quick Start because the pane has five kinds of objects on it and because the most common misreads are mental, not mechanical. If you spend ten minutes here, you stop seeing a busy oscillator and start reading a specific instrument — and you stop trusting a handful of reasonable-sounding habits that do not actually hold on this pane.

A few throughlines run under the whole page and are worth pinning down before the reading order, the layers, or the features. These three facts carry the rest of the explanation.

• Everything lives inside the 0..100 range. Hard clamps at every pipeline stage — slot K, slot D, blend K, blend D, master-smoothed blend — guarantee no drawn series ever exits the range. Every line inside the pane, every guide across it, every column pressed up from zero, every triangle at the floor or ceiling: all of them live inside that bounded space. When price moves, this pane does not move with it; it reports a bounded function of price that lives in its own coordinate system.

• The blend K and blend D lines are the hero. Every other visual either scaffolds the blend (the 0/20/50/80/100 guides) or describes it (the four structure features). The pane has one primary subject. The other objects are adjectives on that subject.

• The four structure features are one series seen through four lenses. Divergence, Keltner envelope, BBWP columns, and Donchian steplines all read the same blended K after master smoothing and the final clamp. They are not four independent witnesses. This fact is load-bearing and it shapes how the whole page is written — the features section names the shared-input truth before the features themselves are introduced, because the most confident-feeling misread on this pane is "four things are agreeing." They are not; they are one thing, measured four ways.

The pane as a stack of layers

Think of the pane as five layers stacked on top of each other. You are not meant to read all five with equal attention at the same time. The order matters.

1. Scaffolding. The 0, 20, 50, 80, and 100 horizontal guides. These never move unless you move them.

2. Hero. The blend K line, blend D line, and the coloured fill between them.

3. Structure overlays around the blend. The Donchian steplines and the Keltner envelope, both on blended K. Donchian is on by default; Keltner is off.

4. Structure readouts about the blend. BBWP columns at the bottom, reporting the blend's own Bollinger width percentile.

5. Discrete markers. Divergence triangles at the floor and ceiling.

Under the hood there is also a sixth layer — the per-slot K plots — but they are hidden by default on slots 01, 02, and 03, disabled by default on slots 04 and 05, and only drawn at all when a reader deliberately unhides one for diagnostic use.

Reading order

The scaffolding is context. Glance at it once and move on. The hero layer is where the read starts. The structure layers answer specific questions about the hero. Divergence markers describe events that already happened to the hero. Slot plots are for the moment you want to ask "which slot is driving this?" — and nothing more.

A sane reading order on a live chart:

1. Note the colour of the blend fill. That tells you the K/D regime.

2. Note where in the 0..100 range the blend K sits.

3. Note whether the blend is pressing a Donchian edge or sitting in the middle of its channel.

4. Note whether BBWP is short, tall, rising, or falling. That tells you about the blend's volatility regime.

5. If a divergence triangle is present in the recent bars, note its direction and note how far back the actual pivot sits (the pivot is Pivot Len bars to the left of the confirmation bar unless you enabled Plot On Pivot, in which case the drawing is over the pivot but the alert still fired at the confirmation bar).

6. If Keltner is on, note whether the blend K is inside the envelope, pushing a band, or outside entirely.

7. Only if the first six are ambiguous and you need more, unhide a slot plot to see which slot is pulling the blend.

Reading in this order keeps you from getting recruited by the most eye-catching visual at the expense of the most informative one.

The hero: blend K and blend D

The blend K is a weighted mean of active slots' K lines. The blend D is the corresponding weighted mean of the slots' D lines. Both are clamped to 0..100 at the exit of the blend compute.

The fill between K and D is where the fastest read lives. When K is above D the fill is lime and the blend line glows lime. When D is above K the fill is red and the blend line glows red. Cross events produce the colour flip. A line width of 3 at the default makes the blend readable at a glance even when the pane is cluttered with structure features.

What the hero pair does not tell you:

• The K/D cross is not a trade signal. It is a regime marker on a weighted-mean construction. On a single-symbol single-timeframe stochastic a K/D cross inside the extremes has a particular folklore attached to it. On a five-slot weighted blend across different timeframes and possibly different symbols, that folklore does not transfer clean. The cross means the blend's leading side flipped. The next move is not implied.

• Position inside the 0..100 range matters, but the 80/20 guides are reference zones, not reversal lines. A blend K pinned above 80 in a real trend can stay pinned for a long time. The guide is an invitation to ask whether the extremity is sustained or fleeting; it is not an answer.

• The blend K minus the blend D says nothing about absolute speed. A steep K/D gap can come from one slot moving fast. A small K/D gap can come from slots disagreeing internally. The colour flip tells you regime; the magnitude of the gap is noisy.

Where the blend's movement actually comes from

Every slot has its own compute chain. At the slot level, changing any of these inputs changes that slot's K line and therefore the blend:

• Source (with the caveat below about the stochastic range).

• K Length.

• K Type and K Smoothing.

• D Type and D Length.

• Timeframe.

• Optional ticker.

• On Bar Close? (which decides whether the slot returns the confirmed previous-bar value or the live current-bar value).

At the blend level, changing a slot's weight, enabling or disabling a slot, or toggling master smoothing changes the blend too.

The stochastic-range gotcha

A fact that trips up readers who know ta.stoch well: the built-in takes a source argument and a separate high and low argument, and the call in this script is ta.stoch(src, high, low, stochLength). The range denominator is always the bar's own high and low, regardless of the source. Changing the Source input from close to hl2, hlc3, or ohlc4 only moves the numerator — where inside the bar's range the current value sits. The range itself does not change.

This is a subtle knob. On quiet, narrow-range bars the slot K will barely move when you change Source because the numerator is close to the midpoint of a narrow high-low window no matter which source you picked. On wide-range bars the effect is more visible but still bounded. The Settings page calls this out; the for-the-geeks page shows the pipeline. If you change Source and expect the range to rescale, you will misread the knob.

Scaffolding: the five guides

The 0 and 100 lines are the pane's floor and ceiling. The 50 line is the geometric midline of the range. All three are hard-coded and do not move.

The 80 and 20 guides are the overbought and oversold reference zones, user-movable via the Overbought Level and Oversold Level inputs. 80/20 is the classical stochastic convention — higher than RSI's 70/30. A reader arriving from an RSI habit will mis-sight the guides until this is in muscle memory; a reader using custom 70/30 stochastics will find the defaults one notch "wider" than they expect.

The 80/20 guides are reference zones. They say: "the blend is pinned into its upper or lower region." They do not say: "the next move is a reversal." Treating them as reversal lines is a category error — a reference position is not an action.

Structure overlay: Donchian steplines around the blend

Donchian is on by default. Three silver steplines frame the blend: upper, lower, and an optional basis midpoint drawn between them.

The upper stepline is ta.highest of blended K over DC Len bars. The lower stepline is ta.lowest of blended K over the same length. The midpoint is the average of the two, optionally passed through an MA whose default length is 1 (which is a passthrough; raise DC Basis Len above 1 to actually smooth the midpoint).

What the Donchian steplines mean:

• The blend pressing the upper stepline. The blended K is making a new local high in the oscillator. That is a statement about the blend's own range, not about price's range. Price can be making new highs while the blend is mid-range; price can be in a chop while the blend presses a stepline.

• The blend pressing the lower stepline. Same logic in the other direction.

• The steplines compressing toward each other. The blended K has been range-bound over the channel length.

• The steplines widening. The blended K has been expanding its own range over the channel length.

What the Donchian steplines do not mean:

• They do not mark chart-price highs or lows.

• They do not mark support and resistance in any price-space sense.

• They do not call reversals when the blend touches them.

The stepline drawing style is deliberate. Steps, not curves, because the lines are highest and lowest — they only move when a new extreme is set. A curve would imply smooth motion that is not there.

Structure overlay: the Keltner envelope on the blend

Keltner is off by default. Enable it when you want the blend's stretch against its own recent range made explicit on the pane.

The envelope has three pieces: an upper band, a lower band, and an optional midline basis drawn between them. The basis is an MA of the blended K, with its own MA family and length (KC Basis Type and KC Basis Len). The half-width is a bar-to-bar absolute-difference range estimator scaled by a user multiplier (KC Mult).

What the envelope means:

• Blended K inside the envelope. The blend is within its own recent range for that length. Normal oscillator behaviour.

• Blended K pushing or exceeding a band. The blend is stretched against its own recent range. Stretched is not the same as exhausted. Stretched reads can persist through a whole leg of a move.

• Bands widening. The blend has been more volatile across the length.

• Bands narrowing. The blend has been quieter.

What the envelope does not mean:

• A Keltner touch on the oscillator is not "price is overbought" or "price is oversold." The envelope wraps the blended K — an oscillator reading, already in 0..100 space — and measures its stretch in oscillator space. Price-level overbought and oversold belong to a different analysis.

• A Keltner band is not a support or resistance level.

• A Keltner upper touch is not a sell signal.

The Keltner bands are in orange at defaults, with a translucent fill, so they do not compete with the blend fill for attention.

Structure readout: BBWP columns

BBWP columns sit at the bottom of the pane, anchored at zero, switching between aqua and blue at a user-configurable threshold (default 50).

The construction: a matched-length Bollinger band is computed on the blended K line (basis MA and standard-deviation window share a single length input — BBWP Length). The band's width — upper minus lower — is measured every bar. The current width is percentile-ranked against the prior BBWP Lookback widths (default 252). The column height is that percentile rank, 0 to 100.

What the columns mean:

• Short blue columns. The blended K has been tightly wound against its own recent history. Low-width regime.

• Tall aqua columns. The blended K's band width is at the upper end of its recent history, at or above the configured threshold. High-width regime.

• Rising columns through the threshold. The blend has been expanding its own band width across bars.

• Falling columns back under the threshold. The blend has been compressing.

The single most important fact about BBWP on this pane

BBWP here is oscillator width, not price width. It reports the blended K line's Bollinger width percentile. Nothing about it measures price.

Some regimes show BBWP and price volatility moving together. Some regimes show them diverging. A choppy, range-bound session can produce low BBWP columns if the blend itself has been compressed by its own recent history. A strongly trending session can produce high BBWP columns even when price is in a slow grind.

If you catch yourself reading "BBWP low = market quiet," correct it in the moment. The BBWP column is the oscillator telling you about itself.

Discrete markers: divergence triangles

Divergence is on by default. Bullish divergences render as lime up-triangles near y=1; bearish divergences render as red down-triangles near y=98. The triangles are absolute-positioned, so they never overlap the K or D plots.

How a divergence is detected

1. The script runs ta.pivotlow(low, n, n) and ta.pivothigh(high, n, n) on chart-price low and chart-price high, where n is Pivot Len (default 20). These are symmetric pivots: a pivot is only confirmed once n bars to the right of the candidate bar have formed.

2. When a new pivot confirms, the script pairs it against the previous pivot of the same kind.

3. For a bullish divergence: the new pivot low must sit below the previous pivot low in chart price, and the blended K value at the new pivot's offset must sit above the blended K value at the previous pivot's offset. A lower chart-price low paired with a higher blended-K low.

4. For a bearish divergence: the new pivot high must sit above the previous pivot high in chart price, and the blended K at the new pivot's offset must sit below the blended K at the previous pivot's offset.

5. The entire check runs inside barstate.isconfirmed. No divergence evaluation happens on a bar that is still forming.

What the triangle actually means

A confirmed bullish divergence is a precise geometric pairing between two chart-price pivot lows and two blended-K values at the corresponding offsets. That is a specific moment with a specific construction. Same for bearish in the other direction.

It is not:

• a directional call on the next bar or the next leg;

• a statement about what price does at the confirmation bar;

• a real-time marker of anything the reader could have acted on at the drawn position when Plot On Pivot is enabled;

• a promise that the previous pivot was a reversal point.

It is a question worth asking: "chart price made a lower low while the oscillator did not." What you do with that question is your work, not the indicator's.

Plot On Pivot — an honest warning

With Plot On Pivot off (the default), the triangle draws on the confirmation bar — Pivot Len bars to the right of the actual pivot. This is the physically honest position: it is where the triangle first became visible.

With Plot On Pivot on, the triangle back-shifts via the offset parameter on plotshape so it draws over the original pivot bar. This is a more readable visual because the mark sits on the pattern you are looking at.

The cost: that triangle was not visible at that bar when that bar was printing. A reader who treats the back-shifted marker as evidence they could have acted on the pivot bar in real time is making a decision on evidence that did not exist yet at that bar. This is not a minor caveat; it is the whole game.

The alert timing is unaffected. Whether Plot On Pivot is on or off, the divergence alert fires on the confirmation bar. The drawing is a visual convenience; the fire time is the truth.

The one fact that binds all four structure features

Divergence reads the blended K at pivot offsets. Keltner wraps a smoothed basis of the blended K. BBWP measures the Bollinger width of the blended K. Donchian finds the highest and lowest values of the blended K.

All four read the same series. All four read it after master smoothing (if enabled) and after the final clamp into 0..100. When the blend presses a Donchian edge, the same blend is likely also near a Keltner band, and the BBWP has usually just moved. When a divergence confirms at that same moment, it is reading a third view of the same line.

That is one line agreeing with itself by construction. It is not four independent witnesses.

If you read the four features as four independent votes, you will feel more confident in exactly the moments where the pane is least informative — the moments where the features are all saying the same thing because they are all derived from the same source. The correct read is the opposite: when several structure features move together, ask what slot or weight or smoothing move in the blend put them all in motion, because something in the blend itself just shifted.

The mature read uses each feature as a different framing question on the same line, not as a separate oracle:

• Donchian: "where is the blend inside its own channel?"

• BBWP: "how wide is the blend's band right now compared to its recent history?"

• Keltner: "is the blend stretched against its own recent range estimate?"

• Divergence: "did chart price and the blended K just disagree at this confirmed pivot?"

Four different questions. One series answering them.

Slot plots — the diagnostic layer

At defaults you do not see individual slot K lines. Slots 01, 02, and 03 have Hide Plot = true; slots 04 and 05 are disabled entirely. The pane stays readable.

When you want to diagnose which slot is driving the blend, unhide a slot. Its K line will draw in its own colour — teal for slot 01, aqua for slot 02, blue for slot 03, orange for slot 04, yellow for slot 05 — with a dimmed-down variant when K is below D on that slot and the full colour when K is above D. A line-colour flip on a slot plot is the slot-level analogue of the blend fill flip.

Slot plots are best used temporarily. If you leave three of them on, the pane becomes five lines, four structure features, and some triangles, which is too dense for a fast read. Use them to answer "which slot pulled the blend here?" and then hide them again.

A short checklist for first-session calibration

Run these on a 1m chart at defaults. Each one takes under a minute and each one locks a fact into place you would otherwise have to take on trust.

• Watch the blend fill flip as K crosses D on an active bar. The colour change is instant; it is not smoothed.

• Move Overbought Level from 80 to 70. Watch the upper dashed guide move. No alert, fill color, or hidden overbought logic changes with it. Move it back to 80.

• Unhide slot 03's plot. Watch the blue K line draw on the pane, tracking the 60-minute stochastic. Re-hide it.

• Set slot 03's weight to 0 with the plot hidden. Watch the blend re-balance onto the remaining two slots. Set the weight back to 33.3.

• Toggle Plot On Pivot? on. Find a recent confirmed divergence and watch the triangle back-shift onto the pivot bar. Confirm that the leftward back-shift does not add new triangles on the right edge — only the drawing shifts.

• Enable master smoothing with default length 3. Watch Donchian, BBWP, and Keltner shift at the same time. That shift is the "one series, four lenses" fact made visible.

Where to go next: Settings for every input by tier, Alerts for the sixteen alert conditions and their timing, MTF and repainting before changing any On Bar Close?, Limitations and trust boundaries for where the instrument stops and your judgment starts.