@kymoscope/sdk 0.3.0 → 0.4.0

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

@@ -5,3 +5,8 @@ import * as duckdb from '@duckdb/duckdb-wasm';
 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>;
+/** The DuckDB of getDuckDb() with the Parquet extension loaded (the browser build doesn't include it). It is loaded
+ *  from this site (`/duckdb-ext/v<version>/wasm_eh/parquet.duckdb_extension.wasm`, DuckDB's own signed file copied
+ *  into public/), never from extensions.duckdb.org. A failed load is retried on the next call.
+ *  ponytail: same origin as the page; an SDK host that serves the app elsewhere copies that folder too. */
+export declare function getParquetDuckDb(): Promise<duckdb.AsyncDuckDB>;

package/dist/types/lib/historian/blockCache.d.ts

@@ -0,0 +1,32 @@
+/**
+ * History bytes cached in the origin-private file system (spec D2; plan P4): "<segmentId>/footer" and
+ * "<segmentId>/<block>". It keeps the bytes as stored (sealed): the device holds ciphertext only, and a segment id
+ * never changes content (a new version is a new segment), so nothing is invalidated. Past the budget (min(2 GiB,
+ * 20 % of the origin's quota)) the oldest-written files go, down to 90 %. Without OPFS (old browsers, some private
+ * windows) every call is a no-op. ponytail: eviction by write time (FIFO); track reads (LRU) if old ranges miss too often.
+ * ponytail: each tab keeps its own index and total, so several tabs writing at once can overshoot the budget until one
+ * of them rescans (next page load); share the index through a BroadcastChannel or a Web Lock if that ever matters.
+ */
+export interface BlockCache {
+    get(key: string): Promise<Uint8Array | null>;
+    put(key: string, bytes: Uint8Array): Promise<void>;
+}
+/** The part of FileSystemDirectoryHandle the cache uses (a fake in tests). */
+export interface CacheDir {
+    getFileHandle(name: string, o?: {
+        create?: boolean;
+    }): Promise<{
+        getFile(): Promise<File>;
+        createWritable(): Promise<{
+            write(b: BufferSource): Promise<void>;
+            close(): Promise<void>;
+            abort?(): Promise<void>;
+        }>;
+    }>;
+    removeEntry(name: string): Promise<void>;
+    entries(): AsyncIterable<[string, {
+        kind: string;
+        getFile?: () => Promise<File>;
+    }]>;
+}
+export declare function blockCache(root?: () => Promise<CacheDir | null>, budget?: () => Promise<number>): BlockCache;

package/dist/types/lib/historian/export.d.ts

@@ -0,0 +1,31 @@
+import type { ExportPart } from '../recordings/export';
+import { type HistoryPiece } from '../data/historyDataSource';
+import { type HistoryReadOptions, type HistorySegmentRef } from './reader';
+export type HistoryExportFormat = 'csv' | 'mf4' | 'parquet';
+/** ponytail: wide tables over unaligned tag groups grow as times x channels (float32 cells); Parquet (long) has no such limit. */
+export declare const MAX_WIDE_CELLS = 25000000;
+/** ponytail: the Parquet file is built in DuckDB-WASM's memory (~4 GB address space); stream row groups out if larger
+ *  exports are needed. */
+export declare const MAX_PARQUET_VALUES = 30000000;
+/** The shortest decimal that reads back as the same float32 (0.1, not 0.10000000149011612). */
+export declare function f32text(v: number): string;
+/** ISO 8601 UTC with microseconds. */
+export declare function isoMicros(t: number): string;
+/** One row per distinct time across `channels`, NaN where a channel has none. */
+export declare function wideDay(pieces: HistoryPiece[], channels: string[]): {
+    t: Float64Array;
+    cols: Float32Array[];
+};
+export declare function exportHistoryTo(o: Omit<HistoryReadOptions, 'level'>, format: HistoryExportFormat, write: (part: ExportPart) => void | Promise<void>, opts?: {
+    onProgress?: (fraction: number) => void;
+}): Promise<{
+    skippedDays: string[];
+    missingDays: string[];
+}>;
+/** Days of raw values into one Parquet file: appended to DuckDB `chunk` values at a time, at most `max` values. */
+export declare function parquetTo(raw: HistorySegmentRef[], day: (s: HistorySegmentRef) => Promise<{
+    pieces: HistoryPiece[];
+}>, channels: string[], write: (part: ExportPart) => void | Promise<void>, step: (i: number) => void, limits?: {
+    max: number;
+    chunk: number;
+}): Promise<void>;

package/dist/types/lib/historian/khd1.d.ts

@@ -0,0 +1,41 @@
+export declare const KHD1_TRAILER_BYTES = 9;
+export type HistoryKind = 'raw' | 'rollup';
+export type HistoryLevel = 0 | 60 | 3600;
+export interface KhdChannel {
+    n: string;
+    u: string;
+}
+export interface KhdBlock {
+    ch: number[];
+    t0: number;
+    t1: number;
+    off: number;
+    len: number;
+    rows: number;
+    values: number;
+}
+export interface KhdFooter {
+    format: 1;
+    stream: string;
+    day: string;
+    tz: string;
+    kind: HistoryKind;
+    level: HistoryLevel;
+    t0: number;
+    t1: number;
+    channels: KhdChannel[];
+    blocks: KhdBlock[];
+}
+/** Which file of a history: what the AAD of its blocks and footer binds. */
+export interface KhdFileId {
+    stream: string;
+    day: string;
+    kind: HistoryKind;
+    level: HistoryLevel;
+}
+export declare const blockAad: (f: KhdFileId, index: number | "footer") => string;
+/** The sealed footer's length, from bytes that end where the file ends (at least the 9-byte trailer). */
+export declare function footerLength(tail: Uint8Array): number;
+/** One sealed block (or the footer) opened; WebCrypto throws on a wrong key, file or index. */
+export declare function openSealed(key: CryptoKey, sealed: Uint8Array, f: KhdFileId, index: number | 'footer'): Promise<Uint8Array>;
+export declare function openFooter(key: CryptoKey, sealed: Uint8Array, f: KhdFileId): Promise<KhdFooter>;

package/dist/types/lib/historian/parquet.d.ts

@@ -0,0 +1,21 @@
+export interface RawBlock {
+    t: Float64Array;
+    cols: Float32Array[];
+}
+export interface RollupBlock {
+    t: Float64Array;
+    ch: Int32Array;
+    min: Float32Array;
+    max: Float32Array;
+}
+/** Loads DuckDB-WASM ahead of the first read (the History dialog calls it while the user picks). */
+/** Loads DuckDB and runs one tiny Parquet round trip, so the first real decode doesn't pay the first-query cost
+ *  (0.3-0.7 s measured, historian-notes/phase4.md). Call it while the user picks channels. */
+export declare function warmHistoryDecoder(): void;
+/** A raw block's times (Unix seconds) and the columns of `channels` (footer indexes; NaN = no value). */
+export declare function decodeRawBlock(bytes: Uint8Array, channels: number[]): Promise<RawBlock>;
+/** Rollup blocks' rows of their `channels`, one result per block, sorted by (ch, t): one query for the whole batch. */
+export declare function decodeRollupBlocks(blocks: Array<{
+    bytes: Uint8Array;
+    channels: number[];
+}>): Promise<RollupBlock[]>;

package/dist/types/lib/historian/reader.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Reading a time range of a history (spec D1; plan Formats "Reading a range"): one file per local day at the wanted
+ * level (else the nearest that day has), its footer (memo, cache, one suffix GET, or the whole file when small), then
+ * only the blocks that overlap the range and hold a wanted channel (neighbours in one GET), RANGE_PARALLEL requests at
+ * a time; opened with the history key and decoded into pieces. Days need no joining: each block carries its own times.
+ */
+import { type HistoryPiece } from '../data/historyDataSource';
+import { type HistoryKind, type HistoryLevel, type KhdFooter } from './khd1';
+import type { BlockCache } from './blockCache';
+/** One verified file of a history (the latest version of its day, kind and level). */
+export interface HistorySegmentRef {
+    id: string;
+    day: string;
+    kind: HistoryKind;
+    level: HistoryLevel;
+    bytes: number;
+    keyId: string;
+}
+export interface HistoryReadOptions {
+    historyStreamId: string;
+    /** Segments of the days in range (any levels; the latest version of each). */
+    segments: HistorySegmentRef[];
+    t0: number;
+    t1: number;
+    channels: string[];
+    level: HistoryLevel;
+    key: (keyId: string) => Promise<CryptoKey>;
+    /** Bytes [start, end) of a segment's file. */
+    fetchRange: (segmentId: string, start: number, end: number, signal?: AbortSignal) => Promise<Uint8Array>;
+    cache?: BlockCache;
+    /** Opened footers by segment id, kept by the caller between reads of one history. */
+    footers?: Map<string, KhdFooter>;
+    signal?: AbortSignal;
+    /** The segments of the same days listed again. A read that fails (a 404 or 403, or no URL for a segment) asks for
+     *  it once: a newer version may have replaced a segment meanwhile (today's summaries every 15 min, a late-data
+     *  rebuild), and the older one is deleted. When the listing picks other files the read runs again on them; when it
+     *  picks the same, the error stands. */
+    relist?: () => Promise<HistorySegmentRef[]>;
+    /** false: blocks are read from `cache` but not added to it (an export would push out what charts reuse). Default true. */
+    cacheWrite?: boolean;
+    /** 'gap': a segment whose `fetchRange` throws an error with `code: 'missing'` (its file is gone from storage) is read
+     *  as no data for its day, listed in `missingDays`, and the rest of the range is read. Default 'error': the read fails. */
+    onMissing?: 'error' | 'gap';
+}
+export interface HistoryRange {
+    pieces: HistoryPiece[];
+    units: Record<string, string>;
+    /** The level each day was read at (a day without the wanted level falls back). */
+    levels: Record<string, HistoryLevel>;
+    /** Days whose file is missing from storage (onMissing 'gap'): read as no data. */
+    missingDays: string[];
+}
+export declare const RANGE_PARALLEL = 16;
+export declare const HISTORY_PIXELS = 2000;
+/** The coarsest level giving at least half a bucket per pixel over `spanS` (plan P2). */
+export declare function chooseLevel(spanS: number, pixels?: number): HistoryLevel;
+/** One file per day, in day order: the wanted level, else the nearest the day has (raw expired, today, a failed upload). */
+export declare function pickSegments(segments: HistorySegmentRef[], level: HistoryLevel): HistorySegmentRef[];
+/** f over items, n at a time; results in order. */
+export declare function pool<T, R>(items: T[], n: number, f: (x: T) => Promise<R>): Promise<R[]>;
+/** Byte ranges covering `blocks`: neighbours closer than 64 KiB join, up to 8 MiB per range. */
+export declare function coalesce(blocks: Array<{
+    off: number;
+    len: number;
+}>): Array<{
+    start: number;
+    end: number;
+}>;
+type Reader = Pick<HistoryReadOptions, 'historyStreamId' | 'key' | 'fetchRange' | 'cache' | 'footers' | 'signal'>;
+/** A segment's opened footer: the memo, else the cache, else the file (whole when ≤ 512 KiB, kept in `whole`). */
+export declare function readFooter(o: Reader, s: HistorySegmentRef, whole?: Map<string, Uint8Array<ArrayBufferLike>>): Promise<KhdFooter>;
+export declare function readHistoryRange(o: HistoryReadOptions): Promise<HistoryRange>;
+export {};

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

@@ -18,6 +18,22 @@ export interface BlockSchema {
 export declare function decodeBlockSchema(p: Uint8Array): BlockSchema;
 /** KIND_BLOCK_SCHEMA plaintext with a given id (tests and local publishers; senders use the CRC-32 of the table). */
 export declare function encodeBlockSchema(id: number, channels: BlockChannel[]): Uint8Array;
+/** One channel of a KIND_LAST_VALUES: its last finite value and that value's time (stream seconds). */
+export interface LastValue {
+    name: string;
+    unit: string;
+    t: number;
+    v: number;
+}
+/**
+ * The channels with a value of a decrypted KIND_LAST_VALUES plaintext (u8 version 1, u8 flags, u16 reserved,
+ * u32 schema id, u32 count, count f64 times then count f64 values, NaN time = none yet; little-endian), named by
+ * the schema it refers to; null until that schema has arrived. Throws RangeError if malformed.
+ * Normative format: docs/superpowers/specs/2026-10-26-last-values.md; pinned by tests/vectors/last-values-v1.json.
+ */
+export declare function decodeLastValues(p: Uint8Array, schemas: ReadonlyMap<number, BlockSchema>): LastValue[] | null;
+/** KIND_LAST_VALUES plaintext of `t` / `v` in `schema`'s channel order, NaN for none (tests and local publishers). */
+export declare function encodeLastValues(schema: BlockSchema, t: ArrayLike<number>, v: ArrayLike<number>): Uint8Array;
 /** A decrypted KIND_BLOCK plaintext's rows; null until its schema has arrived. Throws RangeError if malformed. */
 export declare function decodeBlock(p: Uint8Array, schemas: ReadonlyMap<number, BlockSchema>): Promise<{
     block: LiveColumnsBlock;

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

@@ -79,6 +79,10 @@ export declare class LiveBuffer {
     private readonly mirrors;
     /** The last decimation of a window in the history (its samples don't change while it stays put). */
     private historyDec;
+    /** The buckets of the row snapshot (see toDataset), kept across calls like timeDec. */
+    private snapDec;
+    /** Each column's newest finite value and its time, kept past the ring (see lastKnown). */
+    private latest;
     /**
      * `capacity`: samples kept (the oldest are dropped past it). Memory grows with
      * the samples actually received; `maxBytes` caps it — once the columns would
@@ -273,4 +277,34 @@ export declare class LiveBuffer {
      * keeps a sample selected until it ages out of the buffer.
      */
     toDataset(maxRows?: number): Dataset;
+    /**
+     * At most ~`maxRows` rows of the ring (time ascending): per bucket of time, at its centre (the oldest and
+     * newest buckets at the oldest and newest sample's time), a row of each column's min and, where any differs,
+     * one of its max. The buckets are kept across calls and fold only the samples pushed since (see timeBuckets),
+     * on the absolute grid floor(t / bucket), so a snapshot refreshed while the ring rolls doesn't re-quantise.
+     * Null when every sample has the same time.
+     */
+    private snapshotRows;
+    /** Min/max of `name`'s samples in the ring, or null when it has none (columnBounds reads that as 0..0). */
+    valueBounds(name: string): {
+        x0: number;
+        x1: number;
+    } | null;
+    /** Whether `name` has had a finite value (a sample or a last known value) since the stream started (or was
+     *  cleared), in the ring or not. */
+    hasValues(name: string): boolean;
+    /** How many columns have had a finite value (moves when one gets its first). */
+    get valuedCount(): number;
+    /** The newest finite value of `name` and its time (a sample, or a last known value when newer), past the ring. */
+    lastKnown(name: string): {
+        t: number;
+        v: number;
+    } | undefined;
+    /**
+     * A channel's last value as the sender knows it (KIND_LAST_VALUES): not a sample (the ring, decimation, cycles
+     * and readers of samples never see it), only the value a quiet channel holds. Creates the column (no samples)
+     * so the channel is listed; a newer sample always wins.
+     */
+    setLastKnown(name: string, unit: string, t: number, v: number): void;
+    private noteValue;
 }

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

@@ -0,0 +1,70 @@
+import type { LivePublisher } from './publisher';
+export interface CameraPreset {
+    width: number;
+    height: number;
+    fps: number;
+    kbps: number;
+}
+export declare const CAMERA_PRESETS: Record<'720p30' | '1080p30', CameraPreset>;
+/** The low layer's default: what small panels and camera walls draw. */
+export declare const LOW_PRESET: CameraPreset;
+export interface CameraLayerStats {
+    fps: number;
+    kbps: number;
+    viewers: number;
+    encoding: boolean;
+}
+/** `error`: the encoder's failure message (encoding has stopped), for the page to show; null while healthy.
+ *  `low`: the low layer's, null without one (or when this browser can't encode it). */
+export interface CameraStats extends CameraLayerStats {
+    dropped: number;
+    queue: number;
+    error: string | null;
+    low: CameraLayerStats | null;
+}
+export interface CameraSenderDeps {
+    VideoEncoder?: typeof VideoEncoder;
+    /** ms epoch */
+    now?: () => number;
+    /** The frame source (test seam); defaults to MediaStreamTrackProcessor or a hidden <video>. */
+    frames?: (track: MediaStreamTrack) => AsyncIterable<VideoFrame>;
+    /** The low layer's downscale (test seam); defaults to drawing onto an OffscreenCanvas. The caller closes the result. */
+    scale?: (frame: VideoFrame, width: number, height: number) => VideoFrame;
+}
+type Publisher = Pick<LivePublisher, 'send' | 'viewers' | 'onViewers' | 'limits'>;
+export declare class CameraSender {
+    private readonly high;
+    private readonly lowOpt;
+    private low;
+    /** When the low layer last took a frame (ms, `now`), for its frame rate. */
+    private lowAt;
+    private readonly keyframeMs;
+    private readonly Encoder;
+    private readonly now;
+    private readonly frames;
+    private readonly scale;
+    private stopped;
+    private readonly statsFns;
+    private lastStats;
+    constructor(publisher: Publisher, opts: {
+        preset: CameraPreset;
+        keyframeS?: number;
+        low?: {
+            publisher: Publisher;
+            preset?: CameraPreset;
+        };
+    }, deps?: CameraSenderDeps);
+    /** Encode frames from `track` (a getUserMedia video track). Resolves once the encoder is configured;
+     *  frames then flow until stop(). Throws KymoscopeError('camera_codec_unsupported'). A low layer this
+     *  browser can't encode is left out (stats().low null); the camera still runs. */
+    start(track: MediaStreamTrack): Promise<void>;
+    private loop;
+    private onFrame;
+    stats(): CameraStats;
+    /** At most about once a second, while frames flow. */
+    onStats(fn: (s: CameraStats) => void): () => void;
+    private emitStats;
+    /** Stop encoding. The publishers and the track belong to the caller and keep running. */
+    stop(): void;
+}
+export {};

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

@@ -0,0 +1,20 @@
+/**
+ * Data-stream time → wall time (Unix seconds), for syncing a camera with a data stream.
+ * Senders that stamp samples with Unix seconds (t > 1e9) need no map: "exact". Others
+ * get an estimate: the minimum over a sliding window of (arrival − last sample time of
+ * the message), i.e. the clock offset plus the smallest network delay seen: "approx".
+ */
+export type ClockQuality = 'exact' | 'approx' | 'none';
+export declare class ClockMap {
+    private samples;
+    private exact;
+    private windowS;
+    constructor(windowS?: number);
+    /** A data message arrived at wall time `arrival` (s) whose last sample has stream time `t`. */
+    observe(t: number, arrival: number): void;
+    quality(): ClockQuality;
+    /** Stream time → wall seconds; `offsetMs` is the user's manual correction. */
+    toWall(t: number, offsetMs?: number): number | null;
+    /** Wall seconds → stream time (to draw the "frame shown" marker on a chart). */
+    toStream(wall: number, offsetMs?: number): number | null;
+}

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

@@ -117,6 +117,13 @@ 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;
+/** A collector's day-history key sealed under the project key (resource_keys 'history_key'). Python twin:
+ *  kymoscope.crypto.history_key_aad. */
+export declare const historyKeyAad: (keyId: string, projectId: string, epoch: number) => string;
+/** A project's config key (alert rules) sealed under the project key: resource_keys 'project_config', id = the project. */
+export declare const projectConfigKeyAad: (projectId: string, epoch: number) => string;
+/** An alert rule's kyr/1 body sealed under its project's config key: bound to the rule, its version and project. */
+export declare const alertRuleAad: (ruleId: string, version: number, projectId: string) => 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;

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

@@ -0,0 +1,163 @@
+/**
+ * A browser sender of Live Streams: the TypeScript port of the Python sender's protocol
+ * (packages/python/src/kymoscope/stream.py LiveStream + _RelayTransport, client.py). Generic over the
+ * message kind: the caller hands plaintext to send(kind, plaintext) and the publisher seals and publishes it.
+ *
+ * stream-token (`x-api-key`: the key's auth part) gives a `pt.` token; register and every heartbeat
+ * (stream-publisher) give the `pp.` ticket the relay's publish socket takes. A password stream's key
+ * derives from the API key's secret part, which never leaves this side, and goes to the owner's browsers
+ * sealed to each (device wraps). A key of an end-to-end encrypted project makes this sender a device of
+ * the project: nothing is published until a member's browser approves it, then a random stream key goes
+ * up sealed under the project key and messages carry the key id (epoch & 0xff).
+ *
+ * Persisted key material stays as non-extractable CryptoKeys: an e2ee stream key is kept with its
+ * project wrap ({iv, ct}, not secret), which a restart within the epoch uploads again instead of
+ * re-sealing raw bytes it no longer has.
+ */
+import { type SealedKey } from './crypto';
+/** What a sender keeps across restarts (per API key). Device and stream keys only count for `apiKeyId`. */
+export interface PublisherState {
+    apiKeyId: string | null;
+    streamId: string;
+    salt: string;
+    /** An e2ee project's sender device (non-extractable private key). */
+    device: {
+        privateKey: CryptoKey;
+        publicKey: string;
+    } | null;
+    /** An e2ee stream key, reused only within its epoch, with its project wrap. */
+    streamKey: {
+        epoch: number;
+        key: CryptoKey;
+        sealed: SealedKey;
+    } | null;
+}
+export interface PublisherDeps {
+    fetch: typeof fetch;
+    WebSocket: typeof WebSocket;
+    /** ms epoch */
+    now: () => number;
+    store: {
+        load(): Promise<PublisherState | null>;
+        save(s: PublisherState): Promise<void>;
+    };
+}
+export interface PublisherOptions {
+    supabaseUrl: string;
+    apiKey: string;
+    name: string;
+    kind: 'data' | 'camera';
+    /** Where the stream goes is the API key's: a project's key publishes into that project, a personal key a personal stream. */
+    visibility?: 'private' | 'public';
+    /** The caller's own data stream a camera belongs to (required for kind 'camera'); its placement comes from it. */
+    parentStreamId?: string;
+    /** A camera's low layer (360p, for small panels and camera walls): `layer: 'low'` with `lowOf`, its high camera's
+     *  stream id (same parent). Both or neither. */
+    layer?: 'low';
+    lowOf?: string;
+}
+export type PublisherStatus = {
+    phase: 'registering';
+} | {
+    phase: 'waiting_approval';
+} | {
+    phase: 'live';
+    viewers: number;
+} | {
+    phase: 'reconnecting';
+} | {
+    phase: 'refused';
+    code: string;
+    message: string;
+};
+export declare class LivePublisher {
+    private readonly opts;
+    private readonly deps;
+    private readonly auth;
+    private readonly secret;
+    private token;
+    private ticket;
+    /** The current ticket says rec (the reply's `recording`); `authRec`: the one the open socket authenticated with. */
+    private ticketRec;
+    private authRec;
+    private relayUrl;
+    private apiKeyId;
+    private projectId;
+    private e2ee;
+    private sid;
+    private salt;
+    private key;
+    /** A password stream's raw key, for device wraps (derivable from the secret anyway). */
+    private raw;
+    private epoch;
+    private haveKey;
+    private sealed;
+    private device;
+    private senderDeviceId;
+    private deviceRetried;
+    private maxBytesPerSec;
+    private maxMessageBytes;
+    private ws;
+    private open;
+    private everOpen;
+    private connectedAt;
+    private authAt;
+    private delay;
+    private lastToken;
+    private viewerCount;
+    private busy;
+    private stopped;
+    private refusal;
+    private heartbeatTimer;
+    private pingTimer;
+    private retryTimer;
+    private readonly statusFns;
+    private readonly viewerFns;
+    private lastStatus;
+    constructor(opts: PublisherOptions, deps: PublisherDeps);
+    /** The registered stream id (null until start() registers). */
+    get streamId(): string | null;
+    /** The relay's viewer count (0 while disconnected). */
+    get viewers(): number;
+    /** Bytes/second the account negotiated (0: not limited) and the relay's message size limit. */
+    get limits(): {
+        maxBytesPerSec: number;
+        maxMessageBytes: number;
+    };
+    onStatus(fn: (s: PublisherStatus) => void): () => void;
+    onViewers(fn: (n: number) => void): () => void;
+    /** Mint, register (reusing a persisted stream id and salt), open the socket, heartbeat. Rejects when
+     *  registration fails; a 4xx (a refusal) also sets status `refused`. */
+    start(): Promise<void>;
+    /** Seal with the current stream key (the key id of its epoch when e2ee) and send; false if not sent
+     *  (no key yet, socket down, stopped). */
+    send(kind: number, plaintext: Uint8Array): Promise<boolean>;
+    /** Close the socket and stop the timers. The stream stays registered (never deleted here). */
+    stop(): void;
+    private post;
+    private mint;
+    private call;
+    private register;
+    private senderDevice;
+    /** Token refresh, then the heartbeat (each new ticket also refreshes the socket). 401/403 stop the
+     *  publisher (revoked key, plan, stale_epoch); anything else is retried on the next interval. */
+    private housekeeping;
+    /** Seal the stream key to the owner's browsers that lack it (password streams), at most 50 per call. */
+    private wrapFor;
+    /** The project key arrived: seal the stream key under it; a new epoch (rotation) gets a new stream key.
+     *  A key this device can't open re-registers once with a new device key. */
+    private applyProject;
+    private reregister;
+    private save;
+    private connect;
+    private disconnect;
+    /** Reconnect: at once after a stable connection, else after the backoff (1 s doubling to 10 s). */
+    private dropped;
+    /** Use `ticket` from now on; re-authenticate the open socket in-band when due, or at once when it
+     *  says rec and the socket's ticket didn't. */
+    private setTicket;
+    private setViewers;
+    private refuse;
+    private status;
+    private emit;
+}

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

@@ -3,6 +3,8 @@ import type { EncryptedEnvelope } from './crypto';
 import type { LiveColumnsBlock, LiveMessage } from './buffer';
 import type { LiveDataSource } from '../data/liveDataSource';
 import type { Dataset } from '../parseDataset';
+import type { VideoTrack } from './videoTrack';
+import type { ClockMap } from './clockMap';
 /** What a viewer needs to join an encrypted relay stream (from the stream registry). */
 export interface LiveStreamDescriptor {
     id: string;
@@ -21,6 +23,12 @@ export interface LiveStreamDescriptor {
      * owner hosts). The engine's `getToken` is still asked for the credential.
      */
     relay_url?: string | null;
+    /** A camera stream carries encoded video (KIND_VIDEO), not samples. Default 'data'. */
+    kind?: 'data' | 'camera';
+    /** A camera's data stream (a camera is a channel of it); null/absent for data streams. */
+    parent_stream_id?: string | null;
+    /** A camera's low layer (360p, for small panels and walls): its high camera's id; null/absent otherwise. */
+    low_of_stream_id?: string | null;
 }
 /**
  * The keys of a stream in an end-to-end encrypted project: frames name their key id
@@ -60,12 +68,22 @@ export interface LiveConnection {
     visibility: 'private' | 'public' | 'org' | 'project';
     orgName: string | null;
     projectName?: string | null;
+    kind: 'data' | 'camera';
+    /** A camera's data stream (LiveStreamDescriptor.parent_stream_id); null for data streams. */
+    parentId: string | null;
+    /** A camera's low layer: its high camera's id (LiveStreamDescriptor.low_of_stream_id); null otherwise. */
+    lowOf: string | null;
+    /** A camera's encoded video (the same instance for the connection's life); null for data. */
+    video: VideoTrack | null;
+    /** A data stream's time → wall time map (to sync cameras with it); null for cameras. */
+    clock: ClockMap | null;
     /** Slow (~1 Hz) snapshot for column discovery / count / non-multiband charts. */
     dataset: Dataset;
     /** Live decimation source read by the multiband chart every frame (no React). */
     source: LiveDataSource;
     rowCount: number;
-    status: 'connecting' | 'live' | 'stale' | 'error';
+    /** 'idle': a camera no panel shows (connected, not downloading). */
+    status: 'idle' | 'connecting' | 'live' | 'stale' | 'error';
     error: string | null;
     /** When a recording is running: its start time (ms since epoch). */
     recordingSince: number | null;