supervision 0.1.7 → 0.2.0-next.1

package/dist/web-video-engine/scrub-cursor.d.ts

@@ -0,0 +1,347 @@
+import type { CreateScrubCursorOptions } from "./create-scrub-cursor";
+import type { FrameCacheStats } from "./frame-cache";
+import type { FrameId, FrameTimeline } from "./frame-timeline";
+import type { GopStats } from "./keyframe-index";
+import type { Rotation } from "./rotation";
+import type { DecodePath, Sec } from "./types";
+/**
+ * How good a painted frame is. "exact" is a full decode-resolution frame;
+ * "preview" is the coarse downscaled stand-in the cache serves at once while a
+ * crisp one decodes. The two look materially different on screen, so anything
+ * reporting what was painted has to say which it was.
+ */
+export type FrameQuality = "exact" | "preview";
+export declare enum ScrubCursorState {
+    Idle = "idle",
+    Seeking = "seeking",
+    Closed = "closed"
+}
+/** Fields every paint-ready frame carries, independent of how its pixels reach
+ *  the renderer. */
+export interface ScrubFrameBase {
+    readonly timestampS: Sec;
+    readonly width: number;
+    readonly height: number;
+    readonly isKeyFrame: boolean;
+    readonly quality: FrameQuality;
+}
+/**
+ * The structural slice of mediabunny's VideoSample the runtime touches: enough
+ * to draw it into a 2D canvas, hand its pixels to WebGPU without an intermediate
+ * transfer copy where the selected path supports that, and release it. Kept as
+ * a slice rather than the concrete class so the runtime never
+ * imports mediabunny and stays fake-injectable under test.
+ *
+ * close() is the caller's obligation and is made idempotent at the cursor
+ * boundary, so a sample drawn into the cache, painted, and then closed on
+ * teardown is closed at most once for real.
+ */
+export interface VideoSampleLike {
+    /**
+     * A fresh VideoFrame per call; the caller closes the returned frame.
+     *
+     * The frame carries the stored pixels and NOT the track's rotation, on this
+     * and on mediabunny's own implementation, which drops it deliberately. So
+     * whoever takes one owes it the turn named by `rotation` below.
+     */
+    toVideoFrame(): VideoFrame;
+    /** The sample owns storage independent of a decoder output pool, so a host
+     * transfer may rewrap it without copying its pixels again. */
+    readonly independentPixels?: true;
+    /** The turn the pixels still need, already applied by draw() and dropped by
+     *  toVideoFrame(). */
+    readonly rotation: Rotation;
+    draw(context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, dx: number, dy: number, dWidth?: number, dHeight?: number): void;
+    close(): void;
+    readonly timestamp: number;
+    readonly duration: number;
+}
+/**
+ * A paint-ready frame yielded by the cursor, tagged by how its pixels reach the
+ * renderer.
+ *
+ * A canvas frame carries a canvas and no close obligation: it is a cache blit
+ * or a CanvasSink decode. WebGPU uploads it with copyExternalImageToTexture,
+ * which accepts neither an SVG image nor a video element. A sample frame carries
+ * a live VideoSample that an eligible VideoSampleSink route can import directly
+ * into WebGPU. A DecodeSession route may first materialize independently owned
+ * pixels. Whoever stashes the sample owns its close, so only fresh decodes on
+ * the sample source produce one.
+ */
+export interface CanvasScrubFrame extends ScrubFrameBase {
+    readonly kind: "canvas";
+    readonly source: OffscreenCanvas | HTMLCanvasElement;
+}
+export interface SampleScrubFrame extends ScrubFrameBase {
+    readonly kind: "sample";
+    readonly sample: VideoSampleLike;
+}
+export type ScrubFrame = CanvasScrubFrame | SampleScrubFrame;
+/**
+ * The turn a frame's raw pixels still need. A canvas frame has none left: a
+ * CanvasSink decode arrives upright, and a cache blit was drawn through a
+ * sample's own draw, which applies it. Only a live sample still owes one.
+ */
+export declare function frameRotation(frame: ScrubFrame): Rotation;
+/**
+ * Wraps a raw sample so its close() runs at most once, then no-ops. The
+ * lifetime is hard to keep linear: a sample is drawn into the cache, stashed for
+ * paint, then closed after paint, and may be closed again on teardown if a
+ * gesture left it unpainted. An idempotent close lets every path call it
+ * defensively without double-free.
+ */
+export declare function idempotentSample(sample: VideoSampleLike): VideoSampleLike;
+export type ScrubFrameListener = (frame: ScrubFrame) => void;
+/** A frame considered for the screen, and what is already on it. */
+export interface ScreenCandidate {
+    readonly timestampMs: number;
+    readonly quality: FrameQuality;
+}
+/**
+ * Whether a frame earns the screen over what is already showing, judged from
+ * where the user is pointing rather than from what happens to be up. Closer
+ * wins; equally close wins only by being sharper, since repainting the same
+ * ground with the same or worse pixels is a visible change for no information.
+ *
+ * Both painters share this. They used to disagree: one applied it to coarse
+ * frames only and the other to everything, so which rule you got depended on
+ * which path served the frame.
+ */
+export declare function earnsScreen(candidate: ScreenCandidate, showing: ScreenCandidate | null, targetMs: number): boolean;
+/** Rolling scrub-decode latency, in milliseconds, since the cursor opened.
+ *  p50Ms/p95Ms are percentiles over a bounded recent-sample ring, so a single
+ *  slow region shows up in p95 without dragging the all-time avg. targetVsLandedMs
+ *  is how far the last exact seek landed from where it aimed (long-GOP forces a
+ *  distant anchor); timeToCrispMs is the gap between a preview paint and the crisp
+ *  decode that replaced it on the same seek. */
+export interface ScrubLatencyStats {
+    readonly samples: number;
+    readonly lastMs: number;
+    readonly avgMs: number;
+    readonly maxMs: number;
+    readonly p50Ms: number;
+    readonly p95Ms: number;
+    readonly targetVsLandedMs: number;
+    readonly timeToCrispMs: number;
+}
+/** Decodes the scheduler has run, split by why. foreground is a gesture-driven
+ *  seek/step/play pull; the prefetch counts are background sweep fills per tier;
+ *  keyframeAnchored is a key-only seek landing on its anchor. Counters only, never
+ *  reset, so ratios over a session describe where decode bandwidth went. */
+export interface DecodeCounters {
+    readonly foreground: number;
+    readonly prefetchExact: number;
+    readonly prefetchPreview: number;
+    readonly keyframeAnchored: number;
+    /** Frames the decode machinery has produced since open, all paths, walk
+     *  pre-roll included where the path can see it. The pipeline ledger's
+     *  decoded column. */
+    readonly framesOut: number;
+    /** Forward-playback pulls in flight (0 or 1); a free read of the drain latch. */
+    readonly nextPending: number;
+}
+/** Seeks the scheduler has serviced. exact is a full-resolution scrub; key is a
+ *  key-only navigation seek; coalesceDepth counts how often a pending target was
+ *  overwritten before it drained (the decoder falling behind a fast drag). */
+export interface SeekCounters {
+    readonly exact: number;
+    readonly key: number;
+    readonly coalesceDepth: number;
+}
+/** Background prefetch sweep liveness: whether a sweep is decoding right now and
+ *  the generation token (bumped by every foreground gesture, so a jumping value
+ *  is a churning sweep that never warms the cache). */
+export interface PrefetchState {
+    readonly inFlight: boolean;
+    readonly generation: number;
+}
+/**
+ * Observability snapshot a caching cursor can report: how often the cache
+ * answered a scrub, and how long the misses took to decode. Cache hit-rate and
+ * decode latency together describe perceived scrub responsiveness.
+ */
+/**
+ * Why the playhead is moving. A hand on a timeline keeps feeding positions, so
+ * the runtime reads their direction and speed to decide what to prepare next.
+ * A jump produces one position and no motion to read, so prediction from the
+ * positions around it would be prediction from a gesture nobody is making.
+ */
+export type SeekIntent = "gesture" | "jump";
+/** The decode window the scheduler is filling around the playhead, in ms. */
+/** The decode targets the next background sweep would aim at, given what the
+ *  runtime currently knows. A bounds pair cannot represent a hole, and holes
+ *  are what a coverage instrument exists to show. */
+export interface PrefetchPlan {
+    readonly targetsMs: number[];
+}
+export interface SchedulerStats {
+    /** The runtime's live read of how the consumer is moving (idle/scrubbing/
+     *  stepping/playing). The single highest-signal field for a human watching
+     *  the engine interpret their gesture. */
+    readonly mode: string;
+    /** Which decode machinery this source was opened through. Resolved once at
+     *  open from the track and the realm; a hang-recovery rebuild re-resolves
+     *  it, so a path change here means the source was re-opened. */
+    readonly decodePath: DecodePath;
+    readonly cache: FrameCacheStats;
+    readonly scrub: ScrubLatencyStats;
+    readonly decode: DecodeCounters;
+    readonly seek: SeekCounters;
+    /** GOP-gap distribution over the keyframes discovered so far. A long maxGopS
+     *  is the badly-encoded-source tell every off-anchor scrub pays for. */
+    readonly gop: GopStats;
+    /** Container round-trips the keyframe index has made resolving anchors; the
+     *  rest resolve from memory. */
+    readonly probeRoundTrips: number;
+    /** Discovered keyframe timestamps (ms), ascending. Lazy: grows as the source
+     *  is scrubbed/swept, so it shows what the runtime actually knows. */
+    readonly keyframesMs: number[];
+    /** The targets the scheduler would prefetch around the playhead, or null
+     *  while playing (the forward stream iterator covers ahead). */
+    readonly prefetch: PrefetchPlan | null;
+    /** Background sweep liveness (in-flight + generation token). */
+    readonly prefetchState: PrefetchState;
+    /** Cache lookup tolerances, so a timeline can draw the "served" bands. */
+    readonly exactToleranceMs: number;
+    readonly previewToleranceMs: number;
+    /** True after a decode hung on a non-re-openable source: the decoder could
+     *  not be rebuilt, so the runtime is degraded (decodes no-op) but not frozen.
+     *  Lets a consumer surface the state rather than show a silent freeze. */
+    readonly decoderDead: boolean;
+    /** True once the decoder is judged unable to decode this source at all: it
+     *  refused to configure, it errored, or it acknowledged decode requests and
+     *  produced nothing. Distinct from decoderDead, which is a rebuild the
+     *  source made impossible; this one survives every rebuild, so the runtime
+     *  stops rebuilding. The transport reads Errored at the same moment. */
+    readonly decoderStalled: boolean;
+    /** State of the seek drain. Every play pull is refused while a seek drains,
+     *  so a drain that never finishes shows on screen as playback dying with no
+     *  other symptom: without this the panel can say the pump is dead but not
+     *  that a seek is the reason. */
+    readonly drain: DrainState;
+}
+export interface DrainState {
+    /** A seek is being serviced right now, which refuses every play pull. */
+    readonly draining: boolean;
+    /** Target waiting behind the one being serviced, in ms, or null. */
+    readonly pendingTargetMs: number | null;
+    /** A hung-decode rebuild is in progress. */
+    readonly recovering: boolean;
+}
+/**
+ * Resolved track facts the engine reads after open(). width/height are the
+ * source's native resolution (used for aspect, metadata, cache sizing).
+ * decodeWidth/decodeHeight are the resolution frames are actually decoded to
+ * after the decode-resolution strategy runs, and size the visible canvas
+ * backing store. They equal native unless a downscaling strategy is in play.
+ */
+export interface ScrubTrackInfo {
+    readonly width: number;
+    readonly height: number;
+    readonly decodeWidth: number;
+    readonly decodeHeight: number;
+    /**
+     * The track's quarter turn. Every dimension above is the display size, so all
+     * four already account for it. This exists for the pixels, which do not.
+     */
+    readonly rotation: Rotation;
+    readonly nativeFps: number | null;
+    readonly durationS: Sec;
+    /**
+     * Timestamp of the track's first sample, in seconds. Usually near zero but
+     * may be positive (a trimmed clip) or negative (offset timing). The seed
+     * seek and seek clamping use it as the origin so a non-zero start does not
+     * mis-seek to t=0.
+     */
+    readonly firstTimestampS: Sec;
+    /** Every real frame of this track, by its container tick timestamp. The one
+     *  place a frame's identity is defined; everything else snaps into it. */
+    readonly timeline: FrameTimeline;
+}
+/**
+ * Random-access cursor over a video source: the seam between the engine and
+ * the mediabunny primitives it wraps.
+ *
+ * The implementation (CanvasSinkScrubCursor) rides CanvasSink.getCanvas(t)
+ * for random-access seeks, which does the keyframe walk and GOP decode
+ * internally, and a sink.canvases(start) iterator for forward playback that
+ * lives only between attachPlay and detachPlay. The interface is kept as a
+ * seam so a future mediabunny SampleCursor backend can replace the
+ * implementation without touching consumers.
+ *
+ * Contract notes consumers rely on:
+ *   - seekTo coalesces concurrent seeks latest-wins, so rapid pointermove
+ *     scrubs collapse to the most recent target.
+ *   - seekToKey lands on the sample at or before t and marks the emitted
+ *     frame as a keyframe result.
+ *   - next is VFR-correct and a no-op while paused (no iterator attached),
+ *     so it never advances media time across a paused canvas. The 1/fps step
+ *     approximation lives in WebVideoEngine.step, not here.
+ *   - isIdle is true only when no seek is draining and no pull is in flight.
+ *   - subscribe replays the most recent frame to a new listener so the seed
+ *     frame from open() is never dropped.
+ *   - close is final; reusing a closed cursor is a programming error.
+ */
+export interface ScrubCursor {
+    readonly state: ScrubCursorState;
+    readonly track: ScrubTrackInfo;
+    readonly isIdle: boolean;
+    open(): Promise<void>;
+    seekTo(timestamp: Sec, intent?: SeekIntent): void;
+    seekToKey(timestamp: Sec): void;
+    next(): void;
+    /**
+     * Attach a forward-playback iterator anchored at startS. Required for
+     * next() to advance; paused mode keeps no iterator.
+     */
+    attachPlay(startS: number): void;
+    /** Detach the forward-playback iterator. */
+    detachPlay(): void;
+    /**
+     * Decode the named frame of the source and emit it through the listener
+     * chain. Returns the emitted ScrubFrame, or null at a boundary or once
+     * closed. Steps are index arithmetic on the frame table, so a caller names
+     * the frame it wants and not a time near it.
+     */
+    seekToFrame(frame: FrameId): Promise<ScrubFrame | null>;
+    idle(): Promise<void>;
+    /**
+     * Resolves at the seek drain's next settle: whichever target it is servicing
+     * has landed. The wait spans one decode. idle() spans the whole gesture,
+     * since a drag re-arms the drain on every pointer move, so a caller that has
+     * to answer while the hand is still down asks this one.
+     */
+    seekSettled(): Promise<void>;
+    /**
+     * Registers a frame listener. The cache replays the most recently emitted
+     * frame synchronously on subscribe so the seed frame from open() is
+     * delivered to controllers that wire up afterwards.
+     */
+    subscribe(listener: ScrubFrameListener): () => void;
+    /**
+     * Synchronous best-effort cache lookup the render loop calls on scrub to
+     * paint a frame this same tick, before the full-res decode resolves. The
+     * uncached implementation returns null; the caching scheduler returns the
+     * closest cached frame within tolerance, or null on a miss.
+     */
+    peekCached(timeMs: number): ScrubFrame | null;
+    /**
+     * Observability snapshot (cache hit-rate, scrub-decode latency). Present
+     * only on the caching backend; the uncached cursor omits it.
+     */
+    /** Decoded frames the consumer may hold ahead of the playhead; see
+     *  FrameProvider.playReadAhead. Absent on cursors with no decode path of
+     *  their own, where the caller falls back to the canvas depth. */
+    readonly playReadAhead?: number;
+    getStats?(): SchedulerStats;
+    /**
+     * Eagerly walks the whole track's keyframes into the index, metadata only,
+     * so the diagnostics keyframe lane reflects the entire file rather than just
+     * the swept regions. Idempotent and off the hot seek path. Present only on
+     * the caching backend (the uncached cursor keeps no index); callers invoke
+     * it from the diagnostics layer, never during a gesture.
+     */
+    ensureKeyframeIndex?(): Promise<void>;
+    close(): Promise<void>;
+}
+export type ScrubCursorFactory = (options: CreateScrubCursorOptions) => Promise<ScrubCursor>;

package/dist/web-video-engine/scrub-trajectory.d.ts

@@ -0,0 +1,29 @@
+import type { Sec } from "./types";
+/**
+ * Reads which way a scrub gesture is travelling, so a prefetch window can spend
+ * its budget on the side of the playhead the hand is moving toward.
+ *
+ * The heading spans a bounded ring of recent samples, so one jittery pointer
+ * move cannot swing it. A step opposing the ring's heading drops the samples
+ * behind it, leaving the reversal as the only evidence of where the gesture is
+ * going.
+ */
+export declare class ScrubTrajectory {
+    private readonly capacity;
+    private readonly positionsS;
+    private readonly timesMs;
+    private count;
+    private writeIndex;
+    constructor(capacity?: number);
+    sample(positionS: Sec, atMs: number): void;
+    /**
+     * Which way the gesture is travelling: 1 forward, -1 backward, 0 when there
+     * is not enough of a gesture to say. The direction survives being uncertain
+     * about how far, which is all a window split needs.
+     */
+    heading(): -1 | 0 | 1;
+    reset(): void;
+    private netDisplacementS;
+    private indexFromNewest;
+    private indexFromOldest;
+}

package/dist/web-video-engine/source-residency.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Byte residency for a URL source: the bytes this process holds, the fetch that
+ * serves them to the demuxer, and a background walk that fills the rest in.
+ *
+ * The browser HTTP cache does not do this job for media. A 200 response is
+ * stored whole and read back in about a millisecond, but the demuxer never
+ * issues one: it opens the file with `Range: bytes=N-` and abandons the
+ * response once it has what it wanted, so every read is stored as sparse data
+ * against a single cache entry. Sparse data is evicted long before a hundred
+ * megabytes of it accumulates, and a whole-file fetch issued after the demuxer
+ * has already touched the URL lands in that same sparse entry and is discarded
+ * with it. Bytes held here are held for as long as this session wants them,
+ * whatever the cache does.
+ */
+/** A held run of the source file, `end` exclusive. */
+export interface ResidentRange {
+    readonly start: number;
+    readonly end: number;
+}
+export interface ResidencySnapshot {
+    /** Held runs, ascending, never touching or overlapping. */
+    readonly ranges: readonly ResidentRange[];
+    readonly residentBytes: number;
+    /** Source length once a response has disclosed it, else null. */
+    readonly totalBytes: number | null;
+    /** Bytes the background walk has pulled, excluding what playback pulled. */
+    readonly prefetchedBytes: number;
+    readonly warming: boolean;
+}
+export interface SourceResidencyOptions {
+    readonly url: string;
+    /** Ceiling on held bytes. Runs furthest from the focus offset are dropped first. */
+    readonly budgetBytes: number;
+    /** Largest single background request. */
+    readonly chunkBytes?: number;
+    readonly requestInit?: RequestInit;
+    readonly fetchImpl?: typeof fetch;
+}
+export interface SourceResidency {
+    /** Hand to mediabunny's `UrlSource` as its `fetchFn`. */
+    readonly fetchFn: typeof fetch;
+    snapshot(): ResidencySnapshot;
+    /**
+     * Offset the background walk works outward from, so the bytes nearest the
+     * playhead arrive first and a viewer who seeks nearby stops waiting soonest.
+     */
+    focusAt(offset: number): void;
+    startWarming(): void;
+    stopWarming(): void;
+    dispose(): void;
+}
+/** Granularity at which a streaming read is banked. Mediabunny never asks
+ *  the network for less than half a mebibyte, so every read it makes banks
+ *  at least one block. */
+export declare const READ_BLOCK_BYTES: number;
+/** How long a delivered chunk may sit unclaimed before the walk stops deferring
+ *  to the read that produced it. It measures the gap between a chunk and the
+ *  consumer's next pull, not the wait for the server, so a slow link reads as
+ *  a live read while a reader that walked away frees the link. */
+export declare const FOREGROUND_STALL_MS = 250;
+/**
+ * Bytes held in one buffer per contiguous run, so a lookup is a single scan and
+ * a served range is a subarray with nothing copied. Insert is where copying
+ * happens: a run keeps spare capacity so an append that extends it writes into
+ * that room, and only a backward or overlapping insert re-materializes the run.
+ */
+export declare class ByteStore {
+    #private;
+    get residentBytes(): number;
+    /** Bytes retained by backing arrays, including append headroom. */
+    get allocatedBytes(): number;
+    ranges(): ResidentRange[];
+    /** The held run from `offset` to the end of its run, or null. */
+    runAt(offset: number): Uint8Array | null;
+    /** Where the gap containing `offset` ends, or null when nothing is held past it. */
+    nextHeldStart(offset: number): number | null;
+    insert(start: number, bytes: Uint8Array): void;
+    /**
+     * Brings held bytes under the budget: whole runs go first, furthest from
+     * `focus`, and a lone run that has outgrown the budget is narrowed to a
+     * `budgetBytes` window at `focus`.
+     */
+    evictTo(budgetBytes: number, focus: number): void;
+    clear(): void;
+}
+/**
+ * Outstanding claims on the link, for this module's own tests: they drive every
+ * way a read can end and assert the count comes back to zero.
+ */
+export declare function outstandingForegroundHolds(residency: SourceResidency): number;
+export declare function createSourceResidency(options: SourceResidencyOptions): SourceResidency;

package/dist/web-video-engine/trace-recorder.d.ts

@@ -0,0 +1,163 @@
+import type { FrameQuality } from "./scrub-cursor";
+import { type DiagnosticsSnapshot, type Warning } from "./diagnostics";
+/**
+ * Worker-realm trace recorder. Two fixed-capacity ring buffers capture a rolling
+ * window of what the runtime did: an EVENT ring (paints, scrubs, seeks, and
+ * status transitions, the moments EngineCore drives directly) and a SNAPSHOT
+ * ring (the same DiagnosticsSnapshot references already assembled for the
+ * broadcast). Both overwrite oldest in place, so a long session has a constant,
+ * predictable footprint and the appends are O(1) with no growth or GC churn.
+ *
+ * Stall and decode-spike depth are not separate events: stalls ride the snapshot
+ * ring (realtime.stalls), and per-decode latency rides the scrub stats, so the
+ * event ring stays to the moments the engine itself initiates.
+ *
+ * Allocated on arm, freed on disarm or export, so a disarmed recorder costs
+ * zero memory. assemble() walks both rings ascending into one self-describing
+ * versioned JSON document an agent or a human can read cold: the summary carries
+ * the exact Warning diagnoses the UI shows, so the trace explains itself.
+ *
+ * Pure data. It never touches decode, the sink, or the cursor.
+ */
+export declare const TRACE_SCHEMA = "roboflow.videoEngine.trace/2";
+/** One captured runtime event. type is the moment ("paint", "scrub", "seek",
+ *  "status"); tMs is worker-clock relative to arm; the rest are optional payload
+ *  fields the relevant moment fills. All plain data. */
+export interface TraceEvent {
+    readonly type: "paint" | "scrub" | "seek" | "status" | "rate";
+    readonly tMs: number;
+    readonly mediaTimeMs?: number;
+    readonly paintSeq?: number;
+    /** paint: which frame of the source these pixels are, by the engine's frame
+     *  table. The snapshot ring samples at 10Hz and paints outrun it, so without
+     *  this the frame most paints put up is named nowhere in the trace. */
+    readonly frameIndex?: number;
+    readonly catchUpMs?: number;
+    /** paint: whether a full decode or the coarse stand-in reached the canvas.
+     *  Paints come from sources with materially different pixel quality, so a
+     *  trace without this cannot tell a crisp frame from a blurry one. */
+    readonly quality?: FrameQuality;
+    /** seek/scrub: the target the gesture aimed at, and where it landed.
+     *  paint: the position the paint was serving (the engine clock at paint). */
+    readonly targetMs?: number;
+    readonly landedMs?: number;
+    /** seek: whether it was a key-only navigation seek. */
+    readonly keyOnly?: boolean;
+    /** status: the new playback status string. */
+    readonly status?: string;
+    /** rate: the new playback rate. Every paint after it is served by a clock
+     *  running at a different slope, which the timestamps alone do not show. */
+    readonly rate?: number;
+}
+/** A broadcast snapshot with the moment it was taken, in the same worker-clock
+ *  milliseconds since arm that every event carries, so the two series line up. */
+export type TracedSnapshot = DiagnosticsSnapshot & {
+    readonly tMs: number;
+};
+/** Environment facts captured once at export, so a trace read elsewhere carries
+ *  the device context that shaped the numbers. */
+export interface TraceEnvironment {
+    readonly userAgent: string;
+    readonly webgpuAvailable: boolean;
+    /** Null when nobody measured one: the engine has no window to read it off, so
+     *  it knows the ratio only when a host hands it a display box or a canvas. */
+    readonly devicePixelRatio: number | null;
+    readonly hardwareConcurrency: number;
+}
+/** Rolled-up totals for a glanceable read, with the same Warning diagnoses the
+ *  UI shows so the trace is self-explaining. effectivePaintFps is measured across
+ *  every snapshot pushed since arm, so it covers more than the snapshots the ring
+ *  still holds; no snapshot carries such a reading. cacheHitRatePct is null until
+ *  something looks the cache up, and cacheLookups is its denominator, so a reader
+ *  can tell a cold cache from a failing one. */
+export interface TraceSummary {
+    readonly scrubP50Ms: number;
+    readonly scrubP95Ms: number;
+    readonly scrubMaxMs: number;
+    readonly effectivePaintFps: number | null;
+    readonly lateFrames: number;
+    readonly stalls: number;
+    readonly maxCatchUpMs: number;
+    readonly cacheHitRatePct: number | null;
+    readonly cacheLookups: number;
+    readonly exactEvictions: number;
+    readonly warnings: Warning[];
+}
+/**
+ * How much of the capture one ring can still answer for. A capture older than a
+ * ring's capacity keeps only its tail, so durationMs describes the session and
+ * this describes the evidence: coveredMs runs from the oldest entry still held,
+ * and dropped counts what was overwritten to make room.
+ */
+export interface TraceRingCoverage {
+    readonly capacity: number;
+    readonly retained: number;
+    readonly dropped: number;
+    readonly oldestTMs: number | null;
+    readonly newestTMs: number | null;
+    readonly coveredMs: number;
+}
+/** Per-ring coverage. The two rings fill at different rates, so they reach back
+ *  different distances and neither one is "the captured window". */
+export interface TraceCoverage {
+    readonly events: TraceRingCoverage;
+    readonly snapshots: TraceRingCoverage;
+}
+/** The assembled trace document. Versioned by schema so a reader knows the shape. */
+export interface EngineTrace {
+    readonly schema: typeof TRACE_SCHEMA;
+    readonly capturedAt: number;
+    readonly armOriginMs: number;
+    readonly durationMs: number;
+    readonly coverage: TraceCoverage;
+    /** Why the capture stopped early, or null when a reader closed it. */
+    readonly truncatedReason: string | null;
+    readonly environment: TraceEnvironment;
+    readonly events: TraceEvent[];
+    readonly snapshots: TracedSnapshot[];
+    readonly summary: TraceSummary;
+}
+export interface TraceRecorderEnvironment {
+    readonly userAgent: string;
+    readonly webgpuAvailable: boolean;
+    readonly devicePixelRatio: number | null;
+    readonly hardwareConcurrency: number;
+}
+export declare class TraceRecorder {
+    private readonly env;
+    private readonly now;
+    private readonly events;
+    private readonly snapshots;
+    private readonly armOriginMs;
+    private paintedFrames;
+    private playingMs;
+    private lastSnapshotAtMs;
+    private lastPaints;
+    private lastSnapshotPlaying;
+    private truncatedReason;
+    constructor(env: TraceRecorderEnvironment, now?: () => number, eventCap?: number, snapshotCap?: number);
+    pushEvent(event: TraceEvent): void;
+    /**
+     * Stamps the broadcast snapshot with when it was taken and rings it. The
+     * stamp is the whole point of keeping a series: without it the snapshots are
+     * an unordered pile with no way to line them up against the events, which
+     * carry one, or to tell a freeze from a slow stretch.
+     */
+    pushSnapshot(snapshot: DiagnosticsSnapshot): void;
+    /** Records that the capture was cut short by something other than a reader
+     *  closing it, so an assembled trace says why it ends where it does. The
+     *  first reason sticks: it is the one that ended the capture. */
+    truncate(reason: string): void;
+    /**
+     * Paints between two consecutive snapshots over the wall time between them.
+     * An interval counts only when playback was up at both ends, since one
+     * folded-in pause paints nothing and sinks the rate far below what the user
+     * watched. The paint counter restarts with each play session, so a negative
+     * delta means a new session began and that interval is dropped.
+     */
+    private accumulatePaintRate;
+    /** Worker-clock milliseconds since arm; the stamp every pushed event uses. */
+    elapsedMs(): number;
+    assemble(): EngineTrace;
+    private summarize;
+}