@kymoscope/sdk 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,194 @@
+import type { LiveStreamOptions } from '../lib/live/types';
+import type { DashboardPanelKind } from '../components/dashboardGridLayout';
+import type { PanelChartSettings } from '../lib/panelChartSettings';
+import type { ChartAnnotation } from '../lib/annotations';
+import type { MathChannel, MathChannelPatch } from '../lib/mathChannels/types';
+import type { LiveRelayConfig } from '../lib/live/stream';
+import type { BeaconConfig } from '../lib/beacon';
+import type { DatasetParseConfig } from '../lib/parseDataset';
+import type { DatasetFileInfo } from '../lib/importers/types';
+export type ChartKind = DashboardPanelKind;
+/** Why a limit blocked an action. */
+export type LimitReason = 'charts-per-worksheet' | 'channels-per-chart' | 'worksheets' | 'workspaces-io' | 'math-channels';
+/** Quantity limits; `null` = unlimited. */
+export interface KymoscopeLimits {
+    maxChartsPerWorksheet: number | null;
+    maxChannelsPerChart: number | null;
+    maxWorksheets: number | null;
+    maxMathChannels: number | null;
+    canImportExportWorkspaces: boolean;
+}
+export declare const UNLIMITED: KymoscopeLimits;
+/**
+ * Where math channels are persisted. Without one they live in memory. With one,
+ * the engine calls these for every change and the host pushes its authoritative
+ * list back with `engine.mathChannels.sync(list)`.
+ */
+export interface MathChannelStoreAdapter {
+    create(channel: MathChannel): void | Promise<void>;
+    update(id: string, patch: MathChannelPatch): void | Promise<void>;
+    remove(id: string): void | Promise<void>;
+    importMany(channels: MathChannel[]): void | Promise<void>;
+}
+export interface EngineOptions {
+    /** License key for this domain, checked once at creation. Without a valid key, charts show a small
+     *  attribution badge. For keys that renew themselves use `license` (with both, this one is used until
+     *  the first successful `license.get`). */
+    licenseKey?: string;
+    /** Fetches license keys from your backend (which calls Kymoscope's `license-renew`). Called at creation
+     *  and again 7 days before the held key expires; a failure, an invalid key or no answer within 30 s keeps the current key and
+     *  retries every hour. The badge shows only while no held key verifies. */
+    license?: {
+        get: () => Promise<string>;
+    };
+    limits?: Partial<KymoscopeLimits>;
+    mathChannels?: MathChannelStoreAdapter;
+    /** Live streams: the relay, and how much of each stream viewers keep (per-stream
+     *  options of `live.openLocal` / `live.connect` override these). */
+    live?: {
+        relay?: LiveRelayConfig;
+    } & LiveStreamOptions;
+    /** Runs before every file import; return false to cancel it (throws `import_vetoed`). */
+    beforeImport?: () => boolean | void | Promise<boolean | void>;
+    /** Colors given to plotted datasets in order (first plotted gets the first,
+     *  and so on, cycling); a color picked for a dataset still wins. Hex colors.
+     *  Default: defaultDatasetPalette for the page's theme (white first on dark,
+     *  black first on light), updated when the theme changes. */
+    palette?: string[];
+}
+export interface ColumnInfo {
+    name: string;
+    unit: string;
+    numeric: boolean;
+}
+export interface LapInfo {
+    id: string;
+    name: string;
+    /** Lap metric value (e.g. lap time), null when not computable. */
+    value: number | null;
+    unit: string;
+    isTime: boolean;
+    color: string;
+    offset: number;
+    selected: boolean;
+}
+export interface DatasetInfo {
+    id: string;
+    name: string;
+    /** 'memory' = parsed in memory; 'duckdb' = large file queried out of core; 'columnar' = large `addColumns` data kept as typed arrays. */
+    kind: 'memory' | 'duckdb' | 'columnar';
+    columns: ColumnInfo[];
+    /** Rows (in memory) or sampled rows (out of core). */
+    rowCount: number;
+    color: string;
+    /** True when the colour was set with `datasets.setColor` (not the palette default). */
+    customColor: boolean;
+    /** X shift applied when several datasets are plotted together. */
+    offset: number;
+    /** Delimited text only; null for binary files. */
+    parseConfig: DatasetParseConfig | null;
+    /** 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). */
+    laps: LapInfo[] | null;
+    /** Selection state: true, false, or 'partial' when only some laps are selected. */
+    selected: boolean | 'partial';
+}
+export interface ChartModel {
+    id: string;
+    kind: ChartKind;
+    title: string | null;
+    settings: PanelChartSettings;
+    /** Plot background; null = theme. */
+    background: string | null;
+    /** Marks drawn over the chart (same list as `settings.annotations`). */
+    annotations: ChartAnnotation[];
+    /** Opaque grid rectangle for hosts that lay charts out on a 96×96 grid. */
+    layout: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+}
+export interface WorksheetState {
+    id: string;
+    name: string;
+    /** Shared X column of the worksheet's charts. */
+    xKey: string;
+    /** Linked X zoom of the worksheet (null = full range). */
+    xRange: [number, number] | null;
+    charts: ChartModel[];
+}
+export interface LiveConnectionInfo {
+    id: string;
+    name: string;
+    ownerName: string;
+    visibility: 'private' | 'public' | 'org' | 'project';
+    orgName: string | null;
+    status: 'connecting' | 'live' | 'stale' | 'error';
+    error: string | null;
+    rowCount: number;
+    selected: boolean;
+    /** Trace colour when several sources are plotted together. */
+    color: string;
+    /** When a recording is running: its start time (ms since epoch), else null. */
+    recordingSince: number | null;
+}
+export interface EngineState {
+    datasets: DatasetInfo[];
+    /** Plotted ids: dataset ids, lap ids and live connection ids. */
+    selection: string[];
+    worksheets: WorksheetState[];
+    activeWorksheetId: string;
+    mathChannels: MathChannel[];
+    live: LiveConnectionInfo[];
+    /** Scrolling window for live charts on a time X axis (seconds; null = all). */
+    liveWindowSeconds: number | null;
+    limits: KymoscopeLimits;
+    /** Colors given to plotted datasets in order (EngineOptions.palette). */
+    palette: string[];
+    /** Files currently being imported. */
+    importing: number;
+    /** Licence check result for this page; null while checking. */
+    licensed: boolean | null;
+    /** Something is plotted (a selected dataset, lap or live stream). */
+    hasData: boolean;
+    /** More than one source (dataset, lap or live stream) plotted: series are drawn once per source. */
+    multiDataset: boolean;
+    /** Numeric columns across the plotted data (+ math channels), for column pickers. */
+    numericColumns: string[];
+    /** Every column (numeric or not) across the plotted data, plus math channels. */
+    allColumns: string[];
+    /** Units by column name across the plotted data. */
+    columnUnits: Record<string, string>;
+    /** Undo/redo of the analysis (engine.history): worksheets, charts, settings, annotations and the math channels the
+     *  workbook carries. Own (library) math channels are saved to the library at once and are not undone; laps settings
+     *  follow the data and are not undone; switching worksheets is not a step. During a live stream an undo may plot
+     *  against the step's X key until the next connection change. */
+    history: {
+        canUndo: boolean;
+        canRedo: boolean;
+    };
+}
+export interface EngineEvents extends Record<string, unknown> {
+    change: EngineState;
+    limit: {
+        reason: LimitReason;
+    };
+    error: {
+        error: Error;
+        context: string;
+    };
+    import: {
+        file: string;
+        phase: 'start' | 'progress' | 'done' | 'error';
+        /** phase 'progress': 0..1 of the file read. */
+        fraction?: number;
+        datasetId?: string;
+        /** phase 'done': every dataset made from the file (several when it was split). */
+        datasetIds?: string[];
+        error?: Error;
+    };
+}

package/dist/types/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @kymoscope/sdk — the Kymoscope data engine and charts, without an app UI.
+ *
+ * `createEngine()` holds every capability (datasets, laps, worksheets, 27 chart
+ * kinds, math channels, end-to-end encrypted live streams, import/export);
+ * `engine.charts.mount()` renders a chart into any element. You build the UI.
+ *
+ * This file is the only public surface (plus `@kymoscope/sdk/react` and
+ * `@kymoscope/sdk/styles/charts.css`).
+ */
+export { createEngine } from './engine/createEngine';
+export type { KymoscopeEngine, Snapshot, ImportSource, ImportResult, ImportOptions, Exported, ParsedFile, ChartSettingsPatch, } from './engine/createEngine';
+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 { CHART_KINDS, chartLabel } from './engine/kinds';
+export type { ChartKindInfo } from './engine/kinds';
+export type { ColumnsInput } from './engine/columns';
+export { verifyLicense } from './embed/license';
+export type { LicenseResult } from './embed/license';
+export type { ChartView, ChartViewEvents, MountOptions, ChartStyle } from './charts/runtime';
+export type { ChartWindow, ChartWindowOptions } from './charts/chartWindow';
+export type { ChartStatus, ContextMenuEvent } from './charts/ChartBody';
+export * from './lib/panelChartSettings';
+export { ANNOTATION_KINDS, DEFAULT_ANNOTATION_WIDTH, type AnnotationKind, type AnnotationTool, type ChartAnnotation } from './lib/annotations';
+export { ANNOTATION_CONTROLS_ATTR } from './charts/AnnotationLayer';
+export { colorAt, colorsCss, presetStops, type GaugeColorMode, type GaugeColorStop, type GaugePreset } from './lib/gaugeColors';
+export type { PlotSeries, AlarmLine, AlarmStyle } from './types/plotSeries';
+export { newSeriesId, clampPct } from './types/plotSeries';
+export type { DashboardPanel, DashboardPanelKind } from './components/dashboardGridLayout';
+export { DASHBOARD_GRID_COLS, DASHBOARD_GRID_ROWS, DASHBOARD_GRID_GAP_PX, MIN_PANEL_W, MIN_PANEL_H, clampRectForKind, dragLayout, newPanel, arrangeAutoLayout } from './components/dashboardGridLayout';
+export type { Worksheet } from './lib/savedLayout';
+export { DEFAULT_XY_POINT_RADIUS, DEFAULT_XYZ_POINT_RADIUS } from './lib/savedLayout';
+export type { WorkspaceExportEnvelope, WorkspaceExportEnvelopeV1, WorkbookBody, WorkbookChannel } from './lib/workspaces/io';
+export type { EncryptedWorkbookFile, PasswordWorkbookFile, ScopedWorkbookFile, WorkbookFileScope, WorkbookFileOptions, WorkbookFileInfo, } from './lib/workspaces/encrypted';
+export { encryptWorkbookFile, workbookExportAad, workbookFileInfo } from './lib/workspaces/encrypted';
+export { niceMajorStep } from './lib/yAxisTicks';
+export { computePolyFit, computeR2, buildEquation } from './lib/xyFit';
+export type { XYPoint } from './components/XYScatterChart';
+export type { XYColumns } from './lib/data/xyColumns';
+export type { XYZPoint, XYZViewMode } from './components/XYZMeshChart';
+export type { LoadedDataset } from './types/loadedDataset';
+export type { DatasetFileInfo, FileEvent, GroupSelection, ChannelChooser, ChannelRequest } from './lib/importers/types';
+export type { Dataset, DatasetRow, DatasetParseConfig } from './lib/parseDataset';
+export { parseDatasetWithConfig, inferParseConfig, getRawNonEmptyLines, parseColumnNames, columnIsNumeric, parseConfigsEqual, subsampleIndices, } from './lib/parseDataset';
+export { openDatasetFromText } from './lib/data/openDataset';
+export type { BeaconConfig, BeaconStat } from './lib/beacon';
+export { BEACON_STATS, bestCycleIndex, cyclicChannels, guessBeaconChannel, splitLaps, suggestBeacon, formatLapValue } from './lib/beacon';
+export type { FolderEntry, DirNode } from './lib/folderTree';
+export { buildTree, isImportable, IMPORTABLE_EXT } from './lib/folderTree';
+export { DATASET_PALETTE, colorForDataset, defaultDatasetPalette } from './lib/datasetColors';
+export { colorSchemeOf, observeColorScheme, eventWithin } from './lib/colorScheme';
+export type { MathChannel, MathChannelPatch, MathChannelSource, EvalResult, EvalStatus } from './lib/mathChannels/types';
+export { newMathChannel, evalChannel, parseFormula, extractFreeIdentifiers, FUNCTION_REFERENCE, WINDOW_FN_NAMES, isMathChannelName, decorateColumnLabel, } from './lib/mathChannels';
+export type { FunctionDoc } from './lib/mathChannels';
+export { buildExportBlob as buildMathChannelsBlob, parseImportFile as parseMathChannelsFile } from './lib/mathChannels/io';
+export type { LiveRelayConfig } from './lib/live/stream';
+export type { LiveStreamDescriptor, LiveStreamOptions, LocalLiveStream, StreamKeyProvider } from './lib/live/types';
+export type { LiveColumnsBlock, LiveMessage } from './lib/live/buffer';
+export { LIVE_TIME_COLUMN } from './lib/live/buffer';
+export { openMessage, sealMessage } from './lib/live/wire';
+export type { RecordingKey } from './lib/recordings/keys';
+export { recordingKeyAad, recordingKeySealAad } from './lib/recordings/keys';
+export { parseKrc, parseKrcHeader, KRC_HEADER_BYTES } from './lib/recordings/krc';
+export type { RecordingInput } from './engine/createEngine';
+export { exportRecording, exportRecordingTo, EXPORT_TYPES, type ExportPart, type RecordingSource } from './lib/recordings/export';
+export type { EncryptedEnvelope, DeviceWrap, SealedKey, PasswordSealed } from './lib/live/crypto';
+export { generateApiToken, splitApiKey, generateDeviceKeyPair, unwrapStreamKey, unwrapForDevice, wrapForDevice, projectWrapAad, streamKeyAad, bindKeyAad, randomKey, importStreamKey, sealUnderProjectKey, openUnderProjectKey, senderBindKey, senderBinding, verifySenderBinding, deviceFingerprint, hashToken, generateSalt, deriveKey, deriveRawKeyBase64, makeKeyCheck, verifyKeyCheck, WORKBOOK_EXPORT_AAD, workbookBodyAad, workbookKeyAad, recoveryKeyAad, recoveryAttestationAad, sealWithKey, openWithKey, sealWithPassword, openWithPassword, recoveryCode, parseRecoveryCode, generateRecoveryKeyPair, recoveryPrivateKey, } from './lib/live/crypto';

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

@@ -0,0 +1,37 @@
+/**
+ * Chart annotations: marks a user draws over any chart (text, freehand brush,
+ * arrow, box). They live in the chart's settings (`settings.annotations`), so
+ * they travel with exports, imports and copies. Threshold lines are not
+ * annotations: they are the charts' alarm lines.
+ *
+ * A point is [x, y]. y is a fraction of the chart's height (0 top, 1 bottom).
+ * x is a fraction of its width, or, with `anchor: 'x'`, a value on the chart's
+ * X axis: the annotation then follows the data when the chart zooms, pans or
+ * scrolls (charts with a numeric X axis pin new annotations this way).
+ */
+export type AnnotationKind = 'text' | 'brush' | 'arrow' | 'box';
+export declare const ANNOTATION_KINDS: readonly AnnotationKind[];
+export interface ChartAnnotation {
+    id: string;
+    kind: AnnotationKind;
+    /** text: its top-left. arrow: from, to. box: two opposite corners. brush: the stroke, in order. */
+    points: [number, number][];
+    /** 'x': each point's x is a value on the chart's X axis (else a fraction of its width). */
+    anchor?: 'x';
+    /** Hex colour. */
+    color: string;
+    /** Stroke width in px; for text, the font size in px. */
+    width: number;
+    /** The text of a text annotation; the label of a box. */
+    text?: string;
+}
+/** What a pointer gesture on the chart creates (`ChartView.setAnnotationTool`). */
+export interface AnnotationTool {
+    kind: AnnotationKind;
+    color: string;
+    width: number;
+}
+export declare const DEFAULT_ANNOTATION_WIDTH: Record<AnnotationKind, number>;
+/** One annotation from untrusted input (a file, an SDK call), or null if it isn't one. */
+export declare function coerceAnnotation(v: unknown): ChartAnnotation | null;
+export declare function coerceAnnotations(v: unknown): ChartAnnotation[] | null;

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

@@ -0,0 +1,62 @@
+import type { DatasetRow } from './parseDataset';
+/**
+ * Beacon (lap split): a dataset is cut into sub-datasets every time `channel`
+ * resets (e.g. a lap-time channel dropping back to 0). Each lap is quantified by
+ * `stat` over the `metric` channel (lap time, distance, mean speed, …).
+ */
+export type BeaconStat = 'span' | 'mean' | 'max' | 'min';
+export interface BeaconConfig {
+    channel: string;
+    metric: string;
+    stat: BeaconStat;
+}
+export declare const BEACON_STATS: {
+    value: BeaconStat;
+    label: string;
+}[];
+/** Half-open row range [start, end) of one lap. */
+export interface LapRange {
+    start: number;
+    end: number;
+}
+/**
+ * Split rows wherever `channel` resets. A reset is a drop larger than half of
+ * the current lap's span so far, so small sensor jitter backwards never starts
+ * a new lap. Rows whose channel is not numeric stay inside the current lap.
+ */
+export declare function splitLaps(rows: DatasetRow[], channel: string): LapRange[];
+/**
+ * Channels that start over in cycles — lap time, lap distance, a battery cycle:
+ * they ramp up between resets and reset at least once. Ramping up means almost
+ * never going down (≥ 90% of steps, so noisy signals like speed or RPM don't
+ * qualify) AND actually rising in most samples (≥ 50%, which still allows a
+ * pit stop): a channel that mostly holds still and sometimes drops — gear,
+ * throttle at 100% — is not a cycle. Most cycles first.
+ */
+export declare function cyclicChannels(rows: DatasetRow[], cols: string[]): string[];
+/**
+ * Default beacon: the channel that splits into the most laps while ramping up
+ * between resets (lap time / lap distance). Falls back to the first channel.
+ */
+export declare function guessBeaconChannel(rows: DatasetRow[], cols: string[]): string;
+/**
+ * The beacon to offer for a dataset, or null when no channel cycles. `preferred`
+ * (a predefined beacon) wins when its channels exist and it splits the data
+ * into laps; otherwise the most-cycling channel, valued by the span of a cyclic
+ * time channel (the lap time) when there is one, else by its own span.
+ */
+export declare function suggestBeacon(rows: DatasetRow[], cols: string[], preferred?: BeaconConfig | null): BeaconConfig | null;
+/** `stat` of the numeric values of `col` in rows[start, end); null if none. */
+export declare function lapMetric(rows: DatasetRow[], lap: LapRange, col: string, stat: BeaconStat): number | null;
+/**
+ * Index of the cycle with the lowest value, or null when none has one. Partial
+ * cycles — an out-lap, the stub where a recording stops — are ignored when at
+ * least two full ones exist (full = at least 80% of the median value), else
+ * the lowest of all wins.
+ */
+export declare function bestCycleIndex(values: (number | null)[]): number | null;
+/** Time metrics read as lap times: m:ss.sss, and the lowest one is the best lap. */
+export declare function isTimeMetric(metric: string, unit: string): boolean;
+export declare function formatLapValue(v: number | null, unit: string, isTime: boolean): string;
+/** Id of a lap sub-dataset; laps are selected/colored like any dataset. */
+export declare function lapId(datasetId: string, index: number): string;

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

@@ -0,0 +1,5 @@
+export declare function colorSchemeOf(el: Element | null): 'light' | 'dark';
+/** Calls `onChange` when the theme around `el` changes. Returns a disposer. */
+export declare function observeColorScheme(el: Element | null, onChange: () => void): () => void;
+/** True when `node` is inside `container`, across shadow-DOM retargeting. */
+export declare function eventWithin(e: Event, container: Element | null | undefined): boolean;

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

@@ -0,0 +1,9 @@
+/** Shared blue→cyan→green→yellow→red colormap used by XYZ and XY-color charts. */
+type RGB = {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function colormapRGB(t: number): RGB;
+export declare function colormapStr(t: number): string;
+export {};

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

@@ -0,0 +1,37 @@
+import type { DatasetRow } from './parseDataset';
+/**
+ * A parsed table stored by column: one Float64Array per column (NaN = empty or
+ * text), plus the text cells of the few columns that have any. Built in the parse
+ * worker and transferred to the page without copying.
+ */
+export interface ColumnTable {
+    /** Row keys, one per column (header name, or `col_<i>` when empty). */
+    keys: string[];
+    length: number;
+    values: Float64Array[];
+    /** Per column: its text cells by row index, or null when it has none. */
+    text: ((string | null | undefined)[] | null)[];
+}
+/** The column table `rows` were built from, if any (a slice or derived rows have none). */
+export declare function tableOf(rows: DatasetRow[]): ColumnTable | undefined;
+/** Column `key` of `t` (the last one when the name repeats, like row reads), or undefined. */
+export declare function tableColumn(t: ColumnTable, key: string): Float64Array | undefined;
+/**
+ * Rows over a table: each row holds only its index, and every column is a getter
+ * shared on one prototype, so `row[col]` reads the column. Plain object rows of a
+ * wide table (hundreds of columns × tens of thousands of rows) took ~1 GB and ~1 s
+ * to build, and as long again to copy out of the parse worker.
+ *
+ * With `previous` rows of the same columns and length (new data for the same
+ * dataset), their row objects are reused and read `t` from now on: replacing a
+ * million-row column every frame made a million objects per frame (most of the
+ * time went to collecting them). The returned rows are a new array to callers
+ * (a proxy of the same row list: no million-entry copy and its garbage every
+ * frame), so anything cached per rows array recomputes; `previous` now reads
+ * the new values too.
+ */
+export declare function tableRows(t: ColumnTable, previous?: DatasetRow[]): DatasetRow[];
+/** The same rows as plain objects (no workers, e.g. tests and server-side). */
+export declare function plainRows(t: ColumnTable): DatasetRow[];
+/** ArrayBuffers to transfer with a table (the text cells are cloned). */
+export declare function tableTransfer(t: ColumnTable): ArrayBuffer[];

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

@@ -0,0 +1,11 @@
+import type { DecimatedSeries } from './dataSource';
+/** One row of the decimation query result (see buildDecimationSql). */
+export interface DecimationRow {
+    b: number;
+    lo: number;
+    hi: number;
+    first: number;
+    last: number;
+}
+/** Convert decimation rows (ascending b) to a DecimatedSeries with bucket-center x. */
+export declare function rowsToDecimatedSeries(rows: DecimationRow[], x0: number, bucket: number): DecimatedSeries;

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

@@ -0,0 +1,27 @@
+import type { DatasetRow } from '../parseDataset';
+import type { HeatmapCell } from '../../components/HeatmapChart';
+export interface BinnedHeatmapConfig {
+    xCol: string;
+    yCol: string;
+    /** '' = count/density; otherwise the mean of this column per bin. */
+    valueCol: string;
+    xBins: number;
+    yBins: number;
+    /** undefined = auto from the data's finite extent. */
+    xMin?: number;
+    xMax?: number;
+    yMin?: number;
+    yMax?: number;
+}
+/**
+ * Bin rows into an `Nx x Ny` grid over [xMin,xMax] x [yMin,yMax] and aggregate
+ * per cell: a count (valueCol === '') or the mean of `valueCol`. Empty *mean*
+ * cells are NaN (so the chart can render them empty); empty count cells are 0.
+ * Y is oriented with the largest value on top (yLabels[0] is the top row).
+ * Returns the exact shape HeatmapChart consumes.
+ */
+export declare function buildBinnedHeatmap(rows: DatasetRow[], cfg: BinnedHeatmapConfig): {
+    cells: HeatmapCell[];
+    xLabels: string[];
+    yLabels: string[];
+};

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

@@ -0,0 +1,6 @@
+/** Register a cache keyed by column arrays (returned as is). */
+export declare function columnCache<T extends {
+    delete(key: Float64Array): unknown;
+}>(cache: T): T;
+/** Drop `col` from every registered cache: its values are about to change. */
+export declare function forgetColumn(col: Float64Array): void;

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

@@ -0,0 +1,34 @@
+import type { DataSource, ColumnSchema, SeriesQuery, DecimatedSeries, Viewport, MultiSeriesResult } from './dataSource';
+import type { PointColumns } from './pointColumns';
+import type { XRange } from '../duckdb/sql';
+import type { DatasetRow } from '../parseDataset';
+/**
+ * DataSource over host-provided typed arrays (large `datasets.addColumns`).
+ * Decimates straight from the columns: no row objects, no CSV text. Missing
+ * values are NaN.
+ */
+export declare class ColumnarDataSource implements DataSource {
+    #private;
+    constructor(columns: Map<string, Float64Array>, units?: Record<string, string>);
+    get length(): number;
+    /** The columns by name (the arrays themselves, not copies). */
+    get columnMap(): ReadonlyMap<string, Float64Array>;
+    getSchema(): Promise<ColumnSchema[]>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    /** {@link getSeriesMulti} without the Promise: decimating the columns is pure computation. */
+    getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
+    getColumnsSync(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    xBounds(column: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    xBoundsSync(column: string): {
+        x0: number;
+        x1: number;
+    };
+    /** Strided, order-preserving sample of ~`maxRows` rows (within `range` when given) for the row-based charts. */
+    sampleRowsSync(maxRows: number, range?: XRange): DatasetRow[];
+    sampleRows(maxRows: number, range?: XRange): Promise<DatasetRow[]>;
+    dispose(): Promise<void>;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Values (rows × columns) all in-memory datasets may hold together. In memory a
+ * value costs 8 bytes (one Float64Array per column), so this is ~800 MB; past it,
+ * files go out of core into DuckDB. In memory every row is there for laps and
+ * math channels; out of core those only see a ~12k-row sample.
+ */
+export declare const IN_MEMORY_VALUE_BUDGET = 100000000;
+/** Files above this always go out of core: parsing holds the whole text (and its lines) at once. */
+export declare const MAX_IN_MEMORY_BYTES: number;
+/** How much of a file is read to estimate its size in values (and kept for previews). */
+export declare const HEAD_BYTES: number;
+export type SourceKind = 'memory' | 'duckdb';
+/**
+ * Where a file goes: in memory while it fits the value budget next to the
+ * `priorValues` already loaded in memory, out of core (DuckDB) otherwise.
+ */
+export declare function chooseSourceKind(sizeBytes: number, values: number, priorValues?: number, budget?: number): SourceKind;
+/**
+ * Rows × columns of a delimited file of `sizeBytes`, estimated from its first
+ * bytes (`head`): the column count from the header, the rows from the average
+ * length of the data lines read.
+ */
+export declare function estimateValues(sizeBytes: number, head: string): number;

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

@@ -0,0 +1,75 @@
+import type { PointColumns } from './pointColumns';
+/** A data-space window on the x axis to fetch. */
+export interface Viewport {
+    xKey: string;
+    x0: number;
+    x1: number;
+}
+export interface SeriesQuery {
+    column: string;
+    viewport: Viewport;
+    /** Target number of x-buckets (≈ chart pixel width). */
+    maxPoints: number;
+}
+/**
+ * Min/max decimation of one series over a viewport. One entry per NON-EMPTY
+ * x-bucket; arrays are parallel and ascending in `x`. `first`/`last` are the y
+ * values at the bucket's smallest/largest x (for endpoint-preserving rendering).
+ */
+export interface DecimatedSeries {
+    x: Float64Array;
+    min: Float64Array;
+    max: Float64Array;
+    first: Float64Array;
+    last: Float64Array;
+}
+export interface ColumnSchema {
+    name: string;
+    type: 'number' | 'string';
+    unit: string;
+}
+/** One row of a multi-column decimation: `{ b, y0lo, y0hi, y1lo, … }`. */
+export type MultiDecimationRow = Record<string, number | bigint | null>;
+/** Result of decimating several columns at once over a viewport. */
+export interface MultiSeriesResult {
+    x0: number;
+    bucket: number;
+    rows: MultiDecimationRow[];
+    /** The columns actually decimated (a subset of those requested that the
+     *  dataset has). y{i}lo/y{i}hi in each row index into THIS list. */
+    columns: string[];
+}
+/** Read interface every chart will use; implementations may be in-memory or out-of-core. */
+export interface DataSource {
+    getSchema(): Promise<ColumnSchema[]>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    /** Decimate SEVERAL columns over a viewport in one pass (min/max per bucket). */
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    /** Min/max of a numeric column over the whole dataset (for axis auto-scaling). */
+    xBounds(column: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    /**
+     * Synchronous {@link getSeriesMulti} / {@link xBounds}, for sources where they
+     * are pure computation (in memory): a chart then gets new data in the same
+     * render, with no query to wait for (and none for a newer update to cancel).
+     */
+    getSeriesMultiSync?(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
+    /**
+     * The samples of `columns` in the viewport as they are (no decimation), or null
+     * when there are more than `limit` of them or X isn't ascending.
+     */
+    getColumnsSync?(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    xBoundsSync?(column: string): {
+        x0: number;
+        x1: number;
+    };
+    /** Release any held resources (DB connections, registered files). */
+    dispose(): Promise<void>;
+}
+/** Progress of a large file being loaded into DuckDB (here, not in duckDbDataSource, so the public types need no DuckDB). */
+export interface IngestProgress {
+    phase: 'reading' | 'parsing' | 'done';
+    message: string;
+}

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

@@ -0,0 +1,25 @@
+import type { DecimatedSeries, MultiSeriesResult } from './dataSource';
+import type { PointColumns } from './pointColumns';
+/**
+ * Min/max-per-bucket decimation of SEVERAL y columns sharing one x array, in the
+ * same `{ b, y{i}lo, y{i}hi }` row shape the SQL path produces (so the in-memory
+ * and live sources feed the same point builder as DuckDB). NaN samples and
+ * out-of-range (or NaN) x are skipped; bucketing matches buildMultiDecimationSql.
+ * Accumulates into typed arrays per bucket (an object per bucket and a Map
+ * lookup per sample made a million-point series ~17 ms and most of its garbage).
+ */
+export declare function multiDecimateColumns(x: Float64Array, ys: Float64Array[], columns: string[], x0: number, x1: number, maxPoints: number): MultiSeriesResult;
+/**
+ * Min/max decimation over parallel x/y arrays. Mirrors buildDecimationSql:
+ * bucket = (x1-x0)/maxPoints, b = floor((x-x0)/bucket). Points outside [x0,x1]
+ * or with NaN y are skipped; empty buckets are omitted; per-bucket x is the
+ * bucket center x0+(b+0.5)*bucket.
+ */
+export declare function decimateArrays(x: Float64Array, y: Float64Array, x0: number, x1: number, maxPoints: number): DecimatedSeries;
+/**
+ * The samples with X in [x0, x1] as they are (views of the columns, nothing
+ * copied) when X is ascending and there are at most `limit` of them; otherwise
+ * null, and the caller decimates. Drawing them all costs the GPU little, and
+ * data replaced every frame then skips decimation and its conversions entirely.
+ */
+export declare function rawColumns(x: Float64Array, ys: Float64Array[], columns: string[], x0: number, x1: number, limit: number): PointColumns | null;