Market Structure Trend Matrix Indicator – MARKET STRUCTURE TREND [MST] — STRATEGY

1.1 Indicator Concept

This indicator combines three classic price-action/quant mechanics into one system:

• Change of Character (ChoCh): when price closes past the nearest opposite-side swing pivot (high or low), price-action theory treats this as evidence that the market's "character" has flipped - the side that was previously in control has lost it, and a new trend has likely begun.
• One-Directional "Ratchet" ATR Trailing Stop: a dynamic stop level, offset from price by ATR × multiplier, but only allowed to move IN FAVOR of the trend (up while bullish, down while bearish) - never backward, similar to a Chandelier Exit mechanism.
• Infinite Target Ladder: instead of a single fixed target, the indicator automatically places a whole series of evenly-spaced targets (spaced by an ATR multiple), and every time price reaches one, it immediately sets the next rung further out - forming a ladder of targets that extends indefinitely as the trend continues, each rung stamped with the % gain achieved from the broken structure level (the ChoCh entry, in theory).

In other words: ChoCh answers "when to enter", the trailing stop answers "is the trend still structurally safe", and the target ladder answers "how much profit has been captured and where's the next take-profit level" - all updated automatically in real time, no manual drawing required.

1.2 Indicator Features

• ChoCh Line & Label: a horizontal line connecting the broken pivot bar to the confirmation bar, with a "ChoCh ↑" (green) or "ChoCh ↓" (pink) label placed at the line's midpoint - pinpointing the exact structural reversal event.
• Target Ladder:
  • Pending target: a thin, solid line projected 10 bars into the future, representing the next unreached target level.
  • Hit target: once price touches it, the line switches to dashed and stretches back to the exact trend-start bar, with a percentage-gain label (e.g. "+2.15%") measured from the structure entry level.
  • "Show Target History" toggle: when OFF, all hit targets from the PREVIOUS trend are wiped the moment a new ChoCh fires, leaving only the currently active target visible.
• ATR Trailing Stop + Fill Zone: a trailing-stop line that only moves in the trend's favor (up while bullish, down while bearish), plus a translucent fill between the close price and the stop line for a quick visual read of the current risk buffer. The "Show Trailing Stop" toggle controls both the line and the fill together.
• No Alerts: this is a purely visual indicator - it ships with zero alertcondition() calls.

1.3 How to Use the Indicator

• Enter on a ChoCh: when the "ChoCh ↑" line + label appear → BUY in the bullish direction; when "ChoCh ↓" appears → SELL in the bearish direction.
• Use the Trailing Stop line as a dynamic SL: since it only ratchets in the trend's favor, it can be used directly as a progressively tightening stop loss instead of a fixed SL.
• Take profit off the Target Ladder: every time a pending target is touched (line turns dashed + a % label appears), that's a reference point for partial profit-taking - the next rung on the ladder appears automatically right after, if the trend keeps going.
• Tune structure sensitivity with "Market Structure Length": increase to only catch large, strong swing points (fewer but more reliable ChoCh signals); decrease to catch smaller structure, more responsive but noisier.
• Tune SL/target spacing with "ATR Multiplier" and "Target Step": increase "ATR Multiplier" for a wider stop (more noise tolerance but larger risk per trade); increase "Target Step" to space ladder rungs further apart (fewer take-profits but more captured per rung).
• Turn off "Show Target History" for live trading to keep the chart clean and show only the active target; turn it back on when reviewing all past take-profit levels to evaluate performance.

1.4 How the Indicator Works

Inputs & Roles

• msLen (Integer, default: 10): number of bars on each side (left + right) required to confirm a pivot high/low used as market structure. Example: msLen=10 means a swing high is only confirmed once 10 following bars are all lower - so structure signals always lag the actual swing point by at least 10 bars. Increase → only catches major swing points, rarer but more reliable ChoCh. Decrease → catches smaller structure, more ChoCh signals but noisier and with less lag.
• atrLength (Integer, default: 14): number of bars used to calculate the Average True Range (ATR), which underlies both the trailing-stop distance and the spacing between targets.
• atrMult (Float, default: 4.0): multiplier applied to ATR to determine the trailing stop's distance from price. Example: ATR=0.0050, atrMult=4.0 → the stop sits 0.0050×4=0.02 away from price. Increase → wider stop, less prone to being swept by noise but larger risk per trade. Decrease → tighter stop, locks in profit better but easier to get swept during chop.
• targetStepMult (Float, default: 2.0): multiplier applied to ATR to determine the vertical distance between two consecutive rungs on the ladder. Example: ATR=0.0050, targetStepMult=2.0 → each rung is spaced 0.0050×2=0.01 apart. Increase → rungs spaced further apart (fewer take-profits but more captured each time). Decrease → denser rungs, smaller gains per take-profit.
• bullColor, bearColor (Color, default: green rgb(52,230,126) / pink rgb(255,82,241)): color used for all ChoCh lines, targets, trailing stop, and fill zone for each trend direction.
• showHistory (Boolean, default: true): when OFF, every hit target line + label from the PREVIOUS trend is deleted the moment a new ChoCh fires (the current trend's own objects are never affected by this toggle).
• showStop (Boolean, default: true): toggles both the trailing-stop line AND the fill zone between price and the stop together.

Main Logic Blocks

🎯 Flow 1: Pivot / Market Structure Detection

• Every bar, the indicator checks ta.pivothigh(msLen, msLen) and ta.pivotlow(msLen, msLen) - a swing high/low is only confirmed once msLen bars on BOTH sides are all lower (for a high) or higher (for a low).
• When a new pivot high confirms: save phVal = the exact pivot bar's high (msLen bars back), phIndx = that bar's position. Same for a pivot low with plVal/plIndx. Both values are HELD until a newer pivot confirms - acting as the "nearest structure level still waiting to be broken".
• Example: msLen=10. The highest high of the swing forms at bar 500 (price 1.2700). It must wait until bar 510 (10 bars later) to be confirmed as a valid pivot → at that point phVal:=1.2700, phIndx:=500. The 1.2700 level stays tracked until a newer high forms.

🎯 Flow 2: ChoCh Detection & Trend Flip

• Bullish ChoCh: when close crosses above phVal (ta.crossover) WHILE the current trend is bearish (not direction): switch direction := true, reset the trailing stop atrTS := close - atr×atrMult, entryPrice := phVal (the broken structure level, NOT the actual close price at the time of the break), currentTarget := entryPrice + atr×targetStepMult, trendStart := current bar.
• Draws a horizontal line from phIndx to the current bar at level phVal (bullColor, width 2) + a "ChoCh ↑" label at its midpoint. Deletes the previous target line (if any) and creates a new one from the current bar extending 10 bars into the future at level currentTarget.
• Bearish ChoCh is symmetric: when close crosses under plVal WHILE the current trend is bullish → direction:=false, atrTS:=close+atr×atrMult, entryPrice:=plVal, currentTarget:=entryPrice-atr×targetStepMult, draws the line + "ChoCh ↓" label (bearColor).
• Example: phVal=1.2700, atr=0.0050, atrMult=4.0, targetStepMult=2.0. At bar 530, close=1.2705 just crossed above 1.2700 while in a bearish trend → bullish ChoCh confirms: atrTS=1.2705-0.02=1.2685, entryPrice=1.2700, currentTarget=1.2700+0.01=1.2710, trendStart=530. The ChoCh line is drawn from bar 500 (where the pivot formed) to bar 530.

🎯 Flow 3: History Cleanup on Trend Change

• directionChange = this bar's direction differs from the previous bar's (i.e. a ChoCh just fired). If true AND showHistory is OFF: delete every hit-target line + label from the trend that just ended out of the storage arrays - keeping the chart clean with only the new trend's targets visible.

🎯 Flow 4: ATR Trailing Stop Update (every bar, ratchet style)

• While trend is bullish: atrTS := max(previous atrTS, close - atr×atrMult) - only allowed to INCREASE, never decrease. If a pullback would produce a lower candidate value, the previously held (higher) level is kept.
• While trend is bearish: symmetric, using min() - only allowed to DECREASE, never increase.
• Example (bullish trend): previous atrTS = 1.2650. Current close=1.2680, atr×atrMult=0.02 → candidate = 1.2680-0.02=1.2660. Since 1.2660 > 1.2650 → atrTS updates to 1.2660 (moves up with price). Next bar price pulls back to close=1.2670 → candidate=1.2670-0.02=1.2650 < 1.2660 (the held level) → atrTS STAYS at 1.2660, never pulled back down.

🎯 Flow 5: Target Ladder Progression (every bar, parallel to Flow 4)

• Bullish trend: checks high >= currentTarget. If true (target reached): finalize the current target line (set x2 = current bar, switch to dashed, pull x1 back to trendStart), push this line + a %-gain label ((currentTarget - entryPrice) / entryPrice × 100) into the two storage arrays. Then compute the NEXT target = currentTarget + atr×targetStepMult and draw a new (lighter, more transparent) target line from trendStart extending 10 bars into the future. If the target has NOT been reached yet: simply extend the current target line further into the future (same price level, always staying 10 bars ahead of price).
• Bearish trend is symmetric, using low <= currentTarget and subtracting ATR×targetStepMult for each next rung (the % label comes out negative).
• Example: entryPrice=1.2700, currentTarget=1.2710. At bar 545, high=1.2715 ≥ 1.2710 → target reached: the line becomes dashed, spanning from bar 530 (trendStart) to bar 545, and a "+0.08%" label (= (1.2710-1.2700)/1.2700×100) appears at (530, 1.2710). The next target = 1.2710+0.01=1.2720, and a new (lighter) target line is drawn from bar 530 to bar 555.

🎨 Flow 6: Draw Trailing Stop & Fill Zone

• The ATR Trailing Stop line is only plotted when showStop is on AND it's NOT the bar where direction just flipped (not directionChange) - on the exact bar the trend flips, the plotted value is forced to na, creating a short gap (thanks to the linebr style) to avoid drawing an ugly diagonal connector between the old stop level and the freshly reset one.
• A translucent fill is drawn between the close price line and the trailing-stop line, colored by the current trend direction (bullColor/bearColor at 70% transparency) - visualizing the "buffer zone" between price and the stop.

Outputs & Usage Roles

• ChoCh line + label: pinpoints the exact time and price of a structural reversal - used as the entry trigger and reference level.
• ATR Trailing Stop line: a dynamic stop that only moves in the trend's favor - used directly as a progressively tightening SL throughout the trade's life.
• Target ladder (pending + hit): a multi-tier take-profit roadmap that auto-extends indefinitely by ATR steps as the trend continues; the % labels show exactly how much gain was captured at each tier.
• Fill zone between price and stop: a quick visual read of the current risk buffer without reading raw numbers.