@kymoscope/sdk 0.3.0 → 0.4.0

package/dist/types/lib/live/videoTrack.d.ts

@@ -0,0 +1,96 @@
+import type { VideoMessage } from './videoWire';
+/** One complete encoded access unit (H.264), never a decoded frame. */
+export interface EncodedUnit {
+    t: number;
+    seq: number;
+    key: boolean;
+    data: Uint8Array;
+    arrivedAt: number;
+}
+export interface VideoTrackInfo {
+    width: number;
+    height: number;
+    codec: string;
+    latestT: number | null;
+    lagMs: number | null;
+    units: number;
+    bytes: number;
+}
+/**
+ * A camera's video as the Camera panel plays it: a live camera connection's ring (kind 'live'), or a camera
+ * recorded with a cloud recording (kind 'recorded', RecordedVideoSource). Listed by engine.video.sources().
+ */
+export interface VideoSource {
+    /** The camera stream's id (the same for its live connection and its recordings). */
+    id: string;
+    name: string;
+    kind: 'live' | 'recorded';
+    /** The camera's data stream id; null when unknown. */
+    parentId: string | null;
+    /** Live: a camera's low layer names its high camera (the Camera panel picks the layer; pickers skip it). */
+    lowOf?: string | null;
+    /** Recorded: the parent data stream's name, for labels when that stream isn't connected. */
+    parentName?: string | null;
+    /** Recorded: the data recording it was recorded with (that dataset's info.meta.recordingId). */
+    recordingId?: string | null;
+    info(): VideoTrackInfo;
+    /** Earliest and latest capture times (Unix s), or null. */
+    range(): [number, number] | null;
+    /** Units to decode to show the frame at capture time `t` (Unix s): the last keyframe <= t through the last unit <= t. */
+    seekPlan(t: number): EncodedUnit[] | Promise<EncodedUnit[]>;
+    /** Live: the newest keyframe and everything after it. */
+    livePlan?(): EncodedUnit[];
+    /** Live: each new unit; returns an unsubscribe. */
+    onUnit?(fn: (u: EncodedUnit) => void): () => void;
+    /** Live: hold the video while it is shown; returns the release. */
+    acquire?(): () => void;
+    /** Recorded: resolves once the codec is known (info().codec). */
+    ready?(): Promise<void>;
+}
+/** A live camera connection's track as a VideoSource (the same object per track while id/name/parent stay). */
+export declare function liveVideoSource(c: {
+    id: string;
+    name: string;
+    parentId: string | null;
+    lowOf?: string | null;
+    video: VideoTrack;
+}): VideoSource;
+/** Per-camera ring of encoded units: reassembles fragments, bounds memory at GOP boundaries, plans decodes. */
+export declare class VideoTrack {
+    private ring;
+    private bytes;
+    private needKey;
+    private width;
+    private height;
+    private codec;
+    private pending;
+    private subs;
+    private holders;
+    private demand;
+    private maxBytes;
+    private now;
+    constructor(maxBytes?: number, now?: () => number);
+    /** Feed a decoded KIND_VIDEO message; returns the completed unit, or null while incomplete or discarded. */
+    push(m: VideoMessage): EncodedUnit | null;
+    /** Drop whole GOPs from the front while over budget; the only GOP is never dropped. */
+    private trim;
+    /** Units to decode to show the frame at wall time `t` (unix s): last keyframe <= t through last unit <= t. */
+    seekPlan(t: number): EncodedUnit[];
+    /** The newest keyframe and everything after it. */
+    livePlan(): EncodedUnit[];
+    /** Called with each completed unit added to the ring. Returns an unsubscribe. */
+    onUnit(fn: (u: EncodedUnit) => void): () => void;
+    /**
+     * Hold the video while it is shown (a Camera panel): the connection downloads only while
+     * someone holds it. Returns the release (calling it again does nothing).
+     */
+    acquire(): () => void;
+    /** The connection's hook: called with true when the first holder arrives, false when the last leaves. */
+    onDemandChange(fn: (wanted: boolean) => void): void;
+    info(): VideoTrackInfo;
+    /** Earliest and latest buffered capture times, or null. */
+    range(): [number, number] | null;
+    /** After a gap (e.g. a rejoin): drop the half-received unit and skip deltas until the next keyframe. The ring stays. */
+    resync(): void;
+    clear(): void;
+}

package/dist/types/lib/live/videoWire.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Plaintext of a KIND_VIDEO relay message: one H.264 access unit (Annex B), or one
+ * fragment of it, stamped with its capture time in Unix seconds. A keyframe's first
+ * fragment carries the codec string, so a viewer joining mid-stream configures its
+ * decoder from it (Annex B keyframes carry SPS/PPS). Byte-compatible with
+ * packages/python/src/kymoscope/wire.py (encode_video / decode_video).
+ */
+export declare const VIDEO_VERSION = 1;
+export declare const VIDEO_CODEC_H264 = 1;
+/** Fragments stay under the cloud relay's 1 MiB message limit with room for the header and seal. */
+export declare const VIDEO_MAX_FRAGMENT: number;
+export interface VideoMessage {
+    key: boolean;
+    last: boolean;
+    t: number;
+    seq: number;
+    fragIndex: number;
+    fragCount: number;
+    width: number;
+    height: number;
+    codec: string;
+    payload: Uint8Array;
+}
+export declare function encodeVideo(m: VideoMessage): Uint8Array;
+export declare function decodeVideo(b: Uint8Array): VideoMessage | null;
+/** One access unit as the plaintexts to seal, split to VIDEO_MAX_FRAGMENT. */
+export declare function fragmentVideo(au: {
+    key: boolean;
+    t: number;
+    seq: number;
+    width: number;
+    height: number;
+    codec: string;
+    data: Uint8Array;
+}): Uint8Array[];

package/dist/types/lib/live/wire.d.ts

@@ -6,6 +6,10 @@ export declare const KIND_COLUMNS = 3;
 export declare const KIND_BLOCK = 4;
 /** The channel table KIND_BLOCK messages refer to (see blockWire.ts). */
 export declare const KIND_BLOCK_SCHEMA = 5;
+/** One encoded video access unit or a fragment of one (see videoWire.ts). */
+export declare const KIND_VIDEO = 6;
+/** Each channel's last value and its time, against a KIND_BLOCK_SCHEMA (see blockWire.ts). */
+export declare const KIND_LAST_VALUES = 7;
 export declare const KEY_ID_FLAG = 128;
 export interface SealedMessage {
     kind: number;

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

@@ -372,12 +372,24 @@ export interface GanttPanelChartSettings {
     gtEndCol: string;
     gtGroupCol: string;
 }
+export interface CameraPanelSettings {
+    kind: 'camera';
+    /** The camera stream's id; '' until chosen. Always the first of `cameras` (kept for settings saved before walls). */
+    cameraStreamId: string;
+    /** The cameras shown, in order (up to MAX_PANEL_CAMERAS): two or more make a wall. See panelCameras. */
+    cameras: string[];
+    /** The data stream this camera syncs with; '' = its own stream (the camera's parent) when connected, else the first live data stream. */
+    syncStreamId: string;
+    /** Manual correction, ms (−10000..10000). */
+    offsetMs: number;
+    fit: 'contain' | 'cover';
+}
 /** Settings every chart kind has besides its own. */
 export interface CommonPanelChartSettings {
     /** Marks drawn over the chart (text, brush, arrows, boxes, lines). */
     annotations?: ChartAnnotation[];
 }
-export type PanelChartSettings = CommonPanelChartSettings & (MultibandPanelChartSettings | XyPanelChartSettings | XyzPanelChartSettings | HistogramPanelChartSettings | PolarPanelChartSettings | SpectrumPanelChartSettings | BoxPlotPanelChartSettings | SpectrogramPanelChartSettings | HeatmapPanelChartSettings | ViolinPanelChartSettings | ConfusionPanelChartSettings | RocPanelChartSettings | LossCurvePanelChartSettings | ControlChartPanelChartSettings | ParallelCoordsPanelChartSettings | EmbeddingPanelChartSettings | FlameGraphPanelChartSettings | BarChartPanelChartSettings | RadarPanelChartSettings | AreaChartPanelChartSettings | CdfChartPanelChartSettings | BubbleChartPanelChartSettings | TreemapPanelChartSettings | SankeyPanelChartSettings | CalibrationPanelChartSettings | GaugePanelChartSettings | QQPlotPanelChartSettings | GanttPanelChartSettings);
+export type PanelChartSettings = CommonPanelChartSettings & (MultibandPanelChartSettings | XyPanelChartSettings | XyzPanelChartSettings | HistogramPanelChartSettings | PolarPanelChartSettings | SpectrumPanelChartSettings | BoxPlotPanelChartSettings | SpectrogramPanelChartSettings | HeatmapPanelChartSettings | ViolinPanelChartSettings | ConfusionPanelChartSettings | RocPanelChartSettings | LossCurvePanelChartSettings | ControlChartPanelChartSettings | ParallelCoordsPanelChartSettings | EmbeddingPanelChartSettings | FlameGraphPanelChartSettings | BarChartPanelChartSettings | RadarPanelChartSettings | AreaChartPanelChartSettings | CdfChartPanelChartSettings | BubbleChartPanelChartSettings | TreemapPanelChartSettings | SankeyPanelChartSettings | CalibrationPanelChartSettings | GaugePanelChartSettings | QQPlotPanelChartSettings | GanttPanelChartSettings | CameraPanelSettings);
 /** Parse optional axis range from min/max strings (same rules as App useMemo). */
 export declare function parseOptionalAxisRange(minStr: string, maxStr: string): [number, number] | undefined;
 /** Keep in sync with `savedLayout.ts` defaults. */
@@ -412,8 +424,35 @@ export declare function defaultGaugePanelSettings(): GaugePanelChartSettings;
 export declare function defaultCalibrationPanelSettings(): CalibrationPanelChartSettings;
 export declare function defaultQQPlotPanelSettings(): QQPlotPanelChartSettings;
 export declare function defaultGanttPanelSettings(): GanttPanelChartSettings;
+/** A camera in pickers: "Bench 3 · Camera 1" (its data stream's name: connected, or a recorded camera's parentName),
+ *  else the camera's own name. */
+export declare function cameraLabel(cam: {
+    name: string;
+    parentId?: string | null;
+    parentName?: string | null;
+}, live: readonly {
+    id: string;
+    name: string;
+}[]): string;
+export declare const defaultCameraPanelSettings: () => CameraPanelSettings;
+/** A Camera panel shows at most this many cameras (a 3x3 wall). */
+export declare const MAX_PANEL_CAMERAS = 9;
+/** The cameras a Camera panel shows: `cameras` while it starts with cameraStreamId, else just cameraStreamId
+ *  (a host that sets only cameraStreamId, as before walls, gets that one camera). */
+export declare function panelCameras(s: Pick<CameraPanelSettings, 'cameraStreamId' | 'cameras'>): string[];
 /** An alarm line from untrusted input, or null. */
 export declare function coerceAlarmLine(v: unknown): AlarmLine | null;
+/** What a linked line shows for its rule: the rule's threshold, and whether the rule is active now. */
+export interface LinkedRuleLine {
+    value: number;
+    active: boolean;
+}
+/**
+ * Lines linked to rules the runtime holds draw the rule's threshold and state (`linked`). Walks the four alarm
+ * places (multiband series, the simple kinds' alarm field, gauge rows, X-Y / X-Y-Z axes). Returns `s` itself when no
+ * line resolves, so memoised charts don't redraw.
+ */
+export declare function resolveLinkedAlarms(s: PanelChartSettings, rules: ReadonlyMap<string, LinkedRuleLine>): PanelChartSettings;
 /** The setting holding the alarm line of the chart kinds whose frame draws it. */
 export declare const CHART_ALARM_FIELDS: {
     readonly histogram: "histAlarm";

package/dist/types/lib/recordings/export.d.ts

@@ -15,6 +15,7 @@ export interface ExportOptions {
 export declare const EXPORT_TYPES: {
     readonly csv: "text/csv";
     readonly mf4: "application/octet-stream";
+    readonly parquet: "application/vnd.apache.parquet";
 };
 /**
  * A recording as a CSV or MF4 file, built in the browser from its encrypted chunks and handed to `write` piece by

package/dist/types/lib/recordings/videoSource.d.ts

@@ -0,0 +1,56 @@
+import { type MessageKey } from '../live/wire';
+import type { EncodedUnit, VideoSource, VideoTrackInfo } from '../live/videoTrack';
+export interface RecordedVideoSourceOptions {
+    /** The camera stream's id (what a Camera panel's cameraStreamId names). */
+    id: string;
+    name: string;
+    /** The camera's data stream id. */
+    parentId: string | null;
+    /** The data stream's name (labels "Stream · Camera" when that stream isn't connected). */
+    parentName?: string | null;
+    /** The data recording the camera was recorded with: the recording dataset's info.meta.recordingId. */
+    recordingId: string;
+    /** The camera recording's chunks: relay times (ms since epoch) of each one's first and last message. */
+    chunks: {
+        seq: number;
+        t0: number;
+        t1: number;
+    }[];
+    fetchChunk(seq: number): Promise<ArrayBuffer>;
+    /** The camera's key(s). */
+    open: MessageKey;
+    /** Decoded units kept, in bytes (default 256 MB); least recently used chunks go first. */
+    maxBytes?: number;
+}
+export declare class RecordedVideoSource implements VideoSource {
+    readonly kind: "recorded";
+    readonly id: string;
+    readonly name: string;
+    readonly parentId: string | null;
+    readonly parentName: string | null;
+    readonly recordingId: string;
+    private chunks;
+    private fetch;
+    private open;
+    private maxBytes;
+    /** By chunk index, least recently used first. */
+    private cache;
+    /** Settled entries: [bytes, units]. */
+    private sizes;
+    private bytes;
+    private width;
+    private height;
+    private codec;
+    private waiting;
+    constructor(o: RecordedVideoSourceOptions);
+    private parse;
+    private parsed;
+    private evict;
+    /** Chunk i's units in order, its last one finished from the next chunk; [] when it can't be downloaded. */
+    private units;
+    seekPlan(t: number): Promise<EncodedUnit[]>;
+    /** Resolves once the codec is known (the first keyframe of the first chunks), or they had none. */
+    ready(): Promise<void>;
+    info(): VideoTrackInfo;
+    range(): [number, number] | null;
+}

package/dist/types/lib/render/alertGlyph.d.ts

@@ -0,0 +1,7 @@
+/** A 10 px bell, drawn at the label end of an alarm line linked to an alert rule (canvas and SVG share the path). */
+export declare const ALERT_GLYPH_PATH = "M5 .8a3.1 3.1 0 0 0-3.1 3.1v2.3L.8 7.6h8.4L8.1 6.2V3.9A3.1 3.1 0 0 0 5 .8zM3.9 8.4a1.1 1.1 0 0 0 2.2 0z";
+export declare const ALERT_GLYPH_SIZE = 10;
+/** A linked line is dashed while its rule is active (spec §6.1.1); otherwise it keeps its own style. */
+export declare const ACTIVE_DASH: number[];
+/** Paint the bell with its top-left at (x, y). */
+export declare function drawAlertGlyph(ctx: CanvasRenderingContext2D, x: number, y: number, color: string): void;

package/dist/types/lib/render/glSeries.d.ts

@@ -4,7 +4,7 @@ export interface GpuSeriesStyle {
     bandBottom: number;
     scaleMin: number;
     scaleMax: number;
-    /** Median consecutive |Δx| of the column (0 if unknown): drives gap-splitting. */
+    /** Mean consecutive |Δx| of the column (0 if unknown): drives gap-splitting (see joinGapThresholdForColumn). */
     gapMedian: number;
     /** Line thickness in CSS px; defaults to the renderer's `lineWidth`. */
     width?: number;

package/dist/types/lib/segments/align.d.ts

@@ -0,0 +1,85 @@
+import { type CompareOp } from './rules';
+export type AlignAxis = {
+    kind: 'elapsed';
+    preroll_s?: number;
+} | {
+    kind: 'event';
+    channel: string;
+    op: CompareOp;
+    value: number;
+} | {
+    kind: 'cumulative';
+    channel: string;
+    integral?: boolean;
+} | {
+    kind: 'clock';
+    tz: string;
+};
+export interface AlignedSegment {
+    x: Float64Array;
+    t: Float64Array;
+    cols: Map<string, Float64Array>;
+}
+export interface ReferenceChannel {
+    mean: Float32Array;
+    sd: Float32Array;
+    min: Float32Array;
+    max: Float32Array;
+    n: Uint16Array;
+}
+export interface ReferenceCurve {
+    x: Float64Array;
+    channels: Map<string, ReferenceChannel>;
+}
+export interface Comparison {
+    /** Per sample of the segment: value − reference mean at its X (NaN where either is missing). */
+    delta: Map<string, Float64Array>;
+    /** Highest first: mean |delta| / σ (the grid point's σ with ≥ 2 sources, else the channel's spread over the grid). */
+    score: Array<{
+        channel: string;
+        z: number;
+    }>;
+    /** Runs out of band: from the first sample out to the first sample back in (or the last sample). */
+    deviations: Array<{
+        t0: number;
+        t1: number;
+        channels: string[];
+    }>;
+}
+export declare const MAX_GRID = 8000;
+/** ponytail: channels × grid points of one reference (2.4 MB raw); split references by channel group if a customer needs more. */
+export declare const MAX_BAND_CELLS = 131072;
+export declare function axisColumn(a: AlignAxis, units?: Record<string, string>): {
+    name: string;
+    unit: string;
+};
+export declare function localSeconds(t: number, tz: string): number;
+/** X of one segment's samples, fed in time order: history in one pass, live sample by sample. */
+export declare class AxisState {
+    #private;
+    readonly axis: AlignAxis;
+    constructor(axis: AlignAxis);
+    /** A segment starts at t0 (resets the state). */
+    begin(t0: number): void;
+    /** X at time t; `c` is the axis channel's value there (NaN when it has none). NaN when undefined (live: before an event). */
+    x(t: number, c: number): number;
+}
+/** A segment's samples (t and NaN-padded columns, e.g. wideDay of its pieces) on `axis`; `tstart` is its start. For
+ *  `event` the event is searched over the whole segment first, so samples before it get negative X. */
+export declare function alignSegment(t: Float64Array, cols: Map<string, Float64Array>, tstart: number, axis: AlignAxis): AlignedSegment;
+/** y(x) at the grid points: linear between finite neighbours; NaN outside the data or across a gap wider than 4× the
+ *  median step. Unsorted X (a noisy cumulative tag) is sorted first. */
+export declare function resample(x: Float64Array, y: ArrayLike<number>, grid: Float64Array): Float64Array;
+/** A grid array's value at x (linear; NaN outside the grid or next to a NaN). */
+export declare function gridAt(grid: Float64Array, a: ArrayLike<number>, x: number): number;
+/** The reference of `segs` on a uniform grid of `points` over their X range (one segment: σ 0, n 1). */
+export declare function buildReference(segs: AlignedSegment[], channels: string[], points: number): ReferenceCurve;
+/** A channel's band edges: mean ± k·σ, or min..max. */
+export declare function bandEdges(c: ReferenceChannel, k: number, band: 'sigma' | 'minmax'): {
+    lo: Float32Array;
+    hi: Float32Array;
+};
+export declare function compareToReference(seg: AlignedSegment, ref: ReferenceCurve, k: number, band?: 'sigma' | 'minmax', minS?: number): Comparison;
+/** A reference curve as bytes (plan Formats "Reference band", zlib). */
+export declare function encodeBand(ref: ReferenceCurve, channels: string[]): Uint8Array;
+export declare function decodeBand(bytes: Uint8Array, channels: string[]): ReferenceCurve;

package/dist/types/lib/segments/liveAxis.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Live against a reference (Historian phase 5; spec E3 "Live against reference"; plan S6): on every ingested block the
+ * definition's rule runs over the new samples, and the open segment's X on the alignment axis is written into the ring
+ * as a computed column (`column`), restarting at each segment, so the beacon chart (cycles on that column) draws the
+ * open segment over the reference dataset with no React at data rate. With a reference, `<channel> Δ` columns (value −
+ * reference mean at the same X) are written too, and every sample is checked against the band where the reference has
+ * ≥ 2 segments (a single reference gives a delta, never deviations; as compareToReference): `onEvent` fires only on
+ * transitions (open, close, deviation start once it lasted minDeviationS, deviation end after minDeviationS back in band). Work is per block: a few arrays per
+ * block, nothing allocated per sample.
+ */
+import { type LiveBuffer } from '../live/buffer';
+import { type AlignAxis } from './align';
+import { type DetectedSegment, type KpiSpec, type SegmentRule } from './rules';
+export declare const DELTA_SUFFIX = " \u0394";
+export interface LiveReference {
+    grid: Float64Array;
+    /** Per channel: mean and band edges on the grid, and the segments behind each point (the band counts where n ≥ 2). */
+    channels: Map<string, {
+        mean: Float32Array;
+        lo: Float32Array;
+        hi: Float32Array;
+        n: ArrayLike<number>;
+    }>;
+}
+export type LiveSegmentEvent = {
+    type: 'open';
+    tstart: number;
+} | {
+    type: 'close';
+    segment: DetectedSegment;
+} | {
+    type: 'deviation';
+    t0: number;
+    channels: string[];
+} | {
+    type: 'deviation-end';
+    t0: number;
+    t1: number;
+    channels: string[];
+};
+export interface LiveSegmentAxis {
+    rule: SegmentRule;
+    kpis?: KpiSpec[];
+    axis: AlignAxis;
+    /** The computed X column written into the ring, and its unit. */
+    column: string;
+    unit: string;
+    /** The open segment's start when the ring may no longer hold it (the collector's open segment), else null. */
+    start?: number | null;
+    reference?: LiveReference | null;
+    /** A deviation is reported once out of band this long (s); default 5. */
+    minDeviationS?: number;
+    onEvent?: (e: LiveSegmentEvent) => void;
+}
+export declare function liveSegmentTracker(cfg: LiveSegmentAxis): {
+    /** Samples from absolute index `from` on. `quiet`: no events (a replay of samples already seen). */
+    feed(buf: LiveBuffer, from: number, quiet?: boolean): void;
+};

package/dist/types/lib/segments/rules.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Segment rules (Historian phase 5; spec E1 "Segment definition"): where a stream is cut into segments, and the KPIs
+ * captured when a segment closes. One state machine for every use: a history read day by day (app segmentRun.ts), the
+ * live ring buffer (liveAxis.ts) and, from the same JSON, the collector (packages/collector/src/kymoscope_collector/
+ * segments.py), pinned by tests/vectors/segment-rules-v1.json. Semantics: the plan's Formats "Rule JSON". A NaN value
+ * never changes a rule. splitLaps (../beacon.ts) is the edge rule `reset` through resetStep.
+ */
+export type CompareOp = '>' | '>=' | '<' | '<=' | '==' | '!=';
+export type EdgeOn = 'change' | 'rise' | 'fall' | 'reset';
+export type SegmentRule = {
+    kind: 'manual';
+} | {
+    kind: 'edge';
+    channel: string;
+    on: EdgeOn;
+    value?: number;
+} | {
+    kind: 'condition';
+    channel: string;
+    op: CompareOp;
+    value: number;
+    hysteresis?: number;
+    min_s?: number;
+} | {
+    kind: 'window';
+    starts: string[];
+    tz: string;
+};
+export type KpiStat = 'min' | 'max' | 'mean' | 'integral' | 'first' | 'last' | 'delta';
+export declare const KPI_STATS: KpiStat[];
+export interface KpiSpec {
+    channel: string;
+    stat: KpiStat;
+}
+/** `duration` (s) and `<channel>:<stat>`; null when the channel had no sample in the segment. */
+export type Kpis = Record<string, number | null>;
+export interface DetectedSegment {
+    tstart: number;
+    tend: number | null;
+    kpis: Kpis;
+}
+export declare const kpiKey: (k: KpiSpec) => string;
+export declare const ruleChannels: (r: SegmentRule) => string[];
+export declare function compareOp(op: CompareOp, v: number, c: number): boolean;
+/** A cycle's running state for resetStep; prev NaN: nothing seen yet. */
+export interface ResetState {
+    prev: number;
+    lo: number;
+    hi: number;
+}
+export declare const newResetState: () => ResetState;
+/** One value through the reset rule (laps, battery cycles): true when it starts a new cycle, a drop larger than half
+ *  of the span seen since the cycle began, so jitter backwards never cuts. Mutates `s`. */
+export declare function resetStep(s: ResetState, v: number): boolean;
+/** Local wall clock minus UTC, in seconds, at instant t. */
+export declare function tzOffsetS(t: number, tz: string): number;
+/** The local date (YYYY-MM-DD) of t in tz. */
+export declare function localDay(t: number, tz: string): string;
+/** The instant of a local wall-clock time (a DST gap resolves forward, an overlap to the first occurrence). */
+export declare function zonedInstant(day: string, hhmm: string, tz: string): number;
+export declare const shiftDay: (day: string, n: number) => string;
+export declare class RuleRunner {
+    #private;
+    readonly rule: SegmentRule;
+    readonly kpis: KpiSpec[];
+    constructor(rule: SegmentRule, kpis?: KpiSpec[]);
+    /** Continue a segment that started at `tstart`, before the data fed from now on (a live ring that no longer holds it). */
+    assumeOpen(tstart: number): void;
+    /**
+     * Samples in time order; returns the segments they closed. `col(name)`: the column of a channel, aligned with `t`
+     * (NaN where it has no value), or undefined. `each(i, start)`: after sample i, the start of the open segment (a
+     * condition still shorter than min_s counts), null outside one.
+     */
+    feed(t: ArrayLike<number>, col: (name: string) => ArrayLike<number> | undefined, each?: (i: number, start: number | null) => void): DetectedSegment[];
+    /** The open segment so far (its KPIs up to the last sample; tend null), or null. A condition shows once it lasted min_s. */
+    open(): DetectedSegment | null;
+}

package/dist/types/lib/workspaces/io.d.ts

@@ -4,6 +4,7 @@ import type { PanelChartSettings } from '../panelChartSettings';
 import type { DashboardPanel, DashboardPanelKind } from '../../components/dashboardGridLayout';
 import type { BeaconConfig } from '../beacon';
 import type { MathChannel } from '../mathChannels/types';
+import type { SegmentContext } from '../../engine/types';
 type ExportedWorksheet = {
     name: string;
     xKey: string;
@@ -32,6 +33,8 @@ export interface WorkbookBody {
     liveWindowSeconds: number | null;
     /** Lap / cycle split, without the dataset it came from. */
     laps: BeaconConfig | null;
+    /** The Segments panel's ids (Historian phase 5); absent in older bodies. */
+    segments?: SegmentContext | null;
 }
 /** What `exportWorkspace()` returns (envelope v2 since cloud workbooks). */
 export type WorkspaceExportEnvelope = WorkbookBody;
@@ -74,6 +77,8 @@ export interface ParsedWorkbook extends ImportResult {
     mathChannels: WorkbookChannel[];
     liveWindowSeconds: number | null | undefined;
     laps: BeaconConfig | null | undefined;
+    /** Undefined: a body from before segments (keep the current context). */
+    segments: SegmentContext | null | undefined;
 }
 export type ParsedKymoscopeFile = {
     type: 'workspace';
@@ -100,6 +105,7 @@ export declare function buildWorkbookBody(s: {
     }>;
     liveWindowSeconds: number | null;
     laps: BeaconConfig | null;
+    segments?: SegmentContext | null;
 }): WorkbookBody;
 export declare function buildWorkspaceExportBlob(worksheets: Worksheet[]): Blob;
 export declare function buildWorksheetEnvelope(worksheet: Worksheet): WorksheetExportEnvelope;

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

@@ -26,3 +26,14 @@ export declare function formatTick(v: number, step: number): string;
  * at any scale (0.6523, 3.142, 12035), SI prefixes outside 0.001..1e6.
  */
 export declare function formatValue(v: number): string;
+/** X reads as clock time: a seconds axis ("Name (s)") whose both ends are Unix times of 2000–2100 (collector streams
+ *  and Historian ranges carry Unix seconds in ElapsedTime). */
+export declare function isClockAxis(xLabel: string, lo: number, hi: number): boolean;
+export declare function setClockTimeZone(tz: string | undefined): void;
+export declare const getClockTimeZone: () => string | undefined;
+export declare function subscribeClockTimeZone(cb: () => void): () => void;
+/** A clock tick (the clock zone unless `timeZone`): the date from a day's step, date and minutes across days, minutes,
+ *  seconds, then milliseconds. ponytail: ticks stay evenly spaced, not on round times; snap to round times if asked. */
+export declare function formatClockTick(v: number, step: number, span: number, timeZone?: string | undefined): string;
+/** The crosshair readout on a clock axis: date, year and time to the millisecond. */
+export declare function formatClockValue(v: number, timeZone?: string | undefined): string;

package/dist/types/rules/compile.d.ts

@@ -0,0 +1,47 @@
+import type { Derived, RuleDoc } from './types';
+/**
+ * A rule compiled for block evaluation: the condition tree flattened into ops in post-order (children before their
+ * parent, the root last), so each op fills one Int8Array of tri-states (0 false, 1 unknown, 2 true) per block with a
+ * plain typed loop. No closures per row.
+ */
+export type Op = {
+    k: 'above' | 'below' | 'outside' | 'inside' | 'equals' | 'changes' | 'noData';
+    i: number;
+    v: number;
+    lo: number;
+    hi: number;
+    h: number;
+    f: number;
+    prev: number;
+    /** Where the leaf writes: its own slot (mode 0), or straight into its all/any parent's (0 first, then min / max). */
+    into: number;
+    mode: 0 | 1 | 2;
+} | {
+    k: 'all' | 'any';
+    kids: number[]; /** the kids that are not leaves written into this slot */
+    rest: number[];
+    fused: boolean;
+} | {
+    k: 'not';
+    kid: number;
+};
+export interface Compiled {
+    aliases: string[];
+    base: number;
+    derived: Array<{
+        i: number;
+        d: Derived;
+        src: number[];
+    }>;
+    ops: Op[];
+    /** Per alias: a `changes` leaf reads its previous sample value. */
+    needPrev: boolean[];
+    /** Per alias: something reads the time of its last sample (a noData leaf, or staleS). */
+    needAt: boolean[];
+    /** The peak's signal (spec §2.3.6): the first leaf's alias and how far a value is past its threshold (> 0: past). */
+    first: {
+        i: number;
+        excess: (x: number) => number;
+    } | null;
+}
+export declare function compileRule(r: RuleDoc): Compiled;

package/dist/types/rules/evaluator.d.ts

@@ -0,0 +1,51 @@
+import type { RuleDoc } from './types';
+export interface RuleTarget {
+    kind: 'stream' | 'history' | 'dataset';
+    id: string;
+    name?: string;
+    tags?: Record<string, string>;
+}
+export type RuleStateName = 'disabled' | 'not_applicable' | 'waiting' | 'idle' | 'pending' | 'active' | 'clearing';
+export interface AlertTransition {
+    ruleId: string;
+    ruleVersion: number;
+    target: RuleTarget;
+    kind: 'raised' | 'cleared' | 'lost';
+    t: number;
+    peak?: {
+        v: number;
+        t: number;
+    };
+}
+export interface RuleEvaluatorState {
+    state: RuleStateName;
+    missing?: string[];
+    since?: number;
+    late: number;
+    lastT: number;
+}
+export interface LiveBlock {
+    t: Float64Array;
+    columns: Record<string, Float64Array | undefined>;
+    /** Optional: pass the same (empty) map with one block to every evaluator that reads it, and the per-column checks
+     *  (no NaN, ascending time) run once per block instead of once per rule. Don't reuse it for another block. */
+    scan?: Map<string, boolean>;
+}
+/**
+ * One rule on one target (spec §2.3). Pure: no DOM, no timers. `bind` with the target's channel names whenever they
+ * change, `push` appended rows in time order, `tick` to advance the timed parts (noData, forS, clearForS).
+ *
+ * A block is evaluated column-wise: first the rows the rule evaluates (a sample of one of its signals, later than the
+ * last evaluated time), then per alias the held value / time of its last sample / "new sample here" arrays, then one
+ * typed loop per condition op, then the state machine over the root's tri-states. A block where every signal has a
+ * sample on every row in ascending time (the common live case) uses the columns as they are, without copying.
+ */
+export declare function createRuleEvaluator(rule: RuleDoc, target: RuleTarget): {
+    rule: RuleDoc;
+    target: RuleTarget;
+    bind: (names: Iterable<string>) => AlertTransition[];
+    push: (block: LiveBlock) => AlertTransition[];
+    tick: (now: number) => AlertTransition[];
+    state: () => RuleEvaluatorState;
+};
+export type RuleEvaluator = ReturnType<typeof createRuleEvaluator>;