@kymoscope/sdk 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,42 @@
+import * as duckdb from '@duckdb/duckdb-wasm';
+import type { DataSource, ColumnSchema, SeriesQuery, DecimatedSeries, Viewport, MultiSeriesResult } from './dataSource';
+import { type XRange } from '../duckdb/sql';
+import type { IngestProgress } from './dataSource';
+import { type DatasetRow } from '../parseDataset';
+export type { IngestProgress } from './dataSource';
+/** A table name no other open dataset uses. */
+export declare const nextTableName: () => string;
+export declare class DuckDbDataSource implements DataSource {
+    #private;
+    private constructor();
+    /** Ingest a file into an in-memory DuckDB table and return a ready DataSource. */
+    static open(file: File, onProgress?: (p: IngestProgress) => void): Promise<DuckDbDataSource>;
+    /** A source over a table already in DuckDB (a CSV ingest, a binary import); its schema from DESCRIBE. */
+    static attach(conn: duckdb.AsyncDuckDBConnection, table: string, unitByName: Map<string, string>): Promise<DuckDbDataSource>;
+    getSchema(): Promise<ColumnSchema[]>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    /**
+     * Decimate SEVERAL columns over a viewport in ONE query. Returns the raw query
+     * rows (aliased y{i}lo/y{i}hi) plus the bucket geometry; the caller turns them
+     * into points. One round-trip for all series, vs one query per series.
+     */
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    /**
+     * A decimated, order-preserving sample of ~`maxRows` rows as plain objects, so
+     * the row-based chart pipelines (scatter, histogram, mesh, …) can render a
+     * large dataset with bounded memory — the same way multiband uses decimation,
+     * just materialized into rows instead of per-series buckets.
+     *
+     * Pass `range` to sample only within an x window: as the shared X view zooms
+     * in, the sample is re-taken inside that window, so the row-based charts gain
+     * resolution on zoom exactly like multiband's per-viewport decimation. Rows in
+     * a narrow window are denser, so the same `maxRows` budget buys finer detail.
+     */
+    sampleRows(maxRows: number, range?: XRange): Promise<DatasetRow[]>;
+    /** Full-range x bounds for a column, for an initial viewport. */
+    xBounds(xKey: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    dispose(): Promise<void>;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * The min–max envelope of several traces of one signal (one per dataset or
+ * lap): each trace is read at the same X positions (linear interpolation
+ * between its samples), and at each position the envelope spans the smallest
+ * to the largest value. Where fewer than two traces have a value, it is NaN.
+ */
+export interface Envelope {
+    x: Float64Array;
+    lo: Float64Array;
+    hi: Float64Array;
+}
+export interface Trace {
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+}
+export declare function minMaxEnvelope(traces: Trace[], points: number): Envelope | null;

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

@@ -0,0 +1,25 @@
+import type { DataSource, ColumnSchema, SeriesQuery, DecimatedSeries, Viewport, MultiSeriesResult } from './dataSource';
+import type { PointColumns } from './pointColumns';
+import { type Dataset } from '../parseDataset';
+/** DataSource backed by an already-parsed in-memory Dataset (small files). */
+export declare class InMemoryDataSource implements DataSource {
+    #private;
+    constructor(dataset: Dataset);
+    getSchema(): Promise<ColumnSchema[]>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    /** {@link getSeriesMulti} without the Promise: in memory it is pure computation. */
+    getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
+    /** {@link DataSource.getColumnsSync}: a table's columns are the samples (other rows: null, decimate). */
+    getColumnsSync(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    /** Exact min/max like the DuckDB source ({0, 0} when the column has no numbers), not `columnBounds`' padded axis range. */
+    xBounds(column: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    xBoundsSync(column: string): {
+        x0: number;
+        x1: number;
+    };
+    dispose(): Promise<void>;
+}

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

@@ -0,0 +1,77 @@
+import type { DataSource, ColumnSchema, SeriesQuery, DecimatedSeries, Viewport, MultiSeriesResult } from './dataSource';
+import type { LiveBuffer } from '../live/buffer';
+import type { Dataset } from '../parseDataset';
+import type { PointColumns } from './pointColumns';
+/**
+ * A `DataSource` over a live `LiveBuffer`. Decimates straight from the columnar
+ * ring buffer (no row objects), so a live stream feeds the same decimated
+ * interface as static/out-of-core sources — the prerequisite for compositing
+ * many datasets + streams at flat cost. The buffer is read lazily on each query,
+ * so new samples are picked up without rebuilding anything.
+ */
+export declare class LiveDataSource implements DataSource {
+    #private;
+    constructor(buffer: LiveBuffer | (() => LiveBuffer));
+    /** Current sample count of the underlying ring, read live (no allocation). Lets
+     *  a host's sample-count badge show the climbing count by polling itself, instead of the
+     *  count riding on the ~1 Hz `connections` state whose update re-renders the App. */
+    size(): number;
+    /** Changes whenever the buffered data does (see LiveBuffer.version). */
+    version(): number;
+    /**
+     * Every buffered sample, column by column, read on demand: a column is copied
+     * out of the ring when first asked for (incrementally, see
+     * LiveBuffer.mirrorColumn). A new map per call: the columns as they are now.
+     */
+    columns(): ReadonlyMap<string, Float64Array>;
+    /** A fresh row snapshot of the newest samples (at most `maxRows`, evenly thinned). */
+    snapshot(maxRows: number): Dataset;
+    getSchema(): Promise<ColumnSchema[]>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    /**
+     * Synchronous multi-column decimation — the live multiband chart calls this
+     * every animation frame from its own rAF loop, so it must not go through a
+     * Promise (a microtask per frame would add churn). Reads the ring buffer lazily,
+     * so each call sees the newest samples. Buckets by x VALUE, so a wrapping X
+     * channel (lap distance resetting each lap) decimates correctly.
+     */
+    getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
+    /** {@link getSeriesMultiSync} as chart points: on the live time axis with no
+     *  row objects in between (see LiveBuffer.decimatePoints). */
+    getPointsSync(columns: string[], viewport: Viewport, maxPoints: number): PointColumns;
+    xBounds(column: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    /** Synchronous {@link xBounds} for the chart's per-frame pull (no allocation). */
+    xBoundsSync(column: string): {
+        x0: number;
+        x1: number;
+    };
+    /** X distance covered by the newest `seconds` of samples (see LiveBuffer.xTravel). */
+    xTravelSync(column: string, seconds: number): number;
+    /** Time of the newest sample (NaN if empty). */
+    latestTimeSync(): number;
+    /** Value of `column` at time `t` (see LiveBuffer.xAtTime). */
+    xAtTimeSync(column: string, t: number): number;
+    /** The newest sample's value of `column` (NaN if none): the live position on X. */
+    latestSync(column: string): number;
+    /** Newest received value of each column it has (finite values only). */
+    latestValuesSync(columns: string[]): Map<string, number>;
+    /** Follow cycles on `xKey` (beacon): see LiveBuffer.trackCycles. */
+    trackCycles(xKey: string): void;
+    /** X span of every sample seen on a tracked key, or null. */
+    cycleSpanSync(xKey: string): [number, number] | null;
+    /** Decimated columns of the current or previous cycle on `xKey`. */
+    decimateCycleSync(xKey: string, which: 'current' | 'previous', columns: string[], viewport: {
+        x0: number;
+        x1: number;
+    }, maxPoints: number): MultiSeriesResult;
+    /** {@link decimateCycleSync} as chart points (see LiveBuffer.decimateCyclePoints). */
+    cyclePointsSync(xKey: string, which: 'current' | 'previous', columns: string[], viewport: {
+        x0: number;
+        x1: number;
+    }, maxPoints: number): PointColumns;
+    dispose(): Promise<void>;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Tiny insertion-ordered LRU cache. `get` marks an entry as most-recently used;
+ * `set` evicts the least-recently used once `max` is exceeded.
+ */
+export declare class LruCache<K, V> {
+    #private;
+    constructor(max: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    get size(): number;
+}

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

@@ -0,0 +1,24 @@
+import type { LoadedDataset } from '../../types/loadedDataset';
+import type { IngestProgress } from './dataSource';
+/** Build an in-memory LoadedDataset from text handed over directly (the whole text is kept). */
+export declare function openDatasetFromText(id: string, name: string, text: string): Promise<LoadedDataset>;
+/**
+ * Build an in-memory LoadedDataset from a file. The parse worker reads the file
+ * itself, so its text never reaches the page; the dataset keeps only `head` (the
+ * start of the file, for previews) and the file, read again to re-parse.
+ */
+export declare function openDatasetFromBlob(id: string, name: string, blob: Blob, head: string, readText?: (b: Blob) => Promise<string>, signal?: AbortSignal): Promise<LoadedDataset>;
+/** Build a DuckDB-backed LoadedDataset (large files; out-of-core). */
+export declare function openDatasetFromFile(id: string, file: File, onProgress?: (p: IngestProgress) => void): Promise<LoadedDataset>;
+/** Route by values: in memory while it fits the budget (see chooseSourceKind), DuckDB otherwise. */
+export declare function openDataset(id: string, file: File, readText: (f: File) => Promise<string>, onProgress?: (p: IngestProgress) => void, 
+/** Values (rows × columns) already held by in-memory datasets, for the shared budget. */
+priorInMemoryValues?: number, signal?: AbortSignal): Promise<LoadedDataset>;
+/**
+ * `file` again when an open dataset already holds it as parsed in memory: the new
+ * dataset reads the same columns (no read, no parse, no second copy). Null when
+ * there is no such dataset, or it was re-parsed with another config.
+ */
+export declare function openTwin(id: string, file: File, datasets: LoadedDataset[]): Promise<LoadedDataset | null>;
+/** Values (rows × columns) held in memory by `datasets`, counting shared columns once. */
+export declare function inMemoryValues(datasets: LoadedDataset[]): number;

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

@@ -0,0 +1,4 @@
+/** Deterministic, filesystem-safe OPFS Parquet name for an identity key. */
+export declare function opfsParquetName(identityKey: string): string;
+/** Ingest only when the target parquet is not already present in OPFS. */
+export declare function shouldIngest(parquetName: string, existingNames: string[]): boolean;

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

@@ -0,0 +1,59 @@
+import type { MultiDecimationRow } from './dataSource';
+import { type DatasetRow } from '../parseDataset';
+/**
+ * Points of a multiband chart, stored by column: X, the trace starts, and one
+ * array per series key (NaN where a point has no value for it). What the chart
+ * draws, measures and hands to the GPU as is. Point objects (`{ x, values }`)
+ * cost an object per point and a property per value: 2000 series × 2000 points
+ * was 4 million properties written, then read back to fill the GPU buffers.
+ */
+export interface PointColumns {
+    readonly length: number;
+    readonly x: Float64Array;
+    /** 1 where an independent trace starts (never joined to the previous point). */
+    readonly brk?: Uint8Array;
+    readonly cols: ReadonlyMap<string, Float64Array>;
+}
+/**
+ * Columns known to hold no NaN (marked where they are made, which reads every
+ * value anyway): a reader can skip scanning them for gaps.
+ */
+export declare const finiteColumns: WeakSet<Float64Array<ArrayBufferLike>>;
+export declare const NO_COLUMNS: PointColumns;
+/** One point as an object: hand-made data and tests (the chart takes {@link PointColumns}). */
+export interface ChartPoint {
+    x: number;
+    values: Record<string, number>;
+    /** An independent trace starts here: never join it to the previous point
+     *  (e.g. the previous lap ahead of the car on a wrapping lap-distance X). */
+    brk?: boolean;
+}
+/** Point objects as columns. */
+export declare function pointsToColumns(pts: ChartPoint[]): PointColumns;
+/** Layers as point objects (a point keeps only the values it has). */
+export declare function columnsToPoints(layers: PointColumns | PointColumns[]): ChartPoint[];
+/**
+ * Multi-column decimation rows (`{ b, y0lo, y0hi, … }`) as points: per bucket, at
+ * its centre X, one point with every column's min and one with every max. A
+ * bucket where every column has min == max (a single sample) is one point: the
+ * pair only drew a zero-length bar and on fast channels read as a flickering
+ * comb. A change of pass (laps of a wrapping X) starts a new trace.
+ */
+export declare function multiDecimatedToColumns(rows: MultiDecimationRow[], columns: string[], x0: number, bucket: number): PointColumns;
+/** X-sorted points up to `cut` (all when undefined): a live trace's display edge. */
+export declare function columnsUpTo(pc: PointColumns, cut: number | undefined): PointColumns;
+/** Points with X in [x0, x1] of an X-sorted set (views, no copy). */
+export declare function columnsInRange(pc: PointColumns, x0: number, x1: number): PointColumns;
+/** The points whose X passes `keep` (any order; a copy). */
+export declare function filterColumns(pc: PointColumns, keep: (x: number) => boolean): PointColumns;
+/**
+ * Rows as points: X from `xKey`, each of `cols` keyed `col + suffix`, X shifted
+ * by `offset`, at most `maxPoints` rows (evenly subsampled). Rows over a column
+ * table are read by column; when every row is kept, unshifted, the table's own
+ * arrays are the points (nothing copied). Rows without a numeric X are left out.
+ */
+export declare function rowsToColumns(rows: DatasetRow[], xKey: string, cols: string[], maxPoints: number, suffix?: string, offset?: number): PointColumns;
+/** Series keys with `suffix` appended and X shifted by `offset` (multi-dataset overlays). */
+export declare function remapColumns(pc: PointColumns, suffix: string, offset: number): PointColumns;
+/** Point sets one after the other (each key's column NaN where a part lacks it). */
+export declare function concatColumns(parts: PointColumns[]): PointColumns;

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

@@ -0,0 +1,5 @@
+import type { ColumnSchema } from './dataSource';
+/** Numeric column names from a schema (the plottable channels). */
+export declare function schemaNumericCols(schema: ColumnSchema[]): string[];
+/** Unit string for a column, or '' if unknown. */
+export declare function schemaUnitOf(schema: ColumnSchema[], name: string): string;

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

@@ -0,0 +1,48 @@
+import type { Viewport } from './dataSource';
+import { type PointColumns } from './pointColumns';
+/** The slice of DuckDbDataSource this hook needs (one query for all columns). */
+export interface MultiSeriesSource {
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<{
+        x0: number;
+        bucket: number;
+        rows: Array<Record<string, number | bigint | null>>;
+        columns: string[];
+    }>;
+    /** The samples as they are, when few enough: see `rawLimit` in useSeriesPoints. */
+    getColumnsSync?(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    /** Synchronous variant (in-memory sources): see `sync` in useSeriesPoints. */
+    getSeriesMultiSync?(columns: string[], viewport: Viewport, maxPoints: number): {
+        x0: number;
+        bucket: number;
+        rows: Array<Record<string, number | bigint | null>>;
+        columns: string[];
+    };
+}
+/** Fetch min/max envelope points for ALL `columns` over `viewport` in one query. */
+export declare function fetchMultiSeriesPoints(source: MultiSeriesSource, columns: string[], viewport: Viewport, maxPoints: number): Promise<PointColumns>;
+/**
+ * React hook: re-fetches decimated points for `columns` over `viewport` whenever
+ * they change, in a SINGLE multi-column query. Debounced so a continuous
+ * zoom/pan (the chart re-renders existing points fluidly meanwhile) triggers one
+ * query on settle rather than one per wheel event. Previous points are kept
+ * until the new ones arrive, so there is no flicker.
+ */
+export declare function useSeriesPoints(source: MultiSeriesSource | null, columns: string[], viewport: Viewport | null, maxPoints: number, 
+/** Data version: a change re-fetches the same viewport (a growing live source). */
+version?: number, 
+/**
+ * Decimate in the render with `source.getSeriesMultiSync` (an in-memory source):
+ * no debounce and no Promise, so data replaced every frame is drawn every frame
+ * instead of each update cancelling the previous, still pending, query.
+ */
+sync?: boolean, 
+/**
+ * With `sync`: up to this many samples in the viewport are handed over as they
+ * are (`full`), not decimated: the GPU draws them for less than decimating costs.
+ */
+rawLimit?: number): {
+    points: PointColumns;
+    loading: boolean;
+    fetchedViewport: Viewport | null;
+    full?: boolean;
+};

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

@@ -0,0 +1,77 @@
+import type { DatasetRow } from '../parseDataset';
+import type { XYPoint } from '../../components/XYScatterChart';
+/**
+ * X-Y points as columns: what the scatter draws (every point, on the GPU) and
+ * what its fit and dialogs read. `c` is a 0..1 colour value per point
+ * (colormap), `d` a dataset index per point (several datasets at once).
+ */
+export interface XYColumns {
+    length: number;
+    x: ArrayLike<number>;
+    y: ArrayLike<number>;
+    c?: Float32Array;
+    d?: Uint8Array;
+}
+export declare function isXYColumns(v: unknown): v is XYColumns;
+/** XYPoint objects as columns (the SDK still accepts them). */
+export declare function xyColumnsFromPoints(pts: XYPoint[]): XYColumns;
+/** Point `i` as an XYPoint. */
+export declare function xyPointAt(cols: XYColumns, i: number): XYPoint;
+/**
+ * Column `name` of `rows`: the table's own array when the rows are table-backed
+ * (no copy), else read row by row (non-numbers → NaN). `full` (the dataset's
+ * columns when it is columnar, `rows` then being a sample) wins. Undefined when
+ * no row has the column.
+ */
+export declare function rowsColumn(rows: DatasetRow[], name: string, full?: ReadonlyMap<string, Float64Array>): Float64Array | undefined;
+/** The finite values of a column, in order: the column itself when it has none missing. */
+export declare function finiteValues(rows: DatasetRow[], name: string, full?: ReadonlyMap<string, Float64Array>): Float64Array | undefined;
+/**
+ * The finite values of `valueCol` split by the value of `groupCol`, groups in
+ * order of first appearance (label 'unknown' for a missing group); without a
+ * group column, one group labelled `valueCol`. Read from columns, no row objects.
+ */
+export declare function groupedValues(rows: DatasetRow[], valueCol: string, groupCol: string | undefined, full?: ReadonlyMap<string, Float64Array>): {
+    label: string;
+    values: Float64Array;
+}[];
+/**
+ * Samples per unit of a time column (Hz for seconds): its finite samples over
+ * the span they cover, so uniformly sampled data gets its exact rate. Null
+ * when it doesn't advance.
+ */
+export declare function sampleRateOf(t: ArrayLike<number>): number | null;
+export interface XySource {
+    id: string;
+    rows: DatasetRow[];
+    /** The dataset's own full columns when `rows` is only a sample of it. */
+    full?: ReadonlyMap<string, Float64Array>;
+}
+/**
+ * The scatter's columns for one dataset: every point (no sampling), only those
+ * whose `xKey` is inside `viewXRange` when one is set, and a colormap value per
+ * point when `colorCol` has a range. X and Y are the dataset's own arrays when
+ * nothing filters them.
+ */
+export declare function buildXyColumns(src: XySource, xCol: string, yCol: string, opts: {
+    xKey: string;
+    viewXRange: [number, number] | null;
+    colorCol?: string;
+}): {
+    cols: XYColumns;
+    color?: {
+        label: string;
+        min: number;
+        max: number;
+    };
+} | null;
+/** Several datasets on one scatter, each point carrying its dataset index and colour. */
+export declare function buildMultiDatasetXyColumns(sources: XySource[], xCol: string, yCol: string, opts: {
+    xKey: string;
+    viewXRange: [number, number] | null;
+    colorOverrides: Record<string, string>;
+    palette?: readonly string[];
+}): {
+    cols: XYColumns;
+    colors: string[];
+};

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

@@ -0,0 +1,10 @@
+import type { DatasetRow } from './parseDataset';
+/**
+ * Min/max of a column. Scans every row up to `maxScan`; past that, rows spread
+ * evenly over the WHOLE array (never just the first ones: merged data puts one
+ * source after another, so a later source's values would be ignored).
+ */
+export declare function columnBounds(rows: DatasetRow[], col: string, maxScan?: number): {
+    min: number;
+    max: number;
+};

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

@@ -0,0 +1,19 @@
+/**
+ * Per-dataset color palette — each selected dataset gets a distinct hue: orange,
+ * blue, green, red, then the rest. No purples: they read as one muddy family
+ * next to each other on a dark chart.
+ */
+export declare const DATASET_PALETTE: string[];
+/**
+ * The color for a dataset: a user override keyed by dataset id, or the palette
+ * hue for its position when no override is set (the host's palette, see
+ * EngineOptions.palette, else the default one).
+ */
+export declare function colorForDataset(overrides: Record<string, string>, dsId: string, index: number, palette?: readonly string[]): string;
+/**
+ * The default palette for a color scheme: the first dataset in the theme's
+ * strongest contrast (white on dark, black on light), then DATASET_PALETTE.
+ */
+export declare function defaultDatasetPalette(scheme: 'light' | 'dark'): string[];
+/** A host palette as given (valid colors only), or the default one for `scheme`. */
+export declare function resolvePalette(palette: readonly string[] | undefined, scheme?: 'light' | 'dark'): string[];

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

@@ -0,0 +1,3 @@
+import { type DatasetRow } from './parseDataset';
+/** The subset of `columnNames` whose values are numeric (by `columnIsNumeric`). */
+export declare function deriveNumericCols(columnNames: string[], rows: DatasetRow[]): string[];

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

@@ -0,0 +1,8 @@
+import type { Dataset } from './parseDataset';
+/**
+ * Union-merge datasets into one: union of column names, rows concatenated in part
+ * order, and per column the LAST non-empty unit across parts. Returns the single
+ * part unchanged (same reference) when there's one, and null when there are none.
+ * This is the exact merge the chart pipeline has always used.
+ */
+export declare function mergeDatasets(parts: Dataset[]): Dataset | null;

package/dist/types/lib/duckdb/duckdbInstance.d.ts

@@ -0,0 +1,7 @@
+import * as duckdb from '@duckdb/duckdb-wasm';
+/** The module URL DuckDB's worker fetches: a `.gz` asset is inflated here into a blob: URL (same origin as the page).
+ *  Some servers send a `.gz` file with `Content-Encoding: gzip` (the browser has inflated it already): the gzip
+ *  magic bytes decide. */
+export declare function wasmModuleUrl(url: string): Promise<string>;
+/** Lazily instantiate a single DuckDB-WASM database for this tab. */
+export declare function getDuckDb(): Promise<duckdb.AsyncDuckDB>;

package/dist/types/lib/duckdb/fileIdentity.d.ts

@@ -0,0 +1,9 @@
+export interface FileMeta {
+    name: string;
+    size: number;
+    lastModified: number;
+}
+/** Stable identity key for a picked file + a hash of its header bytes. */
+export declare function fileIdentityKey(meta: FileMeta, headerHashHex: string): string;
+/** Hash the first `bytes` of a File via SubtleCrypto (browser). */
+export declare function hashHeader(file: Blob, bytes?: number): Promise<string>;

package/dist/types/lib/duckdb/sql.d.ts

@@ -0,0 +1,124 @@
+/** Quote a SQL identifier (column/table), escaping embedded double quotes. */
+export declare function quoteIdent(name: string): string;
+export interface DecimationParams {
+    table: string;
+    xcol: string;
+    ycol: string;
+    x0: number;
+    x1: number;
+    maxPoints: number;
+}
+/**
+ * Build a min/max-per-x-bucket decimation query. Returns SQL with `?`
+ * placeholders and the ordered numeric params [x0, bucket, x0, x1].
+ */
+export declare function buildDecimationSql(p: DecimationParams): {
+    sql: string;
+    params: number[];
+};
+export interface MultiDecimationParams {
+    table: string;
+    xcol: string;
+    ycols: string[];
+    x0: number;
+    x1: number;
+    maxPoints: number;
+}
+/**
+ * Build ONE decimation query returning min/max per x-bucket for SEVERAL y
+ * columns at once (aliased `y{i}lo` / `y{i}hi` by column index). Lets a
+ * multi-series chart fetch every series in a single round-trip instead of one
+ * query per series. Params: [x0, bucket, maxPoints, x0, x1].
+ */
+export declare function buildMultiDecimationSql(p: MultiDecimationParams): {
+    sql: string;
+    params: number[];
+};
+export interface PyramidBuildL0Params {
+    srcTable: string;
+    dstTable: string;
+    xcol: string;
+    /** Numeric columns to aggregate (NOT the x column). */
+    ycols: string[];
+    /** Pyramid base = the column's minimum x. */
+    x0base: number;
+    /** Bin width of the finest level. */
+    binWidth: number;
+}
+/** CREATE the finest pyramid level by binning the raw table's x into min/max. */
+export declare function buildPyramidBuildL0Sql(p: PyramidBuildL0Params): string;
+/** CREATE the next coarser level (half the bins) from a finer one. */
+export declare function buildPyramidCascadeSql(p: {
+    srcTable: string;
+    dstTable: string;
+    ycols: string[];
+}): string;
+export interface PyramidQueryParams {
+    levelTable: string;
+    /** Requested numeric columns (subset of the level's columns), in order. */
+    ycols: string[];
+    /** Pyramid base x and this level's bin width. */
+    x0base: number;
+    binWidth: number;
+    /** Query viewport + target bucket count. */
+    x0: number;
+    x1: number;
+    maxPoints: number;
+}
+/**
+ * Query one pyramid level for a viewport, re-binning its bins into the query's
+ * `maxPoints` buckets. Returns the SAME shape as {@link buildMultiDecimationSql}
+ * (`b`, `y{i}lo`, `y{i}hi`), so the row→points conversion is unchanged.
+ * Params: [D, C, maxPoints-1, binLo, binHi].
+ */
+export declare function buildPyramidQuerySql(p: PyramidQueryParams): {
+    sql: string;
+    params: number[];
+};
+export interface XRange {
+    xcol: string;
+    x0: number;
+    x1: number;
+}
+/**
+ * Build a row-count query, optionally restricted to an x range. Used to size the
+ * decimation stride before sampling rows. Params are [] or [x0, x1].
+ */
+export declare function buildRowCountSql(p: {
+    table: string;
+    range?: XRange;
+}): {
+    sql: string;
+    params: number[];
+};
+/**
+ * Build an order-preserving, strided row sample (every `stride`-th row),
+ * optionally restricted to an x range. `stride` is a positive integer computed
+ * from the row count, interpolated as a literal (never user input). When
+ * `stride` is 1 it selects all matching rows. Params are [] or [x0, x1].
+ */
+export declare function buildSampleRowsSql(p: {
+    table: string;
+    stride: number;
+    range?: XRange;
+}): {
+    sql: string;
+    params: number[];
+};
+/** Quote a SQL string literal, escaping single quotes by doubling them. */
+export declare function quoteStr(s: string): string;
+export interface ReadCsvParams {
+    handle: string;
+    columnNames: string[];
+    delim: '\t' | ',' | ';';
+    dataStartRow: number;
+    /** True for European-locale files where the comma is the decimal separator. */
+    decimalComma?: boolean;
+}
+/**
+ * Build a read_csv() call that ingests data rows only. The header and any units
+ * row are skipped (skip=dataStartRow), names are supplied explicitly, and each
+ * column is typed as DOUBLE when possible else VARCHAR. When `decimalComma` is
+ * set, a comma is read as the decimal point so "232,6" parses as 232.6.
+ */
+export declare function buildReadCsvSql(p: ReadCsvParams): string;

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

@@ -0,0 +1,15 @@
+/** In-place radix-2 complex FFT (length a power of two). */
+export declare function fft(re: Float64Array, im: Float64Array): void;
+/**
+ * |X[k]| for k < n/2 of the length-`n` DFT (n a power of two ≥ 2) of `x`
+ * (zero-padded to n), each sample first multiplied by `w[i]` when given: the
+ * real signal is packed into an n/2-point complex FFT (half the work of an
+ * n-point one) and the halves untangled. Scratch is reused between calls.
+ */
+export declare function realFftMagnitudes(x: ArrayLike<number>, n: number, w?: ArrayLike<number>): Float64Array;
+/**
+ * The Hann window over `len` samples, in a buffer reused between calls (a live
+ * signal asks for a slightly longer one each time): its cosine by rotation,
+ * no trigonometry per sample.
+ */
+export declare function hannWindow(len: number): Float64Array;

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

@@ -0,0 +1,29 @@
+/** A file picked from a folder, keyed by its path relative to the picked root. */
+export interface FolderEntry {
+    path: string;
+    file: File;
+}
+export interface DirNode {
+    name: string;
+    path: string;
+    dirs: DirNode[];
+    files: FolderEntry[];
+    /** Every importable file path in this subtree (for tri-state checkboxes). */
+    allPaths: string[];
+}
+/** Delimited text plus every binary format and its companion files. */
+export declare const IMPORTABLE_EXT: string[];
+export declare function isImportable(name: string): boolean;
+/** Build a folder tree of importable files; empty folders are pruned. */
+export declare function buildTree(entries: FolderEntry[], rootName?: string): DirNode;
+/** Entries from an `<input webkitdirectory>` FileList. */
+export declare function entriesFromFileList(files: File[]): FolderEntry[];
+/** Recursively read dropped files and folders (Chromium, Firefox and Safari). */
+export declare function entriesFromDrop(roots: FileSystemEntry[]): Promise<FolderEntry[]>;
+/** True where the browser can open a folder without the "upload N files" prompt (Chrome, Edge). */
+export declare function canPickDirectory(): boolean;
+/**
+ * Let the user pick a folder via the File System Access API. Returns null if
+ * they cancel. getFile() only snapshots metadata; contents are read on import.
+ */
+export declare function pickDirectoryEntries(): Promise<FolderEntry[] | null>;