@christtrade/depth 0.12.24 → 0.12.25

package/types/core/strategy-walkforward.d.ts

@@ -0,0 +1,91 @@
+import type { StrategyStats } from './strategy-runtime';
+export interface WalkForwardSpec {
+    /** How many out-of-sample segments to test. */
+    windows: number;
+    /**
+     * In-sample length as a multiple of out-of-sample length.
+     *
+     * 3 or 4 is conventional: enough history to optimise on, tested against a
+     * meaningful stretch of what followed. At 1 the optimiser sees as much data
+     * as it is judged on, which makes every window statistically thin.
+     */
+    isMultiple: number;
+    /**
+     * Anchored keeps the in-sample start fixed and lets it grow; rolling slides
+     * a fixed-width window.
+     *
+     * Neither is correct in general. Anchored uses more data and assumes the
+     * distant past still applies; rolling adapts to regime change and forgets.
+     * Which one flatters a strategy is itself a finding.
+     */
+    anchored: boolean;
+}
+export interface WalkForwardWindow {
+    index: number;
+    /** Bar indices, half-open: [from, to). */
+    isFrom: number;
+    isTo: number;
+    oosFrom: number;
+    oosTo: number;
+}
+export interface WalkForwardWindowResult {
+    window: WalkForwardWindow;
+    /** What the optimiser chose on the in-sample segment. */
+    params: Record<string, unknown>;
+    inSample: StrategyStats;
+    outOfSample: StrategyStats;
+}
+export interface ParameterStability {
+    param: string;
+    /** The value chosen in each window, in order. */
+    values: number[];
+    distinct: number;
+    /**
+     * Standard deviation over the mean. Scale-free, so a period and a percentage
+     * are comparable.
+     *
+     * Under ~0.15 the windows broadly agree. Over ~0.5 they do not, and a single
+     * "optimal" value quoted from the full-history sweep is a coincidence.
+     */
+    coefficientOfVariation: number;
+}
+/**
+ * Divides a series into overlapping optimise/test windows.
+ *
+ * Anchored keeps every in-sample segment starting at bar zero instead.
+ *
+ * Returns an empty array when the series cannot support the schedule. Refusing
+ * is the honest answer - a walk-forward over 40-bar windows produces numbers
+ * that look like analysis and are noise.
+ */
+export declare function planWalkForward(barCount: number, spec: WalkForwardSpec): WalkForwardWindow[];
+/**
+ * How much of the optimised edge survived on unseen data.
+ *
+ * Per-bar instead of total - anchored windows differ in length and an
+ * unweighted ratio would let the longest in-sample segment dominate.
+ *
+ * 1.0 means out-of-sample matched in-sample. Below ~0.5 is the usual warning
+ * line. Negative means the optimised parameters lost money on what followed,
+ * which is the most useful result a backtest can give you.
+ *
+ * Returns 0 when in-sample made nothing - there is no ratio to a zero
+ * denominator, and reporting Infinity as "infinitely efficient" would be absurd.
+ */
+export declare function walkForwardEfficiency(results: WalkForwardWindowResult[]): number;
+/**
+ * Whether the optimiser kept choosing the same thing.
+ *
+ * Only numeric parameters - the spread of a boolean or a string across windows
+ * has no meaningful coefficient.
+ */
+export declare function parameterStability(results: WalkForwardWindowResult[]): ParameterStability[];
+/**
+ * Picks the best row of a scored grid.
+ *
+ * `higherIsBetter` is false for drawdown-like objectives. Rows whose metric is
+ * not finite are skipped rather than winning: a profit factor of Infinity means
+ * a run with no losing trade, which on a two-trade in-sample window is noise
+ * dressed as perfection.
+ */
+export declare function pickBest<T>(rows: T[], metric: (row: T) => number | undefined, higherIsBetter?: boolean): T | null;

package/types/hooks/useChartData.d.ts

@@ -126,6 +126,8 @@ export interface ChartDataResult {
     seekHorizon: (horizon: bigint, triggerResample?: boolean, hotPath?: boolean, 
     /** Explicit navigation: bring the view along instead of leaving it behind. */
     recenter?: boolean) => void;
+    /** Frames a span of time. Does not move the playhead - see 'chart:goto-range'. */
+    gotoRange: (fromNs: bigint, toNs?: bigint, padding?: number) => void;
     applyHorizon: (horizon: bigint, triggerResample?: boolean, hotPath?: boolean) => void;
     scheduleResample: () => void;
     runIndicatorWorker: (trades: SerialTrade[], barNs: bigint) => void;

package/types/hooks/useChartSubscriptions.d.ts

@@ -45,6 +45,7 @@ export interface UseChartSubscriptionsParams {
     setPluginChartTypes: (types: ChartTypePlugin[]) => void;
     setChartSettings: (updater: ChartSettings | ((prev: ChartSettings) => ChartSettings)) => void;
     resetView: () => void;
+    gotoRange: (fromNs: bigint, toNs?: bigint, padding?: number) => void;
     buildChartTypeActiveCtx: () => ChartTypeActiveContext;
     pushDrawParams: () => void;
     runIndicatorWorker: (trades: SerialTrade[], barNs: bigint) => void;

package/types/interfaces/plugins/IChartPlugin.d.ts

@@ -13,7 +13,7 @@ import type { SerialTrade, PriceHistory } from '../../lib/types';
 import type { FootprintBar } from '../../lib/types/footprint';
 import type { BracketAmendment } from '../../lib/types/trading-types';
 import type { PlaceOrderRequest } from '../../lib/matchingEngine';
-export type PluginType = 'indicator' | 'drawing' | 'chart-type' | 'data-source' | 'extension';
+export type PluginType = 'indicator' | 'drawing' | 'chart-type' | 'data-source' | 'extension' | 'strategy';
 export type Permission = 'data:read' | 'data:write' | 'eventbus:emit' | 'eventbus:intercept' | 'ui:pane' | 'ui:panel' | 'ui:toolbar' | 'ui:context-menu' | 'render:overlay' | 'render:shader' | 'drawing:register' | 'chart-type:register' | 'theme:register' | 'audio' | 'network' | 'storage' | 'intercept' | 'execution:read' | 'execution:write';
 export interface ToolbarItem {
     id: string;