pinets 0.9.18 → 0.9.20

package/dist/types/Context.class.d.ts

@@ -36,6 +36,10 @@ export declare class Context {
     }[];
     /** Alert mode: 'realtime' = only fire on live bars (TV behavior), 'all' = fire on every bar (backtest). */
     _alertMode: 'realtime' | 'all';
+    /** Name-keyed map of declaration-prop overrides from `Indicator.prop`. Layered on top of
+     *  the source's `indicator()`/`strategy()` call args inside the per-bar handlers
+     *  (see Core.indicator and initializeStrategy). Empty object when no overrides are set. */
+    _propOverrides: Record<string, unknown>;
     /** Monotonically increasing counter, incremented each time a bar starts executing.
      *  Used by alertcondition/AlertHelper to detect re-execution of the same bar. */
     _execTick: number;

package/dist/types/Indicator/Indicator.class.d.ts

@@ -0,0 +1,100 @@
+import type { IPineInput, IPineProp, PreparedScript } from './types';
+/**
+ * The single owner of every per-script artifact. Holds the source, lazily
+ * transpiles + scans inputs on first `prepare()`, and caches the result so
+ * the same Indicator instance can be passed to multiple `pine.run()` calls
+ * without re-transpiling.
+ *
+ * Roles:
+ *   - `source`            — the original Pine string or JS callback.
+ *   - `input`             — live, title-keyed view of input values. Read or
+ *                            mutate per key; the container itself is frozen.
+ *   - `inputs`            — LEGACY title-keyed override map (constructor
+ *                            arg). Kept for back-compat; merged into the
+ *                            prepared inputs by `prepare()`.
+ *   - `prepare(opts?)`    — idempotent: transpiles, scans inputs, runs
+ *                            visible-range static analysis. Caches result.
+ *   - `usesVisibleRange()`— derived from the cached prepare() result.
+ *
+ * For JS-function source the AST scan returns `[]`, so `input` is empty and
+ * per-key writes throw "unknown title". The legacy `inputs` field still
+ * works for that path.
+ */
+export declare class Indicator {
+    readonly source: Function | string;
+    inputs: Record<string, unknown>;
+    readonly input: Record<string, unknown>;
+    readonly prop: Record<string, unknown>;
+    private _prepared;
+    private _inputMeta;
+    private _inputValues;
+    private _explicitOverrides;
+    private _inputProxy;
+    private _propMeta;
+    private _propValues;
+    private _propProxy;
+    private _declarationType;
+    private _sourcePropArgs;
+    private _explicitPropOverrides;
+    constructor(source: Function | string, inputs?: Record<string, unknown>);
+    /**
+     * Normalize ANY accepted run() argument into an Indicator. Raw functions
+     * and strings get wrapped in a throwaway Indicator; existing Indicators
+     * pass through. This is the single entry point used by PineTS's run /
+     * stream / update so the rest of the engine only deals with Indicators.
+     */
+    static from(arg: Indicator | Function | string): Indicator;
+    /**
+     * Idempotent transpile + scan + viewport detection. The result is cached
+     * on the instance, so passing the same Indicator to multiple `pine.run()`
+     * calls produces a single transpilation pass.
+     *
+     * NB: cache is keyed by *instance identity*, not by options. If you need
+     * different debug settings, create a new Indicator.
+     */
+    prepare(opts?: {
+        debug?: boolean;
+        ln?: boolean;
+    }): PreparedScript;
+    /** True iff the script references any built-in in `VIEWPORT_DEPENDENT_BUILTINS`. */
+    usesVisibleRange(): boolean;
+    /**
+     * Title-keyed input map used by the runtime (read by
+     * `input.utils.resolveInput`). Composed at call time so live mutations
+     * to `.input` between `pine.run()` calls are picked up automatically.
+     *
+     * Precedence:
+     *   1. Legacy constructor `inputs`            (back-compat)
+     *   2. Explicit writes to `.input[...]`       (new API; takes priority)
+     *
+     * Defaults are NOT included — the runtime falls back to `defval` when a
+     * title is absent.
+     */
+    getRuntimeInputs(): Record<string, unknown>;
+    /**
+     * AST-parsed input metadata. Lazy. Empty array for JS-function source.
+     */
+    getInputsMeta(): IPineInput[];
+    /**
+     * Schema metadata for declaration props applicable to this script's type.
+     * Includes non-mutable entries (`title`, `shorttitle`) for completeness —
+     * UI builders can render them; writes to those keys via `.prop` still throw.
+     */
+    getPropsMeta(): IPineProp[];
+    /**
+     * Name-keyed map of user-overridden props for the runtime to merge on top
+     * of the source-code's indicator()/strategy() call args. Only explicit
+     * writes via `.prop` are included — source-code values flow through the
+     * normal Pine call path.
+     */
+    getRuntimePropOverrides(): Record<string, unknown>;
+    /**
+     * Detected declaration type, or null if the source code has neither call.
+     * `.prop` falls back to the indicator schema in the null case.
+     */
+    getDeclarationType(): 'indicator' | 'strategy' | null;
+    private _ensureInputsScanned;
+    private _getInputProxy;
+    private _ensurePropsScanned;
+    private _getPropProxy;
+}

package/dist/types/Indicator/inputProxy.d.ts

@@ -0,0 +1,14 @@
+import type { IPineInput } from './types';
+/**
+ * Build the live `.input` view exposed on an `Indicator` instance.
+ * Title-keyed; entries without an explicit `title=` on the Pine source are
+ * excluded (Pine's runtime keys overrides by title, so a title-less input is
+ * not overridable).
+ *
+ * Backing machinery lives in `keyedProxy.ts` and is shared with `.prop`.
+ */
+export declare function buildInputProxy(metas: IPineInput[], onSet?: (title: string) => void): {
+    proxy: Record<string, unknown>;
+    values: Record<string, unknown>;
+    metaByTitle: Map<string, IPineInput>;
+};

package/dist/types/Indicator/keyedProxy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic title/name-keyed Proxy with per-key validation. Shared backend for
+ * both `Indicator.input` (keyed by input title) and `Indicator.prop` (keyed
+ * by declaration arg name).
+ *
+ * Contract:
+ *   - Read:    returns current value (default OR user-overridden) at the key.
+ *   - Write:   validates against the entry's meta — type, options, minval,
+ *              maxval — and stores the override. Invalid writes THROW with
+ *              a tailored message.
+ *   - Delete:  throws.
+ *   - Unknown key write: throws, listing the known keys.
+ *   - Object.keys() / spread / console.log show real keys with current values.
+ */
+export type KeyedType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'enum' | 'price' | 'time' | 'session' | 'symbol' | 'timeframe' | 'text_area';
+export interface KeyedSchemaEntry {
+    key: string;
+    type: KeyedType;
+    defval: unknown;
+    options?: unknown[];
+    minval?: number;
+    maxval?: number;
+}
+export interface BuildKeyedProxyResult {
+    proxy: Record<string, unknown>;
+    values: Record<string, unknown>;
+    entryByKey: Map<string, KeyedSchemaEntry>;
+}
+/**
+ * Build a keyed proxy view.
+ *
+ * @param entries  schema entries — defaults seeded into `values`
+ * @param label    display label for error messages, e.g. 'Indicator.input' or 'Indicator.prop'
+ * @param onSet    optional callback fired after a successful write (for explicit-override tracking)
+ * @param seedValues  optional initial values overriding entry defvals (used by .prop to seed
+ *                    source-code defaults on top of spec defaults)
+ * @param keyNoun  noun for the unknown-key message, defaults to 'key'. Inputs use 'input title'.
+ */
+export declare function buildKeyedProxy(entries: KeyedSchemaEntry[], label: string, onSet?: (key: string) => void, seedValues?: Record<string, unknown>, keyNoun?: string): BuildKeyedProxyResult;
+/**
+ * Per-entry write validation. Throws on any rule violation.
+ */
+export declare function validate(entry: KeyedSchemaEntry, value: unknown, label: string): void;

package/dist/types/Indicator/propProxy.d.ts

@@ -0,0 +1,16 @@
+import type { IPineProp } from './types';
+/**
+ * Build the live `.prop` view exposed on an `Indicator` instance.
+ * Name-keyed; non-mutable entries (`title`, `shorttitle`) are excluded.
+ *
+ * `sourceArgs` seeds source-code defaults on top of spec defaults so the
+ * read view matches what TradingView's runtime would see before any user
+ * override. Layer order: spec.defval ← sourceArgs ← user `.prop` writes.
+ *
+ * Backing machinery lives in `keyedProxy.ts` and is shared with `.input`.
+ */
+export declare function buildPropProxy(props: IPineProp[], sourceArgs: Record<string, unknown>, onSet?: (name: string) => void): {
+    proxy: Record<string, unknown>;
+    values: Record<string, unknown>;
+    propByName: Map<string, IPineProp>;
+};

package/dist/types/Indicator/propsSchema.d.ts

@@ -0,0 +1,8 @@
+import type { IPineProp } from './types';
+export declare const INDICATOR_PROPS: IPineProp[];
+export declare const STRATEGY_PROPS: IPineProp[];
+/**
+ * Pick the right schema for a detected declaration type. Returns the
+ * indicator schema when type is unknown (sensible fallback per spec).
+ */
+export declare function propsForDeclaration(type: 'indicator' | 'strategy' | null): IPineProp[];

package/dist/types/Indicator/scanDeclaration.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Detect whether a script is a `strategy()` or `indicator()`, and extract
+ * the actual values passed to that call from source so they can seed
+ * `.prop` defaults.
+ *
+ * Both source kinds are handled:
+ *   - Pine string  → pineToJS() AST → walk for the top-level CallExpression
+ *   - JS function  → acorn.parse(fn.toString()) → walk for CallExpression with
+ *                    callee Identifier matching 'indicator' / 'strategy'
+ *
+ * Enum-typed args are resolved by the "rightmost-identifier rule": for any
+ * `MemberExpression` the rightmost `Identifier` name is the runtime string.
+ * Holds for every Pine-namespace constant accepted by indicator()/strategy()
+ * (format.percent → "percent", currency.USD → "USD",
+ *  strategy.percent_of_equity → "percent_of_equity",
+ *  strategy.commission.percent → "percent").
+ *
+ * Returns `{ type, args }`:
+ *   - type   = 'indicator' | 'strategy' | null
+ *   - args   = name → resolved value extracted from the source call
+ *
+ * If the declaration call isn't found, returns `{ type: null, args: {} }`.
+ * The Indicator class falls back to the indicator schema in that case.
+ */
+export interface ScannedDeclaration {
+    type: 'indicator' | 'strategy' | null;
+    args: Record<string, unknown>;
+}
+export declare function scanDeclaration(source: unknown): ScannedDeclaration;

package/dist/types/Indicator/scanInputs.d.ts

@@ -0,0 +1,5 @@
+import type { IPineInput } from './types';
+/**
+ * Public entry point. Returns `[]` for invalid Pine or for non-string source.
+ */
+export declare function scanInputs(source: unknown): IPineInput[];

package/dist/types/Indicator/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Pine Script `input.*` typing classification. Mirrors TradingView's input
+ * widget types 1:1. The bare `input()` wrapper auto-detects from `defval`
+ * and dispatches to one of these — there is no `'auto'` member.
+ *
+ * v6 adds `'enum'`. Everything else exists in both v5 and v6.
+ */
+export type PineInputType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'enum' | 'price' | 'time' | 'session' | 'symbol' | 'timeframe' | 'text_area';
+/**
+ * Value of an input's `display=` argument. Stored as the suffix (without the
+ * `display.` prefix), matching what the existing runtime parses into
+ * `InputOptions.display` at the call site.
+ */
+export type PineInputDisplay = 'none' | 'data_window' | 'status_line' | 'all';
+/**
+ * Parsed metadata for a single `input.*` declaration in a Pine script.
+ *
+ * Field presence matches the Pine reference (v6 superset):
+ *   - title, tooltip, group, display, active        — universal (all 14 fns)
+ *   - inline                                         — universal except text_area
+ *   - confirm                                        — universal except bare input()
+ *   - options                                        — enum, float, int, session, string, timeframe
+ *   - minval / maxval / step                         — float, int only
+ *
+ * `defval` is fully resolved at scan time — for enum inputs we resolve
+ * `tz.utc` → "UTC" (the field title) so JS callers see what TradingView's
+ * `str.tostring()` would print, never the AST path.
+ */
+export interface IPineInput {
+    type: PineInputType;
+    defval: unknown;
+    title?: string;
+    tooltip?: string;
+    group?: string;
+    display?: PineInputDisplay;
+    active?: boolean;
+    confirm?: boolean;
+    inline?: string;
+    options?: unknown[];
+    minval?: number;
+    maxval?: number;
+    step?: number;
+}
+/**
+ * Pine Script declaration-arg typing classification (used by `IPineProp`).
+ *
+ * `enum` covers every Pine-namespace constant used as a declaration arg
+ * (e.g. `format.percent`, `currency.USD`, `strategy.percent_of_equity`).
+ * The scanner resolves these to bare strings via the rightmost-identifier
+ * rule, matching what the runtime sees.
+ */
+export type PinePropType = 'string' | 'int' | 'float' | 'bool' | 'enum';
+/**
+ * Schema entry for a single `indicator()` / `strategy()` declaration argument.
+ *
+ * The full set of entries is curated from the Pine v6 reference:
+ *   - https://www.tradingview.com/pine-script-reference/v6/#fun_indicator
+ *   - https://www.tradingview.com/pine-script-reference/v6/#fun_strategy
+ *
+ * `title` and `shorttitle` are present in the schema with `mutable: false`
+ * so UI consumers can render them, but are filtered out of `.prop` writes.
+ *
+ * For enum-typed entries, `options` enumerates the accepted runtime strings.
+ * The schema source file points to the corresponding exported Pine enum
+ * (e.g. `enum format` in Types.ts) so JS callers can import the same source.
+ */
+export interface IPineProp {
+    name: string;
+    type: PinePropType;
+    defval: unknown;
+    options?: unknown[];
+    minval?: number;
+    maxval?: number;
+    mutable: boolean;
+    appliesTo: 'indicator' | 'strategy' | 'both';
+    version?: 5 | 6;
+}
+/**
+ * Result of `Indicator.prepare()`. The single artifact handed to the engine.
+ *
+ * `inputs` is the title-keyed map the runtime already expects — built by
+ * merging each `IPineInput`'s current value (post-user-override) into a
+ * flat `{ [title]: value }` object that `input.utils.resolveInput()` reads.
+ */
+export interface PreparedScript {
+    fn: Function;
+    inputs: Record<string, unknown>;
+    usesVisibleRange: boolean;
+    ltfSlices?: any[];
+}

package/dist/types/Indicator.d.ts

@@ -1,5 +1,3 @@
-export declare class Indicator {
-    source: Function | String;
-    inputs: Record<string, any>;
-    constructor(source: Function | String, inputs?: Record<string, any>);
-}
+export { Indicator } from './Indicator/Indicator.class';
+export { INDICATOR_PROPS, STRATEGY_PROPS, propsForDeclaration } from './Indicator/propsSchema';
+export type { IPineInput, IPineProp, PineInputType, PineInputDisplay, PinePropType, PreparedScript, } from './Indicator/types';

package/dist/types/PineTS.class.d.ts

@@ -28,6 +28,7 @@ export declare class PineTS {
     private _debugSettings;
     private _transpiledCode;
     get transpiledCode(): Function | String;
+    private _currentIndicator;
     private _isSecondaryContext;
     markAsSecondary(): void;
     private _syminfo;
@@ -254,26 +255,6 @@ export declare class PineTS {
      * @private
      */
     private _initializeContext;
-    /**
-     * Transpile the Pine Script code
-     * @private
-     */
-    private _transpileCode;
-    /**
-     * Static analysis on the transpiled function body to detect references to
-     * host-bound built-ins (currently visible-range; extensible via
-     * VIEWPORT_DEPENDENT_BUILTINS). Comments are stripped during pine2js, so
-     * scanning the post-transpile output is comment-safe.
-     *
-     * Why post-transpile (not regex on Pine source): a `chart.left_visible_bar_time`
-     * literal inside a // comment would be a false positive at the source level.
-     * After pine2js, only live code remains.
-     *
-     * Why regex (not AST visitor): `chart` is a reserved namespace in
-     * KNOWN_NAMESPACES — Pine scripts cannot shadow it with a local identifier,
-     * so a whole-word match on `chart.<prop>` is unambiguous.
-     */
-    private _detectViewportUsage;
     /**
      * Execute iterations from startIdx to endIdx, updating the context
      * @private

package/dist/types/index.d.ts

@@ -12,3 +12,5 @@ export type { Kline, PeriodType } from './marketData/types';
 export { computeNextPeriodStart, localTimeToUTC, computeSessionClose, TIMEFRAME_SECONDS, TIMEFRAME_PERIOD_INFO } from './marketData/types';
 export { aggregateCandles, selectSubTimeframe, getAggregationRatio } from './marketData/aggregation';
 export { PineTS, Context, Provider, Indicator, PineRuntimeError };
+export type { IPineInput, IPineProp, PineInputType, PineInputDisplay, PinePropType, PreparedScript } from './Indicator';
+export { INDICATOR_PROPS, STRATEGY_PROPS, propsForDeclaration } from './Indicator';

package/dist/types/namespaces/strategy/methods/avg_losing_trade_percent.d.ts

@@ -1,5 +1,9 @@
 /**
- * Average per-trade loss (as a positive percent) across losing closed trades.
- * NaN when no losers yet. Matches Pine's strategy.avg_losing_trade_percent.
+ * Average per-trade loss (as a SIGNED negative percent) across losing
+ * closed trades. NaN when no losers yet.
+ *
+ * Note: `strategy.avg_losing_trade` (the dollar version) is reported as
+ * a POSITIVE magnitude by Pine convention, but `_percent` is signed —
+ * negative values, since they represent losses.
  */
 export declare function avg_losing_trade_percent(context: any): () => number;

package/dist/types/namespaces/strategy/methods/convert_to_account.d.ts

@@ -1,9 +1,15 @@
 /**
  * Convert a value from the symbol's currency to the account currency.
  *
- * For the common same-currency case (e.g. BTCUSDC's quote currency USDC ≈ USD),
- * this is an identity. Genuine cross-currency conversion would require an FX
- * rate source which we don't model; returns the input unchanged in that case
- * with a console warning on first call.
+ * Pine semantics:
+ *   - same currency string → return the value unchanged (identity)
+ *   - different currency strings → return `na` (NaN), since no FX
+ *     rate is available. String equality is used, not economic
+ *     equivalence — so nominally pegged pairs like USDC vs USD still
+ *     return NaN when their currency strings differ.
+ *
+ * When `syminfo.currency` is undefined we fall back to identity rather
+ * than NaN, so synthetic / array-fed datasets without a syminfo block
+ * don't get poisoned.
  */
 export declare function convert_to_account(context: any): (value: number) => number;

package/dist/types/namespaces/strategy/methods/convert_to_symbol.d.ts

@@ -1,5 +1,8 @@
 /**
  * Inverse of convert_to_account: from account currency → symbol currency.
- * Same identity passthrough for matching-currency case.
+ *
+ * Mirrors convert_to_account's TV-matching behavior: identity passthrough
+ * when account and symbol currencies are the same string, NaN when they
+ * differ. See convert_to_account.ts for the full rationale.
  */
 export declare function convert_to_symbol(context: any): (value: number) => number;

package/dist/types/namespaces/strategy/methods/margin_liquidation_price.d.ts

@@ -2,12 +2,22 @@
  * Price at which the current leveraged position would be force-liquidated.
  * Returns NaN when flat or when the relevant margin% is 100 (no leverage).
  *
- * Formula (simplified):
- *   long  → entry_avg_price * (1 - margin_long / 100)
- *   short → entry_avg_price * (1 + margin_short / 100)
+ * Official TV formula, documented at
+ * https://www.tradingview.com/support/solutions/43000717375/ :
  *
- * This is the simple peak-loss-tolerable price; real broker liquidation
- * depends on maintenance margin schedules which we don't model.
- * Matches Pine's strategy.margin_liquidation_price in the common case.
+ *   MarginLiquidationPriceRaw =
+ *       ((InitialCapital + NetProfit) / (PointValue * AbsPositionSize)
+ *        − Direction * EntryPrice)
+ *     / (MarginPercent / 100 − Direction)
+ *
+ * Where:
+ *   InitialCapital + NetProfit = realized account equity (initial cash
+ *                                 plus closed-trade P&L; excludes openprofit)
+ *   PointValue                 = syminfo.pointvalue (1 for crypto, varies
+ *                                 for futures contracts)
+ *   AbsPositionSize            = |strategy.position_size|
+ *   Direction                  = +1 for long, −1 for short
+ *   EntryPrice                 = strategy.position_avg_price
+ *   MarginPercent              = margin_long for longs, margin_short for shorts
  */
 export declare function margin_liquidation_price(context: any): () => number;

package/dist/types/namespaces/strategy/methods/max_drawdown_percent.d.ts

@@ -1,5 +1,14 @@
 /**
- * Maximum drawdown as a percent of the equity high-water mark.
- * Matches Pine's strategy.max_drawdown_percent.
+ * Maximum drawdown percent. Pine's semantic is the RUNNING MAX of
+ * `(latched_drawdown / equity_at_that_latch) × 100` across all latch
+ * events over the strategy's lifetime — NOT a derived
+ * `(current_max_drawdown / current_equity_at_peak) × 100`. The two
+ * interpretations diverge when a later latch produces a larger absolute
+ * drawdown but a smaller percentage (because equity grew faster than
+ * the drawdown), in which case the earlier latch's higher ratio is the
+ * reported value.
+ *
+ * The running max is maintained in `updateEquityPeaks` (utils.ts) on
+ * every latch event; this getter is a pure read.
  */
-export declare function max_drawdown_percent(context: any): () => number;
+export declare function max_drawdown_percent(context: any): () => any;

package/dist/types/namespaces/strategy/methods/max_runup_percent.d.ts

@@ -1,5 +1,17 @@
 /**
- * Maximum equity run-up as a percent of initial capital.
- * Matches Pine's strategy.max_runup_percent.
+ * Maximum equity run-up percent. Mirrors the `max_drawdown_percent`
+ * semantic — TV reports the RUNNING MAX of the per-latch ratio,
+ * `(latched_runup / equity_at_that_latch) × 100`, across all latches
+ * in the strategy's lifetime.
+ *
+ * In most strategies the runup ratio grows monotonically with each
+ * latch, so this matches a derived `(current_max_runup /
+ * current_equity_at_runup_peak) × 100`. But in scenarios where a
+ * later latch produces a larger absolute runup yet a smaller
+ * percentage (because equity grew faster than the runup), TV keeps
+ * the highest ratio ever seen — same as the drawdown semantic.
+ *
+ * The running max is maintained in `updateEquityPeaks` whenever
+ * max_runup is latched to a new peak — see utils.ts.
  */
-export declare function max_runup_percent(context: any): () => number;
+export declare function max_runup_percent(context: any): () => any;

package/dist/types/namespaces/strategy/types.d.ts

@@ -111,6 +111,10 @@ export interface Order {
     immediately?: boolean;
     trail_peak?: number;
     trail_armed?: boolean;
+    _isReversalEntry?: boolean;
+    _attachedAtReversal?: boolean;
+    _isPersistent?: boolean;
+    _callsiteId?: string;
 }
 /**
  * Strategy state stored on the Context after a backtest run.
@@ -144,6 +148,10 @@ export interface StrategyState {
     max_runup: number;
     equity_peak: number;
     equity_trough: number;
+    equity_at_runup_peak: number;
+    equity_at_drawdown_peak: number;
+    max_drawdown_percent_value: number;
+    max_runup_percent_value: number;
     wintrades: number;
     losstrades: number;
     eventrades: number;
@@ -173,4 +181,7 @@ export interface StrategyState {
         max_position_size?: number;
     };
     risk_halted: boolean;
+    _exit_call_history?: Map<string, number>;
+    _exit_fallback_counter?: number;
+    _exit_fallback_last_bar?: number;
 }

package/dist/types/namespaces/strategy/utils.d.ts

@@ -3,6 +3,58 @@ import { Order, StrategyState } from './types';
  * Parse strategy() function arguments
  */
 export declare function parseStrategyOptions(args: any[]): any;
+/**
+ * Round a stop/limit price to the symbol's mintick grid, AWAY from the
+ * reference price (typically the current bar's close at order placement).
+ *
+ * Pine's broker emulator places stop/limit orders on the mintick grid
+ * conservatively — a buy stop at 4188.4541 above current 4184 becomes
+ * 4188.46 (ceiling), not 4188.45. This makes the order trigger LATER
+ * (requires more price movement), mirroring real-broker order placement.
+ *
+ * The rule:
+ *   price > referencePrice → ceil to mintick (push price UP)
+ *   price < referencePrice → floor to mintick (push price DOWN)
+ *   price === referencePrice → return as-is
+ *
+ * Covers all four cases naturally:
+ *   - Buy stop above current  → ceil
+ *   - Sell stop below current → floor
+ *   - Buy limit below current → floor
+ *   - Sell limit above current → ceil
+ *   - Long TP above entry / SL below entry → ceil / floor
+ *   - Short TP below entry / SL above entry → floor / ceil
+ *
+ * For mintick === 0 or undefined (defensive), returns the price unchanged.
+ */
+export declare function roundToMintick(price: number, referencePrice: number, mintick: number): number;
+/**
+ * Margin required to hold a position of `qty` contracts at `price`, given
+ * the `marginPct` (% of notional that must be posted as collateral). The
+ * pointValue factor converts price units to account-currency dollars
+ * (1 for crypto, varies for futures).
+ *
+ * Pine docs (strategy() declaration): `margin_long` / `margin_short` is
+ * the percentage of notional held as collateral. 100 = no leverage, 20 =
+ * 5× leverage, etc.
+ */
+export declare function computeRequiredMargin(qty: number, price: number, marginPct: number, pointValue: number): number;
+/**
+ * Account equity computed AS IF the marketprice were `atPrice` — used to
+ * check what equity would be at a hypothetical intra-bar price (e.g. the
+ * bar's adverse extreme for a margin-call check).
+ *
+ *   equity_at_price = initial_capital + netprofit + unrealizedPnL_at_price
+ *
+ * The mark-to-market is computed against EVERY open trade's entry price.
+ */
+export declare function computeEquityAtPrice(context: any, atPrice: number): number;
+/**
+ * Total margin currently held by all open positions, valued at `atPrice`.
+ * Per-position margin uses `margin_long` for longs and `margin_short` for
+ * shorts (Pine semantic — see strategy() declaration).
+ */
+export declare function computeHeldMargin(context: any, atPrice: number): number;
 /**
  * Calculate order quantity based on strategy configuration
  */
@@ -51,14 +103,31 @@ export declare function evaluateCatastrophicRiskHalt(strategy: StrategyState): v
  * @param price     fill price
  * @param time      fill time (ms)
  */
-export declare function openTrade(context: any, entryId: string, direction: number, qty: number, price: number, time: number): void;
+export declare function openTrade(context: any, entryId: string, direction: number, qty: number, price: number, time: number, entryComment?: string, isReversalOpen?: boolean): void;
 /**
  * Close partial or full position.
  *
  * FIFO accounting: closes oldest open trades first. Splits a trade if the
  * close qty is smaller than the trade's remaining qty.
  */
-export declare function closePartialPosition(context: any, qtyToClose: number, exitPrice: number, exitTime: number): void;
+export interface CloseInfo {
+    /** Which exit leg triggered ('profit'/'loss'/'trailing'), null otherwise. */
+    triggerKind?: 'profit' | 'loss' | 'trailing' | null;
+    /** Exit order's id, set onto the closed trade as trade.exit_id. */
+    exitId?: string;
+    /** Resolved exit comment (the matching comment_profit/loss/trailing). */
+    exitComment?: string;
+    /**
+     * True when this close is part of a single REVERSAL order that will
+     * also open a new trade in the opposite direction. Affects
+     * `cash_per_order` commission: TV charges the flat fee ONCE per order
+     * placement, attributed to the new entry — the implicit close leg of
+     * the reversal does NOT incur a second flat charge. Per-leg types
+     * (percent, cash_per_contract) are unaffected by this flag.
+     */
+    isImplicitReversal?: boolean;
+}
+export declare function closePartialPosition(context: any, qtyToClose: number, exitPrice: number, exitTime: number, closeInfo?: CloseInfo): void;
 /**
  * FIFO close of `qtyToClose` contracts from open trades, optionally filtered
  * by `fromEntry` — when set, only trades whose `entry_id === fromEntry` are
@@ -67,7 +136,7 @@ export declare function closePartialPosition(context: any, qtyToClose: number, e
  * Wraps `closePartialPosition` by temporarily reorganizing `opentrades` so
  * the matching trades sit at the head of the FIFO queue.
  */
-export declare function closeMatching(context: any, fromEntry: string | undefined, qtyToClose: number, exitPrice: number, exitTime: number): void;
+export declare function closeMatching(context: any, fromEntry: string | undefined, qtyToClose: number, exitPrice: number, exitTime: number, closeInfo?: CloseInfo): void;
 /**
  * Process exit-category orders each bar (after entry-order fills, before the
  * user script runs). Handles:
@@ -78,6 +147,29 @@ export declare function closeMatching(context: any, fromEntry: string | undefine
  *     peak (trade.trail_peak) is updated each bar even when not triggered.
  */
 export declare function processExitOrders(context: any): void;
+/**
+ * Margin-call check (TV broker emulator). After all entries and user-defined
+ * exits have processed for the bar, check whether the bar's INTRA-BAR
+ * adverse movement (low for longs, high for shorts) would have pushed
+ * account equity below required maintenance margin. If yes, FORCE LIQUIDATE
+ * all open positions at the bar's adverse extreme with exit_id="Margin call".
+ *
+ * The exit price is the bar's adverse extreme itself, NOT the theoretical
+ * threshold where equity would exactly equal required margin. This is the
+ * pessimistic broker model — the trader is assumed to be liquidated at
+ * the worst intra-bar price, since intra-bar tick order is unknown.
+ *
+ * Skipped entirely when the position's `margin_pct >= 100` (no leverage)
+ * or when there are no open positions.
+ */
+export declare function processMarginCall(context: any): void;
+/**
+ * End-of-bar finalize: refresh equity at CLOSE and latch
+ * `strategy.max_drawdown` / `strategy.max_runup` using the bar's H/L. Runs
+ * UNCONDITIONALLY once per bar (after entry+exit fills are done), regardless
+ * of whether the strategy uses exit orders.
+ */
+export declare function finalizeStrategyBar(context: any): void;
 /**
  * Initialize strategy state
  */