@kymoscope/sdk 0.2.0 → 0.4.0

package/dist/types/components/multiBandHover.d.ts

@@ -1,4 +1,11 @@
 import type { PointColumns } from '../lib/data/pointColumns';
+/**
+ * Sends the hovered X (or null) at most once per animation frame, the newest
+ * value winning. With no frame scheduler (no window: tests, node) it sends at once.
+ */
+export declare function createCursorEmitter(send: (x: number | null) => void, schedule?: ((cb: () => void) => void) | null): {
+    set(x: number | null): void;
+};
 /** X in data units under a cursor pixel, for the current view. */
 export declare function dataXAtPx(px: number, left: number, plotW: number, xmin: number, xmax: number): number;
 /**

package/dist/types/engine/alerts.d.ts

@@ -0,0 +1,56 @@
+import { type AlertTransition, type LiveBlock, type RuleTarget } from '../rules/evaluator';
+import { type RuleProblem } from '../rules/validate';
+import type { RuleDoc, Severity } from '../rules/types';
+/** A span on the charts from one rule episode (read-only; never stored in chart settings). t1 null: still open. */
+export interface ChartMark {
+    id: string;
+    ruleId: string;
+    ruleName: string;
+    severity: Severity;
+    targetId: string;
+    timeColumn: string;
+    t0: number;
+    t1: number | null;
+}
+export interface RuleStateInfo {
+    ruleId: string;
+    target: RuleTarget;
+    state: string;
+    missing?: string[];
+    since?: number;
+}
+export interface AlertsHost {
+    /** Targets now open, with their channel names. */
+    targets(): Array<RuleTarget & {
+        channels: string[];
+    }>;
+    maxRules(): number | null;
+    emit(t: AlertTransition): void;
+    limit(): void;
+    setMarks(marks: ChartMark[]): void;
+    setStates(s: RuleStateInfo[]): void;
+    /** DataSource.readColumns of a loaded dataset. */
+    readDataset(id: string, columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
+}
+export declare function createAlerts(host: AlertsHost): {
+    /** Replace the rule set (the host's whole list). Returns the problems of the refused rules. */
+    setRules(docs: RuleDoc[]): Array<RuleProblem & {
+        ruleId: string;
+    }>;
+    rules: () => RuleDoc[];
+    state: () => RuleStateInfo[];
+    /** Evaluate the rules over a loaded dataset from its first row (fresh evaluators: "Test on loaded data"). */
+    evaluate(datasetId: string, o: {
+        timeColumn: string;
+        ruleIds?: string[];
+    }): Promise<AlertTransition[]>;
+    /** Live: called by the live controller with the newly appended rows of a stream. */
+    pushLive(streamId: string, block: LiveBlock): void;
+    tickLive(streamId: string, t: number): void;
+    /** The channel names the rules bound on a stream use (what pushLive needs from the buffer). */
+    liveColumns(streamId: string): string[];
+    /** The host's targets or their channel sets changed (a dataset loaded, a stream's schema grew). */
+    sync: () => void;
+    clearMarks(targetId?: string): void;
+};
+export type EngineAlerts = ReturnType<typeof createAlerts>;

package/dist/types/engine/columns.d.ts

@@ -1,4 +1,5 @@
 import type { LoadedDataset } from '../types/loadedDataset';
+import { type HistoryPiece } from '../lib/data/historyDataSource';
 /** Columnar numeric data handed over by the host. */
 export interface ColumnsInput {
     name: string;
@@ -11,6 +12,11 @@ export interface ColumnsInput {
      * times a second, where the copy is most of the cost.
      */
     transfer?: boolean;
+    /** Bands to shade under columns (a reference's envelope, Historian phase 5): edges aligned with the columns' rows. */
+    bands?: Record<string, {
+        lo: ArrayLike<number>;
+        hi: ArrayLike<number>;
+    }>;
 }
 /**
  * Above this many rows host columns stay columnar (no row objects at all):
@@ -19,6 +25,8 @@ export interface ColumnsInput {
  * so laps and math channels see every row.
  */
 export declare const COLUMNAR_ROWS = 1000000;
+/** Rows kept from a columnar dataset for the row-based charts (scatter, histogram, …). */
+export declare const COLUMNAR_SAMPLE_ROWS = 12000;
 /** Build a dataset from host-provided numeric columns (each is copied once). */
 export declare function datasetFromColumns(id: string, input: ColumnsInput): LoadedDataset;
 /**
@@ -42,3 +50,11 @@ export declare function replaceColumns(ds: LoadedDataset, input: Record<string,
  * (cached), never on load or on each replaceColumns.
  */
 export declare function columnsText(ds: LoadedDataset): string;
+/** A Historian range handed to the engine (Historian phase 4): pieces from readHistoryRange and the channels' units. */
+export interface HistoryRangeView {
+    name: string;
+    pieces: HistoryPiece[];
+    units?: Record<string, string>;
+}
+/** A Historian range as a dataset: read through HistoryDataSource; its rows are a time-ordered sample. */
+export declare function historyDataset(id: string, view: HistoryRangeView): LoadedDataset;

package/dist/types/engine/createEngine.d.ts

@@ -13,6 +13,7 @@ import { type PanelChartSettings } from '../lib/panelChartSettings';
 import type { MathChannel, MathChannelPatch } from '../lib/mathChannels/types';
 import type { EvalResult } from '../lib/mathChannels/types';
 import type { LiveConnection, LiveStreamDescriptor, LiveStreamOptions, LocalLiveStream, StreamKeyProvider } from '../lib/live/types';
+import { type VideoSource } from '../lib/live/videoTrack';
 import type { ChannelChooser } from '../lib/importers/types';
 import type { RecordingKey } from '../lib/recordings/keys';
 import { DATASET_PALETTE } from '../lib/datasetColors';
@@ -23,12 +24,16 @@ import { type WorkbookFileOptions } from '../lib/workspaces/encrypted';
 import { canPickDirectory, isImportable, pickDirectoryEntries, type DirNode, type FolderEntry } from '../lib/folderTree';
 import { type ChartView, type MountOptions } from '../charts/runtime';
 import { type ChartWindow, type ChartWindowOptions } from '../charts/chartWindow';
-import { type ColumnsInput } from './columns';
+import { type ColumnsInput, type HistoryRangeView } from './columns';
 import { createDerivations } from './derive';
 import { chartLabel, type ChartKindInfo } from './kinds';
 import { createLiveController } from './liveController';
+import type { LiveSegmentAxis } from '../lib/segments/liveAxis';
+import { type ChartMark, type RuleStateInfo } from './alerts';
+import type { RuleDoc } from '../rules/types';
+import type { LinkedRuleLine } from '../lib/panelChartSettings';
 import { createStore } from './store';
-import { type ChartKind, type ChartModel, type EngineEvents, type EngineOptions, type EngineState, type KymoscopeLimits } from './types';
+import { type ChartKind, type ChartModel, type EngineEvents, type EngineOptions, type EngineState, type KymoscopeLimits, type SegmentContext } from './types';
 export declare const DEFAULT_X = "ET";
 /** Default series / scatter colours (matches the app). */
 export declare const PALETTE: string[];
@@ -42,7 +47,10 @@ export interface InternalState {
     offsets: Record<string, number>;
     colors: Record<string, string>;
     liveWindowSeconds: number | null;
+    segmentContext: SegmentContext | null;
     live: LiveConnection[];
+    /** Video sources registered by the host (engine.video.register): recorded cameras. */
+    video: VideoSource[];
     mathChannels: MathChannel[];
     limits: KymoscopeLimits;
     palette: string[];
@@ -50,6 +58,10 @@ export interface InternalState {
     /** null until the licence check finishes. */
     licensed: boolean | null;
     history: EngineState['history'];
+    marks: ChartMark[];
+    alerts: RuleStateInfo[];
+    /** The rules in force (engine.alerts.rules()), here so a new set re-renders the lines linked to them. */
+    alertRules: RuleDoc[];
 }
 export type ImportSource = File | FolderEntry;
 export interface ImportResult {
@@ -90,6 +102,8 @@ export interface Exported {
 }
 export type ParsedFile = Awaited<ReturnType<typeof parseKymoscopeFile>>;
 export type ChartSettingsPatch = Partial<PanelChartSettings> & Record<string, unknown>;
+/** Point every chart's column picks at columns the new data actually has (X: time when there is one). */
+export declare function adoptColumns(ws: Worksheet, nums: string[]): Worksheet;
 export declare function createEngine(options?: EngineOptions): {
     getState: () => EngineState;
     subscribe(listener: () => void): () => void;
@@ -124,6 +138,13 @@ export declare function createEngine(options?: EngineOptions): {
         openRecording(input: RecordingInput): Promise<string>;
         /** New chunks of an open recording: the dataset keeps its id, selection, colour, offset and laps. */
         reopenRecording(id: string, input: RecordingInput): Promise<void>;
+        /**
+         * A time range of a Historian history as a dataset (pieces from readHistoryRange; X `ElapsedTime`, Unix seconds).
+         * Returns the id. Selected like any new dataset.
+         */
+        openHistoryRange(view: HistoryRangeView): string;
+        /** New pieces for a history dataset (pan/zoom, a later read): same id, selection, colour and offset. */
+        updateHistoryRange(id: string, view: HistoryRangeView): void;
         /** Add numeric columns from the host (selected immediately). */
         addColumns(input: ColumnsInput): string;
         /**
@@ -266,7 +287,12 @@ export declare function createEngine(options?: EngineOptions): {
         /** Linked X zoom of a worksheet (default: active); null = full range. */
         setXRange(range: [number, number] | null, worksheetId?: string): void;
         resetZoom(worksheetId?: string): void;
+        /** Shared chart cursor of a worksheet (default: active), in X data units; null = none. Fires 'cursorchange'. */
+        setCursorX(x: number | null, worksheetId?: string): void;
+        cursorX(worksheetId?: string): number | null;
         setLiveWindow(seconds: number | null): void;
+        /** The Segments panel's ids (history, definition, reference); saved with the workbook. */
+        setSegmentContext(ctx: SegmentContext | null): void;
     };
     mathChannels: {
         /** Create a channel (`name` and `formula` at least). Returns it. */
@@ -307,10 +333,22 @@ export declare function createEngine(options?: EngineOptions): {
             name: string;
             startedAt: number;
         } | null;
+        /** Live against a reference (Historian phase 5): the definition's rule, the axis column and deltas on a connection. */
+        setSegmentAxis(id: string, cfg: LiveSegmentAxis | null): void;
         /** Samples currently buffered for a connection (cheap; poll it for counters). */
         rowCount(id: string): number;
         disconnect(id: string): void;
     };
+    /** Camera video the Camera panel plays: live cameras appear on their own; register recorded ones. `videochange`
+     *  fires when the list changes. */
+    video: {
+        /** Live cameras (kind 'live', one per camera connection) and the registered sources (recorded cameras). */
+        sources: () => VideoSource[];
+        /** Add a video source (e.g. a RecordedVideoSource of an open recording); replaces one with the same id and recordingId. */
+        register(source: VideoSource): void;
+        /** Remove the registered sources of camera `id` (of only that recording when `recordingId` is given). */
+        unregister(id: string, recordingId?: string): void;
+    };
     io: {
         /** True when there are charts that a workspace import would replace. */
         hasWork: () => boolean;
@@ -371,6 +409,24 @@ export declare function createEngine(options?: EngineOptions): {
         /** Like merged() without the math channels: no row cloning, stable until the data changes. */
         plotted(): Dataset | null;
     };
+    /** Alert rules (kyr/1) on the open datasets and live streams. The engine never stores rules: pass the whole list
+     *  to setRules whenever it changes. Transitions arrive as `alert` events; episodes become `marks`. */
+    alerts: {
+        setRules: (docs: RuleDoc[]) => (import("..").RuleProblem & {
+            ruleId: string;
+        })[];
+        rules: () => RuleDoc[];
+        state: () => RuleStateInfo[];
+        evaluate: (datasetId: string, o: {
+            timeColumn: string;
+            ruleIds?: string[];
+        }) => Promise<import("..").AlertTransition[]>;
+        clearMarks: (targetId?: string) => void;
+    };
+    /** Read-only spans on the charts from alert episodes (never stored in chart settings). */
+    marks: {
+        list: () => ChartMark[];
+    };
     dispose(): void;
 };
 export type KymoscopeEngine = ReturnType<typeof createEngine>;
@@ -389,6 +445,8 @@ export interface EngineInternals {
         columnUnits: Record<string, string>;
     };
     live: ReturnType<typeof createLiveController>;
+    /** Per rule id: the threshold and state lines linked to it draw (resolveLinkedAlarms). */
+    alertLines: () => ReadonlyMap<string, LinkedRuleLine>;
 }
 export declare function getInternals(engine: KymoscopeEngine): EngineInternals;
 export { DATASET_PALETTE };

package/dist/types/engine/derive.d.ts

@@ -20,7 +20,7 @@ export declare function createDerivations(): {
     staticDataset: (selected: LoadedDataset[]) => Dataset | null;
     mergedDataset: (stat: Dataset | null, live: LiveConnection[]) => Dataset | null;
     mergedParts: (selected: LoadedDataset[], live: LiveConnection[]) => Dataset[];
-    numericColumns: (merged: Dataset | null, selected: LoadedDataset[], channels: MathChannel[], parts?: Dataset[] | undefined) => string[];
+    numericColumns: (merged: Dataset | null, selected: LoadedDataset[], channels: MathChannel[], parts?: Dataset[] | undefined, live?: LiveConnection[] | undefined) => string[];
     allColumns: (merged: Dataset | null, selected: LoadedDataset[], channels: MathChannel[]) => string[];
     columnUnits: (merged: Dataset | null, channels: MathChannel[]) => Record<string, string>;
 };

package/dist/types/engine/errors.d.ts

@@ -1,4 +1,4 @@
-export type KymoscopeErrorCode = 'column_length_mismatch' | 'no_columns' | 'bad_workspace' | 'bad_file' | 'import_vetoed' | 'limit_reached' | 'not_found' | 'wrong_password' | 'password_required' | 'scope_key_required' | 'relay_unavailable' | 'disposed' | 'invalid_argument' | 'export_failed' | 'popup_blocked' | 'cancelled';
+export type KymoscopeErrorCode = 'column_length_mismatch' | 'no_columns' | 'bad_workspace' | 'bad_file' | 'import_vetoed' | 'limit_reached' | 'not_found' | 'wrong_password' | 'password_required' | 'scope_key_required' | 'relay_unavailable' | 'disposed' | 'invalid_argument' | 'export_failed' | 'popup_blocked' | 'cancelled' | 'camera_codec_unsupported';
 /** Every failure the SDK reports. `detail` carries structured context (e.g. `{reason}` for limits). */
 export declare class KymoscopeError extends Error {
     readonly code: KymoscopeErrorCode;

package/dist/types/engine/liveController.d.ts

@@ -1,5 +1,7 @@
+import { LiveBuffer } from '../lib/live/buffer';
 import { type LiveRelayConfig } from '../lib/live/stream';
 import type { MathChannel } from '../lib/mathChannels/types';
+import { type LiveSegmentAxis } from '../lib/segments/liveAxis';
 import type { LiveConnection, LiveStreamDescriptor, LiveStreamOptions, LocalLiveStream, StreamKeyProvider } from '../lib/live/types';
 export interface LiveController {
     connections(): LiveConnection[];
@@ -20,8 +22,16 @@ export interface LiveController {
     setRelay(relay: LiveRelayConfig | undefined): void;
     /** Math channels evaluated on every stream (as computed buffer columns). */
     setMathChannels(channels: MathChannel[]): void;
+    /** Run a segment definition live on a connection (plan S6), or stop it (null). Replays the ring quietly. */
+    setSegmentAxis(id: string, cfg: LiveSegmentAxis | null): void;
     dispose(): void;
 }
 export declare function createLiveController(initialRelay: LiveRelayConfig | undefined, onChange: (connections: LiveConnection[]) => void, 
 /** The host's defaults for new streams (read when one opens). */
-defaults?: () => LiveStreamOptions): LiveController;
+defaults?: () => LiveStreamOptions, 
+/** Alert rules: `rows` after every ingested block (from absolute index `from`, math channels already computed),
+ *  `tick` once a second per stream with the arrival time (ms) of its last frame. */
+hooks?: {
+    rows(id: string, buf: LiveBuffer, from: number): void;
+    tick(id: string, buf: LiveBuffer, lastFrameAt: number): void;
+}): LiveController;

package/dist/types/engine/types.d.ts

@@ -1,3 +1,4 @@
+import type { VideoSource } from '../lib/live/videoTrack';
 import type { LiveStreamOptions } from '../lib/live/types';
 import type { DashboardPanelKind } from '../components/dashboardGridLayout';
 import type { PanelChartSettings } from '../lib/panelChartSettings';
@@ -7,15 +8,19 @@ import type { LiveRelayConfig } from '../lib/live/stream';
 import type { BeaconConfig } from '../lib/beacon';
 import type { DatasetParseConfig } from '../lib/parseDataset';
 import type { DatasetFileInfo } from '../lib/importers/types';
+import type { AlertTransition } from '../rules/evaluator';
+import type { ChartMark, RuleStateInfo } from './alerts';
 export type ChartKind = DashboardPanelKind;
 /** Why a limit blocked an action. */
-export type LimitReason = 'charts-per-worksheet' | 'channels-per-chart' | 'worksheets' | 'workspaces-io' | 'math-channels';
+export type LimitReason = 'charts-per-worksheet' | 'channels-per-chart' | 'worksheets' | 'workspaces-io' | 'math-channels' | 'alert-rules';
 /** Quantity limits; `null` = unlimited. */
 export interface KymoscopeLimits {
     maxChartsPerWorksheet: number | null;
     maxChannelsPerChart: number | null;
     maxWorksheets: number | null;
     maxMathChannels: number | null;
+    /** Alert rules evaluated (engine.alerts.setRules keeps the first ones). */
+    maxAlertRules: number | null;
     canImportExportWorkspaces: boolean;
 }
 export declare const UNLIMITED: KymoscopeLimits;
@@ -127,7 +132,14 @@ export interface LiveConnectionInfo {
     ownerName: string;
     visibility: 'private' | 'public' | 'org' | 'project';
     orgName: string | null;
-    status: 'connecting' | 'live' | 'stale' | 'error';
+    /** A camera carries video (a camera panel shows it); a data stream, samples. */
+    kind: 'data' | 'camera';
+    /** A camera's data stream; null for data streams. */
+    parentId: string | null;
+    /** A camera's low layer: its high camera's id (not a camera of its own: lists and pickers skip it); null otherwise. */
+    lowOf: string | null;
+    /** 'idle': a camera no panel shows (connected, not downloading). */
+    status: 'idle' | 'connecting' | 'live' | 'stale' | 'error';
     error: string | null;
     rowCount: number;
     selected: boolean;
@@ -137,6 +149,14 @@ export interface LiveConnectionInfo {
     customColor: boolean;
     /** When a recording is running: its start time (ms since epoch), else null. */
     recordingSince: number | null;
+    /** Its columns as of the last structural change (the time column first). */
+    channels: string[];
+}
+/** What the Segments panel shows (Historian phase 5): saved in workbooks by id (spec E4), never data. */
+export interface SegmentContext {
+    historyId: string;
+    definitionId: string | null;
+    referenceId: string | null;
 }
 export interface EngineState {
     datasets: DatasetInfo[];
@@ -148,6 +168,8 @@ export interface EngineState {
     live: LiveConnectionInfo[];
     /** Scrolling window for live charts on a time X axis (seconds; null = all). */
     liveWindowSeconds: number | null;
+    /** The Segments panel's history, definition and reference, or null. */
+    segmentContext: SegmentContext | null;
     limits: KymoscopeLimits;
     /** Colors given to plotted datasets in order (EngineOptions.palette). */
     palette: string[];
@@ -173,16 +195,33 @@ export interface EngineState {
         canUndo: boolean;
         canRedo: boolean;
     };
+    /** Read-only spans from alert rule episodes (engine.alerts), drawn on time charts. */
+    marks: ChartMark[];
+    /** Per rule and open target: waiting (with the missing channel names), idle, pending, active, clearing… */
+    alerts: RuleStateInfo[];
 }
 export interface EngineEvents extends Record<string, unknown> {
     change: EngineState;
     limit: {
         reason: LimitReason;
     };
+    /** An alert rule raised, cleared, or lost its channel on a target. */
+    alert: AlertTransition;
+    /** The shared chart cursor of a worksheet moved (view.setCursorX); x in data units, null = off the charts. */
+    cursorchange: {
+        worksheetId: string;
+        x: number | null;
+    };
+    /** engine.video.sources() changed: a live camera came or went, or a source was registered or unregistered. */
+    videochange: {
+        sources: VideoSource[];
+    };
     error: {
         error: Error;
         context: string;
     };
+    /** The engine was disposed (once; every call throws KymoscopeError 'disposed' from now on). */
+    dispose: undefined;
     import: {
         file: string;
         phase: 'start' | 'progress' | 'done' | 'error';

package/dist/types/index.d.ts

@@ -14,6 +14,7 @@ export { KymoscopeError } from './engine/errors';
 export type { KymoscopeErrorCode } from './engine/errors';
 export { UNLIMITED } from './engine/types';
 export type { EngineOptions, EngineState, EngineEvents, KymoscopeLimits, LimitReason, MathChannelStoreAdapter, DatasetInfo, ColumnInfo, LapInfo, ChartKind, ChartModel, WorksheetState, LiveConnectionInfo, } from './engine/types';
+export type { ChartMark, RuleStateInfo } from './engine/alerts';
 export { CHART_KINDS, chartLabel } from './engine/kinds';
 export type { ChartKindInfo } from './engine/kinds';
 export type { ColumnsInput } from './engine/columns';
@@ -24,7 +25,7 @@ export type { ChartWindow, ChartWindowOptions } from './charts/chartWindow';
 export type { ChartStatus, ContextMenuEvent } from './charts/ChartBody';
 export * from './lib/panelChartSettings';
 export { chartChannelCount } from './lib/chartChannels';
-export { ANNOTATION_KINDS, DEFAULT_ANNOTATION_WIDTH, type AnnotationKind, type AnnotationTool, type ChartAnnotation } from './lib/annotations';
+export { ANNOTATION_KINDS, DEFAULT_ANNOTATION_WIDTH, coerceAnnotation, markToAnnotation, SEVERITY_HEX, type AnnotationKind, type AnnotationTool, type ChartAnnotation } from './lib/annotations';
 export { ANNOTATION_CONTROLS_ATTR } from './charts/AnnotationLayer';
 export { colorAt, colorsCss, presetStops, type GaugeColorMode, type GaugeColorStop, type GaugePreset } from './lib/gaugeColors';
 export type { PlotSeries, AlarmLine, AlarmStyle } from './types/plotSeries';
@@ -60,11 +61,33 @@ export type { LiveRelayConfig } from './lib/live/stream';
 export type { LiveStreamDescriptor, LiveStreamOptions, LocalLiveStream, StreamKeyProvider } from './lib/live/types';
 export type { LiveColumnsBlock, LiveMessage } from './lib/live/buffer';
 export { LIVE_TIME_COLUMN } from './lib/live/buffer';
-export { openMessage, sealMessage } from './lib/live/wire';
+export { openMessage, sealMessage, KIND_VIDEO } from './lib/live/wire';
+export { encodeVideo, decodeVideo, fragmentVideo, VIDEO_MAX_FRAGMENT, type VideoMessage } from './lib/live/videoWire';
+export type { VideoSource, EncodedUnit, VideoTrackInfo } from './lib/live/videoTrack';
+export { RecordedVideoSource, type RecordedVideoSourceOptions } from './lib/recordings/videoSource';
+export { LivePublisher, type PublisherDeps, type PublisherOptions, type PublisherState, type PublisherStatus } from './lib/live/publisher';
+export { CameraSender, CAMERA_PRESETS, LOW_PRESET, type CameraPreset, type CameraStats, type CameraLayerStats, type CameraSenderDeps } from './lib/live/cameraSender';
 export type { RecordingKey } from './lib/recordings/keys';
 export { recordingKeyAad, recordingKeySealAad } from './lib/recordings/keys';
 export { parseKrc, parseKrcHeader, KRC_HEADER_BYTES } from './lib/recordings/krc';
 export type { RecordingInput } from './engine/createEngine';
 export { exportRecording, exportRecordingTo, EXPORT_TYPES, type ExportPart, type RecordingSource } from './lib/recordings/export';
 export type { EncryptedEnvelope, DeviceWrap, SealedKey, PasswordSealed } from './lib/live/crypto';
-export { generateApiToken, splitApiKey, generateDeviceKeyPair, unwrapStreamKey, unwrapForDevice, wrapForDevice, projectWrapAad, streamKeyAad, bindKeyAad, randomKey, importStreamKey, sealUnderProjectKey, openUnderProjectKey, senderBindKey, senderBinding, verifySenderBinding, deviceFingerprint, hashToken, generateSalt, deriveKey, deriveRawKeyBase64, makeKeyCheck, verifyKeyCheck, WORKBOOK_EXPORT_AAD, workbookBodyAad, workbookKeyAad, recoveryKeyAad, recoveryAttestationAad, sealWithKey, openWithKey, sealWithPassword, openWithPassword, recoveryCode, parseRecoveryCode, generateRecoveryKeyPair, recoveryPrivateKey, } from './lib/live/crypto';
+export { generateApiToken, splitApiKey, generateDeviceKeyPair, unwrapStreamKey, unwrapForDevice, wrapForDevice, projectWrapAad, streamKeyAad, bindKeyAad, randomKey, importStreamKey, sealUnderProjectKey, openUnderProjectKey, senderBindKey, senderBinding, verifySenderBinding, deviceFingerprint, hashToken, generateSalt, deriveKey, deriveRawKeyBase64, makeKeyCheck, verifyKeyCheck, WORKBOOK_EXPORT_AAD, workbookBodyAad, workbookKeyAad, historyKeyAad, projectConfigKeyAad, alertRuleAad, recoveryKeyAad, recoveryAttestationAad, sealWithKey, openWithKey, sealWithPassword, openWithPassword, recoveryCode, parseRecoveryCode, generateRecoveryKeyPair, recoveryPrivateKey, } from './lib/live/crypto';
+export * from './rules/types';
+export { validateRule, type RuleProblem } from './rules/validate';
+export { thresholdOf } from './rules/threshold';
+export { createRuleEvaluator, type RuleEvaluator, type RuleTarget, type AlertTransition, type RuleEvaluatorState, type LiveBlock } from './rules/evaluator';
+export { footerLength, openFooter, openSealed, blockAad, type KhdFooter, type KhdBlock, type KhdChannel, type KhdFileId, type HistoryKind, type HistoryLevel } from './lib/historian/khd1';
+export { warmHistoryDecoder } from './lib/historian/parquet';
+export { blockCache, type BlockCache, type CacheDir } from './lib/historian/blockCache';
+export { HistoryDataSource, splicePieces, clipPiece, slicePiece, type HistoryPiece } from './lib/data/historyDataSource';
+export type { HistoryRangeView } from './engine/columns';
+export { isClockAxis, formatClockTick, formatClockValue, setClockTimeZone, getClockTimeZone, subscribeClockTimeZone } from './lib/yAxisTicks';
+export { readHistoryRange, readFooter, chooseLevel, pickSegments, coalesce, pool, RANGE_PARALLEL, HISTORY_PIXELS, type HistorySegmentRef, type HistoryReadOptions, type HistoryRange } from './lib/historian/reader';
+export { exportHistoryTo, wideDay, f32text, isoMicros, MAX_WIDE_CELLS, MAX_PARQUET_VALUES, type HistoryExportFormat } from './lib/historian/export';
+export { RuleRunner, resetStep, newResetState, compareOp, kpiKey, ruleChannels, localDay, zonedInstant, shiftDay, tzOffsetS, KPI_STATS, type SegmentRule, type CompareOp, type EdgeOn, type KpiStat, type KpiSpec, type Kpis, type DetectedSegment, type ResetState } from './lib/segments/rules';
+export type { SegmentContext } from './engine/types';
+export { referenceBands } from './charts/beacon';
+export { alignSegment, AxisState, axisColumn, localSeconds, resample, gridAt, buildReference, bandEdges, compareToReference, encodeBand, decodeBand, MAX_GRID, MAX_BAND_CELLS, type AlignAxis, type AlignedSegment, type ReferenceCurve, type ReferenceChannel, type Comparison } from './lib/segments/align';
+export { liveSegmentTracker, DELTA_SUFFIX, type LiveSegmentAxis, type LiveSegmentEvent, type LiveReference } from './lib/segments/liveAxis';

package/dist/types/lib/annotations.d.ts

@@ -35,3 +35,23 @@ export declare const DEFAULT_ANNOTATION_WIDTH: Record<AnnotationKind, number>;
 /** One annotation from untrusted input (a file, an SDK call), or null if it isn't one. */
 export declare function coerceAnnotation(v: unknown): ChartAnnotation | null;
 export declare function coerceAnnotations(v: unknown): ChartAnnotation[] | null;
+/** Severity colours of alert marks: the palette's own muted text, amber accent and danger (hex for annotations). */
+export declare const SEVERITY_HEX: {
+    readonly info: "#8a93a6";
+    readonly warning: "#f5a524";
+    readonly critical: "#e5484d";
+};
+/** The same, following the page's theme on screen. */
+export declare const SEVERITY_COLOR: {
+    readonly info: "var(--text-muted, #8a93a6)";
+    readonly warning: "var(--accent, #f5a524)";
+    readonly critical: "var(--danger, #e5484d)";
+};
+/** An alert mark as a box annotation pinned to X ("Keep as annotation"); an open mark ends at `rightEdgeX`. */
+export declare function markToAnnotation(m: {
+    id: string;
+    ruleName: string;
+    severity: keyof typeof SEVERITY_HEX;
+    t0: number;
+    t1: number | null;
+}, rightEdgeX: number): ChartAnnotation;

package/dist/types/lib/beacon.d.ts

@@ -22,7 +22,8 @@ export interface LapRange {
 /**
  * Split rows wherever `channel` resets. A reset is a drop larger than half of
  * the current lap's span so far, so small sensor jitter backwards never starts
- * a new lap. Rows whose channel is not numeric stay inside the current lap.
+ * a new lap (the edge rule `reset` of segments/rules.ts). Rows whose channel is
+ * not numeric stay inside the current lap.
  */
 export declare function splitLaps(rows: DatasetRow[], channel: string): LapRange[];
 /**

package/dist/types/lib/data/columnarDataSource.d.ts

@@ -19,6 +19,7 @@ export declare class ColumnarDataSource implements DataSource {
     /** {@link getSeriesMulti} without the Promise: decimating the columns is pure computation. */
     getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
     getColumnsSync(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     xBounds(column: string): Promise<{
         x0: number;
         x1: number;

package/dist/types/lib/data/dataSource.d.ts

@@ -61,6 +61,9 @@ export interface DataSource {
      * when there are more than `limit` of them or X isn't ascending.
      */
     getColumnsSync?(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    /** The rows [offset, offset + limit) of `columns` in file order, as numbers (NaN for empty or text cells).
+     *  Unknown columns are left out. For whole-column passes (alert rules on loaded data); read in chunks. */
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     xBoundsSync?(column: string): {
         x0: number;
         x1: number;

package/dist/types/lib/data/duckDbDataSource.d.ts

@@ -33,6 +33,7 @@ export declare class DuckDbDataSource implements DataSource {
      * a narrow window are denser, so the same `maxRows` budget buys finer detail.
      */
     sampleRows(maxRows: number, range?: XRange): Promise<DatasetRow[]>;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     /** Full-range x bounds for a column, for an initial viewport. */
     xBounds(xKey: string): Promise<{
         x0: number;

package/dist/types/lib/data/historyDataSource.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Historian ranges as a DataSource (plan P5): a list of pieces, each one block's times with Float32 values per channel
+ * (raw: lo and hi are the same arrays; a rollup: the bucket's min and max at its middle). The time column is
+ * `ElapsedTime` in Unix seconds, the same X as a collector's live stream. Decimation reads each piece on its own times,
+ * so tag groups never share a padded table. Everything is pure computation (sync), like the in-memory sources.
+ */
+import type { ColumnSchema, DataSource, DecimatedSeries, MultiSeriesResult, SeriesQuery, Viewport } from './dataSource';
+import type { DatasetRow } from '../parseDataset';
+import type { HistoryLevel } from '../historian/khd1';
+export interface HistoryPiece {
+    /** Unix seconds, ascending. */
+    t: Float64Array;
+    /** Per channel: the value (raw) or the bucket minimum (rollup). NaN: no value at that time. */
+    lo: Map<string, Float32Array>;
+    /** Per channel: the bucket maximum (rollup); the very same Map as `lo` for raw data. */
+    hi: Map<string, Float32Array>;
+    level: HistoryLevel;
+}
+/** First index with t[i] >= x, or with t[i] > x when `after`. */
+export declare function bound(t: Float64Array, x: number, after?: boolean): number;
+/** Rows [i, j) of a piece (views, nothing copied); null when empty. */
+export declare function slicePiece(p: HistoryPiece, i: number, j: number): HistoryPiece | null;
+/** The rows of `p` with t in [t0, t1]. */
+export declare const clipPiece: (p: HistoryPiece, t0: number, t1: number) => HistoryPiece | null;
+/** The overview outside [a, b] with the detail inside: the pan/zoom view (plan P6). */
+export declare function splicePieces(overview: HistoryPiece[], detail: HistoryPiece[], a: number, b: number): HistoryPiece[];
+export declare class HistoryDataSource implements DataSource {
+    #private;
+    readonly pieces: readonly HistoryPiece[];
+    constructor(pieces: HistoryPiece[], units?: Record<string, string>);
+    schemaSync(): ColumnSchema[];
+    getSchema(): Promise<ColumnSchema[]>;
+    /** Rows are the pieces' rows in time order (a rollup: its minimum); NaN where a piece lacks the channel. */
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
+    getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    xBoundsSync(column: string): {
+        x0: number;
+        x1: number;
+    };
+    xBounds(column: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    /** At most `maxRows` rows in time order for the row-based charts and math channels: one stride over all pieces' rows
+     *  end to end (pieces smaller than the stride may be skipped); a row holds its piece's channels only (a rollup: the
+     *  bucket minimum). ponytail: no cross-group alignment in the sample. */
+    sampleRowsSync(maxRows: number): DatasetRow[];
+    dispose(): Promise<void>;
+}

package/dist/types/lib/data/inMemoryDataSource.d.ts

@@ -12,6 +12,7 @@ export declare class InMemoryDataSource implements DataSource {
     getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
     /** {@link DataSource.getColumnsSync}: a table's columns are the samples (other rows: null, decimate). */
     getColumnsSync(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     /** Exact min/max like the DuckDB source ({0, 0} when the column has no numbers), not `columnBounds`' padded axis range. */
     xBounds(column: string): Promise<{
         x0: number;

package/dist/types/lib/data/liveDataSource.d.ts

@@ -16,6 +16,8 @@ export declare class LiveDataSource implements DataSource {
      *  a host's sample-count badge show the climbing count by polling itself, instead of the
      *  count riding on the ~1 Hz `connections` state whose update re-renders the App. */
     size(): number;
+    /** The stream's column names now (the time column first). */
+    get columnNames(): string[];
     /** Changes whenever the buffered data does (see LiveBuffer.version). */
     version(): number;
     /**
@@ -24,6 +26,8 @@ export declare class LiveDataSource implements DataSource {
      * LiveBuffer.mirrorColumn). A new map per call: the columns as they are now.
      */
     columns(): ReadonlyMap<string, Float64Array>;
+    /** Whether `column` has had a finite value (a column the snapshot rows may thin out of view). */
+    hasValues(column: string): boolean;
     /** A fresh row snapshot of the newest samples (at most `maxRows`, evenly thinned). */
     snapshot(maxRows: number): Dataset;
     getSchema(): Promise<ColumnSchema[]>;
@@ -54,11 +58,25 @@ export declare class LiveDataSource implements DataSource {
     /** Time of the newest sample (NaN if empty). */
     latestTimeSync(): number;
     /** Value of `column` at time `t` (see LiveBuffer.xAtTime). */
-    xAtTimeSync(column: string, t: number): number;
+    xAtTimeSync(column: string, t: number, hold?: boolean): number;
     /** The newest sample's value of `column` (NaN if none): the live position on X. */
     latestSync(column: string): number;
-    /** Newest received value of each column it has (finite values only). */
+    /** Newest received value of each column it has (finite values only): the newest sample's, else the column's
+     *  last known value (a channel that has no value at the newest time, or is quiet). */
     latestValuesSync(columns: string[]): Map<string, number>;
+    /**
+     * Y range of `column` for a scale: its samples in the ring and its last known value (a quiet channel has only
+     * that); a constant gets ±max(0.5, 5%) so it sits mid-band. Null when it has neither.
+     */
+    valueBoundsSync(column: string): {
+        min: number;
+        max: number;
+    } | null;
+    /** The newest finite value of `column` and its time, past the ring (see LiveBuffer.lastKnown). */
+    lastKnownSync(column: string): {
+        t: number;
+        v: number;
+    } | undefined;
     /** Follow cycles on `xKey` (beacon): see LiveBuffer.trackCycles. */
     trackCycles(xKey: string): void;
     /** X span of every sample seen on a tracked key, or null. */
@@ -73,5 +91,6 @@ export declare class LiveDataSource implements DataSource {
         x0: number;
         x1: number;
     }, maxPoints: number): PointColumns;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     dispose(): Promise<void>;
 }