@kymoscope/sdk 0.3.0 → 0.5.0

package/dist/types/lib/cycles/evaluator.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Cycle rules v2 (spec docs/superpowers/specs/2026-10-28-cycles-design.md, "Rules"): where a source is cut into cycles,
+ * and phases inside them. Boundaries and flags only; KPIs are the app's job. The collector runs the same semantics
+ * (packages/collector/src/kymoscope_collector/cycles.py), pinned by tests/vectors/cycle-rules-v2.json. Saved v1 rules
+ * (segment_definitions rule_v 1) keep running through ../segments/rules.ts RuleRunner.
+ *
+ * Semantics:
+ * - A start fires when its trigger becomes true (a condition rising, or an event: change, cross, reset, clock,
+ *   parent-start). With minHold_s, a condition start must stay true that long; the cycle starts when it first held.
+ * - An end fires while its trigger is true, from the sample after the start on. With ignoreDips_s, a condition end must
+ *   stay true that long; the cycle ends when it first held. `next-start`: each start closes the previous cycle.
+ * - A NaN value never changes a condition. A phase only sees samples inside its parent and closes with it (incomplete
+ *   unless its end names parent-end).
+ * - Limits never drop a cycle; a missed one adds a flag: late (expectedWithin_s from the parent's or its own start),
+ *   too-long (max_s), too-short (min_s).
+ */
+import { type CompareOp, type KpiSpec } from '../segments/rules';
+export type Condition = {
+    kind: 'compare';
+    channel: string;
+    op: CompareOp;
+    value: number;
+} | {
+    kind: 'change';
+    channel: string;
+} | {
+    kind: 'cross';
+    channel: string;
+    dir: 'rise' | 'fall';
+    value: number;
+} | {
+    kind: 'reset';
+    channel: string;
+} | {
+    kind: 'elapsed';
+    from: 'parent-start' | 'start';
+    op: '>=' | '<=';
+    seconds: number;
+} | {
+    kind: 'clock';
+    at: string[];
+    tz: string;
+};
+export type Trigger = {
+    kind: 'parent-start';
+} | {
+    kind: 'parent-end';
+} | {
+    kind: 'next-start';
+} | {
+    kind: 'manual';
+} | {
+    kind: 'all' | 'any';
+    of: Trigger[];
+} | Condition;
+export interface CycleLimits {
+    expectedWithin_s?: number;
+    from?: 'parent-start' | 'start';
+    min_s?: number;
+    max_s?: number;
+}
+export interface CycleRule {
+    start: Trigger;
+    end: Trigger;
+    minHold_s?: number;
+    ignoreDips_s?: number;
+    limits?: CycleLimits;
+}
+export type CycleFlag = 'late' | 'too-long' | 'too-short';
+export interface CycleInstance {
+    tstart: number;
+    tend: number | null;
+    flags: CycleFlag[];
+    incomplete?: true;
+}
+/** Every channel a rule reads. */
+export declare function cycleRuleChannels(r: CycleRule): string[];
+export declare class CycleRunner {
+    #private;
+    readonly rule: CycleRule;
+    constructor(rule: CycleRule);
+    /** A phase's parent opened: state starts over. Top-level rules never need it (the first sample is the start). */
+    parentStart(t: number): void;
+    /** The parent closed at t: an open phase closes with it. */
+    parentEnd(t: number, out: CycleInstance[]): void;
+    /** One sample, in time order; closed cycles are pushed to `out`. */
+    step(t: number, v: (channel: string) => number, out: CycleInstance[]): void;
+    /** The open cycle so far (flags up to the last sample), or null. */
+    open(): CycleInstance | null;
+}
+export interface RuleDef {
+    id: string;
+    rule: CycleRule;
+    parentId: string | null;
+}
+export interface CycleFound extends CycleInstance {
+    definitionId: string;
+    index: number;
+    parentIndex?: number;
+    /** Its definition's KPIs by column name ("TIC201 max"), when asked for (engine.datasets.findCycles). */
+    kpis?: Record<string, number | null>;
+}
+/**
+ * Definitions evaluated together, phases inside their parents. Indexes count per definition from 1 (a phase's within
+ * its parent). ponytail: a parent whose start waits for minHold_s opens after the fact, so its phases only see samples
+ * from the moment it was confirmed; buffer the held samples if a phase ever needs them.
+ */
+export declare class CycleSet {
+    #private;
+    constructor(defs: RuleDef[]);
+    /** Samples in time order; returns the cycles and phases they closed. `col(name)`: a channel's column aligned with
+     *  `t` (NaN where it has no value), or undefined. */
+    feed(t: ArrayLike<number>, col: (name: string) => ArrayLike<number> | undefined): CycleFound[];
+    /** The cycles and phases open now. */
+    open(): CycleFound[];
+}
+/** A saved rule: a cycle (parentId null) or a phase inside another definition. `kpis`: a column per KPI in the cycles
+ *  and phases tables (duration is always there). */
+export interface CycleDefinition extends RuleDef {
+    name: string;
+    kpis?: KpiSpec[];
+    /** The value beside each cycle (in a cut's list): a channel's statistic over the cycle; absent, its duration. */
+    show?: KpiSpec;
+}
+/** The definitions in `x` that are well formed (a workbook from anywhere: trust nothing); a phase whose parent is
+ *  missing is dropped too. */
+export declare function parseCycleDefinitions(x: unknown): CycleDefinition[];

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

@@ -19,6 +19,7 @@ export declare class ColumnarDataSource implements DataSource {
     /** {@link getSeriesMulti} without the Promise: decimating the columns is pure computation. */
     getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
     getColumnsSync(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     xBounds(column: string): Promise<{
         x0: number;
         x1: number;

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

@@ -61,6 +61,9 @@ export interface DataSource {
      * when there are more than `limit` of them or X isn't ascending.
      */
     getColumnsSync?(columns: string[], viewport: Viewport, limit: number): PointColumns | null;
+    /** The rows [offset, offset + limit) of `columns` in file order, as numbers (NaN for empty or text cells).
+     *  Unknown columns are left out. For whole-column passes (alert rules on loaded data); read in chunks. */
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     xBoundsSync?(column: string): {
         x0: number;
         x1: number;

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

@@ -33,6 +33,7 @@ export declare class DuckDbDataSource implements DataSource {
      * a narrow window are denser, so the same `maxRows` budget buys finer detail.
      */
     sampleRows(maxRows: number, range?: XRange): Promise<DatasetRow[]>;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     /** Full-range x bounds for a column, for an initial viewport. */
     xBounds(xKey: string): Promise<{
         x0: number;

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

@@ -0,0 +1,51 @@
+/**
+ * Historian ranges as a DataSource (plan P5): a list of pieces, each one block's times with Float32 values per channel
+ * (raw: lo and hi are the same arrays; a rollup: the bucket's min and max at its middle). The time column is
+ * `ElapsedTime` in Unix seconds, the same X as a collector's live stream. Decimation reads each piece on its own times,
+ * so tag groups never share a padded table. Everything is pure computation (sync), like the in-memory sources.
+ */
+import type { ColumnSchema, DataSource, DecimatedSeries, MultiSeriesResult, SeriesQuery, Viewport } from './dataSource';
+import type { DatasetRow } from '../parseDataset';
+import type { HistoryLevel } from '../historian/khd1';
+export interface HistoryPiece {
+    /** Unix seconds, ascending. */
+    t: Float64Array;
+    /** Per channel: the value (raw) or the bucket minimum (rollup). NaN: no value at that time. */
+    lo: Map<string, Float32Array>;
+    /** Per channel: the bucket maximum (rollup); the very same Map as `lo` for raw data. */
+    hi: Map<string, Float32Array>;
+    level: HistoryLevel;
+}
+/** First index with t[i] >= x, or with t[i] > x when `after`. */
+export declare function bound(t: Float64Array, x: number, after?: boolean): number;
+/** Rows [i, j) of a piece (views, nothing copied); null when empty. */
+export declare function slicePiece(p: HistoryPiece, i: number, j: number): HistoryPiece | null;
+/** The rows of `p` with t in [t0, t1]. */
+export declare const clipPiece: (p: HistoryPiece, t0: number, t1: number) => HistoryPiece | null;
+/** The overview outside [a, b] with the detail inside: the pan/zoom view (plan P6). */
+export declare function splicePieces(overview: HistoryPiece[], detail: HistoryPiece[], a: number, b: number): HistoryPiece[];
+export declare class HistoryDataSource implements DataSource {
+    #private;
+    readonly pieces: readonly HistoryPiece[];
+    constructor(pieces: HistoryPiece[], units?: Record<string, string>);
+    schemaSync(): ColumnSchema[];
+    getSchema(): Promise<ColumnSchema[]>;
+    /** Rows are the pieces' rows in time order (a rollup: its minimum); NaN where a piece lacks the channel. */
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
+    getSeriesMultiSync(columns: string[], viewport: Viewport, maxPoints: number): MultiSeriesResult;
+    getSeriesMulti(columns: string[], viewport: Viewport, maxPoints: number): Promise<MultiSeriesResult>;
+    getSeries(q: SeriesQuery): Promise<DecimatedSeries>;
+    xBoundsSync(column: string): {
+        x0: number;
+        x1: number;
+    };
+    xBounds(column: string): Promise<{
+        x0: number;
+        x1: number;
+    }>;
+    /** At most `maxRows` rows in time order for the row-based charts and math channels: one stride over all pieces' rows
+     *  end to end (pieces smaller than the stride may be skipped); a row holds its piece's channels only (a rollup: the
+     *  bucket minimum). ponytail: no cross-group alignment in the sample. */
+    sampleRowsSync(maxRows: number): DatasetRow[];
+    dispose(): Promise<void>;
+}

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

@@ -12,6 +12,7 @@ export declare class InMemoryDataSource implements DataSource {
     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;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     /** 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;

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

@@ -16,6 +16,8 @@ export declare class LiveDataSource implements DataSource {
      *  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;
+    /** The stream's column names now (the time column first). */
+    get columnNames(): string[];
     /** Changes whenever the buffered data does (see LiveBuffer.version). */
     version(): number;
     /**
@@ -24,6 +26,8 @@ export declare class LiveDataSource implements DataSource {
      * LiveBuffer.mirrorColumn). A new map per call: the columns as they are now.
      */
     columns(): ReadonlyMap<string, Float64Array>;
+    /** Whether `column` has had a finite value (a column the snapshot rows may thin out of view). */
+    hasValues(column: string): boolean;
     /** A fresh row snapshot of the newest samples (at most `maxRows`, evenly thinned). */
     snapshot(maxRows: number): Dataset;
     getSchema(): Promise<ColumnSchema[]>;
@@ -57,8 +61,22 @@ export declare class LiveDataSource implements DataSource {
     xAtTimeSync(column: string, t: number, hold?: boolean): 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). */
+    /** Newest received value of each column it has (finite values only): the newest sample's, else the column's
+     *  last known value (a channel that has no value at the newest time, or is quiet). */
     latestValuesSync(columns: string[]): Map<string, number>;
+    /**
+     * Y range of `column` for a scale: its samples in the ring and its last known value (a quiet channel has only
+     * that); a constant gets ±max(0.5, 5%) so it sits mid-band. Null when it has neither.
+     */
+    valueBoundsSync(column: string): {
+        min: number;
+        max: number;
+    } | null;
+    /** The newest finite value of `column` and its time, past the ring (see LiveBuffer.lastKnown). */
+    lastKnownSync(column: string): {
+        t: number;
+        v: number;
+    } | undefined;
     /** Follow cycles on `xKey` (beacon): see LiveBuffer.trackCycles. */
     trackCycles(xKey: string): void;
     /** X span of every sample seen on a tracked key, or null. */
@@ -73,5 +91,6 @@ export declare class LiveDataSource implements DataSource {
         x0: number;
         x1: number;
     }, maxPoints: number): PointColumns;
+    readColumns(columns: string[], offset: number, limit: number): Promise<Record<string, Float64Array>>;
     dispose(): Promise<void>;
 }

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

@@ -13,6 +13,8 @@ export interface PointColumns {
     /** 1 where an independent trace starts (never joined to the previous point). */
     readonly brk?: Uint8Array;
     readonly cols: ReadonlyMap<string, Float64Array>;
+    /** Held values (see heldColumns): a column's points always join, however far apart (no gap rule). */
+    readonly hold?: boolean;
 }
 /**
  * Columns known to hold no NaN (marked where they are made, which reads every
@@ -40,6 +42,15 @@ export declare function columnsToPoints(layers: PointColumns | PointColumns[]):
  * 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;
+/**
+ * A live stream's quiet channels, held: each column whose newest value (`last`: a sample or the sender's last known
+ * value) is older than the window end `x1`, as one flat segment of that value from max(`x0`, its time) to `end` (the
+ * stream's newest time on show). X ascending (the segments' starts, then one shared end); null when none is held.
+ */
+export declare function heldColumns(columns: string[], last: (column: string) => {
+    t: number;
+    v: number;
+} | undefined, x0: number, x1: number, end: number): PointColumns | null;
 /** 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). */

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 {};