@decartai/sdk 0.1.5 → 0.1.6

package/dist/realtime/observability/connection-quality.js

@@ -0,0 +1,219 @@
+import { REALTIME_CONFIG } from "../config-realtime.js";
+//#region src/realtime/observability/connection-quality.ts
+const RANK = {
+	critical: 0,
+	poor: 1,
+	fair: 2,
+	good: 3
+};
+function worst(...qualities) {
+	return qualities.reduce((a, b) => RANK[a] <= RANK[b] ? a : b);
+}
+function scoreLowerBetter(value, good, fair, poor) {
+	if (value === null) return "good";
+	if (value <= good) return "good";
+	if (value <= fair) return "fair";
+	if (value <= poor) return "poor";
+	return "critical";
+}
+function scoreHigherBetter(value, good, fair, poor) {
+	if (value === null) return "good";
+	if (value >= good) return "good";
+	if (value >= fair) return "fair";
+	if (value >= poor) return "poor";
+	return "critical";
+}
+function extractSignals(stats) {
+	const rttSec = stats.remoteInbound?.roundTripTime ?? stats.connection.currentRoundTripTime;
+	const isRelayed = stats.connection.selectedCandidatePairs.some((pair) => pair.local.candidateType === "relay" || pair.remote.candidateType === "relay");
+	return {
+		rttMs: rttSec != null ? rttSec * 1e3 : null,
+		g2gMs: stats.glassToGlass?.medianMs ?? null,
+		ttffMs: stats.glassToGlass?.ttffMs ?? null,
+		upstreamJitterMs: stats.remoteInbound?.jitter != null ? stats.remoteInbound.jitter * 1e3 : null,
+		fractionLost: stats.remoteInbound?.fractionLost != null ? stats.remoteInbound.fractionLost / 256 : null,
+		g2gDropRatio: stats.glassToGlass?.dropRatio ?? null,
+		availableOutgoingKbps: stats.connection.availableOutgoingBitrate != null ? stats.connection.availableOutgoingBitrate / 1e3 : null,
+		fps: stats.video?.framesPerSecond ?? null,
+		freezeCountDelta: stats.video?.freezeCountDelta ?? null,
+		qualityLimitationReason: stats.outboundVideo?.qualityLimitationReason ?? null,
+		isRelayed
+	};
+}
+/** Score an already-extracted (optionally smoothed) signal set. Pure. */
+function scoreMetrics(signals, thresholds, options = {}) {
+	const relayExtra = signals.isRelayed ? thresholds.rtt.relayExtraMs : 0;
+	const latency = signals.g2gMs != null ? scoreLowerBetter(signals.g2gMs, thresholds.glassToGlass.goodMs, thresholds.glassToGlass.fairMs, thresholds.glassToGlass.poorMs) : scoreLowerBetter(signals.rttMs, thresholds.rtt.goodMs + relayExtra, thresholds.rtt.fairMs + relayExtra, thresholds.rtt.poorMs + relayExtra);
+	const loss = scoreLowerBetter(signals.fractionLost, thresholds.loss.good, thresholds.loss.fair, thresholds.loss.poor);
+	let bandwidth = "good";
+	if (!options.skipBitrate) {
+		bandwidth = scoreHigherBetter(signals.availableOutgoingKbps != null ? signals.availableOutgoingKbps / thresholds.upstream.requiredUpstreamKbps : null, thresholds.upstream.goodRatio, thresholds.upstream.fairRatio, thresholds.upstream.poorRatio);
+		if (signals.qualityLimitationReason === "bandwidth") bandwidth = worst(bandwidth, "fair");
+	}
+	let stall = scoreHigherBetter(signals.fps, thresholds.stall.goodFps, thresholds.stall.fairFps, thresholds.stall.poorFps);
+	if (signals.freezeCountDelta != null && signals.freezeCountDelta > 0) stall = worst(stall, "fair");
+	const drop = scoreLowerBetter(signals.g2gDropRatio, thresholds.g2gDrop.good, thresholds.g2gDrop.fair, thresholds.g2gDrop.poor);
+	stall = worst(stall, drop);
+	const quality = worst(bandwidth, latency, loss, stall);
+	let limitingFactor;
+	if (quality === "good") limitingFactor = signals.qualityLimitationReason === "cpu" ? "cpu" : "none";
+	else if (bandwidth === quality) limitingFactor = "bandwidth";
+	else if (loss === quality) limitingFactor = "loss";
+	else if (latency === quality) limitingFactor = "latency";
+	else limitingFactor = "stall";
+	return {
+		quality,
+		limitingFactor
+	};
+}
+function median(values) {
+	if (values.length === 0) return null;
+	const sorted = [...values].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function minOrNull(values) {
+	return values.length === 0 ? null : Math.min(...values);
+}
+var RingBuffer = class {
+	values = [];
+	constructor(size) {
+		this.size = size;
+	}
+	push(value) {
+		if (value === null) return;
+		this.values.push(value);
+		if (this.values.length > this.size) this.values.shift();
+	}
+	median() {
+		return median(this.values);
+	}
+	min() {
+		return minOrNull(this.values);
+	}
+	clear() {
+		this.values = [];
+	}
+};
+/**
+* Smooths metrics over a rolling window and applies asymmetric hysteresis so the
+* emitted level doesn't flap. `update()` returns a report only when the level or
+* warm-up state changes; `current()` returns the latest at any time.
+*/
+var ConnectionQualityEvaluator = class {
+	rtt;
+	glassToGlass;
+	loss;
+	availableOutgoing;
+	fps;
+	sampleCount = 0;
+	currentLevel = null;
+	currentFactor = "none";
+	candidateLevel = null;
+	candidateCount = 0;
+	prevWarmingUp = true;
+	lastReport = null;
+	constructor(thresholds = REALTIME_CONFIG.observability.connectionQuality) {
+		this.thresholds = thresholds;
+		const w = thresholds.windowSamples;
+		this.rtt = new RingBuffer(w);
+		this.glassToGlass = new RingBuffer(w);
+		this.loss = new RingBuffer(w);
+		this.availableOutgoing = new RingBuffer(w);
+		this.fps = new RingBuffer(w);
+	}
+	/** Feed one raw stats sample. Returns a report only when the level or warm-up state changes. */
+	update(stats) {
+		this.sampleCount++;
+		const raw = extractSignals(stats);
+		this.rtt.push(raw.rttMs);
+		this.glassToGlass.push(raw.g2gMs);
+		this.loss.push(raw.fractionLost);
+		this.availableOutgoing.push(raw.availableOutgoingKbps);
+		this.fps.push(raw.fps);
+		const smoothed = {
+			...raw,
+			rttMs: this.rtt.median(),
+			g2gMs: this.glassToGlass.median(),
+			fractionLost: this.loss.median(),
+			availableOutgoingKbps: this.availableOutgoing.median(),
+			fps: this.fps.min()
+		};
+		const warmingUp = this.sampleCount < this.thresholds.warmupSamples;
+		const { quality, limitingFactor } = scoreMetrics(smoothed, this.thresholds, { skipBitrate: warmingUp });
+		const warmupJustEnded = this.prevWarmingUp && !warmingUp;
+		this.prevWarmingUp = warmingUp;
+		let changed;
+		if (warmupJustEnded) {
+			changed = this.currentLevel !== quality;
+			this.currentLevel = quality;
+			this.candidateLevel = null;
+			this.candidateCount = 0;
+		} else changed = this.applyHysteresis(quality);
+		const emitted = this.currentLevel ?? quality;
+		if (emitted === "good") this.currentFactor = smoothed.qualityLimitationReason === "cpu" ? "cpu" : "none";
+		else if (RANK[quality] <= RANK[emitted]) this.currentFactor = limitingFactor;
+		this.lastReport = {
+			quality: emitted,
+			limitingFactor: this.currentFactor,
+			warmingUp,
+			metrics: {
+				rttMs: smoothed.rttMs,
+				g2gMs: smoothed.g2gMs,
+				ttffMs: raw.ttffMs,
+				fps: smoothed.fps,
+				packetLoss: smoothed.fractionLost,
+				upstreamJitterMs: raw.upstreamJitterMs,
+				g2gDropRatio: raw.g2gDropRatio,
+				availableUpstreamKbps: smoothed.availableOutgoingKbps
+			}
+		};
+		return changed || warmupJustEnded ? this.lastReport : null;
+	}
+	current() {
+		return this.lastReport;
+	}
+	reset() {
+		this.rtt.clear();
+		this.glassToGlass.clear();
+		this.loss.clear();
+		this.availableOutgoing.clear();
+		this.fps.clear();
+		this.sampleCount = 0;
+		this.currentLevel = null;
+		this.currentFactor = "none";
+		this.candidateLevel = null;
+		this.candidateCount = 0;
+		this.prevWarmingUp = true;
+		this.lastReport = null;
+	}
+	/** Returns true if the debounced level changed this tick. */
+	applyHysteresis(raw) {
+		if (this.currentLevel === null) {
+			this.currentLevel = raw;
+			this.candidateLevel = null;
+			this.candidateCount = 0;
+			return true;
+		}
+		if (raw === this.currentLevel) {
+			this.candidateLevel = null;
+			this.candidateCount = 0;
+			return false;
+		}
+		if (raw === this.candidateLevel) this.candidateCount++;
+		else {
+			this.candidateLevel = raw;
+			this.candidateCount = 1;
+		}
+		const required = RANK[raw] < RANK[this.currentLevel] ? this.thresholds.downgradeConsecutive : this.thresholds.upgradeConsecutive;
+		if (this.candidateCount >= required) {
+			this.currentLevel = raw;
+			this.candidateLevel = null;
+			this.candidateCount = 0;
+			return true;
+		}
+		return false;
+	}
+};
+//#endregion
+export { ConnectionQualityEvaluator, extractSignals, scoreLowerBetter, worst };

package/dist/realtime/observability/glass-to-glass.d.ts

@@ -0,0 +1,41 @@
+//#region src/realtime/observability/glass-to-glass.d.ts
+
+/**
+ * Aggregated glass-to-glass metrics. TTFF (startup) and mid-stream (steady
+ * state) are measured separately — they differ by an order of magnitude and the
+ * cold-start frames must not pollute the steady-state numbers.
+ */
+type G2GMetrics = {
+  /**
+   * Time-to-first-frame (ms): from the connect attempt start to the first
+   * rendered model output. A one-shot startup metric, ~seconds. Null until the
+   * first frame arrives.
+   */
+  ttffMs: number | null;
+  /**
+   * Median mid-stream (steady-state) glass-to-glass latency (ms), excluding the
+   * warm-up after the first frame. Null until past warm-up. This is the
+   * per-frame responsiveness, distinct from `ttffMs`.
+   */
+  medianMs: number | null;
+  /** p90 mid-stream glass-to-glass latency (ms), or null until past warm-up. */
+  p90Ms: number | null;
+  /** Mid-stream latency samples in the window (post-warm-up). */
+  sampleCount: number;
+  /**
+   * End-to-end frame drop ratio (0–1): seqs stamped but never rendered, over
+   * recent post-warm-up outcomes. Null until enough frames have completed the
+   * round trip — short sessions/probes may never produce it.
+   */
+  dropRatio: number | null;
+};
+/**
+ * Matches outgoing stamp times to incoming render times. Shared by the stamp
+ * pump (writer) and the marker reader (matcher); owned by `RealtimeObservability`.
+ *
+ * Tracks two latencies: TTFF (start → first frame) and mid-stream median (steady
+ * state, after a warm-up). Call `markStart()` at the beginning of each connect
+ * attempt so TTFF measures the full setup→first-frame wait.
+ */
+//#endregion
+export { G2GMetrics };

package/dist/realtime/observability/glass-to-glass.js

@@ -0,0 +1,229 @@
+import { createFrameTransformPump } from "../mirror-stream.js";
+import { MAX_MARKER_HEIGHT, MIN_MARKER_WIDTH, read, stamp } from "./pixel-marker.js";
+//#region src/realtime/observability/glass-to-glass.ts
+/**
+* True glass-to-glass latency measurement for the realtime pipeline.
+*
+* Opt-in (the marker is visible in the output and pixel work has a cost). When
+* enabled, the SDK stamps a monotonic sequence number into the bottom-left of
+* every outgoing frame ({@link createStampPump}) and reads it back off the
+* rendered remote frames ({@link createMarkerReader}); the server re-stamps the
+* seq from input to matching output (its `pixel_latency` mode). The
+* {@link SeqTracker} matches stamp time to render time to compute the real
+* camera→display latency through the model, and infers end-to-end frame drops
+* from seqs that are stamped but never rendered.
+*
+* The stamp pump is built on the shared `createFrameTransformPump` (Insertable
+* Streams where available, canvas `captureStream` fallback). The reader is a
+* passive offscreen-`<video>` tap so it never consumes or re-encodes the track
+* the consumer displays.
+*/
+/** Bound on in-flight seqs; a seq that ages out unmatched is an end-to-end drop. Cf. server `_MAX_PENDING`. */
+const MAX_PENDING = 256;
+/** Rolling window for the latency percentiles (≈10s at 30fps). */
+const LATENCY_WINDOW = 300;
+/** Rolling window of delivered/dropped outcomes for the drop ratio. */
+const OUTCOME_WINDOW = 300;
+/** Don't report a drop ratio until this many outcomes exist (head-of-stream frames are still in flight). */
+const DROP_MIN_OUTCOMES = 30;
+/** Discard implausible deltas (clock weirdness, seq wrap collisions). */
+const MAX_PLAUSIBLE_MS = 6e4;
+/**
+* After the first frame, ignore this long before counting steady-state samples.
+* The first frames after a cold start run slow while the pipeline warms; folding
+* them into the mid-stream median would inflate it. (TTFF still captures the
+* first frame.)
+*/
+const MID_STREAM_WARMUP_MS = 2e3;
+/**
+* Matches outgoing stamp times to incoming render times. Shared by the stamp
+* pump (writer) and the marker reader (matcher); owned by `RealtimeObservability`.
+*
+* Tracks two latencies: TTFF (start → first frame) and mid-stream median (steady
+* state, after a warm-up). Call `markStart()` at the beginning of each connect
+* attempt so TTFF measures the full setup→first-frame wait.
+*/
+var SeqTracker = class {
+	stampTimes = /* @__PURE__ */ new Map();
+	latencies = [];
+	/** true = delivered (matched), false = dropped (aged out unmatched). */
+	outcomes = [];
+	nextSeq = 0;
+	startMs = null;
+	firstMatchMs = null;
+	ttffMs = null;
+	/** Mark the start of a connect attempt; resets measurement state. TTFF is measured from here. */
+	markStart(nowMs) {
+		this.reset();
+		this.startMs = nowMs;
+	}
+	/** Allocate the next seq for an outgoing frame and record its stamp time. Returns the 16-bit seq. */
+	stampNext(nowMs) {
+		const seq = this.nextSeq & 65535;
+		this.nextSeq = this.nextSeq + 1 & 65535;
+		this.stampTimes.set(seq, nowMs);
+		if (this.stampTimes.size > MAX_PENDING) {
+			const oldest = this.stampTimes.keys().next();
+			if (!oldest.done) {
+				this.stampTimes.delete(oldest.value);
+				if (this.isPastWarmup(nowMs)) this.recordOutcome(false);
+			}
+		}
+		return seq;
+	}
+	/** Match a seq read off an inbound rendered frame. Ignores unknown/duplicate seqs. */
+	recordInbound(seq, nowMs) {
+		const stampedAt = this.stampTimes.get(seq);
+		if (stampedAt === void 0) return;
+		this.stampTimes.delete(seq);
+		const g2g = nowMs - stampedAt;
+		if (g2g < 0 || g2g > MAX_PLAUSIBLE_MS) return;
+		if (this.firstMatchMs === null) {
+			this.firstMatchMs = nowMs;
+			if (this.startMs !== null) this.ttffMs = nowMs - this.startMs;
+			for (const [key, stampTime] of this.stampTimes) if (stampTime < stampedAt) this.stampTimes.delete(key);
+			else break;
+		}
+		if (!this.isPastWarmup(nowMs)) return;
+		this.latencies.push(g2g);
+		if (this.latencies.length > LATENCY_WINDOW) this.latencies.shift();
+		this.recordOutcome(true);
+	}
+	snapshot() {
+		const sorted = [...this.latencies].sort((a, b) => a - b);
+		const n = sorted.length;
+		const medianMs = n === 0 ? null : n % 2 === 0 ? Math.round((sorted[n / 2 - 1] + sorted[n / 2]) / 2) : Math.round(sorted[(n - 1) / 2]);
+		const p90Ms = n === 0 ? null : Math.round(sorted[Math.min(n - 1, Math.floor(.9 * n))]);
+		let dropRatio = null;
+		if (this.outcomes.length >= DROP_MIN_OUTCOMES) dropRatio = this.outcomes.reduce((acc, delivered) => acc + (delivered ? 0 : 1), 0) / this.outcomes.length;
+		return {
+			ttffMs: this.ttffMs,
+			medianMs,
+			p90Ms,
+			sampleCount: n,
+			dropRatio
+		};
+	}
+	/** Clear measurement state. Keeps `nextSeq` monotonic to avoid stale collisions. */
+	reset() {
+		this.stampTimes.clear();
+		this.latencies.length = 0;
+		this.outcomes.length = 0;
+		this.startMs = null;
+		this.firstMatchMs = null;
+		this.ttffMs = null;
+	}
+	isPastWarmup(nowMs) {
+		return this.firstMatchMs !== null && nowMs >= this.firstMatchMs + MID_STREAM_WARMUP_MS;
+	}
+	recordOutcome(delivered) {
+		this.outcomes.push(delivered);
+		if (this.outcomes.length > OUTCOME_WINDOW) this.outcomes.shift();
+	}
+};
+/**
+* Wrap `input` so every published video frame carries a fresh marker (drawn into
+* the bottom-left band). Built on the shared frame-transform pump; no-ops when
+* there's no video track or the frame is too small to hold the marker.
+*/
+function createStampPump(input, opts) {
+	const { tracker, fps } = opts;
+	const stampIntervalMs = 1e3 / fps;
+	let lastStampMs = 0;
+	let currentSeq = null;
+	return createFrameTransformPump(input, {
+		fps,
+		transform: (ctx, source, w, h) => {
+			ctx.drawImage(source, 0, 0, w, h);
+			if (w < MIN_MARKER_WIDTH || h < 32) return;
+			const now = performance.now();
+			if (currentSeq === null || now - lastStampMs >= stampIntervalMs - 1) {
+				currentSeq = tracker.stampNext(now);
+				lastStampMs = now;
+			}
+			const band = ctx.getImageData(0, h - 32, w, 32);
+			stamp(band, currentSeq);
+			ctx.putImageData(band, 0, h - 32);
+		}
+	});
+}
+/**
+* Drives `onFrame` once per rendered video frame. Prefers
+* `requestVideoFrameCallback` (fires per decoded frame) over `requestAnimationFrame`
+* (fires at display refresh — ~2× the work on a 30fps stream shown at 60Hz).
+* The `typeof` guard keeps the rAF fallback for browsers that lack rVFC.
+*/
+function createFrameScheduler(video, onFrame) {
+	const supportsRvfc = typeof video.requestVideoFrameCallback === "function";
+	let handle = null;
+	let running = false;
+	const schedule = () => {
+		if (!running) return;
+		handle = supportsRvfc ? video.requestVideoFrameCallback(tick) : requestAnimationFrame(tick);
+	};
+	const tick = () => {
+		if (!running) return;
+		onFrame();
+		schedule();
+	};
+	return {
+		start: () => {
+			if (running) return;
+			running = true;
+			schedule();
+		},
+		stop: () => {
+			running = false;
+			if (handle === null) return;
+			if (supportsRvfc) video.cancelVideoFrameCallback(handle);
+			else cancelAnimationFrame(handle);
+			handle = null;
+		}
+	};
+}
+/**
+* Passively read markers off the rendered remote video. Uses a hidden `<video>`
+* fed by the same track (a track can drive multiple sinks), reading only the
+* bottom band per rendered frame — never consumes or re-encodes the displayed track.
+*/
+function createMarkerReader(tracker) {
+	if (typeof document === "undefined") return {
+		attach: () => {},
+		dispose: () => {}
+	};
+	const video = document.createElement("video");
+	video.muted = true;
+	video.playsInline = true;
+	video.autoplay = true;
+	const canvas = document.createElement("canvas");
+	const ctx = canvas.getContext("2d", { willReadFrequently: true });
+	let attachedTrack = null;
+	const readFrame = () => {
+		const w = video.videoWidth;
+		const h = video.videoHeight;
+		if (w === 0 || h === 0 || !ctx) return;
+		const band = Math.min(h, MAX_MARKER_HEIGHT);
+		if (canvas.width !== w) canvas.width = w;
+		if (canvas.height !== band) canvas.height = band;
+		ctx.drawImage(video, 0, h - band, w, band, 0, 0, w, band);
+		const seq = read(ctx.getImageData(0, 0, w, band));
+		if (seq !== null) tracker.recordInbound(seq, performance.now());
+	};
+	const scheduler = createFrameScheduler(video, readFrame);
+	return {
+		attach: (track) => {
+			if (track === attachedTrack) return;
+			attachedTrack = track;
+			video.srcObject = new MediaStream([track]);
+			video.play().catch(() => {});
+			scheduler.start();
+		},
+		dispose: () => {
+			scheduler.stop();
+			attachedTrack = null;
+			video.srcObject = null;
+		}
+	};
+}
+//#endregion
+export { SeqTracker, createMarkerReader, createStampPump };

package/dist/realtime/observability/pixel-marker.js

@@ -0,0 +1,144 @@
+//#region src/realtime/observability/pixel-marker.ts
+const SYNC = [
+	200,
+	50,
+	200,
+	50
+];
+const SYNC_LEN = SYNC.length;
+const DATA_BITS = 16;
+const CHECKSUM_BITS = 4;
+/** 4 sync + 16 data + 4 checksum logical columns. */
+const TOTAL_LOGICAL = SYNC_LEN + DATA_BITS + CHECKSUM_BITS;
+/** Redundant logical rows, majority-voted on read. */
+const MARKER_ROWS = 4;
+/** Physical pixels per logical pixel when stamping (native resolution). */
+const BLOCK_SIZE = 8;
+/**
+* Candidate received block sizes, ordered by likelihood (nominal 8, no transport
+* scaling). Smaller values appear when WebRTC BWE downscales the stream; larger
+* when the sender upscales pre-encode. Mirrors `_CANDIDATE_BLOCK_SIZES`.
+*/
+const CANDIDATE_BLOCK_SIZES = [
+	8,
+	4,
+	6,
+	2,
+	12,
+	10,
+	16,
+	5,
+	7,
+	14,
+	3
+];
+/** Smallest frame that can hold the marker at nominal block size. */
+const MIN_MARKER_WIDTH = TOTAL_LOGICAL * BLOCK_SIZE;
+MARKER_ROWS * BLOCK_SIZE;
+/** Tallest the marker can be in a received frame (largest auto-detect block size). */
+const MAX_MARKER_HEIGHT = MARKER_ROWS * Math.max(...CANDIDATE_BLOCK_SIZES);
+/** BT.601 luma approximation (integer, matches a >=128 threshold either way). */
+function luma(r, g, b) {
+	return 77 * r + 150 * g + 29 * b >> 8;
+}
+const isHigh = (v) => v >= 128;
+/** XOR of the four 4-bit nibbles of the 16-bit seq (matches the server). */
+function checksumNibbles(seq) {
+	let checksum = 0;
+	for (let i = 0; i < DATA_BITS; i += 4) checksum ^= seq >> i & 15;
+	return checksum;
+}
+/** The TOTAL_LOGICAL grayscale values for one logical row encoding `seq`. */
+function rowValues(seq) {
+	const masked = seq & 65535;
+	const values = [...SYNC];
+	for (let i = 0; i < DATA_BITS; i++) values.push(masked >> DATA_BITS - 1 - i & 1 ? 200 : 50);
+	const checksum = checksumNibbles(masked);
+	for (let i = 0; i < CHECKSUM_BITS; i++) values.push(checksum >> CHECKSUM_BITS - 1 - i & 1 ? 200 : 50);
+	return values;
+}
+/**
+* Stamp `seq` into the bottom-left of `img` as grayscale blocks (mutates in
+* place). Returns false (no-op) if the frame is too small to hold the marker.
+* Always stamps at BLOCK_SIZE=8, matching the server's native-resolution stamp.
+*/
+function stamp(img, seq) {
+	const { width, height, data } = img;
+	if (width < MIN_MARKER_WIDTH || height < 32) return false;
+	const values = rowValues(seq);
+	for (let logRow = 0; logRow < MARKER_ROWS; logRow++) {
+		const rowStart = height - (MARKER_ROWS - logRow) * BLOCK_SIZE;
+		for (let by = 0; by < BLOCK_SIZE; by++) {
+			const y = rowStart + by;
+			if (y < 0 || y >= height) continue;
+			for (let logCol = 0; logCol < TOTAL_LOGICAL; logCol++) {
+				const v = values[logCol];
+				const xStart = logCol * BLOCK_SIZE;
+				const xEnd = Math.min(xStart + BLOCK_SIZE, width);
+				for (let x = xStart; x < xEnd; x++) {
+					const o = (y * width + x) * 4;
+					data[o] = v;
+					data[o + 1] = v;
+					data[o + 2] = v;
+					data[o + 3] = 255;
+				}
+			}
+		}
+	}
+	return true;
+}
+function syncMatches(rowValues) {
+	for (let i = 0; i < SYNC_LEN; i++) if (isHigh(SYNC[i]) !== isHigh(rowValues[i])) return false;
+	return true;
+}
+/**
+* Read the marker seq from the bottom of `img`, or null if absent/unreadable.
+* Auto-detects the received block size so it works at any received resolution
+* (the transport may uniformly scale the frame after the server stamped it).
+*/
+function read(img) {
+	const { width, height, data } = img;
+	const sample = (row, col) => {
+		const o = (row * width + col) * 4;
+		return luma(data[o], data[o + 1], data[o + 2]);
+	};
+	for (const blockSize of CANDIDATE_BLOCK_SIZES) {
+		if (width < TOTAL_LOGICAL * blockSize || height < MARKER_ROWS * blockSize) continue;
+		const seq = decodeAtBlockSize(sample, width, height, blockSize);
+		if (seq !== null) return seq;
+	}
+	return null;
+}
+function decodeAtBlockSize(sample, width, height, blockSize) {
+	const half = blockSize >> 1;
+	const validRows = [];
+	for (let logRow = 0; logRow < MARKER_ROWS; logRow++) {
+		let row = height - (MARKER_ROWS - logRow) * blockSize + half;
+		row = Math.max(0, Math.min(row, height - 1));
+		const rv = [];
+		for (let logCol = 0; logCol < TOTAL_LOGICAL; logCol++) {
+			let col = logCol * blockSize + half;
+			col = Math.max(0, Math.min(col, width - 1));
+			rv.push(sample(row, col));
+		}
+		if (syncMatches(rv)) validRows.push(rv);
+	}
+	if (validRows.length === 0) return null;
+	const threshold = validRows.length / 2;
+	let seq = 0;
+	for (let i = 0; i < DATA_BITS; i++) {
+		let votes = 0;
+		for (const rv of validRows) if (isHigh(rv[SYNC_LEN + i])) votes++;
+		if (votes > threshold) seq |= 1 << DATA_BITS - 1 - i;
+	}
+	const expectedChecksum = checksumNibbles(seq);
+	let actualChecksum = 0;
+	for (let i = 0; i < CHECKSUM_BITS; i++) {
+		let votes = 0;
+		for (const rv of validRows) if (isHigh(rv[SYNC_LEN + DATA_BITS + i])) votes++;
+		if (votes > threshold) actualChecksum |= 1 << CHECKSUM_BITS - 1 - i;
+	}
+	return expectedChecksum === actualChecksum ? seq : null;
+}
+//#endregion
+export { MAX_MARKER_HEIGHT, MIN_MARKER_WIDTH, read, stamp };