@kymoscope/sdk 0.0.0-stage → 0.1.0

package/dist/types/lib/live/buffer.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Rolling buffer that turns a live stream of decrypted messages into the same
+ * `Dataset` shape produced by file imports, so the existing chart pipeline can
+ * render it unchanged. Keeps at most `capacity` rows (oldest dropped first).
+ */
+import type { Dataset } from '../parseDataset';
+import type { MultiSeriesResult } from '../data/dataSource';
+import { type PointColumns } from '../data/pointColumns';
+export interface LiveSignal {
+    name: string;
+    unit?: string;
+    value: number;
+}
+export interface LiveMessage {
+    /** Timestamp for the X axis (any monotonic numeric clock the sender chooses). */
+    t: number;
+    signals: LiveSignal[];
+}
+/**
+ * Samples by column: `t` and every signal the same length. What a high-rate
+ * source pushes: arrays copied into the ring in bulk, no object per sample.
+ */
+export interface LiveColumnsBlock {
+    t: ArrayLike<number>;
+    columns: Record<string, ArrayLike<number>>;
+    units?: Record<string, string>;
+}
+/** The names of a block's signals (lengths checked against `t`). */
+export declare function blockSignals(block: LiveColumnsBlock, timeColumn: string): string[];
+/** `y{j}lo` / `y{j}hi` row keys, built once per column count: the decimation
+ *  loops read them per sample, and a template string there allocated a new
+ *  string for every sample of every column (~170k per pull on a full ring). */
+/** Name of a live stream's time column (the per-frame `t` of the wire protocol). */
+export declare const LIVE_TIME_COLUMN = "ElapsedTime";
+export declare class LiveBuffer {
+    private time;
+    /** Samples allocated per column (grows to `capacity` while the ring fills). */
+    private alloc;
+    private readonly maxBytes;
+    private readonly cols;
+    private head;
+    private count;
+    private full;
+    /** Rows ever pushed (never wraps). Anchors decimation to an absolute grid. */
+    private pushed;
+    /** Times the buffer was cleared (keeps `version` moving even though `pushed` resets). */
+    private clears;
+    private readonly signalOrder;
+    private readonly unitByName;
+    private capacity;
+    private readonly timeColumn;
+    private readonly timeUnit;
+    /**
+     * Absolute index of the newest sample whose time stepped back from the one
+     * before it (-1: none). The ring's time is ascending again once that sample's
+     * predecessor has left it: one late timestamp (clock jitter) doesn't take the
+     * time-axis fast paths away for the rest of the stream.
+     */
+    private lastBackAbs;
+    /** Time never decreases across the buffered samples (see lastBackAbs). */
+    private get timeMonotonic();
+    private lastPushT;
+    /** Cached bucket map for the incremental live pull; see {@link decimateColumns}. */
+    private decCache;
+    /** The previous cycle's points (see decimateCyclePoints). */
+    private prevCyclePts;
+    /** The current cycle's buckets, kept across pulls (see decimateCyclePoints). */
+    private curCyclePts;
+    /** Cycle trackers by X column (see {@link trackCycles}). */
+    private readonly trackers;
+    /** Diagnostic: ring samples read by the last decimateColumns call (tests assert
+     *  a warm incremental pull reads only the new tail, not the whole ring). */
+    debugLastScan: number;
+    /** Time-axis decimation cache (see decimateTime). */
+    private timeDec;
+    /** Logical-order copies of columns, kept current by {@link mirrorColumn}. */
+    private readonly mirrors;
+    /** The last decimation of a window in the history (its samples don't change while it stays put). */
+    private historyDec;
+    /**
+     * `capacity`: samples kept (the oldest are dropped past it). Memory grows with
+     * the samples actually received; `maxBytes` caps it — once the columns would
+     * outgrow it, the ring keeps the samples it has room for.
+     */
+    constructor(capacity: number, timeColumn?: string, timeUnit?: string, maxBytes?: number);
+    /** Samples this ring keeps at most (lowered when the memory budget is reached). */
+    get maxSamples(): number;
+    private newColumn;
+    /** Room for more samples before the ring wraps: double the columns, or stop at the budget. */
+    private grow;
+    /** Samples ever pushed (and bumped by clear): a data version for consumers. */
+    get version(): number;
+    get size(): number;
+    push(msg: LiveMessage): void;
+    /**
+     * A block of samples (see LiveColumnsBlock), copied into the ring a run at a
+     * time. Same result as pushing them one by one: a signal the block lacks reads
+     * as a gap for its samples; past the capacity only the newest are kept.
+     */
+    pushColumns(block: LiveColumnsBlock): void;
+    /** The sample at absolute index `abs` is earlier than the one before it. */
+    private steppedBack;
+    /** Forget every sample of one column (unit change): gaps, caches rebuilt. */
+    private dropColumnSamples;
+    clear(): void;
+    private columnArray;
+    private physOf;
+    /** Copy ring rows with absolute index in [from, to) (clamped to what the ring
+     *  still holds): X plus `names` (default: every column). */
+    private copyRange;
+    /** Feed one X value (absolute index `abs`) to a tracker; a restart closes the cycle. */
+    private advanceCycle;
+    /**
+     * Start following cycles on `key` (idempotent). The samples already buffered
+     * are replayed through the same rule, so the current and — when the ring holds
+     * it — previous cycle are known immediately.
+     */
+    trackCycles(key: string): void;
+    /** X span of every sample seen on a tracked key, or null. */
+    cycleSpan(key: string): [number, number] | null;
+    /**
+     * Min/max-decimated `columns` of the current or previous cycle on `key` over
+     * [x0, x1]. A cycle longer than the ring only has its buffered part.
+     */
+    decimateCycle(key: string, which: 'current' | 'previous', columns: string[], x0: number, x1: number, maxPoints: number): MultiSeriesResult;
+    /**
+     * {@link decimateCycle} as chart points, without its per-frame copy of the whole
+     * cycle: the previous cycle's points are kept until it changes, and the current
+     * cycle's buckets are kept across pulls with only the samples since the last
+     * pull folded in. Same points as converting decimateCycle's rows.
+     */
+    decimateCyclePoints(key: string, which: 'current' | 'previous', columns: string[], x0: number, x1: number, maxPoints: number): PointColumns;
+    private readonly computed;
+    /** Absolute index of the oldest buffered sample; samples are [firstAbs, endAbs). */
+    get firstAbs(): number;
+    get endAbs(): number;
+    /** Values of `name` for absolute samples [from, to), clamped to the ring (NaN if missing). */
+    range(name: string, from: number, to: number): Float64Array;
+    /**
+     * Every buffered value of `name`, oldest to newest, as a view of an array the
+     * buffer keeps: a call copies only the samples pushed since the last one
+     * (dropped samples are shifted out in place), so a chart reading the whole
+     * stream every frame costs O(new samples), not O(buffer). The same view while
+     * nothing changed; the next change rewrites the array under older views.
+     * Unknown columns: undefined.
+     */
+    mirrorColumn(name: string): Float64Array | undefined;
+    /** Write a computed column's values for absolute samples starting at `from` (created on first write). */
+    writeComputed(name: string, unit: string, from: number, values: ArrayLike<number | null>): void;
+    /** Drop every computed column; caches are rebuilt (version moves, so readers re-pull). */
+    clearComputed(): void;
+    /** Column names in order: the time column first, then the signals. */
+    get columnNames(): string[];
+    /** Unit string for a column (empty if unknown). */
+    unitOf(name: string): string;
+    /**
+     * The values of one column in logical order (oldest → newest) as a typed
+     * array — read straight from the columnar ring buffer, no row objects. Missing
+     * samples and unknown columns read as NaN. Used to decimate without
+     * materializing rows (the live `DataSource` path).
+     */
+    columnValues(name: string): Float64Array;
+    /** Fold one ring sample (at physical index `phys`) into a bucket row's per-column
+     *  min/max. Shared by the full scan and the incremental tail update so both paths
+     *  produce byte-identical rows. Buckets on an ABSOLUTE grid (floor(xv/bucket)),
+     *  NOT relative to the moving window origin: during live auto-scroll x0 slides a
+     *  fraction of a bucket each frame, and a relative index would re-quantize which
+     *  samples land in each bucket every pull, flickering stepped (gear) and fast
+     *  (RPM) channels. Absolute buckets keep a sample in the same bucket as the view
+     *  scrolls, so shared buckets are identical between pulls. */
+    private accumulate;
+    /**
+     * Min/max-decimate several columns over [x0,x1] straight from the ring — no
+     * per-column copy, so the live pull allocates only the small bucket result.
+     * (A full-column copy per frame was ~23 MB/s of garbage → ~300 ms GC pauses.)
+     * Buckets by x VALUE, so a wrapping X (lap distance) decimates correctly. Output
+     * matches `multiDecimateColumns` so the same `multiDecimatedToPoints` converts it.
+     *
+     * Live auto-scroll (a monotonic time axis) is INCREMENTAL: the bucket map is
+     * cached, and each pull folds in only the samples pushed since the last one plus
+     * the single evicting boundary bucket — O(new), not O(buffer). Re-scanning a 12k
+     * ring every frame cost ~7 ms and grew with the buffer, so 12k scrolled less
+     * fluidly than 2k; incremental keeps the pull flat (~2 ms) at any depth. A
+     * non-monotonic X (wrapping lap distance) or changed pull params fall back to a
+     * full scan clipped to the visible samples — bounded, just not cached.
+     */
+    decimateColumns(xKey: string, columns: string[], x0: number, x1: number, maxPoints: number): MultiSeriesResult;
+    /** Logical index (0 = oldest) of the first sample whose time is ≥ `t` (time ascending). */
+    private timeIndex;
+    /** Fold the samples at logical indices [from, to) into `store` (time ascending). */
+    private foldBuckets;
+    /**
+     * The samples at logical indices [from, to) (time ascending) as runs of one
+     * bucket each: `fn(b, p, l)` for physical indices [p, l) in bucket `b`. The ring
+     * part is split into its (at most two) contiguous runs; in each, a bucket's end
+     * is found by galloping + bisection on the bucket index (monotonic in time).
+     */
+    private eachBucketRun;
+    /**
+     * {@link decimateColumns} on the time axis (time ascending), at any ring size:
+     *
+     * - A view reaching the live edge keeps a bucket map from its start to the
+     *   newest sample: each pull folds in only the samples pushed since the last
+     *   one, drops the buckets that scrolled out of view or out of the ring, and
+     *   recomputes the one bucket the oldest sample straddles. Nothing behind the
+     *   view is kept, so a ring of hours costs what the window costs.
+     * - A window in the history is decimated from its own samples (found by
+     *   bisection), once per change of them: data arriving past it changes nothing.
+     *
+     * Buckets are one per sample while that is at most MAX_BUCKETS_PER_POINT per
+     * point (a per-sample line for slow streams), min/max beyond. Widths snap to
+     * 1-2-5 steps with hysteresis, on the absolute grid floor(t / bucket), so
+     * scrolling never re-quantises a sample.
+     */
+    private decimateTime;
+    /**
+     * {@link decimateColumns} as chart points (what multiDecimatedToColumns makes of
+     * its rows). On the live time axis they come straight from the typed buckets,
+     * with no row objects: the chart's per-frame pull.
+     */
+    decimatePoints(xKey: string, columns: string[], x0: number, x1: number, maxPoints: number): PointColumns;
+    /** The buckets of {@link decimateTime}: rows [i0, i1) of `store` are the view's. */
+    private timeBuckets;
+    /** The newest sample's value of a column (NaN if empty or missing). */
+    lastValue(name: string): number;
+    /**
+     * X distance covered by the newest `seconds` of samples on `key`: forward
+     * movement only, so a lap-distance wrap doesn't count. While less than
+     * `seconds` is buffered it extrapolates from what is. On the time column it
+     * is `seconds` itself. NaN with fewer than two samples.
+     */
+    xTravel(key: string, seconds: number): number;
+    /** Time of the newest sample (NaN if empty). */
+    latestTime(): number;
+    /**
+     * Value of `key` at time `t`: interpolated between the samples around it, but
+     * never across a drop (a lap-distance wrap), where it holds the earlier sample.
+     * Clamped to the buffered range; NaN if empty or the time column steps back.
+     */
+    xAtTime(key: string, t: number): number;
+    private boundsCache;
+    /** Min/max of a column over the ring (the chart asks every frame): the ends of
+     *  an ascending time axis, else a scan once per data change. */
+    columnBounds(name: string): {
+        x0: number;
+        x1: number;
+    };
+    private scanBounds;
+    /**
+     * Snapshot of the buffer as a Dataset, rows ordered oldest → newest.
+     *
+     * Pass `maxRows` to decimate: only ~`maxRows` evenly-strided rows (plus the
+     * newest) are materialized, reading the typed columns directly so a full buffer
+     * never allocates a copy of every row each snapshot. A chart can't resolve more
+     * points than it has pixels, so this slashes the memory/CPU the live pipeline
+     * spends rebuilding, merging and sampling the dataset — with no visible loss.
+     *
+     * The stride is anchored to the ABSOLUTE sample index, not to the ring's head.
+     * The head advances with every arriving frame, so a head-relative stride picks
+     * a different raw sample for each plotted point on every snapshot: the trace
+     * re-rolls in place several times a second instead of scrolling. Anchoring
+     * keeps a sample selected until it ages out of the buffer.
+     */
+    toDataset(maxRows?: number): Dataset;
+}

package/dist/types/lib/live/columnsWire.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Plaintext of a KIND_COLUMNS relay message: a block of samples by column.
+ * Self-describing (every block names its channels), so a viewer joining mid-stream
+ * or missing a message needs nothing else. Little-endian:
+ *
+ *   u8   version (1)
+ *   u8   reserved (0)
+ *   u16  channels C
+ *   u32  samples n
+ *   C ×  u8 bytes per value (4 = float32, 8 = float64), u8 name length,
+ *        u8 unit length, name (UTF-8), unit (UTF-8)
+ *   zero padding to a multiple of 8 bytes
+ *   n ×  float64 time
+ *   per channel: n values, zero-padded to a multiple of 8 bytes
+ *
+ * NaN marks a missing value. Every array starts 8-byte aligned, so a reader
+ * views them in place (no copy). Byte-compatible with
+ * examples/kymoscope_live/wire.py (encode_columns / decode_columns).
+ */
+import type { LiveColumnsBlock } from './buffer';
+/** The block in a decrypted KIND_COLUMNS plaintext; arrays are views of it. Throws RangeError if malformed. */
+export declare function decodeColumns(p: Uint8Array): LiveColumnsBlock;
+/** A block as KIND_COLUMNS plaintext (values as float32 unless `float64`). */
+export declare function encodeColumns(block: LiveColumnsBlock, float64?: string[]): Uint8Array;

package/dist/types/lib/live/crypto.d.ts

@@ -0,0 +1,157 @@
+/**
+ * End-to-end encryption primitives for Live Streams.
+ *
+ * The AES-256 key is derived in the browser from a user passphrase via PBKDF2
+ * and NEVER leaves the device. The server only ever relays the resulting
+ * ciphertext envelopes. The same key is used by the sender script (the user
+ * pastes the derived key, or re-derives it from the passphrase + salt).
+ *
+ * AES-GCM provides confidentiality + integrity; a 96-bit random IV is used per
+ * message (safe given the per-message random nonce and the low message volume
+ * of a single stream).
+ */
+/** A self-contained encrypted message: random IV + ciphertext, both base64. */
+export interface EncryptedEnvelope {
+    iv: string;
+    ciphertext: string;
+}
+/** Random 16-byte KDF salt, base64-encoded. Stored server-side; not secret. */
+export declare function generateSalt(): string;
+/** Derive an AES-256-GCM key from a passphrase + base64 salt via PBKDF2. */
+export declare function deriveKey(passphrase: string, saltB64: string): Promise<CryptoKey>;
+/**
+ * Derive the raw AES-256 key bytes (base64) from a passphrase + salt. This is
+ * the exact key a sender script must use; it is byte-identical to the key
+ * `deriveKey` produces, so the browser can decrypt what the script encrypts.
+ */
+export declare function deriveRawKeyBase64(passphrase: string, saltB64: string): Promise<string>;
+/** Import raw AES-256 key bytes (base64) for encrypt/decrypt — e.g. a stream key. */
+export declare function importRawKeyBase64(keyB64: string): Promise<CryptoKey>;
+/** Encrypt a JSON-serializable value into an envelope. */
+export declare function encryptJSON(key: CryptoKey, value: unknown): Promise<EncryptedEnvelope>;
+/** Decrypt an envelope to raw plaintext bytes. Throws if tampered/wrong key. */
+export declare function decryptRaw(key: CryptoKey, env: EncryptedEnvelope): Promise<Uint8Array>;
+/** Decrypt raw AES-GCM bytes (ciphertext ‖ tag) bound to `aad`. Throws if tampered/wrong key. */
+export declare function decryptBytes(key: CryptoKey, iv: Uint8Array, data: Uint8Array, aad: Uint8Array): Promise<Uint8Array>;
+/** Decrypt an envelope back into its original JSON value. */
+export declare function decryptJSON(key: CryptoKey, env: EncryptedEnvelope): Promise<unknown>;
+/** Produce a passphrase verifier (encrypted known marker). Store server-side. */
+export declare function makeKeyCheck(key: CryptoKey): Promise<EncryptedEnvelope>;
+/** Return true if `key` decrypts the verifier to the expected marker. */
+export declare function verifyKeyCheck(key: CryptoKey, check: EncryptedEnvelope): Promise<boolean>;
+/** SHA-256 hex digest of a token. Identical on client (insert) and edge (lookup). */
+export declare function hashToken(token: string): Promise<string>;
+/**
+ * Generate an API token plus a short display prefix. The token is
+ * `kymoscope_<auth>.<secret>`: only the auth part is ever sent to (and hashed
+ * by) the server; the secret part stays with the sender and the owner's browser
+ * and is what stream encryption keys are derived from, so the server can
+ * authenticate a sender yet never decrypt its streams (end-to-end).
+ */
+export declare function generateApiToken(): {
+    token: string;
+    prefix: string;
+};
+/**
+ * Split an API token into the part the server authenticates (`auth`, the only
+ * part to hash or send) and the end-to-end `secret` (null for keys created
+ * before secrets existed, or for anything that is not an API key).
+ */
+export declare function splitApiKey(token: string): {
+    auth: string;
+    secret: string | null;
+};
+/** A stream key sealed to one device: {epk, iv, ct}, all base64. */
+export interface DeviceWrap {
+    epk: string;
+    iv: string;
+    ct: string;
+}
+/**
+ * New device key pair. The private key is NON-extractable (it can unwrap, but
+ * no script can read it out); `publicKey` is the base64 uncompressed point to
+ * register with the account.
+ */
+export declare function generateDeviceKeyPair(): Promise<{
+    privateKey: CryptoKey;
+    publicKey: string;
+}>;
+/** Open raw key bytes sealed to this device under `aad`; throws if they aren't for
+ *  this device or this aad (a stream key, a project key). */
+export declare function unwrapForDevice(privateKey: CryptoKey, wrap: DeviceWrap, aad: string): Promise<Uint8Array>;
+/** Seal raw key bytes to a device's public key (base64 point) under `aad`: what a key
+ *  steward does with a project key. A fresh ephemeral key and IV every time. */
+export declare function wrapForDevice(publicKey: string, raw: Uint8Array, aad: string): Promise<DeviceWrap>;
+/** @internal wrapForDevice with a fixed ephemeral key / IV: pinned test vectors only (not in index.ts). */
+export declare function wrapForDeviceWith(publicKey: string, raw: Uint8Array, aad: string, _ephemeral?: CryptoKeyPair, _iv?: Uint8Array): Promise<DeviceWrap>;
+/** Open a stream key sealed to this device; throws if it isn't for this
+ *  device, stream or key. Returns the AES-GCM key the stream is encrypted with. */
+export declare function unwrapStreamKey(privateKey: CryptoKey, wrap: DeviceWrap, streamId: string, deviceId: string): Promise<CryptoKey>;
+/** Raw key bytes sealed under a project key: {iv, ct}, both base64. */
+export interface SealedKey {
+    iv: string;
+    ct: string;
+}
+export declare const projectWrapAad: (projectId: string, epoch: number, deviceId: string) => string;
+export declare const streamKeyAad: (streamId: string, projectId: string, epoch: number) => string;
+export declare const bindKeyAad: (apiKeyId: string, projectId: string, epoch: number) => string;
+/** 32 random bytes: a new project key. */
+export declare function randomKey(): Uint8Array;
+/** Import raw stream key bytes as the AES-GCM key frames are opened with. */
+export declare function importStreamKey(raw: Uint8Array): Promise<CryptoKey>;
+/** AES-256-GCM under a project key, a random IV every time. */
+export declare function sealUnderProjectKey(pk: Uint8Array, data: Uint8Array, aad: string): Promise<SealedKey>;
+/** @internal sealUnderProjectKey with a fixed IV: pinned test vectors only (not in index.ts). */
+export declare function sealUnderProjectKeyWith(pk: Uint8Array, data: Uint8Array, aad: string, _iv?: Uint8Array): Promise<SealedKey>;
+/** Throws if `sealed` isn't for this project key and aad. */
+export declare function openUnderProjectKey(pk: Uint8Array, sealed: SealedKey, aad: string): Promise<Uint8Array>;
+/** B = SHA-256(utf8(secret) || "kymoscope-sender-bind-v1"): from an API key's secret part. */
+export declare function senderBindKey(secret: string): Promise<Uint8Array>;
+/** base64(HMAC-SHA256(B, "sender|<apiKeyId>|<publicKey>")): a sender proving it holds the key. */
+export declare function senderBinding(bindKey: Uint8Array, apiKeyId: string, publicKey: string): Promise<string>;
+/** Does `binding` prove `publicKey` holds the API key behind `bindKey`? HMAC verify
+ *  (constant time), never a string compare. False on a malformed binding. */
+export declare function verifySenderBinding(bindKey: Uint8Array, apiKeyId: string, publicKey: string, binding: string): Promise<boolean>;
+/** First 8 bytes of SHA-256(raw public key) as 3F2A-91C0-7B44-E215: compared when linking a browser. */
+export declare function deviceFingerprint(publicKey: string): Promise<string>;
+export declare const WORKBOOK_EXPORT_AAD = "kymoscope-workbook-export-v2";
+export declare const workbookBodyAad: (workbookId: string, version: number) => string;
+export declare const workbookKeyAad: (workbookId: string, projectId: string, epoch: number) => string;
+export declare const recoveryKeyAad: (orgId: string, deviceId: string) => string;
+/** The recovery attestation: SHA-256 of the recovery public key sealed under a project key (plan Decision 30). */
+export declare const recoveryAttestationAad: (orgId: string, projectId: string, epoch: number) => string;
+/** AES-256-GCM with a key the caller holds (a workbook's K), a random IV every time. */
+export declare function sealWithKey(key: CryptoKey, data: Uint8Array, aad: string): Promise<SealedKey>;
+/** @internal sealWithKey with a fixed IV: pinned test vectors only (not in index.ts). */
+export declare function sealWithKeyWith(key: CryptoKey, data: Uint8Array, aad: string, _iv?: Uint8Array): Promise<SealedKey>;
+/** Throws if `sealed` isn't for this key and aad. */
+export declare function openWithKey(key: CryptoKey, sealed: SealedKey, aad: string): Promise<Uint8Array>;
+/** Data sealed under a password: PBKDF2-SHA256 (600k) → AES-256-GCM. */
+export interface PasswordSealed {
+    kdf: {
+        name: 'PBKDF2';
+        hash: 'SHA-256';
+        iterations: number;
+        salt: string;
+    };
+    iv: string;
+    ct: string;
+}
+export declare function sealWithPassword(password: string, data: Uint8Array, aad: string): Promise<PasswordSealed>;
+/** @internal sealWithPassword with a fixed salt / IV: pinned test vectors only (not in index.ts). */
+export declare function sealWithPasswordWith(password: string, data: Uint8Array, aad: string, _salt?: Uint8Array, _iv?: Uint8Array): Promise<PasswordSealed>;
+/** Throws on a wrong password (or another aad) and on a KDF this SDK doesn't write. */
+export declare function openWithPassword(password: string, sealed: PasswordSealed, aad: string): Promise<Uint8Array>;
+/** The recovery key's 32-byte scalar as a printable code: base32 (RFC 4648, no padding), groups of four. */
+export declare function recoveryCode(d: Uint8Array): string;
+/** The scalar back from a typed code (case, spaces and dashes ignored); null unless it's 32 bytes. */
+export declare function parseRecoveryCode(code: string): Uint8Array | null;
+/** A new organization recovery key: P-256 (ECDH, the device-wrap curve). The scalar `d` leaves only as the
+ *  password-protected file and the printed code; `publicKey` (base64 uncompressed point) goes to the server. */
+export declare function generateRecoveryKeyPair(): Promise<{
+    d: Uint8Array;
+    publicKey: string;
+}>;
+/** The recovery private key (non-extractable) from its scalar and the public key the server keeps. A wrong
+ *  scalar imports but opens nothing: unwrapping a recovery wrap is the check. */
+export declare function recoveryPrivateKey(d: Uint8Array, publicKey: string): Promise<CryptoKey>;

package/dist/types/lib/live/liveMathChannels.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Math channels on a live stream: evaluated into computed columns of the ring
+ * buffer, so every live reader (the multiband fast path, live over datasets,
+ * beacon, the legend's newest values) gets them exactly like a stream signal.
+ */
+import type { LiveBuffer } from './buffer';
+import type { MathChannel } from '../mathChannels/types';
+/** Evaluate `channels` over the buffered samples from absolute index `from` on. */
+export declare function computeLiveChannels(buf: LiveBuffer, channels: MathChannel[], from: number): void;
+/** Replace the buffer's math channels with `channels`, evaluated over everything buffered. */
+export declare function resetLiveChannels(buf: LiveBuffer, channels: MathChannel[]): void;

package/dist/types/lib/live/recorder.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Records every sample a live stream receives, independent of the live ring
+ * buffer (which keeps only the newest samples for the charts): a recording of
+ * any length is kept whole, columnar, and exported as CSV.
+ */
+import { type LiveColumnsBlock, type LiveMessage } from './buffer';
+export declare class LiveRecorder {
+    readonly startedAt: number;
+    private n;
+    private capacity;
+    private time;
+    private readonly cols;
+    private readonly order;
+    private readonly units;
+    private readonly timeColumn;
+    private readonly timeUnit;
+    constructor(timeColumn?: string, timeUnit?: string);
+    /** Samples recorded so far. */
+    get rows(): number;
+    add(msg: LiveMessage): void;
+    /** A block of samples by column (see LiveColumnsBlock). */
+    addColumns(block: LiveColumnsBlock): void;
+    private grow;
+    /**
+     * The recording as CSV parts (join them, or pass them to `new Blob(parts)`):
+     * a header row, a units row, then one row per sample. Missing values are empty.
+     */
+    toCsvParts(): string[];
+}
+/** A text cell (a channel name or unit: chosen by the sender). One starting with = + - @ tab or CR gets a leading '
+ *  so a spreadsheet reads it as text, not a formula (CSV injection); sample values are numbers and never come here. */
+export declare function csvCell(s: string): string;

package/dist/types/lib/live/stream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Viewer side of the Kymoscope live relay.
+ *
+ * Opens a WebSocket to `<relay.url>/v1/streams/<id>/watch`, carrying a bearer
+ * token in the subprotocol (`bearer.<token>`; browsers can't set headers on a
+ * WebSocket and a URL would leak into logs). The token comes from the host:
+ * the Kymoscope app passes the user's session JWT; an embedder passes a watch
+ * ticket minted by its backend. The relay only forwards the publisher's
+ * encrypted binary messages — it never sees plaintext.
+ */
+export declare const RELAY_SUBPROTOCOL = "kymoscope-live.v1";
+export type StreamStatus = 'subscribed' | 'closed' | 'error';
+/** Where the relay lives and how to authenticate to it (host-provided). */
+export interface LiveRelayConfig {
+    /** Relay base URL, e.g. `wss://live.example.com`. */
+    url: string;
+    /** Fresh credential for watching one stream; `null` = not available now (retried). */
+    getToken: (streamId: string) => Promise<string | null>;
+}
+/**
+ * `exp` (unix seconds) of a session JWT (`h.<payload>.s`) or a watch ticket
+ * (`wt.<payload>.s`) — both carry base64url JSON in the second segment.
+ * Unverified: only used to time the refresh. null if unreadable.
+ */
+export declare function tokenExp(token: string): number | null;
+export declare function watchUrl(relayUrl: string, streamId: string): string;
+/**
+ * Subscribe to a live stream. Returns an unsubscribe function. `onMessage`
+ * fires with each (encrypted) binary relay message. Re-connects with a fresh
+ * token after any unexpected close, so a transient drop never leaves the
+ * stream permanently silent.
+ */
+export declare function subscribeToStream(relay: LiveRelayConfig, streamId: string, onMessage: (data: ArrayBuffer) => void, onStatus?: (status: StreamStatus) => void): () => void;

package/dist/types/lib/live/timeBuckets.d.ts

@@ -0,0 +1,71 @@
+import type { MultiDecimationRow } from '../data/dataSource';
+import type { PointColumns } from '../data/pointColumns';
+/**
+ * Min/max buckets of several columns on an ascending time axis, kept in typed
+ * arrays (bucket ids ascending in rows [start, end)), plus the chart points they
+ * make, kept up to date as the buckets change. The live time-axis pull keeps one
+ * of these across frames: new samples merge into the last bucket or append,
+ * scrolled-out buckets drop off the front, and only the changed buckets' points
+ * are rewritten, so a pull costs what arrived since the last one, not the window
+ * (a few minutes of a 320 Hz stream rebuilt as row objects cost ~20 ms a pull).
+ * Missing values are NaN (a row's `null`).
+ */
+export declare class TimeBuckets {
+    readonly nc: number;
+    /** Bucket width (x of a bucket's points: its centre). */
+    readonly bucket: number;
+    b: Float64Array;
+    lo: Float64Array[];
+    hi: Float64Array[];
+    start: number;
+    end: number;
+    private rowP;
+    private px;
+    private pv;
+    private pStart;
+    private pEnd;
+    private mStart;
+    private mEnd;
+    /** Lowest row changed since the points were written (besides the oldest one). */
+    private dirty;
+    /** The oldest row, changed on its own (refolded after the ring dropped samples). */
+    private dirtyFront;
+    private invalid;
+    constructor(nc: number, bucket: number, cap?: number);
+    get count(): number;
+    /** First row (absolute index) whose bucket is ≥ `b`. */
+    lowerBound(b: number): number;
+    /** Re-lay the rows at `at` in arrays of `cap` (compacts or grows). */
+    private relocate;
+    private touch;
+    private clearRow;
+    /**
+     * The row of bucket `b`: an existing one, or a new one appended (b past the
+     * last bucket) or prepended (before the first, into the headroom).
+     */
+    row(b: number): number;
+    /** Drop the rows below bucket `b`. */
+    dropBelow(b: number): void;
+    /** Forget row `i`'s values (it is about to be refolded). */
+    reset(i: number): void;
+    /** Merge the samples [p, l) of `ycols` into row `i`. */
+    fold(i: number, ycols: Float64Array[], p: number, l: number): void;
+    /** Rows [i0, i1) as decimation rows (`{ b, pass, y{j}lo, y{j}hi }`), for row-based callers. */
+    toRows(i0: number, i1: number, template: MultiDecimationRow, lo: string[], hi: string[]): MultiDecimationRow[];
+    /** Points of row `i`: 2 (its mins, then its maxes) unless every column has min == max. */
+    private pointsOf;
+    private writeRow;
+    /** Room for `need` more points after pEnd (compacting or growing the point arrays). */
+    private reserve;
+    /** Write the points of rows [from, end), from pEnd on. */
+    private writeFrom;
+    /** Bring the points up to date with the rows. */
+    private sync;
+    /**
+     * Rows [i0, i1) as chart points, exactly what multiDecimatedToColumns makes of
+     * their rows: per bucket, at its centre, one point of mins and one of maxes —
+     * or a single point where every column has min == max. The arrays are views of
+     * this store's, valid until its next change.
+     */
+    toPoints(i0: number, i1: number, columns: string[]): PointColumns;
+}