@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/dts/widget/history/historyDataUtils.d.ts

@@ -0,0 +1,82 @@
+import type { FinalityMode } from "../../lib/adapters";
+import type { Timeframe } from "../../lib/types/adapter";
+import type { OHLCVBar } from "../../lib/types/ohlcv";
+/**
+ * Options controlling how new bars override existing bars during merge.
+ *
+ * - `immutable`:              Never overwrite an existing bar (append-only for new timestamps).
+ * - `near-now-provisional`:   Bars within `provisionalWindowMs` of `nowMs` may be overwritten;
+ *                             older bars are treated as immutable.
+ * - `historically-correctable`: Bars within `correctionLookbackMs` of `nowMs` may be overwritten;
+ *                             bars older than the lookback are treated as immutable.
+ *
+ * When `finalityMode` is omitted the legacy behaviour (always overwrite) is preserved.
+ */
+export interface FinalityMergeOptions {
+    readonly finalityMode: FinalityMode;
+    /** Wall-clock "now" in epoch milliseconds. Defaults to Date.now() when omitted. */
+    readonly nowMs?: number;
+    /**
+     * Window (ms) around `nowMs` inside which `near-now-provisional` bars may be
+     * overwritten. Defaults to one timeframe bar width (caller should pass
+     * `resolveTimeframeMs(timeframe)` or similar).
+     */
+    readonly provisionalWindowMs?: number;
+    /**
+     * Lookback (ms) from `nowMs` inside which `historically-correctable` bars may be
+     * overwritten. Maps directly to `SourceSemanticsDescriptor.correctionLookbackMs`.
+     * When 0 or undefined, correction mode behaves like immutable for historical bars.
+     */
+    readonly correctionLookbackMs?: number;
+}
+export interface HistoryWindow {
+    startMs: number;
+    endMs: number;
+}
+export declare function resolveFetchWindow(timeframe: Timeframe): {
+    from: Date;
+    to: Date;
+};
+/**
+ * Screen-first window for Phase 1 initial fetch.
+ * Returns a window clipped to `screenBars` latest bars, but never
+ * exceeding the full `resolveFetchWindow`. This keeps the blocking
+ * initial load proportional to screen density per timeframe.
+ */
+export declare function resolveInitialFetchWindow(timeframe: Timeframe): {
+    from: Date;
+    to: Date;
+};
+export declare function resolveTimeframeMs(timeframe: Timeframe): number;
+export declare function computeLoadedHistoryWindow(bars: readonly OHLCVBar[]): HistoryWindow | null;
+export declare function resolveRetentionWindow(visibleDomain: readonly [Date, Date], timeframe: Timeframe): HistoryWindow;
+export declare function trimBarsToRetentionWindow(bars: readonly OHLCVBar[], visibleDomain: readonly [Date, Date] | null, timeframe: Timeframe): readonly OHLCVBar[];
+export declare function mergeBarPagesByDate(previousBars: readonly OHLCVBar[], nextBars: readonly OHLCVBar[]): readonly OHLCVBar[];
+export declare function mergeBarsByDate(previousBars: readonly OHLCVBar[], nextBar: OHLCVBar): readonly OHLCVBar[];
+/**
+ * Finality-aware variant of `mergeBarPagesByDate`.
+ *
+ * When `opts` is provided each incoming bar is only allowed to overwrite an
+ * existing bar when `isMutableBar` returns true for that bar's timestamp.
+ * Bars with new timestamps are always inserted regardless of finality.
+ */
+export declare function mergeBarPagesByDateWithFinality(previousBars: readonly OHLCVBar[], nextBars: readonly OHLCVBar[], opts: FinalityMergeOptions): readonly OHLCVBar[];
+/**
+ * Finality-aware variant of `mergeBarsByDate`.
+ *
+ * Rules:
+ *  - New timestamp → always insert.
+ *  - Existing timestamp + mutable → overwrite (same as legacy behaviour).
+ *  - Existing timestamp + immutable → keep existing bar, discard incoming.
+ */
+/**
+ * Filter `incomingBars` so that bars whose timestamps already exist in
+ * `residentBars` are kept only when they fall within the mutable window.
+ *
+ * Use this BEFORE passing bars to `HistoryChunkStore.prepend / append` when
+ * you want finality-aware merge without changing the chunkStore internals.
+ *
+ * Bars with entirely new timestamps pass through unconditionally.
+ */
+export declare function filterBarsForFinalityMerge(incomingBars: readonly OHLCVBar[], residentBars: readonly OHLCVBar[], opts: FinalityMergeOptions): readonly OHLCVBar[];
+export declare function mergeBarsByDateWithFinality(previousBars: readonly OHLCVBar[], nextBar: OHLCVBar, opts: FinalityMergeOptions): readonly OHLCVBar[];

package/dist/dts/widget/history/historyWindowPlanner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * historyWindowPlanner.ts
+ *
+ * Resident 3x window planner for VNInvestCharts history management.
+ *
+ * Computes the resident target window (3x visible span) and plans only the
+ * missing segments that need to be fetched, preventing request storms when
+ * data is already loaded.
+ */
+import type { ResidentWindow } from "./chunkStore";
+import type { GapReason, SourceSemanticsDescriptor } from "../../lib/adapters";
+import type { ExchangeCalendar } from "../../lib/calendars";
+export type { ResidentWindow };
+export interface VisibleWindow {
+    /** Inclusive start of visible domain, ms since epoch */
+    startMs: number;
+    /** Inclusive end of visible domain, ms since epoch */
+    endMs: number;
+}
+export interface MissingSegment {
+    /** Which side of the loaded range is missing */
+    side: "left" | "right";
+    /** Start of missing range, ms since epoch (undefined = fetch from beginning) */
+    from?: number;
+    /** End of missing range, ms since epoch (undefined = fetch to now) */
+    to?: number;
+    /** Why the gap exists, so the scheduler can avoid enqueueing non-fetchable gaps. */
+    reason?: GapReason;
+}
+export interface PrioritizedMissingSegment extends MissingSegment {
+    /** Distance from the nearest viewport edge; lower values should be fetched first. */
+    distance: number;
+}
+/**
+ * Resolves the base resident retention factor from visible density and the
+ * source-class matrix. Session-based sources keep a slightly wider buffer,
+ * while window-hint and finite sources trim more aggressively.
+ */
+export declare function resolveResidentRetentionFactor(visibleBarCount?: number, sourceSemantics?: SourceSemanticsDescriptor): number;
+/**
+ * Computes the resident target window as 3x the visible span:
+ * [visibleStart - 1xSpan, visibleEnd + 1xSpan]
+ *
+ * Uses `minSpanMs` as the floor for the visible span (one bar width).
+ * Ensures the resident window is always at least 3× the minimum span even
+ * when the visible window is very narrow. The resident factor is resolved from
+ * visible density, source-class semantics, and an optional runtime override
+ * from backpressure logic.
+ *
+ * When `liveEdgeMs` is provided, `endMs` is clamped so the resident window
+ * never extends beyond the last known data timestamp. This prevents fetching
+ * data for future time ranges (which most APIs reject with 400 errors).
+ *
+ * CRITICAL FIX: Do NOT clamp endMs at liveEdgeMs — this prevents forward
+ * backfill from detecting gaps between last loaded bar and current date.
+ * The caller should handle Date.now() capping if needed.
+ */
+export declare function computeResidentTarget(visible: VisibleWindow, minSpanMs?: number, visibleBarCount?: number, sourceSemantics?: SourceSemanticsDescriptor, retentionFactorOverride?: number, liveEdgeMs?: number): ResidentWindow;
+/**
+ * Computes which segments of the resident target are not covered by the
+ * loaded window.
+ *
+ * Rules:
+ * - If `loaded` covers the full `resident` range: returns empty array.
+ * - If `loaded` starts after `resident.startMs`: returns a left-segment.
+ * - If `loaded` ends before `resident.endMs`: returns a right-segment.
+ * - Both can be returned simultaneously (initial empty state, large pan).
+ * - When loaded is null/empty (no data yet): returns both sides.
+ */
+export declare function computeMissingSegments(resident: ResidentWindow, loaded: ResidentWindow | null, sourceSemantics?: SourceSemanticsDescriptor, calendar?: ExchangeCalendar): readonly MissingSegment[];
+/**
+ * Orders fetchable missing segments so the nearest resident gap to the
+ * viewport is scheduled first. Ties prefer the left edge for deterministic
+ * execution when both sides are equally close.
+ */
+export declare function prioritizeMissingSegments(segments: readonly MissingSegment[], visible: VisibleWindow): PrioritizedMissingSegment[];
+/**
+ * Computes a hysteresis-aware trim window.
+ *
+ * Returns a trim window slightly wider than the resident target to avoid
+ * thrashing: bars are only evicted when they fall outside the trim window,
+ * which is `hysteresisRatio × span` wider on each side than the resident
+ * target.
+ *
+ * Default `hysteresisRatio = 0.5` means bars within 0.5× span outside the
+ * resident target are retained. This prevents evicting bars that would be
+ * needed again if the user pans back slightly.
+ */
+export declare function computeTrimWindow(resident: ResidentWindow, hysteresisRatio?: number): ResidentWindow;

package/dist/dts/widget/history/inflightController.d.ts

@@ -0,0 +1,15 @@
+export interface AdaptiveInflightControllerState {
+    maxInflight: number;
+    debounceMs: number;
+    chunkBars: number;
+    retentionFactor: number;
+    highFrameTimeCount: number;
+    lowFrameTimeCount: number;
+    highOverfetchCount: number;
+}
+export interface AdaptiveInflightTelemetry {
+    frameP95Ms: number;
+    queueDepth: number;
+    overfetchRatio: number;
+}
+export declare function computeAdaptiveInflightControllerState(current: AdaptiveInflightControllerState, telemetry: AdaptiveInflightTelemetry, baseRetentionFactor: number): AdaptiveInflightControllerState;

package/dist/dts/widget/history/requestCoalescing.d.ts

@@ -0,0 +1,10 @@
+import type { MissingSegment } from "./historyWindowPlanner";
+export interface InflightRange {
+    side: MissingSegment["side"];
+    from: number;
+    to: number;
+}
+export declare function toInflightRequestKey(segment: MissingSegment): string;
+export declare function parseInflightRequestKey(key: string): InflightRange | null;
+export declare function isSegmentCoalescedByInflight(segment: MissingSegment, inflightKeys: Iterable<string>): boolean;
+export declare function coalesceAndAdjustSegment(segment: MissingSegment, inflightKeys: Iterable<string>): MissingSegment | null;

package/dist/dts/widget/history/sessionGuards.d.ts

@@ -0,0 +1,3 @@
+import type { SourceSemanticsDescriptor, Timeframe } from "../../lib/adapters";
+export declare function buildSourceRevisionKey(adapterLabel: string, sourceSemantics: SourceSemanticsDescriptor | null): string;
+export declare function buildHistorySessionRequestKey(symbol: string, timeframe: Timeframe, sourceRevisionKey: string): string;

package/dist/dts/widget/history/singleWriterLane.d.ts

@@ -0,0 +1,4 @@
+export interface SingleWriterLane {
+    run<T>(writer: () => T | Promise<T>): Promise<T>;
+}
+export declare function createSingleWriterLane(): SingleWriterLane;

package/dist/dts/widget/history/useExternalBarsNormalization.d.ts

@@ -0,0 +1,5 @@
+import { type ExternalBarsNormalizationResult } from "./externalBarsNormalization";
+export declare function useExternalBarsNormalization(data: readonly unknown[] | undefined | null, enabled: boolean, useWorker?: boolean): {
+    result: ExternalBarsNormalizationResult;
+    pending: boolean;
+};

package/dist/dts/widget/hooks/ShortcutManager.d.ts

@@ -0,0 +1,65 @@
+export interface ShortcutAction {
+    id: string;
+    keys: string[];
+    description: string;
+    handler: () => void;
+    preventDefault?: boolean;
+    global?: boolean;
+}
+/**
+ * Register a keyboard shortcut
+ * @param action Shortcut action to register
+ * @returns Unregister function
+ */
+export declare function registerShortcut(action: ShortcutAction): () => void;
+/**
+ * Unregister a keyboard shortcut by ID
+ * @param id Shortcut ID to unregister
+ */
+export declare function unregisterShortcut(id: string): void;
+/**
+ * Hook to register shortcuts for a component's lifecycle
+ * @param shortcuts Array of shortcut actions to register
+ */
+export declare function useShortcuts(shortcuts: ShortcutAction[]): void;
+/**
+ * Global keyboard event handler
+ * Should be called once at app root level
+ */
+export declare function useGlobalShortcutHandler(): void;
+/**
+ * Predefined shortcut categories for the UnifiedHeader
+ */
+export declare const HeaderShortcuts: {
+    symbolSearch: (onOpen: () => void) => ShortcutAction;
+    symbolSearchModal: (onOpen: () => void) => ShortcutAction;
+    timeframeNext: (onCycle: () => void) => ShortcutAction;
+    timeframePrev: (onCycle: () => void) => ShortcutAction;
+    chartTypeCycle: (onCycle: () => void) => ShortcutAction;
+    toggleSyncVisibleRange: (onToggle: () => void) => ShortcutAction;
+    toggleSyncCrosshair: (onToggle: () => void) => ShortcutAction;
+    openSystemMenu: (onOpen: () => void) => ShortcutAction;
+    toggleDrawingTools: (onToggle: () => void) => ShortcutAction;
+    dockToggle: (onToggle: () => void) => ShortcutAction;
+};
+export declare function initializeGlobalShortcutHandler(): void;
+declare const _default: {
+    registerShortcut: typeof registerShortcut;
+    unregisterShortcut: typeof unregisterShortcut;
+    useShortcuts: typeof useShortcuts;
+    useGlobalShortcutHandler: typeof useGlobalShortcutHandler;
+    HeaderShortcuts: {
+        symbolSearch: (onOpen: () => void) => ShortcutAction;
+        symbolSearchModal: (onOpen: () => void) => ShortcutAction;
+        timeframeNext: (onCycle: () => void) => ShortcutAction;
+        timeframePrev: (onCycle: () => void) => ShortcutAction;
+        chartTypeCycle: (onCycle: () => void) => ShortcutAction;
+        toggleSyncVisibleRange: (onToggle: () => void) => ShortcutAction;
+        toggleSyncCrosshair: (onToggle: () => void) => ShortcutAction;
+        openSystemMenu: (onOpen: () => void) => ShortcutAction;
+        toggleDrawingTools: (onToggle: () => void) => ShortcutAction;
+        dockToggle: (onToggle: () => void) => ShortcutAction;
+    };
+    initializeGlobalShortcutHandler: typeof initializeGlobalShortcutHandler;
+};
+export default _default;

package/dist/dts/widget/hooks/overlays/PaneHeaderWrapper.d.ts

@@ -0,0 +1,11 @@
+import React, { type CSSProperties } from "react";
+import type { SeriesConfig, SeriesTypeId, PaneDescriptor } from "../../../lib/core/types/pane-descriptor";
+export declare function PaneHeaderWithPickerWrapper({ pane, onToggleVisible, onRemove, onQuickAddSeries, onQuickRemoveSeries, style, children, }: {
+    pane: PaneDescriptor;
+    onToggleVisible: () => void;
+    onRemove: () => void;
+    onQuickAddSeries?: (series: SeriesConfig) => void;
+    onQuickRemoveSeries?: (seriesType: SeriesTypeId) => void;
+    style?: CSSProperties;
+    children?: React.ReactNode;
+}): React.JSX.Element;

package/dist/dts/widget/hooks/overlays/overlayHelpers.d.ts

@@ -0,0 +1,60 @@
+import type { EnrichedDatum } from "../../../lib/core/calculators/types";
+import type { SeriesConfig } from "../../../lib/core/types/pane-descriptor";
+import type { WidgetPaneRuntimeSnapshot } from "../../utils/widgetHelpers";
+export interface LegendSeriesValue {
+    text: string;
+    color?: string;
+}
+export declare function buildLegendSeriesValue(datum: EnrichedDatum, series: SeriesConfig | undefined): LegendSeriesValue | undefined;
+export declare function resolveLeftAxisWidth(axisBounds: WidgetPaneRuntimeSnapshot["axisBounds"] | undefined): number;
+/**
+ * Global left-gutter offset for pane headers (VOL_FIX).
+ * Engine `PaneLayoutEngine.layout` shifts `plotBounds` globally as soon as ANY
+ * pane owns a left slot, but `axisBounds.left` stays per-pane — so a Vol pane
+ * without a left series reports width 0 while its plot area is still pushed
+ * right by the global gutter. Headers must therefore use the max left width
+ * across ALL visible pane snapshots, matching the plot shift; otherwise the
+ * Vol header sits inside the left-axis zone and slides under the docked
+ * drawing toolbar (left:0, z-60 above pane wraps z-40).
+ */
+/**
+ * Gap between a pane header (label/chips/actions) and the Y-axis gutters.
+ * Headers must sit just OUTSIDE the axes — hugging them with a small uniform
+ * clearance — never floating deep inside the plot area.
+ */
+export declare const PANE_HEADER_AXIS_GAP_PX = 4;
+/**
+ * Horizontal room the docked (locked) drawing rail reserves inside the chart
+ * column (`VNInvestCharts` chart-column `marginLeft`). Must stay in sync with
+ * that margin — the pane-chrome overlay layer is anchored at the OUTER
+ * container origin while the engine measures the INNER (margined) box.
+ */
+export declare const DOCKED_TOOLBAR_OFFSET_PX = 44;
+/**
+ * Grip-strip width of the auto-hide drawing rail
+ * (`.vnsc-drawing-toolbar-shell`, toolbar.css). The rail overlays content on
+ * hover — only this strip needs permanent clearance, not the full 44px.
+ */
+export declare const RAIL_GRIP_PX = 10;
+/**
+ * True when a left Y axis is actually rendered. Live snapshots win (the
+ * engine's reconcileEmptyLeftAxis can drop an empty gutter); pane
+ * descriptors are the pre-first-paint fallback.
+ */
+export declare function resolveHasLeftAxis(snapshots: Iterable<WidgetPaneRuntimeSnapshot | undefined> | undefined, panes: readonly {
+    series?: readonly {
+        visible?: boolean;
+        yAxis?: string;
+    }[];
+}[] | undefined): boolean;
+/**
+ * Single source of truth for the chart-column left reserve. Mirrors the
+ * `marginLeft` on the VNInvestCharts chart column: full 44px only while the
+ * rail is locked (docked); zero with no rail. While auto-hiding, the 10px
+ * grip strip needs clearance ONLY when no left axis exists — with a 48px
+ * left gutter (compare/RSI mode) the grip overlays the gutter itself, so the
+ * frame stays perfectly symmetric (48 left == 48 right). Both the column
+ * margin and the outer-layer `dockOffset` must use this.
+ */
+export declare function resolveRailReservePx(showToolbar: boolean | undefined, toolbarLocked: boolean | undefined, hasLeftAxis?: boolean): number;
+export declare function resolveGlobalLeftAxisWidth(snapshots: Iterable<WidgetPaneRuntimeSnapshot | undefined> | undefined): number;

package/dist/dts/widget/hooks/overlays/useDrawingDockNode.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+import type { DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+export interface DrawingDockNodeDeps {
+    showDrawingDock?: boolean;
+    drawingWorkspace: DrawingWorkspaceController | null | undefined;
+    renderDrawingDock?: any;
+    t: (key: string) => string;
+    dockPropertiesContent: React.ReactNode;
+    dockObjectsContent: React.ReactNode;
+    dockTemplatesContent: React.ReactNode;
+    /** S3 (P5 parity F2): workspace bridge force node (host tab owns visibility,
+        không qua cell dock open-state). Default false (single giữ nguyên). */
+    forceOpen?: boolean;
+}
+export declare function useDrawingDockNode(deps: DrawingDockNodeDeps): React.ReactNode;

package/dist/dts/widget/hooks/overlays/useLegendChrome.d.ts

@@ -0,0 +1,36 @@
+import React from "react";
+import type { SeriesTypeId } from "../../../lib/core/types/pane-descriptor";
+import type { PaneDescriptor } from "../../../lib/core";
+import type { EnrichedDatum } from "../../../lib/core/calculators/types";
+export interface LegendChrome {
+    icons: {
+        eye: React.ReactNode;
+        eyeOff: React.ReactNode;
+        edit: React.ReactNode;
+        remove: React.ReactNode;
+    };
+    labels: {
+        showIndicatorTitle: string;
+        hideIndicatorTitle: string;
+        removeIndicatorTitle: string;
+        editIndicatorTitle: string;
+        showIndicatorAriaLabel: (seriesLabel: string) => string;
+        hideIndicatorAriaLabel: (seriesLabel: string) => string;
+        removeIndicatorAriaLabel: (seriesLabel: string) => string;
+        editIndicatorAriaLabel: (seriesLabel: string) => string;
+    };
+}
+export declare function useLegendChrome(t: (key: string) => string): LegendChrome;
+export interface CompareLegendNodeDeps {
+    compareLegendSlot: "embedded" | "statusline";
+    visiblePanes: readonly PaneDescriptor[];
+    legendPanes?: readonly PaneDescriptor[];
+    localizePane: (pane: PaneDescriptor) => PaneDescriptor;
+    legendSeriesSuffix?: (paneId: string, seriesIndex: number) => string | undefined;
+    handlePaneToggleSeries: (paneId: string, seriesType: SeriesTypeId, seriesIndex?: number) => void;
+    handlePaneRemoveSeries: (paneId: string, seriesType: SeriesTypeId, seriesIndex?: number) => void;
+    handlePaneEditSeries: (paneId: string) => void;
+    legendChrome: LegendChrome;
+    hoveredDatum?: EnrichedDatum | null;
+}
+export declare function useCompareLegendNode(deps: CompareLegendNodeDeps): (paneId: string) => React.ReactNode;

package/dist/dts/widget/hooks/overlays/useMultiSelectActions.d.ts

@@ -0,0 +1,22 @@
+import type { DrawingObject } from "@vninvestcharts/engine-drawing";
+import type { DrawingWorkspaceController } from "@vninvestcharts/engine-react";
+export interface UseMultiSelectActionsProps {
+    drawingWorkspace: DrawingWorkspaceController | null;
+    selectedIds: readonly string[];
+    drawings: readonly DrawingObject[];
+    t: (key: string) => string;
+}
+export interface UseMultiSelectActionsReturn {
+    selectedCount: number;
+    allLocked: boolean;
+    allHidden: boolean;
+    hasUnlocked: boolean;
+    isAllGrouped: boolean;
+    handleDeleteAll: () => void;
+    handleLockAll: () => void;
+    handleSetVisibleAll: (visible: boolean) => void;
+    handleBatchColor: (color: string) => void;
+    handleCloneAll: () => void;
+    handleGroupToggleAll: () => void;
+}
+export declare function useMultiSelectActions({ drawingWorkspace, selectedIds, drawings, }: UseMultiSelectActionsProps): UseMultiSelectActionsReturn;

package/dist/dts/widget/hooks/overlays/useSidebarResize.d.ts

@@ -0,0 +1,13 @@
+export declare const SIDEBAR_WIDTH_KEY = "vnsc_dock_width";
+export declare const DOCK_DEFAULT_WIDTH = 300;
+/**
+ * Viewport-aware cap: the dock (flex-shrink:0) must never push its own
+ * strip off-screen on narrow windows. Falls back to MAX_WIDTH without DOM.
+ */
+export declare function maxAllowedWidth(): number;
+export declare function useSidebarResize(initialWidth?: number): {
+    sidebarWidth: number;
+    isResizingSidebar: boolean;
+    handleSidebarPointerDown: (e: React.PointerEvent<HTMLDivElement>) => void;
+    setSidebarWidth: import("react").Dispatch<import("react").SetStateAction<number>>;
+};

package/dist/dts/widget/hooks/resolveEntitlement.d.ts

@@ -0,0 +1,73 @@
+/**
+ * CS-2 — the single Entitlement Decision Point.
+ *
+ * One pure function answers "what may this user do" from two independent
+ * channels: an offline signed license and a server answer. Neither channel can
+ * remove the other's grants; the output names every source so support can audit
+ * "why does this user have Pro?".
+ *
+ * SCOPE NOTE — HISTORY, READ THIS BEFORE "FIXING" IT. This module shipped first as a
+ * pure function with no callers (CS-2), then got wired (CS-3). The note that used to
+ * sit here said "deliberately NOT wired into the context yet" — that became **false**
+ * the moment CS-3 landed, and a stale "this is dead code" comment is worse than no
+ * comment: it invites deleting the single entitlement decision point.
+ *
+ * Verified live call sites (2026-10-08):
+ *   src/widget/contexts/SaaSFeatureContext.tsx:601  server answered  -> 'live'
+ *   src/widget/contexts/SaaSFeatureContext.tsx:670  no server, no net -> 'none'
+ *   src/widget/contexts/SaaSFeatureContext.tsx:682  license only      -> 'none'
+ *
+ * What is still NOT wired: the `server-cache` source and `graceMs`. All three call
+ * sites pass `live` or `none`, so the freshness arithmetic below has no production
+ * caller yet. Recorded in 13.02-technical-debt-register.md rather than left as a
+ * comment here, so it can be closed by a measured change.
+ *
+ * Client-side checks are a speed bump, not a boundary. Knowing this does not
+ * weaken it; pretending otherwise is how teams burn weeks on obfuscation.
+ */
+import { type PatTier } from '@vninvestcharts/engine-core';
+export type EntitlementSource = "license" | "server" | "server-cache" | "host" | "none";
+/**
+ * Where the server object came from. A boolean cannot express "the server
+ * answered just now" versus "replaying a three-day-old answer", so a previous
+ * draft's `graceExpired` flag contradicted its own truth table twice. Provenance
+ * plus freshness, together, or the criterion is unimplementable.
+ */
+export type DataSourceKind = "live" | "cache" | "none";
+export interface ResolveEntitlementInput {
+    license: {
+        tier: PatTier;
+        expiresAt: number | null;
+        serial?: string;
+    } | null;
+    server: {
+        plan: PatTier;
+    } | null;
+    dataSource: DataSourceKind;
+    /** Epoch seconds the cached answer was fetched. Required iff dataSource==="cache". */
+    cachedAt: number | null;
+    /** Cached answers older than this are ignored. Caller-owned; not in the resolver. */
+    graceMs: number;
+    now: number;
+}
+export interface ResolvedEntitlement {
+    /** Union with attribution: max(licenseTier, serverTier). Nobody revokes anybody. */
+    renderTier: PatTier;
+    /**
+     * Server data reachable and usable. A SINGLE boolean on purpose: an earlier
+     * draft's five-key object had no consumer and duplicated SaaSFeatureFlags.
+     * Requires only a valid token at ANY plan — gating this on pro would take
+     * chart data away from free users, which is a regression, not a gate.
+     */
+    dataUsable: boolean;
+    /** Every grant that contributed, so "why Pro?" is answerable. Never empty. */
+    sources: EntitlementSource[];
+    /**
+     * Offline banner reason. `plan-limited` means the token is valid but the plan
+     * is low — never "rejected", which would lie about a valid token.
+     */
+    degradedReason: "no-pat" | "plan-limited" | "offline" | "grace-expired" | null;
+    /** Epoch seconds, or null when nothing grants. */
+    expiresAt: number | null;
+}
+export declare function resolveEntitlement(input: ResolveEntitlementInput): ResolvedEntitlement;

package/dist/dts/widget/hooks/useBottomPanelBehavior.d.ts

@@ -0,0 +1,38 @@
+/** Default bottom-panel height (must match `--vnsc-bottom-panel-height` fallback in CSS). */
+export declare const BOTTOM_PANEL_HEIGHT_PX = 260;
+/** Approximate single-chart footer height used for chart-area estimation. */
+export declare const SINGLE_FOOTER_HEIGHT_PX = 48;
+/** Collapse indicator subpanes when the chart area drops below this height. */
+export declare const COLLAPSE_CHART_AREA_PX = 300;
+export interface SingleChartPanelCollapseInput {
+    panelOpen: boolean;
+    chartAreaHeight: number;
+    collapseBelowPx?: number;
+    visiblePaneIds: readonly string[];
+    onTogglePaneVisible: (paneId: string) => void;
+}
+/**
+ * UI-D1: auto-collapse indicator subpanes (single chart) while the bottom
+ * panel is open and the chart area is squeezed. Restores exactly the panes
+ * this hook hid (panes the user re-shows mid-collapse are left alone).
+ */
+export declare function useSingleChartPanelCollapse({ panelOpen, chartAreaHeight, collapseBelowPx, visiblePaneIds, onTogglePaneVisible, }: SingleChartPanelCollapseInput): void;
+export type MultiBottomTab = "strategy_tester" | "pine_editor" | "paper_trade" | null;
+export interface MultiChartPanelFocusInput {
+    activeTab: MultiBottomTab;
+    activeChartId: string | null;
+}
+export interface MultiChartPanelFocus {
+    /** Chart id that should render maximized, or null for grid. */
+    maximizedChartId: string | null;
+    /** Manual Solo/Grid override (marks intent so auto-focus stops fighting the user). */
+    setMaximizedChartId: (id: string | null) => void;
+    /** Toggle between Solo (active chart) and grid. */
+    toggleSolo: () => void;
+}
+/**
+ * UI-D2: focus-first behavior (multi chart). Opening Pine Editor or Strategy
+ * Tester auto-maximizes the active chart; closing the tab restores the grid.
+ * Paper Trading keeps the grid (flexible-height panel instead).
+ */
+export declare function useMultiChartPanelFocus({ activeTab, activeChartId, }: MultiChartPanelFocusInput): MultiChartPanelFocus;

package/dist/dts/widget/hooks/useBottomPanelHeight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * useBottomPanelHeight — user-resizable bottom-panel height (drag splitter).
+ *
+ * Single persisted preference (localStorage) shared by the multi-chart
+ * BottomPanelHost and the single-chart forkBottomPanel. JS clamp [180, 900];
+ * the visual 60% cap stays in CSS (maxHeight). Default reuses
+ * BOTTOM_PANEL_HEIGHT_PX so hook/CSS never drift.
+ *
+ * Drag perf (grid-splitter parity): the splitter writes preview height
+ * straight to the panel container DOM during the drag (no React state, no
+ * storage I/O per move) and commits ONCE on pointer-up via `resizeTo`.
+ * Hence persistence lives in the explicit commit paths below — NOT in a
+ * per-change effect (that re-rendered the whole multi grid + localStorage
+ * write on every pointermove, which is what made the drag feel sluggish).
+ */
+export declare const BOTTOM_PANEL_MIN_PX = 180;
+export declare const BOTTOM_PANEL_MAX_PX = 900;
+export declare const BOTTOM_PANEL_NUDGE_PX = 20;
+/**
+ * Per-tab sensible heights (measured content needs): empty paper panels fit
+ * ~200px, strategy needs room for stats + ~5 table rows, pine needs editor
+ * space. Used ONLY while untouched (no persisted manual height) — user drag
+ * always wins (persisted). Null/unknown tabs fall back to global default.
+ */
+export declare const BOTTOM_PANEL_TAB_DEFAULTS: Record<string, number>;
+export declare function defaultBottomPanelHeightForTab(tab: string | null | undefined): number;
+export declare function clampBottomPanelHeight(px: number): number;
+export interface BottomPanelHeightApi {
+    heightPx: number;
+    /** Grow when deltaUpPx > 0 (drag up / ArrowUp). Clamped + persisted. */
+    resizeBy: (deltaUpPx: number) => void;
+    /** Absolute commit (drag release). Clamped + persisted. Single render. */
+    resizeTo: (px: number) => void;
+    /** Keyboard step: dir +1 taller, -1 shorter. */
+    nudge: (dir: 1 | -1) => void;
+    /** Double-click reset to default. */
+    reset: () => void;
+}
+export declare function useBottomPanelHeight(defaultHeightPx?: number): BottomPanelHeightApi;

package/dist/dts/widget/hooks/useCanvasTheme.d.ts

@@ -0,0 +1,24 @@
+export interface CanvasThemeConfig {
+    mode: "dark" | "light";
+    colors: {
+        bullish: string;
+        bearish: string;
+        volume: string;
+        grid: string;
+        gridSubtle: string;
+        gridDash: string;
+        gridWidth: string;
+        crosshair: string;
+        selection: string;
+        background: string;
+        text: string;
+        textSecondary: string;
+        tooltipBg: string;
+        tooltipText: string;
+    };
+    isHighContrast: boolean;
+    presetName: string;
+}
+export declare function useCanvasTheme(rootRef: {
+    current: HTMLElement | null;
+}): CanvasThemeConfig;