@kymoscope/sdk 0.4.0 → 0.5.0

package/dist/types/charts/useWorksheetData.d.ts

@@ -51,6 +51,8 @@ export declare function staticXExtent(parts: {
     rows: Record<string, unknown>[];
     offset: number;
 }[], xKey: string): [number, number] | null;
+/** Unit per column, plus each column's suffixed key (e.g. "FZ__0") per overlaid source. */
+export declare function overlayColumnUnits(data: Pick<Dataset, 'columnNames' | 'units'>, sources: number): Record<string, string>;
 /**
  * Rows of the current lap on a wrapping X: from the last sample where X drops by
  * more than half its range (lap distance at the finish line). A channel that

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

@@ -18,6 +18,8 @@ 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';
@@ -48,6 +50,8 @@ export interface InternalState {
     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[];
@@ -135,7 +139,10 @@ 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>;
         /**
@@ -169,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;
@@ -315,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;

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

@@ -4,6 +4,7 @@ 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';
@@ -76,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;
@@ -95,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';
@@ -130,7 +154,7 @@ export interface LiveConnectionInfo {
     id: string;
     name: string;
     ownerName: string;
-    visibility: 'private' | 'public' | 'org' | 'project';
+    visibility: 'private' | 'public' | 'org' | 'project' | 'open';
     orgName: string | null;
     /** A camera carries video (a camera panel shows it); a data stream, samples. */
     kind: 'data' | 'camera';
@@ -170,6 +194,8 @@ export interface EngineState {
     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[];

package/dist/types/index.d.ts

@@ -13,7 +13,7 @@ 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';
@@ -73,7 +73,7 @@ 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, historyKeyAad, projectConfigKeyAad, alertRuleAad, 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';
@@ -86,7 +86,9 @@ 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 { 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';

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;

package/dist/types/lib/cycles/evaluator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Cycle rules v2 (spec docs/superpowers/specs/2026-10-28-cycles-design.md, "Rules"): where a source is cut into cycles,
+ * and phases inside them. Boundaries and flags only; KPIs are the app's job. The collector runs the same semantics
+ * (packages/collector/src/kymoscope_collector/cycles.py), pinned by tests/vectors/cycle-rules-v2.json. Saved v1 rules
+ * (segment_definitions rule_v 1) keep running through ../segments/rules.ts RuleRunner.
+ *
+ * Semantics:
+ * - A start fires when its trigger becomes true (a condition rising, or an event: change, cross, reset, clock,
+ *   parent-start). With minHold_s, a condition start must stay true that long; the cycle starts when it first held.
+ * - An end fires while its trigger is true, from the sample after the start on. With ignoreDips_s, a condition end must
+ *   stay true that long; the cycle ends when it first held. `next-start`: each start closes the previous cycle.
+ * - A NaN value never changes a condition. A phase only sees samples inside its parent and closes with it (incomplete
+ *   unless its end names parent-end).
+ * - Limits never drop a cycle; a missed one adds a flag: late (expectedWithin_s from the parent's or its own start),
+ *   too-long (max_s), too-short (min_s).
+ */
+import { type CompareOp, type KpiSpec } from '../segments/rules';
+export type Condition = {
+    kind: 'compare';
+    channel: string;
+    op: CompareOp;
+    value: number;
+} | {
+    kind: 'change';
+    channel: string;
+} | {
+    kind: 'cross';
+    channel: string;
+    dir: 'rise' | 'fall';
+    value: number;
+} | {
+    kind: 'reset';
+    channel: string;
+} | {
+    kind: 'elapsed';
+    from: 'parent-start' | 'start';
+    op: '>=' | '<=';
+    seconds: number;
+} | {
+    kind: 'clock';
+    at: string[];
+    tz: string;
+};
+export type Trigger = {
+    kind: 'parent-start';
+} | {
+    kind: 'parent-end';
+} | {
+    kind: 'next-start';
+} | {
+    kind: 'manual';
+} | {
+    kind: 'all' | 'any';
+    of: Trigger[];
+} | Condition;
+export interface CycleLimits {
+    expectedWithin_s?: number;
+    from?: 'parent-start' | 'start';
+    min_s?: number;
+    max_s?: number;
+}
+export interface CycleRule {
+    start: Trigger;
+    end: Trigger;
+    minHold_s?: number;
+    ignoreDips_s?: number;
+    limits?: CycleLimits;
+}
+export type CycleFlag = 'late' | 'too-long' | 'too-short';
+export interface CycleInstance {
+    tstart: number;
+    tend: number | null;
+    flags: CycleFlag[];
+    incomplete?: true;
+}
+/** Every channel a rule reads. */
+export declare function cycleRuleChannels(r: CycleRule): string[];
+export declare class CycleRunner {
+    #private;
+    readonly rule: CycleRule;
+    constructor(rule: CycleRule);
+    /** A phase's parent opened: state starts over. Top-level rules never need it (the first sample is the start). */
+    parentStart(t: number): void;
+    /** The parent closed at t: an open phase closes with it. */
+    parentEnd(t: number, out: CycleInstance[]): void;
+    /** One sample, in time order; closed cycles are pushed to `out`. */
+    step(t: number, v: (channel: string) => number, out: CycleInstance[]): void;
+    /** The open cycle so far (flags up to the last sample), or null. */
+    open(): CycleInstance | null;
+}
+export interface RuleDef {
+    id: string;
+    rule: CycleRule;
+    parentId: string | null;
+}
+export interface CycleFound extends CycleInstance {
+    definitionId: string;
+    index: number;
+    parentIndex?: number;
+    /** Its definition's KPIs by column name ("TIC201 max"), when asked for (engine.datasets.findCycles). */
+    kpis?: Record<string, number | null>;
+}
+/**
+ * Definitions evaluated together, phases inside their parents. Indexes count per definition from 1 (a phase's within
+ * its parent). ponytail: a parent whose start waits for minHold_s opens after the fact, so its phases only see samples
+ * from the moment it was confirmed; buffer the held samples if a phase ever needs them.
+ */
+export declare class CycleSet {
+    #private;
+    constructor(defs: RuleDef[]);
+    /** Samples in time order; returns the cycles and phases they closed. `col(name)`: a channel's column aligned with
+     *  `t` (NaN where it has no value), or undefined. */
+    feed(t: ArrayLike<number>, col: (name: string) => ArrayLike<number> | undefined): CycleFound[];
+    /** The cycles and phases open now. */
+    open(): CycleFound[];
+}
+/** A saved rule: a cycle (parentId null) or a phase inside another definition. `kpis`: a column per KPI in the cycles
+ *  and phases tables (duration is always there). */
+export interface CycleDefinition extends RuleDef {
+    name: string;
+    kpis?: KpiSpec[];
+    /** The value beside each cycle (in a cut's list): a channel's statistic over the cycle; absent, its duration. */
+    show?: KpiSpec;
+}
+/** The definitions in `x` that are well formed (a workbook from anywhere: trust nothing); a phase whose parent is
+ *  missing is dropped too. */
+export declare function parseCycleDefinitions(x: unknown): CycleDefinition[];

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

@@ -15,6 +15,9 @@ export interface EncryptedEnvelope {
     iv: string;
     ciphertext: string;
 }
+/** An open stream's password (visibility 'open', spec 2026-10-31-stream-access-model): anyone watches with nothing
+ *  typed, so its key derives from this published text. Not end-to-end encrypted, by design. Same in Python and plugins. */
+export declare const OPEN_STREAM_PASSWORD = "kymoscope-open-stream-v1";
 /** Random 16-byte KDF salt, base64-encoded. Stored server-side; not secret. */
 export declare function generateSalt(): string;
 /** Derive an AES-256-GCM key from a passphrase + base64 salt via PBKDF2. */

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

@@ -48,7 +48,10 @@ export interface PublisherOptions {
     name: string;
     kind: 'data' | 'camera';
     /** Where the stream goes is the API key's: a project's key publishes into that project, a personal key a personal stream. */
-    visibility?: 'private' | 'public';
+    visibility?: 'private' | 'public' | 'open';
+    /** The stream password viewers type (spec 2026-10-31-stream-access-model); default: the API key's secret. 'open'
+     *  streams take none: anyone watches them (a published password; not end-to-end encrypted). */
+    password?: string;
     /** The caller's own data stream a camera belongs to (required for kind 'camera'); its placement comes from it. */
     parentStreamId?: string;
     /** A camera's low layer (360p, for small panels and camera walls): `layer: 'low'` with `lowOf`, its high camera's
@@ -75,6 +78,8 @@ export declare class LivePublisher {
     private readonly deps;
     private readonly auth;
     private readonly secret;
+    /** What the stream key derives from: the stream password, the open streams' published one, or the API key's secret. */
+    private readonly password;
     private token;
     private ticket;
     /** The current ticket says rec (the reply's `recording`); `authRec`: the one the open socket authenticated with. */

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

@@ -14,7 +14,7 @@ export interface LiveStreamDescriptor {
     /** Encrypted marker proving the password is right before any frame arrives. */
     key_check: EncryptedEnvelope;
     owner_name?: string;
-    visibility?: 'private' | 'public' | 'org' | 'project';
+    visibility?: 'private' | 'public' | 'org' | 'project' | 'open';
     org_name?: string | null;
     /** Null when the viewer can't see the project's name. */
     project_name?: string | null;
@@ -65,7 +65,7 @@ export interface LiveConnection {
     id: string;
     name: string;
     ownerName: string;
-    visibility: 'private' | 'public' | 'org' | 'project';
+    visibility: 'private' | 'public' | 'org' | 'project' | 'open';
     orgName: string | null;
     projectName?: string | null;
     kind: 'data' | 'camera';

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

@@ -11,6 +11,7 @@
 import { type LiveBuffer } from '../live/buffer';
 import { type AlignAxis } from './align';
 import { type DetectedSegment, type KpiSpec, type SegmentRule } from './rules';
+import { type CycleRule } from '../cycles/evaluator';
 export declare const DELTA_SUFFIX = " \u0394";
 export interface LiveReference {
     grid: Float64Array;
@@ -39,7 +40,11 @@ export type LiveSegmentEvent = {
     channels: string[];
 };
 export interface LiveSegmentAxis {
-    rule: SegmentRule;
+    /** A segment rule (v1); unused with `cycle`. */
+    rule?: SegmentRule;
+    /** A cycle rule (rules v2) instead of `rule` ("Follow the running cycle" on a cycle rule): its cycles open and close
+     *  the axis; KPIs are not computed live for it. */
+    cycle?: CycleRule;
     kpis?: KpiSpec[];
     axis: AlignAxis;
     /** The computed X column written into the ring, and its unit. */
@@ -48,6 +53,8 @@ export interface LiveSegmentAxis {
     /** 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;
+    /** Also report the cycles already in the ring when it starts (open / close events for them); default: only new ones. */
+    replay?: boolean;
     /** A deviation is reported once out of band this long (s); default 5. */
     minDeviationS?: number;
     onEvent?: (e: LiveSegmentEvent) => void;

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

@@ -38,6 +38,8 @@ export interface DetectedSegment {
     tstart: number;
     tend: number | null;
     kpis: Kpis;
+    /** A cycle rule's (v2) missed limits. */
+    flags?: Array<'late' | 'too-long' | 'too-short'>;
 }
 export declare const kpiKey: (k: KpiSpec) => string;
 export declare const ruleChannels: (r: SegmentRule) => string[];
@@ -59,6 +61,18 @@ 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 KpiAcc {
+    n: number;
+    sum: number;
+    min: number;
+    max: number;
+    first: number;
+    last: number;
+    integral: number;
+    lastT: number;
+    add(t: number, v: number): void;
+    value(stat: KpiStat): number | null;
+}
 export declare class RuleRunner {
     #private;
     readonly rule: SegmentRule;

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

@@ -5,6 +5,7 @@ import type { DashboardPanel, DashboardPanelKind } from '../../components/dashbo
 import type { BeaconConfig } from '../beacon';
 import type { MathChannel } from '../mathChannels/types';
 import type { SegmentContext } from '../../engine/types';
+import { type CycleDefinition } from '../cycles/evaluator';
 type ExportedWorksheet = {
     name: string;
     xKey: string;
@@ -35,6 +36,8 @@ export interface WorkbookBody {
     laps: BeaconConfig | null;
     /** The Segments panel's ids (Historian phase 5); absent in older bodies. */
     segments?: SegmentContext | null;
+    /** Cycle and phase rules (lib/cycles); absent in older bodies. */
+    cycles?: CycleDefinition[];
 }
 /** What `exportWorkspace()` returns (envelope v2 since cloud workbooks). */
 export type WorkspaceExportEnvelope = WorkbookBody;
@@ -79,6 +82,8 @@ export interface ParsedWorkbook extends ImportResult {
     laps: BeaconConfig | null | undefined;
     /** Undefined: a body from before segments (keep the current context). */
     segments: SegmentContext | null | undefined;
+    /** Cycle and phase rules; [] in bodies without them. */
+    cycles: CycleDefinition[];
 }
 export type ParsedKymoscopeFile = {
     type: 'workspace';
@@ -106,6 +111,7 @@ export declare function buildWorkbookBody(s: {
     liveWindowSeconds: number | null;
     laps: BeaconConfig | null;
     segments?: SegmentContext | null;
+    cycles?: CycleDefinition[];
 }): WorkbookBody;
 export declare function buildWorkspaceExportBlob(worksheets: Worksheet[]): Blob;
 export declare function buildWorksheetEnvelope(worksheet: Worksheet): WorksheetExportEnvelope;

package/dist/types/types/loadedDataset.d.ts

@@ -2,6 +2,7 @@ import type { Dataset, DatasetParseConfig } from '../lib/parseDataset';
 import type { DataSource, ColumnSchema } from '../lib/data/dataSource';
 import type { BeaconConfig } from '../lib/beacon';
 import type { DatasetFileInfo } from '../lib/importers/types';
+import type { CycleDefinition, CycleFound } from '../lib/cycles/evaluator';
 export interface LoadedDataset {
     id: string;
     name: string;
@@ -37,11 +38,25 @@ export interface LoadedDataset {
     columnSpares?: Map<string, Float64Array>;
     /** Beacon lap split; when set, the dataset is shown/selected as its laps. */
     beacon?: BeaconConfig;
+    /** Cut into cycles by a rule (datasets.cut): shown and selected as its cycles and their phases, as laps are. Wins over `beacon`. */
+    cut?: DatasetCut;
     /** Shaded bands under a column's trace (a reference's envelope): per column, low and high edges aligned with the rows. */
     bands?: Record<string, {
         lo: Float64Array;
         hi: Float64Array;
     }>;
 }
+/** A dataset cut into cycles: the rule, what it found, and one dataset per cycle or phase. Never stored: a workbook keeps
+ *  rules, not cycles (a workbook opens with other data). */
+export interface DatasetCut {
+    /** The cycle's definition (`cycleId`) and its phases. */
+    defs: CycleDefinition[];
+    cycleId: string;
+    timeKey: string;
+    /** Cycles and phases by start time, with their definition's KPIs. */
+    found: CycleFound[];
+    /** One per `found` (same order): its samples with `Cycle time` (s since its start); id `<dataset id>::<key>`. */
+    parts: LoadedDataset[];
+}
 /** True when the dataset's rows are materialized in memory (small files). */
 export declare function isInMemory(ld: LoadedDataset): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kymoscope/sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Kymoscope data engine and charts for the browser: import large measurement files, plot them, stream live data end-to-end encrypted.",
   "license": "SEE LICENSE IN LICENSE.md",
   "homepage": "https://kymoscope.com/docs/introduction",