@kymoscope/sdk 0.3.0 → 0.5.0

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,22 +13,29 @@ 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';
 import { type BeaconConfig } from '../lib/beacon';
+import { type CycleDefinition, type CycleFound, type RuleDef } from '../lib/cycles/evaluator';
+import type { KpiSpec } from '../lib/segments/rules';
 import { type Dataset, type DatasetParseConfig } from '../lib/parseDataset';
 import { parseKymoscopeFile, type WorkbookBody } from '../lib/workspaces/io';
 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 +49,12 @@ export interface InternalState {
     offsets: Record<string, number>;
     colors: Record<string, string>;
     liveWindowSeconds: number | null;
+    segmentContext: SegmentContext | null;
+    /** Cycle and phase rules (lib/cycles), saved with the workbook. */
+    cycleRules: CycleDefinition[];
     live: LiveConnection[];
+    /** Video sources registered by the host (engine.video.register): recorded cameras. */
+    video: VideoSource[];
     mathChannels: MathChannel[];
     limits: KymoscopeLimits;
     palette: string[];
@@ -50,6 +62,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 +106,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;
@@ -121,9 +139,19 @@ export declare function createEngine(options?: EngineOptions): {
          * A cloud recording as a dataset: its encrypted chunks (KRC1, in order) decrypted with `keys` in the import
          * worker, in memory or out of core like a file. Returns the id.
          */
-        openRecording(input: RecordingInput): Promise<string>;
+        openRecording(input: RecordingInput, o?: {
+            signal?: AbortSignal;
+            onProgress?: (fraction: number) => void;
+        }): 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;
         /**
@@ -148,6 +176,40 @@ export declare function createEngine(options?: EngineOptions): {
         writeColumns(id: string, names: string[], fill: (cols: Record<string, Float64Array>, current: Record<string, Float64Array | undefined>) => void): void;
         /** Add delimited text (CSV/TSV/.dat), parsed like an imported file. */
         addText(text: string, name?: string): Promise<string>;
+        /** The cycles and phases of a dataset under cycle rules v2 (lib/cycles): closed ones, then the open ones (tend
+         *  null), each with its definition's KPIs (`kpis`, by column name: "TIC201 max"). `timeKey`: its time column
+         *  (seconds). Any kind of dataset: read through its source. */
+        findCycles(id: string, defs: Array<RuleDef & {
+            kpis?: KpiSpec[];
+        }>, timeKey: string): Promise<CycleFound[]>;
+        /**
+         * "Add to datasets": the picked cycles or phases of a dataset (from findCycles), each as a dataset of its samples
+         * with `Cycle time` (s since its start), then the cycles table and phases table of `cycleId` (unless `tables`
+         * false). Returns the new ids, in that order.
+         */
+        addCycles(id: string, o: {
+            timeKey: string;
+            defs: Array<RuleDef & {
+                name: string;
+                kpis?: KpiSpec[];
+            }>;
+            cycleId: string;
+            found: CycleFound[];
+            pick: Array<Pick<CycleFound, "definitionId" | "index" | "parentIndex">>;
+            tables?: boolean;
+        }): Promise<string[]>;
+        /**
+         * Cut a dataset into cycles (the dataset's Cycles button): the cycles of `cycleId` and its phases, found in the
+         * browser over any kind of dataset; each becomes a part with `Cycle time` (s since its start), and the dataset is
+         * shown and selected as them, as laps are (a selected dataset plots all its cycles). `null` undoes it. Nothing is
+         * stored: a workbook keeps the rules, never the cycles. Resolves to the number of cycles (phases not counted).
+         * ponytail: reads the dataset's numeric columns whole (as addCycles); a part is a view, not a copy.
+         */
+        cut(id: string, o: {
+            defs: CycleDefinition[];
+            cycleId: string;
+            timeKey: string;
+        } | null): Promise<number>;
         remove(id: string): void;
         /** Remove every dataset. Worksheets and charts are kept. */
         clear(): void;
@@ -266,7 +328,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. */
@@ -289,6 +356,15 @@ export declare function createEngine(options?: EngineOptions): {
         /** Host-owned store: push the authoritative list after it changes (an open workbook's channels stay). */
         sync(channels: MathChannel[]): void;
     };
+    /** Cycle and phase rules (lib/cycles), saved with the workbook: `getState().cycleRules`. */
+    cycles: {
+        /** Add or replace a cycle or phase rule (by id; a new one gets an id). Returns its id. Saved with the workbook. */
+        save(def: Omit<CycleDefinition, "id"> & {
+            id?: string;
+        }): string;
+        /** Remove a rule and the phases inside it. */
+        remove(id: string): void;
+    };
     live: {
         /** A stream the page feeds itself (no relay, no crypto). */
         openLocal(name: string, options?: LiveStreamOptions): LocalLiveStream;
@@ -307,10 +383,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 +459,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 +495,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,21 +1,27 @@
+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';
 import type { ChartAnnotation } from '../lib/annotations';
 import type { MathChannel, MathChannelPatch } from '../lib/mathChannels/types';
+import type { CycleDefinition, CycleFlag } from '../lib/cycles/evaluator';
 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;
@@ -71,6 +77,23 @@ export interface LapInfo {
     color: string;
     offset: number;
     selected: boolean;
+    /** A cut's cycle or phase (datasets.cut); absent for a beacon lap. */
+    cycle?: LapCycle;
+}
+/** What a cut found for one lap row: a cycle (no parentIndex) or one of its phases. */
+export interface LapCycle {
+    definitionId: string;
+    /** The rule's name ("Cycle", "Heating"). */
+    rule: string;
+    index: number;
+    /** A phase: the index of its cycle. */
+    parentIndex: number | null;
+    tstart: number;
+    tend: number | null;
+    flags: CycleFlag[];
+    kpis: Record<string, number | null>;
+    /** Cut short: by the end of the data, or of its cycle (a phase). */
+    incomplete: boolean;
 }
 export interface DatasetInfo {
     id: string;
@@ -90,7 +113,13 @@ export interface DatasetInfo {
     /** Binary files: format, start time, groups (with rates), events; null for text. */
     fileInfo: DatasetFileInfo | null;
     beacon: BeaconConfig | null;
-    /** Present when the dataset is split into laps (beacon). */
+    /** The rule a dataset is cut by (datasets.cut), or null. */
+    cut: {
+        cycleId: string;
+        timeKey: string;
+        defs: CycleDefinition[];
+    } | null;
+    /** Present when the dataset is split into laps (beacon) or cut into cycles (then each lap has `cycle`). */
     laps: LapInfo[] | null;
     /** Selection state: true, false, or 'partial' when only some laps are selected. */
     selected: boolean | 'partial';
@@ -125,9 +154,16 @@ export interface LiveConnectionInfo {
     id: string;
     name: string;
     ownerName: string;
-    visibility: 'private' | 'public' | 'org' | 'project';
+    visibility: 'private' | 'public' | 'org' | 'project' | 'open';
     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 +173,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 +192,10 @@ 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;
+    /** Cycle and phase rules (engine.cycles), saved with the workbook. */
+    cycleRules: CycleDefinition[];
     limits: KymoscopeLimits;
     /** Colors given to plotted datasets in order (EngineOptions.palette). */
     palette: string[];
@@ -173,16 +221,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

@@ -13,7 +13,8 @@ export type { KymoscopeEngine, Snapshot, ImportSource, ImportResult, ImportOptio
 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 { EngineOptions, EngineState, EngineEvents, KymoscopeLimits, LimitReason, MathChannelStoreAdapter, DatasetInfo, ColumnInfo, LapInfo, LapCycle, 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,35 @@ 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, OPEN_STREAM_PASSWORD, 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 { CycleRunner, CycleSet, cycleRuleChannels, type CycleRule, type Trigger as CycleTrigger, type Condition as CycleCondition, type CycleLimits, type CycleFlag, type CycleInstance, type CycleFound, type RuleDef, type CycleDefinition, parseCycleDefinitions } from './lib/cycles/evaluator';
+export { CYCLE_TIME, readSource, findCycles, cutCycle, cycleTables, definitionChannels, kpiColumn, kpisOf, rowsCsv, type SourceColumns } from './lib/cycles/cut';
+export { RuleRunner, KpiAcc, 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/cycles/cut.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Cutting any source into cycles (spec 2026-10-28-cycles-design, "Cutting any source"): read a source's time and the
+ * channels needed through DataSource.readColumns (every kind has it: memory, columnar, history range, recording, DuckDB),
+ * find the cycles with a CycleSet, and cut each one into columns with `Cycle time` (seconds since its start). The
+ * cycles table and phases table are rows (text flags), for the row-based charts.
+ * ponytail: the channels are read whole into memory; read per cycle (like segmentRun.loadAligned) if a source is too
+ * large for that.
+ */
+import type { DataSource } from '../data/dataSource';
+import type { DatasetRow } from '../parseDataset';
+import { type KpiSpec } from '../segments/rules';
+import { type CycleFound, type RuleDef } from './evaluator';
+export declare const CYCLE_TIME = "Cycle time";
+export interface SourceColumns {
+    t: Float64Array;
+    cols: Map<string, Float64Array>;
+}
+/** `timeKey` and `channels` of a source, whole, in file order. Missing channels are left out. */
+export declare function readSource(source: DataSource, timeKey: string, channels: string[]): Promise<SourceColumns>;
+/** The cycles and phases of `defs` in the columns: closed ones, then the ones still open (tend null). */
+export declare function findCycles(src: SourceColumns, defs: RuleDef[]): CycleFound[];
+/** Every channel the definitions read (their rules and KPIs). */
+export declare const definitionChannels: (defs: Array<RuleDef & {
+    kpis?: KpiSpec[];
+}>) => string[];
+/** A KPI's column name in the cycles and phases tables: "TIC201 max". */
+export declare const kpiColumn: (k: KpiSpec) => string;
+/** The KPIs of [tstart, tend) (an open one: to the end) from the source's columns; null where a channel has no value. */
+export declare function kpisOf(src: SourceColumns, c: Pick<CycleFound, 'tstart' | 'tend'>, kpis: KpiSpec[]): Record<string, number | null>;
+/** One cycle's samples, [tstart, tend) (an open cycle: to the end), as columns: `Cycle time`, the time and the channels
+ *  (views of the source's arrays, not copies). */
+export declare function cutCycle(src: SourceColumns, timeKey: string, c: Pick<CycleFound, 'tstart' | 'tend'>): Record<string, Float64Array>;
+/**
+ * The cycles table (one row per cycle of `cycleId`: Cycle, Start, End, Duration, each phase's duration, Flags) and the
+ * phases table (one row per phase: Cycle, Phase, Start, End, Duration, Flags). `defs`: the definitions, named. A cycle's
+ * Flags also list its phases' flags ("Heating late"). Times in the source's seconds; an open cycle has no End.
+ */
+export declare function cycleTables(found: CycleFound[], cycleId: string, defs: Array<{
+    id: string;
+    name: string;
+    parentId: string | null;
+    kpis?: KpiSpec[];
+}>, src?: SourceColumns): {
+    cycles: DatasetRow[];
+    phases: DatasetRow[];
+};
+/** Rows as CSV (the columns of the first row; text quoted when it needs it; null empty). */
+export declare function rowsCsv(rows: DatasetRow[]): string;