@kymoscope/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,438 @@
+import type { XYZViewMode } from '../components/XYZMeshChart';
+import type { AlarmLine, PlotSeries } from '../types/plotSeries';
+import { type ChartAnnotation } from './annotations';
+import type { GaugeColorMode, GaugeColorStop } from './gaugeColors';
+export interface XyAxisScaleSettings {
+    scaleMin: string;
+    scaleMax: string;
+    majorStep: string;
+    minorStep: string;
+    alarm: AlarmLine | null;
+}
+export declare function defaultXyAxisScaleSettings(): XyAxisScaleSettings;
+export type XyFitDegree = 1 | 2 | 3;
+export interface XyFitSettings {
+    degree: XyFitDegree;
+    color: string;
+    lineStyle: 'solid' | 'dashed' | 'dotted';
+    width: number;
+}
+export type AxisLineStyleStr = 'none' | 'solid' | 'dashed' | 'dotted';
+export interface AxisLineStyle {
+    style: AxisLineStyleStr;
+    /** Stroke width in CSS pixels (0.5–4). */
+    width: number;
+    /** Hex color, or null = use the chart's theme default. */
+    color: string | null;
+}
+export declare const DEFAULT_AXIS_LINE: AxisLineStyle;
+export declare const DEFAULT_GRID_LINE: AxisLineStyle;
+export interface MultibandPanelChartSettings {
+    kind: 'multiband';
+    series: PlotSeries[];
+    addColumn: string;
+    /** 'overlay' = bands set by bandFromPct/bandToPct; 'parallel' = equal bands auto-computed from series order. */
+    layout: 'overlay' | 'parallel';
+    xAxisLine: AxisLineStyle;
+    yAxisLine: AxisLineStyle;
+    gridLine: AxisLineStyle;
+    /** Data trace thickness in CSS px (0.5–6). */
+    lineWidth: number;
+    /** Beacon: while live, show only the current cycle (X starting over — a lap,
+     *  a battery cycle…) against reference data. Unset = off. */
+    beacon?: BeaconSettings;
+    /** With several datasets or laps plotted: shade each series' min–max envelope across them. */
+    envelope?: boolean;
+}
+/** What sits behind the current cycle when the beacon is on. */
+export type BeaconReference = 'dataset' | 'previous' | 'none';
+export interface BeaconSettings {
+    enabled: boolean;
+    reference: BeaconReference;
+    /** Dataset (or lap) id for `reference: 'dataset'`. */
+    datasetId: string | null;
+    datasetColor: string;
+    previousColor: string;
+}
+export declare const DEFAULT_BEACON: BeaconSettings;
+export type XyDrawMode = 'points' | 'lines' | 'both';
+export interface XyPanelChartSettings {
+    kind: 'xyscatter';
+    xyXCol: string;
+    xyYCol: string;
+    /** Optional 3rd column used to color points by value (colormap). Null = solid color. */
+    xyColorCol: string | null;
+    xyColor: string;
+    xyPointRadius: number;
+    /** Points, a line through them in data order, or both (absent: points). */
+    xyDrawMode?: XyDrawMode;
+    /** Line width in CSS px when drawn as a line (absent: 1). */
+    xyLineWidth?: number;
+    xyXAxisLine: AxisLineStyle;
+    xyYAxisLine: AxisLineStyle;
+    xyGridLine: AxisLineStyle;
+    xyFit: XyFitSettings | null;
+    xyXScale: XyAxisScaleSettings;
+    xyYScale: XyAxisScaleSettings;
+}
+export interface XyzPanelChartSettings {
+    kind: 'xyzmesh';
+    xyzXCol: string;
+    xyzYCol: string;
+    xyzZCol: string;
+    xyzViewMode: XYZViewMode;
+    xyzXScale: XyAxisScaleSettings;
+    xyzYScale: XyAxisScaleSettings;
+    xyzZScale: XyAxisScaleSettings;
+    xyzPointRadius: number;
+    /** Show Delaunay surface mesh over the scatter. Default false. */
+    showMesh: boolean;
+    /** How to draw the mesh. Default 'filled'. */
+    meshStyle: 'filled' | 'wireframe' | 'both';
+    /** Fill opacity for triangles (0–1). Default 0.85. */
+    meshOpacity: number;
+    /**
+     * points (default): one point per row at (X, Y, Z). matrix: a surface over a
+     * uniform grid, the rows along X, the `xyzColumns` along Y, each value a height.
+     */
+    xyzMode?: 'points' | 'matrix';
+    xyzColumns?: string[];
+}
+export interface HistogramPanelChartSettings {
+    /** Alarm line on the X axis (a value); null or missing: none. */
+    histAlarm?: AlarmLine | null;
+    kind: 'histogram';
+    histColumn: string;
+    histBins: number;
+    histColor: string;
+    histNormal: boolean;
+    histLogY: boolean;
+}
+export interface PolarPanelChartSettings {
+    kind: 'polar';
+    polarAngleCol: string;
+    polarRadiusCol: string;
+    polarColor: string;
+    polarMode: 'waveform' | 'rose';
+    polarRadiusMin: string;
+    polarRadiusMax: string;
+}
+export interface SpectrumPanelChartSettings {
+    /** Alarm line on the Y axis (amplitude, in the Y mode's unit); null or missing: none. */
+    specAlarm?: AlarmLine | null;
+    kind: 'spectrum';
+    specSignalCol: string;
+    specTimeCol: string;
+    specSampleRate: string;
+    specXMode: 'hz' | 'order';
+    specYMode: 'amplitude' | 'db';
+    specWindow: 'hann' | 'rectangular';
+    specColor: string;
+    specLogX: boolean;
+}
+export interface BoxPlotPanelChartSettings {
+    /** Alarm line on the value axis; null or missing: none. */
+    boxAlarm?: AlarmLine | null;
+    kind: 'boxplot';
+    boxValueCol: string;
+    boxGroupCol: string;
+    boxColor: string;
+    boxWhiskers: '1.5iqr' | 'minmax';
+}
+export interface SpectrogramPanelChartSettings {
+    kind: 'spectrogram';
+    sgSignalCol: string;
+    sgTimeCol: string;
+    sgSampleRate: string;
+    sgWindowSize: number;
+    sgOverlap: number;
+    sgWinFunc: 'hann' | 'rectangular';
+    sgYMode: 'amplitude' | 'db';
+    sgLogFreq: boolean;
+    /** '2d': a time × frequency colour map; 'waterfall': the same in 3-D, level as height. Missing: '2d'. */
+    sgView?: '2d' | 'waterfall';
+}
+export interface HeatmapPanelChartSettings {
+    kind: 'heatmap';
+    /** matrix: the rows along X, the `hmColumns` along Y, each cell a value (a uniform grid). */
+    hmMode: 'correlation' | 'raw' | 'binned' | 'count' | 'matrix';
+    hmColumns: string[];
+    hmXCol: string;
+    hmYCol: string;
+    hmValueCol: string;
+    hmXBins: number;
+    hmYBins: number;
+    hmXMin: string;
+    hmXMax: string;
+    hmYMin: string;
+    hmYMax: string;
+    hmShowValues: boolean;
+    /** Fixed colour range ('' or absent: from the data). */
+    hmRange?: {
+        scaleMin: string;
+        scaleMax: string;
+    };
+    hmColorScheme: 'diverging' | 'plasma' | 'viridis';
+    /**
+     * 'values' (matrix and raw modes): cells sized by their positions instead of
+     * evenly, for breakpoint tables such as engine maps. Matrix: X from the
+     * worksheet's X values, Y from the numbers in the column names; raw: from the
+     * X and Y values. Rows then run with the larger value at the top. Missing: 'uniform'.
+     */
+    hmSpacing?: 'uniform' | 'values';
+    /** Isolines at this many evenly spaced levels across the colour range (0 or missing: none). */
+    hmContours?: number;
+}
+export interface ViolinPanelChartSettings {
+    /** Alarm line on the value axis (follows the orientation); null or missing: none. */
+    vlAlarm?: AlarmLine | null;
+    kind: 'violin';
+    vlValueCol: string;
+    vlGroupCol: string;
+    vlColor: string;
+    vlShowBox: boolean;
+    vlBandwidth: string;
+    vlOrientation: 'vertical' | 'horizontal';
+}
+export interface ConfusionPanelChartSettings {
+    kind: 'confusion';
+    cfActualCol: string;
+    cfPredictedCol: string;
+    cfNormalize: boolean;
+}
+export interface RocPanelChartSettings {
+    kind: 'roc';
+    rocScoreCol: string;
+    rocLabelCol: string;
+    rocMode: 'roc' | 'pr';
+    rocColor: string;
+}
+export interface LossCurvePanelChartSettings {
+    /** Alarm line on the left Y axis; null or missing: none. */
+    lcAlarm?: AlarmLine | null;
+    kind: 'losscurve';
+    lcXCol: string;
+    lcLeftCols: {
+        column: string;
+        color: string;
+    }[];
+    lcRightCols: {
+        column: string;
+        color: string;
+    }[];
+}
+export interface ControlChartPanelChartSettings {
+    kind: 'controlchart';
+    ccValueCol: string;
+    ccSubgroupCol: string;
+    ccSigmaLevel: number;
+    ccColor: string;
+}
+export interface ParallelCoordsPanelChartSettings {
+    kind: 'parallelcoords';
+    pcColumns: string[];
+    pcColorByCol: string;
+    pcColor: string;
+}
+export interface EmbeddingPanelChartSettings {
+    kind: 'embedding';
+    emXCol: string;
+    emYCol: string;
+    emColorCol: string;
+    emColorMode: 'numeric' | 'categorical';
+    emLabelCol: string;
+    emPointSize: number;
+    emColor: string;
+}
+export interface FlameGraphPanelChartSettings {
+    kind: 'flamegraph';
+    fgNameCol: string;
+    fgParentCol: string;
+    fgValueCol: string;
+    fgDirection: 'topdown' | 'bottomup';
+}
+export interface BarChartPanelChartSettings {
+    /** Alarm line on the value axis (follows the orientation); null or missing: none. */
+    bcAlarm?: AlarmLine | null;
+    kind: 'barchart';
+    bcCategoryCol: string;
+    bcValueCols: string[];
+    bcMode: 'grouped' | 'stacked';
+    bcHorizontal: boolean;
+    /** Fixed value range ('' or absent: from the data). */
+    bcValueScale?: {
+        scaleMin: string;
+        scaleMax: string;
+    };
+}
+export interface RadarPanelChartSettings {
+    kind: 'radar';
+    rdAxesCols: string[];
+    rdGroupCol: string;
+    rdColor: string;
+    rdFill: boolean;
+}
+export interface AreaChartPanelChartSettings {
+    /** Alarm line on the Y axis; null or missing: none. */
+    acAlarm?: AlarmLine | null;
+    kind: 'areachart';
+    acXCol: string;
+    acYCols: string[];
+    acStacked: boolean;
+    /** Fixed Y range ('' or absent: from the data). */
+    acYScale?: {
+        scaleMin: string;
+        scaleMax: string;
+    };
+}
+export interface CdfChartPanelChartSettings {
+    /** Alarm line on the X axis (a value); null or missing: none. */
+    cdAlarm?: AlarmLine | null;
+    kind: 'cdfchart';
+    cdValueCols: string[];
+    cdComplement: boolean;
+    cdLogX: boolean;
+}
+export interface BubbleChartPanelChartSettings {
+    /** Alarm line on the Y axis; null or missing: none. */
+    bbAlarm?: AlarmLine | null;
+    kind: 'bubblechart';
+    bbXCol: string;
+    bbYCol: string;
+    bbSizeCol: string;
+    bbColorCol: string;
+    bbColorMode: 'numeric' | 'categorical';
+    bbColor: string;
+    bbMaxRadius: number;
+}
+export interface TreemapPanelChartSettings {
+    kind: 'treemap';
+    tmNameCol: string;
+    tmParentCol: string;
+    tmValueCol: string;
+}
+export interface SankeyPanelChartSettings {
+    kind: 'sankey';
+    skSourceCol: string;
+    skTargetCol: string;
+    skValueCol: string;
+}
+/** One gauge: a channel and how it is shown. */
+export interface GaugeItem {
+    id: string;
+    column: string;
+    color: string;
+    /** What it shows of its column: the latest value (follows a live stream), or the mean, minimum or maximum. */
+    value: 'last' | 'mean' | 'min' | 'max';
+    style: 'arc' | 'linear';
+    /** Scale ends ('' = from the column's data, rounded). */
+    min: string;
+    max: string;
+    /** Marked on the scale; past it the gauge takes its colour. Null or missing: none. */
+    alarm?: AlarmLine | null;
+    /**
+     * 'solid' (missing): `color`. 'gradient': blended through `stops`; 'zones':
+     * each stop's colour from its value to the next stop's. The whole scale shows
+     * the colours faintly; the filled part and the value take them.
+     */
+    colorMode?: GaugeColorMode;
+    /** Colour stops at values of the channel (gradient and zones). */
+    stops?: GaugeColorStop[];
+}
+export interface GaugePanelChartSettings {
+    kind: 'gauge';
+    /** The gauges, in order. */
+    ggGauges: GaugeItem[];
+}
+/** A new gauge for a column: the next colour of the list, its latest value on an arc. */
+export declare function newGaugeItem(column: string, index: number): GaugeItem;
+export interface CalibrationPanelChartSettings {
+    kind: 'calibration';
+    cbScoreCol: string;
+    cbLabelCol: string;
+    cbBins: number;
+    cbColor: string;
+}
+export interface QQPlotPanelChartSettings {
+    kind: 'qqplot';
+    qqValueCol: string;
+    qqMode: 'normal' | 'column';
+    qqRefCol: string;
+    qqColor: string;
+}
+export interface GanttPanelChartSettings {
+    /** Alarm line on the time (X) axis; null or missing: none. */
+    gtAlarm?: AlarmLine | null;
+    kind: 'gantt';
+    gtLabelCol: string;
+    gtStartCol: string;
+    gtEndCol: string;
+    gtGroupCol: string;
+}
+/** 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);
+/** 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. */
+export declare const DEFAULT_XY_POINT_RADIUS = 1.8;
+export declare const DEFAULT_XYZ_POINT_RADIUS = 4;
+export declare const DEFAULT_TRACE_WIDTH = 1;
+export declare function defaultMultibandPanelSettings(): MultibandPanelChartSettings;
+export declare function defaultXyPanelSettings(xyColorFallback: string): XyPanelChartSettings;
+export declare function defaultXyzPanelSettings(xyzPointRadiusFallback?: number): XyzPanelChartSettings;
+export declare function defaultHistogramPanelSettings(): HistogramPanelChartSettings;
+export declare function defaultPolarPanelSettings(): PolarPanelChartSettings;
+export declare function defaultSpectrumPanelSettings(): SpectrumPanelChartSettings;
+export declare function defaultBoxPlotPanelSettings(): BoxPlotPanelChartSettings;
+export declare function defaultSpectrogramPanelSettings(): SpectrogramPanelChartSettings;
+export declare function defaultHeatmapPanelSettings(): HeatmapPanelChartSettings;
+export declare function defaultViolinPanelSettings(): ViolinPanelChartSettings;
+export declare function defaultConfusionPanelSettings(): ConfusionPanelChartSettings;
+export declare function defaultRocPanelSettings(): RocPanelChartSettings;
+export declare function defaultLossCurvePanelSettings(): LossCurvePanelChartSettings;
+export declare function defaultControlChartPanelSettings(): ControlChartPanelChartSettings;
+export declare function defaultParallelCoordsPanelSettings(): ParallelCoordsPanelChartSettings;
+export declare function defaultEmbeddingPanelSettings(): EmbeddingPanelChartSettings;
+export declare function defaultFlameGraphPanelSettings(): FlameGraphPanelChartSettings;
+export declare function defaultBarChartPanelSettings(): BarChartPanelChartSettings;
+export declare function defaultRadarPanelSettings(): RadarPanelChartSettings;
+export declare function defaultAreaChartPanelSettings(): AreaChartPanelChartSettings;
+export declare function defaultCdfChartPanelSettings(): CdfChartPanelChartSettings;
+export declare function defaultBubbleChartPanelSettings(): BubbleChartPanelChartSettings;
+export declare function defaultTreemapPanelSettings(): TreemapPanelChartSettings;
+export declare function defaultSankeyPanelSettings(): SankeyPanelChartSettings;
+export declare function defaultGaugePanelSettings(): GaugePanelChartSettings;
+export declare function defaultCalibrationPanelSettings(): CalibrationPanelChartSettings;
+export declare function defaultQQPlotPanelSettings(): QQPlotPanelChartSettings;
+export declare function defaultGanttPanelSettings(): GanttPanelChartSettings;
+/** An alarm line from untrusted input, or null. */
+export declare function coerceAlarmLine(v: unknown): AlarmLine | null;
+/** The setting holding the alarm line of the chart kinds whose frame draws it. */
+export declare const CHART_ALARM_FIELDS: {
+    readonly histogram: "histAlarm";
+    readonly spectrum: "specAlarm";
+    readonly areachart: "acAlarm";
+    readonly losscurve: "lcAlarm";
+    readonly cdfchart: "cdAlarm";
+    readonly bubblechart: "bbAlarm";
+    readonly boxplot: "boxAlarm";
+    readonly violin: "vlAlarm";
+    readonly barchart: "bcAlarm";
+    readonly gantt: "gtAlarm";
+};
+/** A chart's alarm line and the axis it sits on (null: none, or a kind that draws its own). */
+export declare function chartAlarm(s: PanelChartSettings | undefined): {
+    alarm: AlarmLine;
+    axis: 'x' | 'y';
+} | null;
+/** Validate and clamp radii; drop invalid entries. */
+export declare function parsePanelChartSettingsMap(raw: unknown, _defaultXyColor: string, _defaultXyzRadius: number): Record<string, PanelChartSettings>;
+/** Ensure every xyscatter / xyzmesh panel has an entry (fill from defaults). */
+export declare function ensurePanelSettingsForPanels(panels: {
+    id: string;
+    kind: string;
+}[], current: Record<string, PanelChartSettings>, defaultXyColor: string, defaultXyzRadius: number): Record<string, PanelChartSettings>;

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

@@ -0,0 +1,74 @@
+/**
+ * Tabular data parser. Accepts .dat files (header + units + tab-separated
+ * data, optionally with a meta header line) and CSV/TSV with comma,
+ * semicolon, or tab delimiters and an optional units row.
+ */
+import { type ColumnTable } from './columnTable';
+export type DatasetRow = Record<string, number | string | null>;
+export interface Dataset {
+    meta: string;
+    columnNames: string[];
+    units: string[];
+    rows: DatasetRow[];
+}
+/** Indices (0-based) into the non-empty lines array returned by getRawNonEmptyLines. */
+export interface DatasetParseConfig {
+    headerRow: number;
+    unitsRow: number | null;
+    dataStartRow: number;
+}
+type Delimiter = '\t' | ',' | ';';
+/**
+ * Whether the data uses a comma as the decimal separator (European locale).
+ * Only possible when the field delimiter is not itself a comma. Decided by
+ * comparing how many cells look like "12,5" vs "12.5" across a sample.
+ */
+export declare function detectDecimalComma(lines: string[], delim: '\t' | ',' | ';'): boolean;
+export declare function detectDelimiter(headerLine: string): Delimiter;
+/**
+ * Parse .dat or CSV/TSV content. Supports an optional free-form meta line,
+ * an auto-detected delimiter (tab, comma, or semicolon), and an optional
+ * units row.
+ */
+export declare function parseDataset(text: string): Dataset;
+/** Returns the non-empty lines used internally by the parser (BOM stripped, trimEnd). */
+export declare function getRawNonEmptyLines(text: string): string[];
+/** True when two parse configs select the same header / units / data rows. */
+export declare function parseConfigsEqual(a: DatasetParseConfig, b: DatasetParseConfig): boolean;
+/** Auto-detect the header / units / data-start row indices for a file. */
+export declare function inferParseConfig(text: string): DatasetParseConfig;
+/**
+ * Column names for a header row, derived from a single line of the already-split
+ * non-empty lines. Lets callers that only need the column list (e.g. the config
+ * preview) skip parsing every data row.
+ */
+export declare function parseColumnNames(nonEmptyLines: string[], headerRow: number): string[];
+/** Parse using explicit row indices instead of auto-detection. */
+export declare function parseDatasetWithConfig(text: string, config: DatasetParseConfig): Dataset;
+/** Header part of a dataset plus its cells stored by column (see `ColumnTable`). */
+export interface ParsedTable {
+    meta: string;
+    columnNames: string[];
+    units: string[];
+    table: ColumnTable;
+}
+/**
+ * `parseDatasetWithConfig`, with the cells stored by column instead of as row
+ * objects. Data lines are read in place (no array of lines, no array of cells):
+ * a 214 MB file allocated a string per line and per cell. A line with quotes,
+ * a BOM, trailing whitespace or a lone `\r` goes through the reference
+ * (`parseDatasetTableByLines`) code for that line, so the result is identical.
+ */
+export declare function parseDatasetTable(text: string, config: DatasetParseConfig): ParsedTable;
+/** Reference parser behind `parseDatasetTable`: splits the text into lines, then cells. */
+export declare function parseDatasetTableByLines(text: string, config: DatasetParseConfig): ParsedTable;
+/**
+ * True if `col` holds numbers. Looks at up to 5000 values spread over ALL the
+ * rows, never just the first ones: merged data (several datasets, or imported
+ * data plus a live stream) puts one source after another, so a column only a
+ * later source has would otherwise read as empty. A column the spread sample
+ * misses entirely (only a few rows have it) is searched for row by row.
+ */
+export declare function columnIsNumeric(rows: DatasetRow[], col: string): boolean;
+export declare function subsampleIndices(length: number, maxPoints: number): number[];
+export {};

package/dist/types/lib/parseDataset.worker.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,32 @@
+import { type Dataset, type DatasetParseConfig, type ParsedTable } from './parseDataset';
+/** Request sent to the dataset parse worker: the text, or a file the worker reads itself. */
+export type ParseRequest = {
+    rawText: string;
+    config: DatasetParseConfig;
+} | {
+    file: Blob;
+    config: DatasetParseConfig;
+};
+/** Response posted back from the dataset parse worker. */
+export type ParseResponse = {
+    ok: true;
+    data: ParsedTable;
+} | {
+    ok: false;
+    error: string;
+};
+/** Minimal slice of the Worker API used here — keeps the client testable. */
+export interface WorkerLike {
+    postMessage(msg: ParseRequest): void;
+    terminate(): void;
+    onmessage: ((e: MessageEvent<ParseResponse>) => void) | null;
+    onerror: ((e: unknown) => void) | null;
+}
+/**
+ * Parse a dataset off the main thread. Spins up a worker per call, resolves with
+ * the parsed Dataset (or rejects on a parse/worker error), and always terminates
+ * the worker afterwards. `createWorker` is injectable for tests.
+ */
+export declare function parseDatasetInWorker(req: ParseRequest, createWorker?: () => WorkerLike, signal?: AbortSignal): Promise<Dataset>;
+/** Parse in a worker where there are workers, else here (tests, server-side): column-backed rows either way. */
+export declare function parseDatasetAnywhere(req: ParseRequest, signal?: AbortSignal): Promise<Dataset>;

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

@@ -0,0 +1,4 @@
+/** Time an async operation; logs `[perf] <label> #<n> <ms>` when enabled. */
+export declare function perfTime<T>(label: string, fn: () => Promise<T>): Promise<T>;
+/** Time a synchronous operation; logs `[perf] <label> #<n> <ms>` when enabled. */
+export declare function perfSync<T>(label: string, fn: () => T): T;

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

@@ -0,0 +1,10 @@
+/**
+ * Order statistics without sorting: quickselect puts the value of rank `k` at
+ * a[k], smaller ones before it and larger ones after (expected O(n)).
+ */
+export declare function selectInPlace(a: Float64Array, k: number, lo?: number, hi?: number): number;
+/**
+ * Percentiles `ps` (0..100, ascending) of `a`, interpolated between ranks as
+ * numpy's default (linear). `a` is reordered.
+ */
+export declare function percentilesInPlace(a: Float64Array, ps: number[]): number[];

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

@@ -0,0 +1,10 @@
+import type { Chunk } from '../importers/combine';
+import type { OutColumn } from '../importers/run';
+/** Combined chunks as CSV parts: a header row, a units row, one row per sample (NaN empty), like LiveRecorder. */
+export declare class CsvWriter {
+    #private;
+    constructor(columns: OutColumn[]);
+    head(): string;
+    append(c: Chunk): string;
+    end(): void;
+}

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

@@ -0,0 +1,26 @@
+import { type WorkerLike } from '../importers/session';
+import type { RecordingKey } from './keys';
+export interface RecordingSource {
+    name: string;
+    chunks: Blob[];
+    keys: RecordingKey[];
+}
+/** A piece of the exported file, in order. */
+export type ExportPart = string | Uint8Array<ArrayBuffer>;
+export interface ExportOptions {
+    signal?: AbortSignal;
+    onProgress?: (fraction: number) => void;
+    createWorker?: () => WorkerLike;
+}
+export declare const EXPORT_TYPES: {
+    readonly csv: "text/csv";
+    readonly mf4: "application/octet-stream";
+};
+/**
+ * A recording as a CSV or MF4 file, built in the browser from its encrypted chunks and handed to `write` piece by
+ * piece, in order (awaited: back-pressure). Any size: nothing holds the whole file, so a file sink or a streamed
+ * download keeps memory flat.
+ */
+export declare function exportRecordingTo(src: RecordingSource, format: 'csv' | 'mf4', write: (part: ExportPart) => void | Promise<void>, o?: ExportOptions): Promise<void>;
+/** The same as one Blob of the parts (small exports, tests). Large ones: exportRecordingTo a file or a stream. */
+export declare function exportRecording(src: RecordingSource, format: 'csv' | 'mf4', o?: ExportOptions): Promise<Blob>;

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

@@ -0,0 +1,2 @@
+import type { Importer } from '../importers/types';
+export declare const krcImporter: Importer;

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

@@ -0,0 +1,23 @@
+export interface RecordingKey {
+    /** The project key epoch & 0xff of a project stream's key; null: a password stream's key. */
+    keyId: number | null;
+    /** Non-extractable AES-256-GCM (importStreamKey). */
+    key: CryptoKey;
+}
+/** A recording key re-sealed under a later project key epoch. */
+export declare const recordingKeyAad: (recordingKeyId: string, projectId: string, epoch: number) => string;
+/** The aad of a recording key's row at `epoch`: the sender's own seal at its first epoch (copied by the server),
+ *  a re-seal at any later one (plan Decision 14). */
+export declare const recordingKeySealAad: (k: {
+    id: string;
+    stream_epoch: number;
+    stream_id: string;
+}, projectId: string, epoch: number) => string;
+/**
+ * Opens recorded wire messages (views, never copied) with the keys of their key id, the last one that worked
+ * first. Null: malformed, or no key opens it.
+ */
+export declare function messageOpener(keys: RecordingKey[]): (m: Uint8Array) => Promise<{
+    kind: number;
+    plaintext: Uint8Array;
+} | null>;

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

@@ -0,0 +1,38 @@
+/**
+ * KRC1: one chunk of a cloud recording, written by the relay (workers/live-relay/src/krc.ts, byte-identical):
+ * the wire messages it forwarded, exactly as forwarded, with their relay receive times. Little-endian:
+ *
+ *    0  'KRC1'             24  u32 seq
+ *    4  u16 version (1)    28  u32 messages M
+ *    6  u16 header bytes   32  u32 chunk bytes (header + records)
+ *    8  recording id (16)  36  u32 reserved (0)
+ *                          40  f64 t0, 48 f64 t1: relay time of the first / last message (ms since epoch)
+ *   56  M × { f64 relay ms, u32 length L, L bytes }
+ *
+ * The chunk length makes a concatenation of chunks walkable header to header. Pinned vector:
+ * tests/vectors/krc1-v1.json.
+ */
+export declare const KRC_HEADER_BYTES = 56;
+export interface KrcHeader {
+    recordingId: string;
+    seq: number;
+    count: number;
+    bytes: number;
+    headerBytes: number;
+    t0: number;
+    t1: number;
+}
+export interface KrcMessage {
+    at: number;
+    bytes: Uint8Array;
+}
+export declare function uuidBytes(id: string): Uint8Array;
+/** A chunk (tests, the bench, local tools; the relay has its own copy that never copies the messages). */
+export declare function encodeKrc(recordingId: string, seq: number, messages: KrcMessage[]): Uint8Array<ArrayBuffer>;
+export declare function parseKrcHeader(b: Uint8Array): KrcHeader;
+/** Every record of one chunk (views into `b`); `truncated` when it ends early (the records before the cut are kept). */
+export declare function parseKrc(b: Uint8Array): {
+    header: KrcHeader;
+    messages: KrcMessage[];
+    truncated: boolean;
+};