@kymoscope/sdk 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,37 @@
+export declare function fmtHz(hz: number): string;
+/**
+ * Short-time Fourier transform: the amplitude of every frequency bin of every
+ * window, `frames` × `bins` row by row (row = bin), plus the largest.
+ */
+export declare function computeSTFT(signal: ArrayLike<number>, winSz: number, step: number, useHann: boolean): {
+    amps: Float32Array;
+    frames: number;
+    bins: number;
+    max: number;
+};
+/**
+ * A spectrogram as a grid of cells, `bins` rows × `frames` columns (row r,
+ * frame f at values[r * frames + f]): each cell the bin's amplitude, or its
+ * level in dB (20·log10, not yet relative to the loudest: the caller applies
+ * that through the colour range, so a louder new frame rewrites no cell).
+ * Row r shows bin `rowBin[r]` (a warped frequency axis) or bin r.
+ *
+ * Given the previous result, windows whose samples are unchanged are not
+ * transformed again: a signal that dropped its oldest samples and gained new
+ * ones (a live stream) by a multiple of the hop reuses every window still in
+ * it, so each refresh transforms only the new windows.
+ */
+export interface SpectrogramGrid {
+    values: Float32Array;
+    frames: number;
+    bins: number;
+    /** The largest amplitude. */
+    max: number;
+    /** Windows transformed by this call (the rest were reused). */
+    computed: number;
+    /** For the next call: the signal (a copy) and each frame's largest amplitude. */
+    readonly sig: Float64Array;
+    readonly frameMax: Float32Array;
+    readonly key: string;
+}
+export declare function spectrogramGrid(signal: ArrayLike<number>, winSz: number, step: number, useHann: boolean, db: boolean, rowBin: Int32Array | null, prev?: SpectrogramGrid | null): SpectrogramGrid;

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

@@ -0,0 +1,50 @@
+import { type PasswordSealed } from '../live/crypto';
+import type { WorkbookBody } from './io';
+/** A `.kymo` file (spec "Export / import files"). v3: AES-256-GCM under the key of the scope it was exported for
+ *  ('user': only me, 'org': my organization, 'any': anyone with Kymoscope; the host holds the keys), of the envelope
+ *  v2 JSON or, with `inner: 'password'`, of a v2 file. v2: the envelope sealed under a password only. */
+export type WorkbookFileScope = 'user' | 'org' | 'any';
+export interface PasswordWorkbookFile extends PasswordSealed {
+    format: 'kymoscope-workbook';
+    v: 2;
+}
+export interface ScopedWorkbookFile {
+    format: 'kymoscope-workbook';
+    v: 3;
+    scope: WorkbookFileScope;
+    scope_id: string | null;
+    alg: 'AES-256-GCM';
+    iv: string;
+    ct: string;
+    inner?: 'password';
+}
+export type EncryptedWorkbookFile = PasswordWorkbookFile | ScopedWorkbookFile;
+export interface WorkbookFileOptions {
+    scope: WorkbookFileScope;
+    /** The user's or organization's id; null for 'any'. */
+    scopeId: string | null;
+    /** The scope's 32-byte key. */
+    key: Uint8Array;
+    /** Optional: a password layer inside (the only layer the key holder can't open). */
+    password?: string;
+}
+export interface WorkbookFileInfo {
+    v: 2 | 3;
+    scope: WorkbookFileScope | null;
+    scopeId: string | null;
+    password: boolean;
+}
+/** Binds the scope and the file's v and inner too: a file whose inner was stripped or added doesn't open. */
+export declare const workbookExportAad: (scope: WorkbookFileScope, scopeId: string | null, inner?: "password") => string;
+/** A password-only file (v2): for embedders without scope keys; v3 files carry it inside as their password layer. */
+export declare function encryptPasswordWorkbookFile(body: WorkbookBody, password: string): Promise<PasswordWorkbookFile>;
+export declare function encryptWorkbookFile(body: WorkbookBody, o: WorkbookFileOptions): Promise<ScopedWorkbookFile>;
+export declare function isEncryptedWorkbookFile(x: unknown): x is EncryptedWorkbookFile;
+/** What opening a file needs (null: not a file this SDK reads). */
+export declare function workbookFileInfo(x: unknown): WorkbookFileInfo | null;
+/** The envelope inside (still to be parsed). scope_key_required / password_required: what's missing; another
+ *  scope's key or a damaged file: bad_file; a wrong password: wrong_password. */
+export declare function decryptWorkbookFile(file: EncryptedWorkbookFile, o: {
+    key?: Uint8Array;
+    password?: string;
+}): Promise<unknown>;

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

@@ -0,0 +1,120 @@
+import type { Worksheet } from '../savedLayout';
+import { type WorkbookFileInfo } from './encrypted';
+import type { PanelChartSettings } from '../panelChartSettings';
+import type { DashboardPanel, DashboardPanelKind } from '../../components/dashboardGridLayout';
+import type { BeaconConfig } from '../beacon';
+import type { MathChannel } from '../mathChannels/types';
+type ExportedWorksheet = {
+    name: string;
+    xKey: string;
+    panels: Worksheet['panels'];
+    panelChartSettings: Worksheet['panelChartSettings'];
+    panelChartBackgrounds: Worksheet['panelChartBackgrounds'];
+};
+/** Legacy plain export (still imported). */
+export interface WorkspaceExportEnvelopeV1 {
+    version: 1;
+    exportedAt: string;
+    worksheets: ExportedWorksheet[];
+}
+/** A math channel copied into a workbook, by value. */
+export type WorkbookChannel = Pick<MathChannel, 'name' | 'formula' | 'units' | 'enabled'> & {
+    description?: string;
+};
+/** Envelope v2 — a cloud workbook's body and a `.kymo` file's content. The analysis only, never data: no files,
+ *  streams, selection, dataset colours or offsets (spec "Workbook body"). */
+export interface WorkbookBody {
+    version: 2;
+    worksheets: ExportedWorksheet[];
+    /** Index into `worksheets`. */
+    activeWorksheet: number;
+    mathChannels: WorkbookChannel[];
+    liveWindowSeconds: number | null;
+    /** Lap / cycle split, without the dataset it came from. */
+    laps: BeaconConfig | null;
+}
+/** What `exportWorkspace()` returns (envelope v2 since cloud workbooks). */
+export type WorkspaceExportEnvelope = WorkbookBody;
+export interface WorksheetExportEnvelope {
+    version: 1;
+    kind: 'worksheet';
+    exportedAt: string;
+    worksheet: {
+        name: string;
+        xKey: string;
+        panels: Worksheet['panels'];
+        panelChartSettings: Worksheet['panelChartSettings'];
+        panelChartBackgrounds: Worksheet['panelChartBackgrounds'];
+    };
+}
+export interface ImportedChart {
+    kind: DashboardPanelKind;
+    title?: string;
+    settings: PanelChartSettings;
+    background: string | null;
+}
+export interface ChartExportEnvelope {
+    version: 1;
+    kind: 'chart';
+    exportedAt: string;
+    chart: {
+        kind: DashboardPanelKind;
+        title?: string;
+        settings: PanelChartSettings;
+        background: string | null;
+    };
+}
+export interface ImportResult {
+    worksheets: Worksheet[];
+    errors: string[];
+}
+/** A parsed v1 or v2 envelope. `liveWindowSeconds` / `laps` undefined: a v1 file (keep the current ones). */
+export interface ParsedWorkbook extends ImportResult {
+    activeIndex: number;
+    mathChannels: WorkbookChannel[];
+    liveWindowSeconds: number | null | undefined;
+    laps: BeaconConfig | null | undefined;
+}
+export type ParsedKymoscopeFile = {
+    type: 'workspace';
+    worksheets: Worksheet[];
+    errors: string[];
+} | {
+    type: 'worksheet';
+    worksheet: Worksheet;
+} | {
+    type: 'chart';
+    chart: ImportedChart;
+} | ({
+    type: 'encrypted';
+} & WorkbookFileInfo) | {
+    type: 'error';
+    errors: string[];
+};
+export declare function buildWorkspaceEnvelope(worksheets: Worksheet[]): WorkspaceExportEnvelopeV1;
+export declare function buildWorkbookBody(s: {
+    worksheets: Worksheet[];
+    activeWorksheetId: string;
+    channels: Array<Pick<MathChannel, 'name' | 'formula' | 'units' | 'enabled'> & {
+        description?: string;
+    }>;
+    liveWindowSeconds: number | null;
+    laps: BeaconConfig | null;
+}): WorkbookBody;
+export declare function buildWorkspaceExportBlob(worksheets: Worksheet[]): Blob;
+export declare function buildWorksheetEnvelope(worksheet: Worksheet): WorksheetExportEnvelope;
+export declare function buildWorksheetExportBlob(worksheet: Worksheet): Blob;
+export declare function buildChartEnvelope(panel: DashboardPanel, settings: PanelChartSettings, background: string | null): ChartExportEnvelope;
+export declare function buildChartExportBlob(panel: DashboardPanel, settings: PanelChartSettings, background: string | null): Blob;
+export declare function parseWorkspaceImportFile(file: File): Promise<ImportResult>;
+export declare function isCssColor(v: unknown): v is string;
+/** Parse an already-decoded v1 or v2 envelope. */
+export declare function parseWorkspaceEnvelope(parsed: unknown): ParsedWorkbook;
+/**
+ * True when the given worksheets contain real work worth warning about before
+ * a destructive replace — i.e. at least one worksheet has a panel. A single
+ * empty default worksheet does not count.
+ */
+export declare function workspaceHasWork(worksheets: Worksheet[]): boolean;
+export declare function parseKymoscopeFile(file: File): Promise<ParsedKymoscopeFile>;
+export {};

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

@@ -0,0 +1,14 @@
+/** Least-squares polynomial fits for X-Y scatter trend lines. */
+import type { XYPoint } from '../components/XYScatterChart';
+import { type XYColumns } from './data/xyColumns';
+/** Only the points inside this window take part (the chart's visible area). */
+export interface FitWindow {
+    xmin: number;
+    xmax: number;
+    ymin: number;
+    ymax: number;
+}
+/** Least-squares polynomial of `degree` through the points (those in `win` only, when given). */
+export declare function computePolyFit(pts: XYPoint[] | XYColumns, degree: number, win?: FitWindow): number[] | null;
+export declare function computeR2(pts: XYPoint[] | XYColumns, coeffs: number[]): number;
+export declare function buildEquation(coeffs: number[], xLabel: string, yLabel: string): string;

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

@@ -0,0 +1,28 @@
+/** “Nice” step for roughly `maxTicks` divisions across a span. */
+export declare function niceMajorStep(span: number, maxTicks?: number): number;
+/** X-axis tick budget for a plot width: up to 6, fewer on narrow plots so labels don't collide. */
+export declare function xTickCount(plotWidthPx: number): number;
+export declare function effectiveMajorMinor(scaleMin: number, scaleMax: number, yMajorStep: number | undefined, yMinorStep: number | undefined): {
+    majorStep: number;
+    minorStep: number;
+};
+export declare function majorTickValues(lo: number, hi: number, step: number): number[];
+export declare function minorTickValues(lo: number, hi: number, minorStep: number, majorVals: number[]): number[];
+/**
+ * Decimals that write `step` exactly (0.05 → 2, 0.25 → 2, 2.5 → 1, 20 → 0),
+ * at most two past its leading digit; a step that never ends (1/3, an axis cut
+ * in sixths) gets one past it, so 0.17 0.33 0.50 don't pass for round values.
+ */
+export declare function stepDecimals(step: number): number;
+/**
+ * An axis tick label: decimals from the tick `step` (not the value), so
+ * adjacent ticks always differ (0.60 0.65 0.70, never 1 1 1). Steps of 1000
+ * and up read k/M/G, steps under 0.001 m/µ/n, chosen from the step so a whole
+ * axis shares one prefix; zero is always "0".
+ */
+export declare function formatTick(v: number, step: number): string;
+/**
+ * A single value for tooltips, legends and readouts: four significant digits
+ * at any scale (0.6523, 3.142, 12035), SI prefixes outside 0.001..1e6.
+ */
+export declare function formatValue(v: number): string;

package/dist/types/react/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * React bindings for the Kymoscope engine. Optional: the engine and charts work
+ * without React; these only save the wiring in React hosts.
+ */
+import { type CSSProperties, type ReactNode } from 'react';
+import type { KymoscopeEngine } from '../engine/createEngine';
+import type { EngineState } from '../engine/types';
+import type { ChartView, ChartViewEvents, MountOptions } from '../charts/runtime';
+export declare function KymoscopeProvider({ engine, children }: {
+    engine: KymoscopeEngine;
+    children?: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useEngine(): KymoscopeEngine;
+/**
+ * Subscribe to a slice of the engine state. Re-renders only when the selected
+ * value changes (by `isEqual`, default `Object.is`).
+ */
+export declare function useEngineState<T>(selector: (s: EngineState) => T, isEqual?: (a: T, b: T) => boolean): T;
+export interface ChartProps {
+    /** Chart id (from `engine.charts.add`). */
+    id: string;
+    className?: string;
+    style?: CSSProperties;
+    options?: MountOptions;
+    onStatus?: (status: ChartViewEvents['status']) => void;
+    onContextMenu?: (e: ChartViewEvents['contextmenu']) => void;
+    onViewChange?: (range: ChartViewEvents['viewchange']) => void;
+    /** Receives the ChartView (export, shift mode, autoscale) once mounted. */
+    viewRef?: (view: ChartView | null) => void;
+}
+/** A mounted chart. Size it with `className`/`style`; the plot fills it. */
+export declare function Chart({ id, className, style, options, onStatus, onContextMenu, onViewChange, viewRef }: ChartProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,42 @@
+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';
+export interface LoadedDataset {
+    id: string;
+    name: string;
+    /** 'memory' = fully parsed into rows; 'duckdb' = large file, out-of-core; 'columnar' = large host columns (typed arrays). The last two are read through `source`. */
+    kind: 'memory' | 'duckdb' | 'columnar';
+    /** Read interface (InMemoryDataSource or DuckDbDataSource). */
+    source: DataSource;
+    /** Column schema (numeric/string + units), from the source. */
+    schema: ColumnSchema[];
+    /**
+     * Always present so the existing row-based pipeline keeps working. For
+     * 'duckdb' it is HEADER-ONLY: columnNames + units populated, `rows` empty (the
+     * real data lives in the DuckDB table, queried via `source`).
+     */
+    data: Dataset;
+    /**
+     * The dataset's text: all of it for text handed over directly, only the start
+     * (up to 256 KB, for previews) for an imported file, which `file` keeps instead.
+     * Absent for binary files (see `info`).
+     */
+    rawText?: string;
+    /** The imported file, read again to re-parse or re-import (absent: `rawText` is the whole text). */
+    file?: Blob;
+    /** Files read together with `file` (an MF4's .dbc, a COMTRADE .dat). */
+    companions?: File[];
+    /** Delimited text only. */
+    parseConfig?: DatasetParseConfig;
+    /** Binary files: format, start time, groups, events. */
+    info?: DatasetFileInfo;
+    /** Built from host columns (`datasets.addColumns`): its data can be swapped with `datasets.replaceColumns`. */
+    fromColumns?: boolean;
+    /** Arrays a column was replaced from, reused by the next writeColumns (engine internal). */
+    columnSpares?: Map<string, Float64Array>;
+    /** Beacon lap split; when set, the dataset is shown/selected as its laps. */
+    beacon?: BeaconConfig;
+}
+/** True when the dataset's rows are materialized in memory (small files). */
+export declare function isInMemory(ld: LoadedDataset): boolean;

package/dist/types/types/plotSeries.d.ts

@@ -0,0 +1,27 @@
+export type AlarmStyle = 'solid' | 'dashed' | 'dotted';
+export interface AlarmLine {
+    value: number;
+    style: AlarmStyle;
+    width: number;
+    color: string;
+}
+/** One Y layer: vertical fraction of the plot area and physical scale. */
+export interface PlotSeries {
+    id: string;
+    column: string;
+    color: string;
+    /** % from the bottom of the plot area (0 = bottom of the chart). */
+    bandFromPct: number;
+    /** % from the bottom to the top of the band (100 = top of the plot area). */
+    bandToPct: number;
+    scaleMin: number;
+    scaleMax: number;
+    /** Major tick interval (labels + grid). 0 = automatic. */
+    yMajorStep: number;
+    /** Minor tick interval (marks only). 0 = automatic (~one fifth of major). */
+    yMinorStep: number;
+    /** Optional horizontal alarm line drawn across the band at this value. */
+    alarm?: AlarmLine | null;
+}
+export declare function clampPct(n: number): number;
+export declare function newSeriesId(): string;

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@kymoscope/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "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",
+  "keywords": [
+    "telemetry",
+    "charts",
+    "data-visualization",
+    "duckdb",
+    "time-series",
+    "mdf",
+    "react"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/kymoscope-sdk.js"
+    },
+    "./react": {
+      "types": "./dist/types/react/index.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./embed": "./dist/kymoscope-embed.js",
+    "./styles/*": "./dist/styles/*",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19"
+  },
+  "devDependencies": {
+    "@duckdb/duckdb-wasm": "^1.33.1-dev45.0",
+    "@msgpack/msgpack": "^3.1.3",
+    "apache-arrow": "17.0.0",
+    "delaunator": "^5.1.0",
+    "fflate": "^0.8.3",
+    "h5wasm": "0.10.3",
+    "mathjs": "^15.2.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "build": "vite build && vite build -c vite.embed.config.ts && tsc -p tsconfig.build.json && node -e \"require('fs').cpSync('src/styles','dist/styles',{recursive:true})\"",
+    "license": "node scripts/license.mjs",
+    "prepack": "node scripts/pack-manifest.mjs dist",
+    "postpack": "node scripts/pack-manifest.mjs restore",
+    "prepublishOnly": "node scripts/pack-manifest.mjs guard"
+  },
+  "files": [
+    "dist",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/kymoscope-sdk.js",
+  "module": "./dist/kymoscope-sdk.js",
+  "types": "./dist/types/index.d.ts"
+}