@kymoscope/sdk 0.0.0-stage → 0.1.0

package/dist/types/embed/license.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Offline license check. A key is `b64url(JSON payload).b64url(Ed25519 sig)`
+ * where the signature covers the first segment and the payload is
+ * `{ sub, domains, exp, kid? }` (`exp` in unix seconds; a domain may be `*.x.com`;
+ * `kid` picks the public key, "1" when absent).
+ * Keys are minted with `scripts/license.mjs`; only the public key ships here.
+ *
+ * Every host needs a key that lists it — including localhost, so a desktop
+ * shell or intranet tool served from localhost is not licensed for free. A
+ * failed check never breaks the workspace; it shows the attribution badge.
+ * Enforcement beyond that is contractual (see LICENSE.md): code that runs in
+ * a browser can always be patched.
+ */
+/** Ed25519 public keys (raw, base64url) by key id. "1" is the original key; a key without `kid` uses "1".
+ *  To rotate: add the next key here, release the SDK, then switch the server's signing key and kid. */
+export declare const KYMOSCOPE_LICENSE_PUBLIC_KEYS: Record<string, string>;
+export type LicenseResult = {
+    ok: true;
+    sub: string;
+    exp: number;
+} | {
+    ok: false;
+    reason: 'missing' | 'malformed' | 'bad_signature' | 'expired' | 'domain' | 'unsupported';
+};
+/** Verify against explicit public keys (by kid, or a single key used for every kid) and clock.
+ *  Internal: tests use it with their own keypair. */
+export declare function verifyLicenseWith(key: string | undefined | null, hostname: string, publicKeys: Record<string, string> | string, nowSec: number): Promise<LicenseResult>;
+/** Check a Kymoscope license key for `hostname` (usually `location.hostname`). */
+export declare function verifyLicense(key: string | undefined | null, hostname: string): Promise<LicenseResult>;

package/dist/types/embed/standalone.d.ts

@@ -0,0 +1,5 @@
+/** Entry of the standalone `<script>` build: `window.Kymoscope.createEngine(...)`. */
+export { createEngine } from '../engine/createEngine';
+export { KymoscopeError } from '../engine/errors';
+export { CHART_KINDS, chartLabel } from '../engine/kinds';
+export { verifyLicense } from './license';

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

@@ -0,0 +1,44 @@
+import type { LoadedDataset } from '../types/loadedDataset';
+/** Columnar numeric data handed over by the host. */
+export interface ColumnsInput {
+    name: string;
+    columns: Record<string, ArrayLike<number>>;
+    units?: Record<string, string>;
+    /**
+     * Hand the columns' Float64Arrays over instead of having them copied: the
+     * dataset keeps them as they are (non-finite values are turned into NaN in
+     * place). The host must not touch them afterwards. For data replaced many
+     * times a second, where the copy is most of the cost.
+     */
+    transfer?: boolean;
+}
+/**
+ * Above this many rows host columns stay columnar (no row objects at all):
+ * decimated per viewport like a large file, but no laps and math channels on a
+ * sample. Below it the dataset has rows (index-only objects over the columns),
+ * so laps and math channels see every row.
+ */
+export declare const COLUMNAR_ROWS = 1000000;
+/** Build a dataset from host-provided numeric columns (each is copied once). */
+export declare function datasetFromColumns(id: string, input: ColumnsInput): LoadedDataset;
+/**
+ * New values for `names`, written by `fill` straight into arrays the dataset
+ * reuses: the ones these columns held two writes ago (double buffering), so a
+ * dataset rewritten every frame copies nothing and leaves no garbage. `fill`
+ * gets one Float64Array per name, of the dataset's length, and must set every
+ * value; it may read the current values (`current`). The reused arrays are
+ * first dropped from every cache that assumed them unchanging.
+ */
+export declare function writeColumns(ds: LoadedDataset, names: string[], fill: (cols: Record<string, Float64Array>, current: Record<string, Float64Array | undefined>) => void): LoadedDataset;
+/**
+ * `ds` with the given columns replaced (or added); the others are kept as they
+ * are, not copied. Same id, name and units, so everything keyed by the dataset
+ * (selection, colour, offset, laps, charts) carries over.
+ */
+export declare function replaceColumns(ds: LoadedDataset, input: Record<string, ArrayLike<number>>, transfer?: boolean): LoadedDataset;
+/**
+ * The whole dataset as CSV, for a dataset built from columns (it keeps only a
+ * preview): what `raw()` hands out and what a re-parse reads. Made on demand
+ * (cached), never on load or on each replaceColumns.
+ */
+export declare function columnsText(ds: LoadedDataset): string;

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

@@ -0,0 +1,394 @@
+/**
+ * The Kymoscope engine: every capability of the Kymoscope app as a UI-free API.
+ *
+ * Domain state lives in one immutable store. Operations replace it; `subscribe`
+ * and `on('change')` fire once per effective change. Charts are mounted with
+ * `engine.charts.mount()` (see charts/), which reads the same state.
+ */
+import type { Worksheet } from '../lib/savedLayout';
+import { type ChartAnnotation } from '../lib/annotations';
+import type { LoadedDataset } from '../types/loadedDataset';
+import type { PlotSeries } from '../types/plotSeries';
+import { type PanelChartSettings } from '../lib/panelChartSettings';
+import type { MathChannel, MathChannelPatch } from '../lib/mathChannels/types';
+import type { EvalResult } from '../lib/mathChannels/types';
+import type { LiveConnection, LiveStreamDescriptor, LiveStreamOptions, LocalLiveStream, StreamKeyProvider } from '../lib/live/types';
+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 Dataset, type DatasetParseConfig } from '../lib/parseDataset';
+import { parseKymoscopeFile, type WorkbookBody } from '../lib/workspaces/io';
+import { type WorkbookFileOptions } from '../lib/workspaces/encrypted';
+import { canPickDirectory, isImportable, pickDirectoryEntries, type DirNode, type FolderEntry } from '../lib/folderTree';
+import { type ChartView, type MountOptions } from '../charts/runtime';
+import { type ChartWindow, type ChartWindowOptions } from '../charts/chartWindow';
+import { type ColumnsInput } from './columns';
+import { createDerivations } from './derive';
+import { chartLabel, type ChartKindInfo } from './kinds';
+import { createLiveController } from './liveController';
+import { createStore } from './store';
+import { type ChartKind, type ChartModel, type EngineEvents, type EngineOptions, type EngineState, type KymoscopeLimits } from './types';
+export declare const DEFAULT_X = "ET";
+/** Default series / scatter colours (matches the app). */
+export declare const PALETTE: string[];
+/** Internal domain state. Worksheets keep the persisted shape (panels + settings maps). */
+export interface InternalState {
+    datasets: LoadedDataset[];
+    selection: string[];
+    worksheets: Worksheet[];
+    activeWorksheetId: string;
+    xRanges: Record<string, [number, number] | null>;
+    offsets: Record<string, number>;
+    colors: Record<string, string>;
+    liveWindowSeconds: number | null;
+    live: LiveConnection[];
+    mathChannels: MathChannel[];
+    limits: KymoscopeLimits;
+    palette: string[];
+    importing: number;
+    /** null until the licence check finishes. */
+    licensed: boolean | null;
+    history: EngineState['history'];
+}
+export type ImportSource = File | FolderEntry;
+export interface ImportResult {
+    ids: string[];
+    errors: {
+        file: string;
+        error: Error;
+    }[];
+    /** The signal aborted: the file being read was dropped and later ones skipped. */
+    cancelled?: boolean;
+}
+export interface ImportOptions {
+    /** Cancels the import (KymoscopeError 'cancelled' for the file being read; later files are skipped). */
+    signal?: AbortSignal;
+    /** Asked before reading a binary file with more than 2,000 channels or an ambiguous structure (HDF5); null cancels it. Without it every channel is read. */
+    chooseChannels?: ChannelChooser;
+    /** Ask `chooseChannels` for every binary file. */
+    pickChannels?: boolean;
+}
+/** A cloud recording to open: its chunks in seq order (Blobs straight from the downloads) and its keys. */
+export interface RecordingInput {
+    recordingId: string;
+    name: string;
+    chunks: Blob[];
+    keys: RecordingKey[];
+    startTime: string | null;
+}
+export interface Snapshot {
+    datasets: LoadedDataset[];
+    worksheets: Worksheet[];
+    activeWorksheetId: string;
+    selection: string[];
+}
+export interface Exported {
+    json: unknown;
+    blob: Blob;
+    filename: string;
+}
+export type ParsedFile = Awaited<ReturnType<typeof parseKymoscopeFile>>;
+export type ChartSettingsPatch = Partial<PanelChartSettings> & Record<string, unknown>;
+export declare function createEngine(options?: EngineOptions): {
+    getState: () => EngineState;
+    subscribe(listener: () => void): () => void;
+    on: <K extends keyof EngineEvents>(event: K, cb: (payload: EngineEvents[K]) => void) => () => void;
+    /** Resolves to whether this page holds a valid license, after the first check (of licenseKey, or of the
+     *  first license.get when given). Later renewals update isLicensed() and getState().licensed. */
+    licensed: Promise<boolean>;
+    /** null until the license check finishes. */
+    isLicensed: () => boolean | null;
+    /** Update host options at runtime (e.g. limits once the user's plan loads). */
+    setOptions(next: Partial<Omit<EngineOptions, "licenseKey" | "license">>): void;
+    datasets: {
+        importFiles: (sources: ImportSource[], options?: ImportOptions) => Promise<ImportResult>;
+        /**
+         * Get the next import ready (one-shot): its worker starts now and, for 'hdf5' / 'mat' in
+         * `formats`, loads h5wasm (~4.8 MB, fetched once). Call it on idle, or when the user
+         * shows import intent (drag over, file picker); after it is used, another is prepared on idle.
+         */
+        warmImport(options?: {
+            formats?: string[];
+        }): void;
+        /** A combined multi-rate import as one dataset per group (each read again from its file). Returns the new ids. */
+        splitByRate(id: string): Promise<string[]>;
+        /** A binary import read again with the channels `chooser` picks (it starts from what was read). Null: cancelled, the dataset stays. */
+        chooseChannels(id: string, chooser: ChannelChooser): Promise<string[] | null>;
+        /** The datasets split from one file (pass any of them), combined again into one. Returns its id. */
+        combine(id: string): Promise<string>;
+        /**
+         * 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>;
+        /** New chunks of an open recording: the dataset keeps its id, selection, colour, offset and laps. */
+        reopenRecording(id: string, input: RecordingInput): Promise<void>;
+        /** Add numeric columns from the host (selected immediately). */
+        addColumns(input: ColumnsInput): string;
+        /**
+         * New data for a dataset added with `addColumns`, in place: pass the columns
+         * that changed (the others are kept, not copied); new names add columns. The
+         * dataset keeps its id, selection, colour, offset and laps, and every chart
+         * draws the new data on its next frame — for data that changes many times
+         * a second (a simulation, a sweep), instead of adding a dataset per update.
+         * `transfer`: hand the Float64Arrays over instead of having them copied
+         * (see ColumnsInput.transfer); the host must not touch them afterwards.
+         */
+        replaceColumns(id: string, columns: Record<string, ArrayLike<number>>, opts?: {
+            transfer?: boolean;
+        }): void;
+        /**
+         * New values for columns of a dataset added with `addColumns`, written by
+         * `fill` straight into arrays the engine reuses (no copy, no garbage): for
+         * data rewritten every frame. `fill(cols, current)` gets one Float64Array
+         * per name, of the dataset's length, and must set every value; `current`
+         * holds the values being replaced (read-only).
+         */
+        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>;
+        remove(id: string): void;
+        /** Remove every dataset. Worksheets and charts are kept. */
+        clear(): void;
+        /** Re-parse with another config and/or split into laps (both need an in-memory dataset; `beacon: null` always works). */
+        /** `selectCycles` ('all' by default): when a selected dataset is split, plot
+         *  every cycle, or only the one with the lowest value (see bestCycleIndex). */
+        configure(id: string, change: {
+            parseConfig?: DatasetParseConfig;
+            beacon?: BeaconConfig | null;
+            selectCycles?: "all" | "best";
+        }): Promise<void>;
+        setColor(id: string, color: string | null): void;
+        setOffset(id: string, x: number): void;
+        resetOffsets(): void;
+        /** Replace the plotted ids (dataset, lap or live ids). */
+        select(ids: string[]): void;
+        /** Toggle one id. A dataset split into laps toggles all its laps (on unless all are on). */
+        toggle(id: string): void;
+        selectAll(): void;
+        deselectAll(): void;
+        /**
+         * The parsed content of one dataset (for re-configure dialogs, previews).
+         * `rawText` is made when read: a dataset from columns has no text and builds
+         * its CSV then (cached until its data changes), so reading only `data` or
+         * `parseConfig` never pays for it.
+         */
+        raw(id: string): {
+            rawText: string;
+            data: Dataset;
+            parseConfig: DatasetParseConfig | null;
+            kind: "memory" | "duckdb" | "columnar";
+            beacon: BeaconConfig | null;
+        };
+        /** Min/max of a column across the plotted data (out-of-core and live included). */
+        columnBounds(column: string): Promise<{
+            min: number;
+            max: number;
+        } | null>;
+    };
+    folders: {
+        fromFileList: (files: FileList | File[]) => FolderEntry[];
+        /** Entries from a drag-and-drop (folders are walked recursively). */
+        fromDataTransfer(dt: DataTransfer): Promise<FolderEntry[]>;
+        canPick: typeof canPickDirectory;
+        /** Native directory picker; null when cancelled or unsupported. */
+        pick: typeof pickDirectoryEntries;
+        tree: (entries: FolderEntry[], rootName?: string) => DirNode;
+        isImportable: typeof isImportable;
+    };
+    worksheets: {
+        add(name?: string): string;
+        rename(id: string, name: string): void;
+        remove(id: string): void;
+        reorder(from: number, to: number): void;
+        activate(id: string): void;
+        /** Change the shared X column. Drops series on it and clears zoom, offsets and colours. */
+        setXKey(id: string, key: string): void;
+    };
+    charts: {
+        /** Render a chart into `element` (it fills the element). */
+        mount(chartId: string, element: HTMLElement, options?: MountOptions): ChartView;
+        /**
+         * Open the chart in its own browser window (call it from a click: browsers block other popups).
+         * Opening an already open chart focuses its window. Throws `popup_blocked` when the browser refuses.
+         */
+        openWindow(chartId: string, options?: ChartWindowOptions): ChartWindow;
+        /** Font families for every chart's text (canvas text cannot inherit CSS fonts). */
+        setFonts(fonts: {
+            sans?: string;
+            mono?: string;
+        }): void;
+        kinds: () => ChartKindInfo[];
+        label: typeof chartLabel;
+        add(kind: ChartKind, o?: {
+            worksheetId?: string;
+            title?: string;
+            settings?: ChartSettingsPatch;
+            layout?: ChartModel["layout"];
+        }): string;
+        remove(chartId: string): void;
+        rename(chartId: string, title: string | null): void;
+        /**
+         * Merge a settings patch (the kind cannot change). Changing an X-Y scatter
+         * column auto-scales that axis unless the patch sets the scale too.
+         */
+        update(chartId: string, patch: ChartSettingsPatch): void;
+        /** Replace the whole settings object (same kind). */
+        replaceSettings(chartId: string, settings: PanelChartSettings): void;
+        setBackground(chartId: string, color: string | null): void;
+        /** Add a mark over the chart; returns its id (the one given, or a new one). */
+        addAnnotation(chartId: string, annotation: Omit<ChartAnnotation, "id"> & {
+            id?: string;
+        }): string;
+        /** Change one annotation (its kind and id stay). */
+        updateAnnotation(chartId: string, annotationId: string, patch: Partial<Omit<ChartAnnotation, "id" | "kind">>): void;
+        removeAnnotation(chartId: string, annotationId: string): void;
+        /** Replace every annotation of a chart ([] clears them); invalid entries are dropped. */
+        setAnnotations(chartId: string, annotations: ChartAnnotation[]): void;
+        setLayout(chartId: string, layout: ChartModel["layout"]): void;
+        /** Set several layouts at once (e.g. after a grid drag). */
+        setLayouts(worksheetId: string, layouts: Record<string, ChartModel["layout"]>): void;
+        /** Re-flow a worksheet's charts onto the automatic grid. */
+        autoLayout(worksheetId?: string): void;
+        get(chartId: string): ChartModel;
+        list(worksheetId?: string): ChartModel[];
+        addSeries(chartId: string, column?: string): Promise<string | null>;
+        /** Patch a series; changing its column auto-scales it to the new column. */
+        updateSeries(chartId: string, seriesId: string, patch: Partial<PlotSeries>): Promise<void>;
+        removeSeries(chartId: string, seriesId: string): void;
+        /** New order as series ids (unknown ids are ignored, missing ones appended). */
+        reorderSeries(chartId: string, seriesIds: string[]): void;
+        /** Fit a series' Y scale to its column's data range. */
+        autoScaleSeries(chartId: string, seriesId: string): Promise<void>;
+    };
+    view: {
+        /** Linked X zoom of a worksheet (default: active); null = full range. */
+        setXRange(range: [number, number] | null, worksheetId?: string): void;
+        resetZoom(worksheetId?: string): void;
+        setLiveWindow(seconds: number | null): void;
+    };
+    mathChannels: {
+        /** Create a channel (`name` and `formula` at least). Returns it. */
+        create(input: Partial<MathChannel> & {
+            name: string;
+            formula: string;
+        }): MathChannel;
+        update(id: string, patch: MathChannelPatch): void;
+        remove(id: string): void;
+        /** Import channels from a JSON export. Returns what was imported and per-entry errors. */
+        importFile(file: File): Promise<{
+            channels: MathChannel[];
+            errors: string[];
+        }>;
+        /** Add several channels at once (e.g. parsed from a file by your own UI). */
+        importMany(channels: MathChannel[]): Promise<MathChannel[]>;
+        exportBlob: () => Blob;
+        /** Evaluate a channel against the plotted data (for editors). */
+        preview(channel: MathChannel, worksheetId?: string): EvalResult | null;
+        /** Host-owned store: push the authoritative list after it changes (an open workbook's channels stay). */
+        sync(channels: MathChannel[]): void;
+    };
+    live: {
+        /** A stream the page feeds itself (no relay, no crypto). */
+        openLocal(name: string, options?: LiveStreamOptions): LocalLiveStream;
+        /** Join an end-to-end encrypted relay stream with its password, the API key
+         *  that publishes it, its key (CryptoKey, e.g. from `unwrapStreamKey`), or a
+         *  StreamKeyProvider (streams of end-to-end encrypted projects). */
+        connect(stream: LiveStreamDescriptor, secret: string | CryptoKey | StreamKeyProvider, options?: LiveStreamOptions): Promise<void>;
+        /** Record every sample the connection receives from now on (whole, not just
+         *  the live window the charts keep). */
+        startRecording(id: string): void;
+        /** Stop recording. Returns the recording as CSV parts (`new Blob(csv)` to
+         *  save it) with its row count, stream name and start time; null if none ran. */
+        stopRecording(id: string): {
+            csv: string[];
+            rows: number;
+            name: string;
+            startedAt: number;
+        } | null;
+        /** Samples currently buffered for a connection (cheap; poll it for counters). */
+        rowCount(id: string): number;
+        disconnect(id: string): void;
+    };
+    io: {
+        /** True when there are charts that a workspace import would replace. */
+        hasWork: () => boolean;
+        exportWorksheet(worksheetId?: string): Exported;
+        exportChart(chartId: string): Exported;
+        /** What a file contains: 'workspace' | 'worksheet' | 'chart' | 'encrypted' | 'error'. */
+        parseFile: (file: File) => Promise<ParsedFile>;
+        /** Envelope v2 of every worksheet as JSON (plain: embedders' own storage). Limit: workspaces-io. */
+        exportWorkspace(): Exported;
+        /** A `.kymo` file: v3 under a scope key the host holds (AES-256-GCM; `password`: an optional PBKDF2-SHA256 600k
+         *  layer inside), or, given only a password, v2 (password-only, for embedders without scope keys). Limit:
+         *  workspaces-io. */
+        exportWorkspaceEncrypted(options: WorkbookFileOptions | string): Promise<Exported>;
+        /** Replace every worksheet with a v1, v2 or `.kymo` file (datasets are kept). A v3 file needs its scope's `key`
+         *  (parseFile says which scope) and, when it has one inside, the `password`. */
+        importWorkspace(src: File | Blob | string | object, options?: {
+            password?: string;
+            key?: Uint8Array;
+        }): Promise<{
+            worksheets: number;
+            errors: string[];
+        }>;
+        /** The body a cloud workbook stores (not gated by workspaces-io: the host gates its cloud). */
+        toWorkbook: () => WorkbookBody;
+        /** Open a cloud workbook's body (v1 or v2) over whatever data is loaded. */
+        openWorkbook(body: unknown): {
+            worksheets: number;
+            errors: string[];
+        };
+        /** Append an exported worksheet and activate it. */
+        importWorksheet(src: File | Blob | string | object): Promise<string>;
+        /** Add an exported chart to a worksheet (default: active). */
+        importChart(src: File | Blob | string | object, worksheetId?: string): Promise<string>;
+        /** Everything needed to rebuild this state later in the same page. */
+        snapshot(): Snapshot;
+        /** Replace datasets, worksheets and selection at once (e.g. a prepared demo). */
+        restore(snap: Snapshot): void;
+        /** Empty workspace: no datasets, one blank worksheet. Live connections stay. */
+        reset(): void;
+    };
+    /** Undo/redo of the analysis: worksheets, charts, settings, annotations and the math channels the workbook carries.
+     *  Not data loading, live streams, selection, zoom, switching worksheets, own (library) math channels (saved to the
+     *  library at once) or laps settings (they follow the data). During a live stream an undo may plot against the
+     *  step's X key until the next connection change. Cleared by io.openWorkbook/importWorkspace/restore/reset.
+     *  `getState().history` says whether there is a step to undo or redo. */
+    history: {
+        undo(): void;
+        redo(): void;
+        clear(): void;
+    };
+    data: {
+        /**
+         * The plotted datasets and live streams merged into one table, with every
+         * math channel materialised (against the worksheet's X key). null when
+         * nothing is plotted. For tables, previews and custom renderers.
+         */
+        merged(worksheetId?: string): Dataset | null;
+        /** Like merged() without the math channels: no row cloning, stable until the data changes. */
+        plotted(): Dataset | null;
+    };
+    dispose(): void;
+};
+export type KymoscopeEngine = ReturnType<typeof createEngine>;
+/** Internal access for the chart runtime (not part of the public API). */
+export interface EngineInternals {
+    store: ReturnType<typeof createStore<InternalState>>;
+    derived: () => {
+        laps: ReturnType<ReturnType<typeof createDerivations>['lapsByDataset']>;
+        selectedDatasets: LoadedDataset[];
+        selectedLive: LiveConnection[];
+        staticDataset: Dataset | null;
+        merged: Dataset | null;
+        channels: MathChannel[];
+        numericColumns: string[];
+        allColumns: string[];
+        columnUnits: Record<string, string>;
+    };
+    live: ReturnType<typeof createLiveController>;
+}
+export declare function getInternals(engine: KymoscopeEngine): EngineInternals;
+export { DATASET_PALETTE };

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

@@ -0,0 +1,27 @@
+/**
+ * Shared derivations over the engine's domain state. Each selector recomputes only
+ * when its inputs change identity (live frames never change these inputs: the
+ * live snapshot is rebuilt only on structural changes).
+ */
+import type { LoadedDataset } from '../types/loadedDataset';
+import type { LiveConnection } from '../lib/live/types';
+import type { MathChannel } from '../lib/mathChannels/types';
+import type { Dataset } from '../lib/parseDataset';
+export interface LapGroup {
+    laps: LoadedDataset[];
+    values: (number | null)[];
+    unit: string;
+    isTime: boolean;
+}
+export declare function createDerivations(): {
+    lapsByDataset: (datasets: LoadedDataset[]) => Record<string, LapGroup>;
+    selectedDatasets: (datasets: LoadedDataset[], laps: Record<string, LapGroup>, selection: string[]) => LoadedDataset[];
+    selectedLive: (live: LiveConnection[], selection: string[]) => LiveConnection[];
+    staticDataset: (selected: LoadedDataset[]) => Dataset | null;
+    mergedDataset: (stat: Dataset | null, live: LiveConnection[]) => Dataset | null;
+    mergedParts: (selected: LoadedDataset[], live: LiveConnection[]) => Dataset[];
+    numericColumns: (merged: Dataset | null, selected: LoadedDataset[], channels: MathChannel[], parts?: Dataset[] | undefined) => string[];
+    allColumns: (merged: Dataset | null, selected: LoadedDataset[], channels: MathChannel[]) => string[];
+    columnUnits: (merged: Dataset | null, channels: MathChannel[]) => Record<string, string>;
+};
+export type Derivations = ReturnType<typeof createDerivations>;

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

@@ -0,0 +1,6 @@
+/** Minimal typed event emitter. A throwing listener never breaks the others. */
+export declare function createEmitter<E extends Record<string, unknown>>(): {
+    on<K extends keyof E>(event: K, cb: (payload: E[K]) => void): () => void;
+    emit<K extends keyof E>(event: K, payload: E[K]): void;
+    clear(): void;
+};

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

@@ -0,0 +1,7 @@
+export type KymoscopeErrorCode = 'column_length_mismatch' | 'no_columns' | 'bad_workspace' | 'bad_file' | 'import_vetoed' | 'limit_reached' | 'not_found' | 'wrong_password' | 'password_required' | 'scope_key_required' | 'relay_unavailable' | 'disposed' | 'invalid_argument' | 'export_failed' | 'popup_blocked' | 'cancelled';
+/** Every failure the SDK reports. `detail` carries structured context (e.g. `{reason}` for limits). */
+export declare class KymoscopeError extends Error {
+    readonly code: KymoscopeErrorCode;
+    readonly detail?: unknown;
+    constructor(code: KymoscopeErrorCode, detail?: unknown);
+}

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

@@ -0,0 +1,29 @@
+/** Undo/redo of the analysis: stacks of analysis snapshots (spec 2026-10-20-undo-start-samples-design.md §A).
+ *  `observe` is called after every effective change with the current snapshot; one that is not `equals` to the current
+ *  records a step, and a burst of changes within `mergeMs` of the previous recorded one stays one step. In memory only. */
+export interface HistoryOptions<T> {
+    limit: number;
+    mergeMs: number;
+    now: () => number;
+    equals?: (a: T, b: T) => boolean;
+}
+export declare class AnalysisHistory<T> {
+    private past;
+    private future;
+    private current;
+    private lastAt;
+    private readonly o;
+    private readonly equals;
+    constructor(o: HistoryOptions<T>);
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    /** The analysis after a change. True when it recorded (or extended) a step. */
+    observe(snap: T): boolean;
+    /** The analysis changed without a user edit (loaded data adapted it, a step was applied): the new current, no step. */
+    rebase(snap: T): void;
+    /** The snapshot to apply, or null. */
+    undo(): T | null;
+    redo(): T | null;
+    /** Forget both stacks; `baseline` is the analysis now on screen. */
+    clear(baseline: T | null): void;
+}

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

@@ -0,0 +1,9 @@
+import type { ChartKind } from './types';
+export interface ChartKindInfo {
+    kind: ChartKind;
+    label: string;
+}
+/** Every chart kind the SDK renders, in menu order. */
+export declare const CHART_KINDS: ChartKindInfo[];
+/** Human label of a chart kind (e.g. 'Multi-band'). */
+export declare function chartLabel(kind: ChartKind): string;

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

@@ -0,0 +1,27 @@
+import { type LiveRelayConfig } from '../lib/live/stream';
+import type { MathChannel } from '../lib/mathChannels/types';
+import type { LiveConnection, LiveStreamDescriptor, LiveStreamOptions, LocalLiveStream, StreamKeyProvider } from '../lib/live/types';
+export interface LiveController {
+    connections(): LiveConnection[];
+    /** `secret`: the stream password, the API key that publishes it, the stream key
+     *  itself (e.g. unwrapped from a device wrap), or a key provider (encrypted projects). */
+    connect(stream: LiveStreamDescriptor, secret: string | CryptoKey | StreamKeyProvider, options?: LiveStreamOptions): Promise<void>;
+    disconnect(id: string): void;
+    /** Start recording every sample `id` receives (no-op if already recording). */
+    startRecording(id: string): void;
+    /** Stop recording; the recording as CSV parts, or null if none was running. */
+    stopRecording(id: string): {
+        csv: string[];
+        rows: number;
+        name: string;
+        startedAt: number;
+    } | null;
+    openLocal(name: string, options?: LiveStreamOptions): LocalLiveStream;
+    setRelay(relay: LiveRelayConfig | undefined): void;
+    /** Math channels evaluated on every stream (as computed buffer columns). */
+    setMathChannels(channels: MathChannel[]): void;
+    dispose(): void;
+}
+export declare function createLiveController(initialRelay: LiveRelayConfig | undefined, onChange: (connections: LiveConnection[]) => void, 
+/** The host's defaults for new streams (read when one opens). */
+defaults?: () => LiveStreamOptions): LiveController;

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

@@ -0,0 +1,8 @@
+/** Immutable-snapshot store: `set` replaces the state; listeners run only on a real change. */
+export declare function createStore<S>(initial: S): {
+    get: () => S;
+    set(updater: (prev: S) => S): void;
+    subscribe(listener: () => void): () => void;
+};
+/** Caches the last result; recomputes only when an argument changes identity. */
+export declare function memoizeLast<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;