@camstack/addon-provider-hikvision 1.2.124 → 1.2.126

package/dist/addon.mjs

@@ -1,6 +1,6 @@
 import { createRequire } from "node:module";
 import { createHash, randomBytes } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createReadStream } from "node:fs";
 import { spawn } from "node:child_process";
@@ -5373,7 +5373,7 @@ var ZodIssueCode = {
 var ZodFirstPartyTypeKind;
 ZodFirstPartyTypeKind || (ZodFirstPartyTypeKind = {});
 //#endregion
-//#region ../types/dist/sleep-i3eUVc-d.mjs
+//#region ../types/dist/sleep-COWaSCAi.mjs
 /**
 * The audio chunk plane's byte format, and the ONE expansion from a coded
 * window to float samples (D455).
@@ -7543,6 +7543,24 @@ object({
 		unreachable: number()
 	})
 });
+/** The wire shape of {@link PeerBytesTicket} — see the type for what it is. */
+var PeerBytesTicketSchema = object({
+	/** `http://127.0.0.1:<port>/<token>`. One `GET` takes it. */
+	url: string().min(1),
+	/**
+	* The HOST node this URL means something on — the hub or a named agent,
+	* never a runner. {@link AddonPeerBytes.open} compares it to its own and
+	* refuses `cross-node` by name when they differ, without dialling.
+	*/
+	hostNodeId: string().min(1),
+	expiresAtMs: number().int().nonnegative(),
+	/**
+	* What the producer DECLARED the body to be, when it knows — `null` when it
+	* does not. Never `0` for unknown (D393): a consumer sizing a bound off this
+	* must be able to tell "the producer did not say" from "the body is empty".
+	*/
+	declaredBytes: number().int().nonnegative().nullable()
+});
 /**
 * Adoption job — the background form of `device-adoption.adopt`.
 *
@@ -25016,6 +25034,7 @@ _enum([
 	"sleeping",
 	"camera-refused",
 	"no-keyframe",
+	"decode-failed",
 	"no-catalog-row",
 	"unsupported",
 	"unknown-device",
@@ -25024,8 +25043,43 @@ _enum([
 _enum(["deferred", "final"]);
 /** The camera's / provider's own words. Kept verbatim, never parsed. */
 var CLIP_STILL_REASON_HEADER = "x-camstack-reason";
+/**
+* Make a refusal sentence safe to put in an HTTP header.
+*
+* **An HTTP header value is Latin-1.** Node throws `Invalid character in
+* header content` on anything above U+00FF, the handler dies mid-response,
+* and the client gets a socket hang up — no status, no reason, nothing. The
+* mechanism that exists to EXPLAIN a refusal is then the thing that silences
+* it, and the surface shows "nothing happened".
+*
+* That is not hypothetical: measured 2026-09-23 on 1436, a Hikvision replay
+* refusal read `SETUP of the video track answered 500 — the camera refused
+* this replay`, and the EM DASH in it threw on every clip the operator
+* opened. This repository writes its refusals in prose, and its prose uses
+* `—`, `’` and `…` everywhere, so every reason string is a candidate.
+*
+* Substitutes rather than strips: an operator reading a log or a response
+* should get a readable sentence, not one with holes in it. The typographic
+* characters this repo actually writes have exact ASCII equivalents; anything
+* else non-Latin-1 becomes `?`, which is visible rather than silent. Control
+* characters go too — a newline in a header value is a response-splitting
+* bug, not a formatting one.
+*/
+function clipReasonHeaderValue(reason) {
+	const folded = reason.replace(/[\u2013\u2014\u2212]/g, "-").replace(/[\u2018\u2019\u201b]/g, "'").replace(/[\u201c\u201d]/g, "\"").replace(/\u2026/g, "...").replace(/[\u00a0\u2007\u202f]/g, " ");
+	let out = "";
+	for (const ch of folded) {
+		const code = ch.codePointAt(0) ?? 0;
+		if (code < 32 || code === 127) out += " ";
+		else if (code > 255) out += "?";
+		else out += ch;
+	}
+	return out.slice(0, 500).trim();
+}
 /** One {@link ClipStillRefusalCodeSchema} token, alone. */
 var CLIP_STILL_REASON_CODE_HEADER = "x-camstack-reason-code";
+/** One {@link ClipStillDispositionSchema} token, alone. */
+var CLIP_STILL_DISPOSITION_HEADER = "x-camstack-disposition";
 /**
 * The clip STREAM route's own statement of what it is (D597): the value is
 * `forward-only`. A producer writes it on the 200; a consumer that dials a
@@ -25284,12 +25338,37 @@ var ClipWakeSchema = _enum(["authorised"]);
 * the size in the message, never truncates. Half a video is worse than an
 * honest refusal.
 *
-* The clean follow-on is a CHUNKED read so a `high` twin of a long clip stops
-* being refusable at all. That is a later slice, named here so the bound is
-* not mistaken for a design ceiling.
+* **Superseded as the way a clip export gets its bytes** (D613). The bound is
+* a property of the ENVELOPE, not of clips, so the cure was a transport with
+* no envelope: {@link videoclipsCapability.methods.offerClipBytes} hands back
+* a one-shot `peerBytes` ticket and the consumer streams it straight to disk,
+* holding nothing. This method stays for a consumer that genuinely wants the
+* bytes in hand, and for a provider not yet redeployed — with this bound,
+* which for an inline read is not going to move.
 */
 var VIDEOCLIPS_MAX_READ_BYTES = 50 * 1024 * 1024;
 /**
+* Hard ceiling on ONE {@link videoclipsCapability.methods.offerClipBytes}
+* transfer — ten times {@link VIDEOCLIPS_MAX_READ_BYTES}, and the reasoning is
+* not "ten times more comfortable".
+*
+* The inline bound is set by what is HELD: a base64 envelope is the payload at
+* ~1.33× in the provider AND the same again in the caller, so 50 MiB of clip
+* is ~133 MiB of heap across two processes. Over `peerBytes` the consumer
+* holds one socket chunk at a time and writes straight through to the export
+* file, so its contribution is flat whatever the clip weighs. What is left is
+* the PRODUCER's own copy, and that is a property of how each provider makes a
+* clip rather than of this transport: Hikvision's fetch writes to a scratch
+* FILE and offers it (nothing is held), Reolink's cmd-5 transfer is collected
+* in memory and offered from there (one copy, the one it already had).
+*
+* So this number bounds the worst provider, not the transport, and it is named
+* separately so that lifting it is a statement about a provider rather than
+* about clips. Above it the provider REFUSES with the size in the message and
+* never truncates: half a video is worse than an honest refusal.
+*/
+var VIDEOCLIPS_MAX_OFFER_BYTES = 500 * 1024 * 1024;
+/**
 * A clip's finished bytes, inline — the twin of `recordingExport.readExportBytes`.
 *
 * `bytes` is the DECODED length, so nobody infers it from the base64 length,
@@ -25321,6 +25400,32 @@ var ClipBytesSchema = object({
 	durationMs: number().positive().optional()
 });
 /**
+* Where a clip's finished bytes can be TAKEN (D613) — the answer to
+* {@link videoclipsCapability.methods.offerClipBytes}.
+*
+* Everything {@link ClipBytesSchema} carries except the bytes themselves, plus
+* the one-shot ticket that leads to them. The metadata is answered BEFORE the
+* transfer on purpose: a consumer learns which twin it got, what to call the
+* file and how long the clip runs without having to read a byte, so a decision
+* it would make on that metadata (a wrong twin, an implausible duration) costs
+* no transfer at all.
+*/
+var ClipBytesOfferSchema = object({
+	/**
+	* One shot, seconds-long, loopback, on the PROVIDER's own host. Open it with
+	* `ctx.peerBytes.open(...)`, which refuses a ticket from another node by
+	* name rather than dialling a port that means something else here.
+	*/
+	ticket: PeerBytesTicketSchema,
+	contentType: string(),
+	/** Suggested filename, extension included. */
+	name: string(),
+	/** Which twin was actually served — see {@link ClipBytesSchema.served}. */
+	served: CamProfileSchema,
+	/** See {@link ClipBytesSchema.durationMs}. Absent when nothing measured it. */
+	durationMs: number().positive().optional()
+});
+/**
 * Where a clip's STREAM can be dialled (D597) — the answer to
 * {@link videoclipsCapability.methods.dialClipStream}.
 *
@@ -25396,6 +25501,105 @@ var ClipStreamDialSchema = object({
 	/** Why `servedAudio` is `none` although sound was asked for. */
 	audioReason: ClipStreamAudioReasonSchema.optional()
 });
+/**
+* The playback rates a clip can be DELIVERED at, ascending, always with `1`.
+*
+* These are the BROKER's: it re-paces frames it has already demuxed — the
+* `MonotonicClock` divides source elapsed time by the factor and the pacer
+* pushes that much faster — so the domain is the recorded one, {0} ∪ [0.25, 4],
+* and this is the discrete ladder drawn from it. `1.5` is in it because a
+* re-pacer has no reason to refuse it.
+*
+* `8` and `16` are deliberately NOT here. They are the CAMERA's own
+* `<playSpeed>` (Reolink cmd-5 replay), a different mechanism, still unwired
+* (D597, D600) — a rate change there costs a new dial and a new stream, and
+* the camera's 8x would need a resample the clip audio path has no decoder
+* for. Offering them today accepts a rate and delivers 1x, which is the whole
+* defect this list exists to end (D612). When `playSpeed` IS wired its rates
+* join THIS array — a second list elsewhere is the second authority D62
+* forbids.
+*
+* Every entry must survive the broker's `clampPlaybackRate` unchanged: a set
+* that offers what the clamp then moves is the same lie one step later.
+*/
+var CLIP_BROKER_PACED_RATES = [
+	.25,
+	.5,
+	1,
+	1.5,
+	2,
+	4
+];
+/**
+* The rates a REALTIME-BOUND stream can be delivered at.
+*
+* **Measured, and it is the whole reason this second ladder exists.** A
+* Hikvision RTSP replay is not a fast fetch: it delivers the recording at the
+* speed it was recorded. On 1436, 2026-09-23, one stream carried 176 access
+* units in 14 274 ms of wall clock at a measured 12.5 fps — 14.08 s of media
+* in 14.27 s, **1.01× realtime** — and a whole 18 s clip took 22.3 s to fetch
+* end to end. Reolink's cmd-5 transfer, which {@link CLIP_BROKER_PACED_RATES}
+* was written for, lands the same bytes at 49–62× and therefore has the entire
+* clip in hand within the first second.
+*
+* The broker's pacer consumes `rate` seconds of media per second of wall
+* clock while the socket supplies one. So at any rate above 1 the buffer
+* drains at `(rate − 1)×` and a stream that is only seconds old runs dry
+* almost at once — the viewer stops, the queue empties, and the provider's
+* own drain gate eventually reports `peer-stalled`. Nothing about that is a
+* bug to be fixed with a bigger buffer: there is no buffer, because the bytes
+* do not exist yet.
+*
+* So the honest answer is the DECLARATION (D612's own rule, applied to the
+* case it did not yet have): a rate this transport cannot deliver is never
+* offered. Below 1 is free — a slower pacer only lets the buffer grow.
+*
+* When a clip is served from a FILE the constraint is gone with the transport,
+* which is why `file` keeps the full ladder.
+*/
+var CLIP_REALTIME_SOURCE_RATES = [
+	.25,
+	.5,
+	1
+];
+/**
+* What a surface may DRAW for this provider's clips — the answer to
+* {@link videoclipsCapability.methods.getPlaybackOptions} (D612).
+*
+* The envelope is a PROVIDER fact, not a clip fact, and that is measured, not
+* assumed: the broker's `chooseClipPath` reads exactly two inputs — whether
+* `dialClipStream` and `readClipBytes` are wired — and both are constants of
+* the broker's own closure over the provider's methods. The `profile` it is
+* handed is explicitly not read. So every clip of a provider is served the
+* same way, and a per-clip channel carried a value that could not vary. The
+* per-clip `clipTransport` server message was removed for exactly that reason.
+*
+* Queried per camera, before a clip is picked, so a control is rendered or
+* DISABLED rather than offered and refused at play time (D62: a disabled
+* control reads as unavailable, one that undoes the gesture reads as broken).
+*/
+var ClipPlaybackOptionsSchema = object({
+	/**
+	* How this provider's clips reach the player. `stream` is the provider's
+	* forward-only fMP4 (D597); `file` is one bounded by-handle fetch of the
+	* whole clip, `stbl` indexed (D575).
+	*/
+	transport: _enum(["stream", "file"]),
+	/** `forward` = only ahead of the playhead. `free` = anywhere. */
+	seek: _enum(["forward", "free"]),
+	/** Frame-step BACKWARD is meaningful. Forward always is. */
+	stepBack: boolean(),
+	/** Whether the scrub gesture is served, as opposed to refused by name. */
+	scrub: boolean(),
+	/**
+	* The rates that can be delivered, ascending, always containing `1`. The
+	* viewer draws its picker from this and from nothing else — a constant it
+	* keeps instead is the second authority that produced the defect: `8` and
+	* `16` were offered, the broker clamped them to `4`, and no line anywhere
+	* said so. `0` is not a member: pause is the absence of a rate.
+	*/
+	rates: array(number().positive()).min(1).readonly()
+});
 var ClipSourceAvailabilitySchema = object({
 	state: _enum([
 		"ok",
@@ -25574,14 +25778,18 @@ var videoclipsCapability = {
 		*
 		* `getClipPlayback` is the right answer for a player: it hands back a URL
 		* on a plane the hub serves `access:'authenticated'`, which a browser and a
-		* viewer session satisfy. It is the wrong answer for another ADDON. There
-		* is no addon→addon byte transport in this framework — `AddonDataPlane`
-		* only lets an addon SERVE, on `127.0.0.1` behind a per-listener secret
-		* only the hub may present — so a recorder that wants a camera's clip
-		* cannot fetch that URL. This method is the one seam that exists for it,
-		* and it is deliberately the same shape (and the same bound) as
-		* `recordingExport.readExportBytes`, which exists for the mirror-image
-		* reason.
+		* viewer session satisfy. It is the wrong answer for another ADDON: the
+		* hub's proxy in front of that plane takes only a user credential, which
+		* an addon does not hold, so a recorder that wants a camera's clip cannot
+		* fetch that URL. This method is the shape that answer forced — the same
+		* one (and the same bound) as `recordingExport.readExportBytes`.
+		*
+		* **It is no longer the only seam.** Until D613 there was no addon→addon
+		* byte transport at all; there is now
+		* ({@link offerClipBytes}, over `ctx.peerBytes`), it holds nothing on
+		* either side, and it is what a clip EXPORT uses. This method remains for
+		* a consumer that genuinely wants the bytes in hand, and as the named
+		* fallback for a provider not yet redeployed.
 		*
 		* Routing needs no `provider` pin: the id is source-prefixed and
 		* self-contained, so `device-collection-dispatch.ts` rule 3 hands the call
@@ -25648,6 +25856,65 @@ var videoclipsCapability = {
 			auth: "protected"
 		}),
 		/**
+		* Where this clip's finished bytes can be TAKEN — the by-handle read a
+		* clip EXPORT pulls, over the addon→addon byte transport (D613).
+		*
+		* This is {@link readClipBytes} with the envelope removed. Same gates,
+		* same vocabulary, same completion rules, same `served` contract — the
+		* only difference is that the bytes travel over a one-shot loopback
+		* socket instead of inside a base64 field, so neither side holds the
+		* payload whole and the 50 MiB refusal on a long `high` twin stops
+		* existing. The bound that remains is
+		* {@link VIDEOCLIPS_MAX_OFFER_BYTES}, and it bounds the PRODUCER's own
+		* copy rather than the transport.
+		*
+		* **The ticket is loopback and same-host.** A provider on an agent mints a
+		* URL that means nothing on the hub, and `ctx.peerBytes.open` refuses it
+		* `cross-node` by name rather than dialling whatever else holds that port
+		* here. A consumer that can be on the other side of a node boundary from
+		* its provider must be able to read that refusal and say so; it must not
+		* treat it as "no bytes".
+		*
+		* **A ticket is a one-shot bearer credential with a seconds-long life.**
+		* Take it immediately, never persist it, never log its `url`. An untaken
+		* ticket costs the provider one map entry until its TTL, and outstanding
+		* tickets are bounded — which is also what makes a per-frame misuse of
+		* this method refuse by name rather than work slowly (D9/D18: this is a
+		* by-handle fetch of finished media, not a frame pipe).
+		*
+		* Optional on the provider for the same reason `readClipBytes` is: a
+		* source with no camera socket behind it has no bytes. A provider that
+		* predates this method answers `NOT_IMPLEMENTED`, and a consumer may fall
+		* back to `readClipBytes` — but it says so in the log, with the deploy
+		* hint, because that fallback re-imposes the 50 MiB refusal and an
+		* operator who sees `too-large-to-transfer` after this shipped is looking
+		* at a stale addon, not at a clip that cannot be exported.
+		*/
+		offerClipBytes: optionalMethod(object({
+			deviceId: number(),
+			clipId: string().min(1),
+			/** WHICH provider holds the bytes — see `readClipBytes.provider`. */
+			provider: string().min(1),
+			/** Which twin — `low | mid` → the sub file, `high` → the main twin. */
+			profile: CamProfileSchema.optional(),
+			/**
+			* The CALLER's byte bound, so an over-size clip is refused before the
+			* camera is touched rather than after. Capped by
+			* {@link VIDEOCLIPS_MAX_OFFER_BYTES} whatever is passed; absent means
+			* that ceiling.
+			*/
+			maxBytes: number().int().positive().optional(),
+			/**
+			* The operator's authorisation to wake a sleeping camera for this
+			* read. Absent — the default — means a sleeping standalone battery
+			* camera is REFUSED by name, before any session is opened.
+			*/
+			wake: ClipWakeSchema.optional()
+		}), ClipBytesOfferSchema, {
+			kind: "query",
+			auth: "protected"
+		}),
+		/**
 		* Where this clip's STREAM can be dialled (D597) — the forward-only
 		* fMP4 the provider writes from the first muxed byte, for the broker to
 		* play through the same WebRTC session as recorded footage, with the
@@ -25684,10 +25951,88 @@ var videoclipsCapability = {
 		}), ClipStreamDialSchema, {
 			kind: "query",
 			auth: "protected"
+		}),
+		/**
+		* What a surface may DRAW for this provider's clips: the rates it can be
+		* played at, whether scrub is served, how far a position may be moved,
+		* and whether a backward frame-step means anything (D612).
+		*
+		* **The only authority.** The per-clip `clipTransport` server message
+		* that used to carry the same answer was removed: the broker's transport
+		* choice reads nothing that varies per clip, so the clip level had no
+		* information the provider does not already have, and two channels that
+		* can disagree are worse than one (D62).
+		*
+		* Asked per camera and per provider, so it must stay CHEAP — it is a
+		* statement about wiring, answered from a constant, never a call to the
+		* camera. A provider answers with one of {@link CLIP_PLAYBACK_OPTIONS}
+		* and never composes an envelope of its own.
+		*
+		* Optional, and absence is load-bearing: a provider that has not answered
+		* has not restricted anything, and a viewer reads it as the freedom it
+		* always had. See D612 on the rollout order that absence implies.
+		*/
+		getPlaybackOptions: optionalMethod(object({
+			deviceId: number(),
+			/** WHICH provider to ask — the `addonId` a {@link ClipSourceSchema}
+			*  row carries. Required for the same reason `listClips` requires it:
+			*  a collection cap has no "the bound one" to resolve to (D554). */
+			provider: string().min(1)
+		}), ClipPlaybackOptionsSchema, {
+			kind: "query",
+			auth: "protected"
 		})
 	}
 };
 /**
+* NOTE ON PLACEMENT: this block lives AFTER the capability definition on
+* purpose. `scripts/lib/parse-cap.ts` finds a cap by the FIRST
+* `export const <X> = {` in the file, so an object literal declared above
+* `videoclipsCapability` is silently taken for the capability itself and
+* codegen emits a `DeviceProxy` entry that does not type-check. Found the
+* hard way, 2026-09-23.
+*/
+/**
+* The two envelopes, spelled ONCE.
+*
+* A provider answers with the entry for the transport its own wiring buys —
+* `stream` if it implements `dialClipStream`, `file` if it implements only
+* `readClipBytes` — and never composes one of its own. One table is what
+* makes "the provider may not promise what no clip can be given" structural
+* instead of a discipline: there is nothing else to promise.
+*/
+var CLIP_PLAYBACK_OPTIONS = {
+	stream: {
+		transport: "stream",
+		seek: "forward",
+		stepBack: false,
+		scrub: false,
+		rates: CLIP_BROKER_PACED_RATES
+	},
+	/**
+	* A `stream` whose SOURCE runs at realtime — a Hikvision RTSP replay.
+	*
+	* Same verbs as `stream`, a shorter rate ladder, and the difference is a
+	* measurement rather than a preference: see
+	* {@link CLIP_REALTIME_SOURCE_RATES}. A third entry rather than a parameter,
+	* because a provider must still be able to do nothing but NAME one of these.
+	*/
+	realtimeStream: {
+		transport: "stream",
+		seek: "forward",
+		stepBack: false,
+		scrub: false,
+		rates: CLIP_REALTIME_SOURCE_RATES
+	},
+	file: {
+		transport: "file",
+		seek: "free",
+		stepBack: true,
+		scrub: true,
+		rates: CLIP_BROKER_PACED_RATES
+	}
+};
+/**
 * Optional client-side hints sent at session creation to help the provider
 * pick the best native source. All fields optional — a viewer that knows
 * nothing still gets a sane default. (Relocated from the retired `webrtc`
@@ -46949,6 +47294,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.getPlaybackOptions": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.listClips": {
 		capName: "videoclips",
 		capScope: "device",
@@ -46961,6 +47312,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"videoclips.offerClipBytes": {
+		capName: "videoclips",
+		capScope: "device",
+		addonId: null,
+		access: "view"
+	},
 	"videoclips.readClipBytes": {
 		capName: "videoclips",
 		capScope: "device",
@@ -49007,6 +49364,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.getPlaybackOptions": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.listClips": [{
 		name: "deviceId",
 		form: "single",
@@ -49017,6 +49379,11 @@ Object.freeze({
 		form: "single",
 		optional: false
 	}],
+	"videoclips.offerClipBytes": [{
+		name: "deviceId",
+		form: "single",
+		optional: false
+	}],
 	"videoclips.readClipBytes": [{
 		name: "deviceId",
 		form: "single",
@@ -49680,24 +50047,73 @@ DEFAULT_NATIVE_LEASE_SETTINGS.sceneBudgetMb;
 DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
+/**
+* Per-device bounds for the STILLS, which are a different artifact entirely.
+*
+* A still is ~30 KB against a clip's 40 MB, and it is the thing an operator
+* scrolls past sixty of. It therefore outlives the media it was cut from: the
+* clip scratch holds ten segments and rolls, and a camera whose stills lived
+* in the same directory would lose the picture of every clip but the last ten.
+* Two thousand files and 64 MiB — the same pair the Reolink store uses, and
+* the byte bound still governs.
+*/
+var THUMB_MAX_FILES_PER_DEVICE = 2e3;
+var THUMB_MAX_BYTES_PER_DEVICE = 64 * 1024 * 1024;
 /** A clip key is a hex digest. Anything else is refused rather than joined. */
 var SAFE_KEY = /^[A-Za-z0-9_-]{1,128}$/;
-var KIND = "clip-media";
-var EXTENSION = ".mp4";
+var CLIP_THUMB_KIND = "clip-thumbs";
+var CLIP_THUMB_EXTENSION = ".jpg";
 var ClipArtifactStore = class {
 	options;
 	maxFiles;
 	maxBytes;
+	kind;
+	extension;
 	constructor(options) {
 		this.options = options;
 		this.maxFiles = options.maxFilesPerDevice ?? 10;
 		this.maxBytes = options.maxBytesPerDevice ?? 209715200;
+		this.kind = options.kind ?? "clip-media";
+		this.extension = options.extension ?? ".mp4";
 	}
 	dirFor(deviceId) {
-		return join(this.options.root, KIND, String(deviceId));
+		return join(this.options.root, this.kind, String(deviceId));
 	}
 	pathFor(deviceId, clipKey) {
-		return join(this.dirFor(deviceId), `${clipKey}${EXTENSION}`);
+		return join(this.dirFor(deviceId), `${clipKey}${this.extension}`);
+	}
+	/**
+	* Is there really a file here?
+	*
+	* THE VOUCH. A provider says `thumbnail: <url>` only when this answered
+	* true, because that field means "a still exists" and a URL that then
+	* answers 204 is a request every tile makes and every tile loses (D549 5).
+	*/
+	async has(deviceId, clipKey) {
+		return await this.pathIfPresent(deviceId, clipKey) !== null;
+	}
+	/** The bytes, or `null` — never a zero-length file dressed as a still. */
+	async read(deviceId, clipKey) {
+		const path = await this.pathIfPresent(deviceId, clipKey);
+		if (path === null) return null;
+		try {
+			return await readFile(path);
+		} catch {
+			return null;
+		}
+	}
+	/**
+	* Write bytes under a key, immutably, and enforce the bounds.
+	*
+	* Temp-then-rename, so a crash never leaves a truncated file under the real
+	* key — and a key already present WINS, so two racing mints cost one file.
+	*/
+	async put(deviceId, clipKey, bytes) {
+		const existing = await this.pathIfPresent(deviceId, clipKey);
+		if (existing !== null) return existing;
+		const temp = await this.reserve(deviceId, clipKey);
+		await writeFile(temp, bytes);
+		return await this.publish(deviceId, clipKey, temp);
 	}
 	/** A scratch path to mux INTO, with its directory made. */
 	async reserve(deviceId, clipKey) {
@@ -49748,7 +50164,7 @@ var ClipArtifactStore = class {
 		}
 		const out = [];
 		for (const name of names) {
-			if (!name.endsWith(EXTENSION)) continue;
+			if (!name.endsWith(this.extension)) continue;
 			const path = join(this.dirFor(deviceId), name);
 			try {
 				const info = await stat(path);
@@ -50097,6 +50513,27 @@ async function listClipRows(client, input) {
 	};
 }
 //#endregion
+//#region src/clips/clip-still-refusal.ts
+/** "You are in the queue." */
+function deferStill(code, reason, retryAfterMs) {
+	return {
+		ok: false,
+		code,
+		disposition: "deferred",
+		reason,
+		retryAfterMs
+	};
+}
+/** "This will not happen." */
+function refuseStill(code, reason) {
+	return {
+		ok: false,
+		code,
+		disposition: "final",
+		reason
+	};
+}
+//#endregion
 //#region src/clips/clip-data-plane.ts
 /**
 * The addon's two clip routes: the finished FILE, and the STREAM.
@@ -50130,8 +50567,11 @@ async function listClipRows(client, input) {
 /** URL namespaces under `/addon/provider-hikvision/`. */
 var CLIP_MEDIA_PREFIX = "clip";
 var CLIP_STREAM_PREFIX = "clip-stream";
+var CLIP_THUMB_PREFIX = "clip-thumb";
 /** A clip key is a hex digest; nothing else may reach the filesystem. */
 var MEDIA_PATH = /^\/(\d+)\/([A-Za-z0-9_-]{1,128})\.mp4$/;
+/** The still route carries no extension: the content type says what it is. */
+var THUMB_PATH = /^\/(\d+)\/([A-Za-z0-9_-]{1,128})$/;
 function pathnameOf(req) {
 	const raw = req.url ?? "/";
 	const query = raw.indexOf("?");
@@ -50239,6 +50679,87 @@ function createClipPlaybackHandler(deps) {
 		}).pipe(res);
 	};
 }
+/**
+* `/addon/provider-hikvision/clip-thumb/<deviceId>/<clipKey>`.
+*
+* 200 with the JPEG, or 204 with a reason a tile can read. Never a 404 and
+* never a placeholder: a still that does not exist is an ABSENCE, and it is
+* reported as one (D315).
+*/
+function createClipThumbHandler(deps) {
+	return async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405, { allow: "GET, HEAD" });
+			res.end();
+			return;
+		}
+		const match = THUMB_PATH.exec(pathnameOf(req));
+		if (match === null) {
+			res.writeHead(400);
+			res.end();
+			return;
+		}
+		const deviceId = Number(match[1]);
+		const clipKey = match[2] ?? "";
+		const cached = await deps.readCached(deviceId, clipKey);
+		if (cached !== null) {
+			writeJpeg(res, cached, req.method === "HEAD");
+			return;
+		}
+		let minted;
+		try {
+			minted = await deps.mint(deviceId, clipKey);
+		} catch (err) {
+			minted = refuseStill("camera-refused", err instanceof Error ? err.message : String(err));
+		}
+		if (!minted.ok) {
+			writeStillRefusal(res, minted, deviceId, deps.logger, clipKey);
+			return;
+		}
+		writeJpeg(res, minted.bytes, req.method === "HEAD");
+	};
+}
+/**
+* The 204, with everything the tile needs to decide what to draw next.
+*
+* A FINAL refusal is work that was dropped, so it is warned, per camera. A
+* DEFERRED one dropped nothing — the still is queued behind the camera's one
+* replay slot — and warning it would put a line on the log per tile of a page.
+*/
+function writeStillRefusal(res, refusal, deviceId, logger, clipKey) {
+	const line = "videoclips: thumbnail not minted";
+	const extras = {
+		tags: { deviceId },
+		meta: {
+			clipKey,
+			code: refusal.code,
+			disposition: refusal.disposition,
+			reason: refusal.reason
+		}
+	};
+	if (refusal.disposition === "final") logger.warn(line, extras);
+	else logger.debug(line, extras);
+	const retryAfterMs = refusal.disposition === "deferred" ? refusal.retryAfterMs : void 0;
+	res.writeHead(204, {
+		[CLIP_STILL_REASON_HEADER]: clipReasonHeaderValue(refusal.reason),
+		[CLIP_STILL_REASON_CODE_HEADER]: refusal.code,
+		[CLIP_STILL_DISPOSITION_HEADER]: refusal.disposition,
+		...retryAfterMs === void 0 ? {} : { "retry-after": String(Math.max(1, Math.ceil(retryAfterMs / 1e3))) }
+	});
+	res.end();
+}
+function writeJpeg(res, bytes, headOnly) {
+	res.writeHead(200, {
+		"content-type": "image/jpeg",
+		"content-length": String(bytes.byteLength),
+		"cache-control": "private, max-age=31536000, immutable"
+	});
+	if (headOnly) {
+		res.end();
+		return;
+	}
+	res.end(bytes);
+}
 /** The data plane's own form: the clip is named on the path. */
 var resolveClipStreamPathTarget = (req) => {
 	const match = MEDIA_PATH.exec(pathnameOf(req));
@@ -50265,11 +50786,12 @@ var STREAM_HEADERS = {
 	"cache-control": "no-store",
 	[CLIP_STREAM_TRANSPORT_HEADER]: "forward-only"
 };
-/** `404` = nothing here to serve; `502` = the camera. */
+/** `404` = nothing here to serve; `502` = the camera; `503` = its one slot. */
 function streamRefusalStatus(code) {
 	switch (code) {
 		case "unknown-device":
 		case "no-catalog-row": return 404;
+		case "replay-busy": return 503;
 		case "camera-refused":
 		case "fetch-failed": return 502;
 	}
@@ -50290,7 +50812,7 @@ function createClipStreamHandler(deps) {
 				status: resolved.status
 			} });
 			res.writeHead(resolved.status, {
-				[CLIP_STILL_REASON_HEADER]: resolved.detail.slice(0, 500),
+				[CLIP_STILL_REASON_HEADER]: clipReasonHeaderValue(resolved.detail),
 				[CLIP_STILL_REASON_CODE_HEADER]: resolved.code
 			});
 			res.end();
@@ -50363,7 +50885,7 @@ function createClipStreamHandler(deps) {
 			}
 		});
 		res.writeHead(streamRefusalStatus(outcome.code), {
-			[CLIP_STILL_REASON_HEADER]: outcome.detail.slice(0, 500),
+			[CLIP_STILL_REASON_HEADER]: clipReasonHeaderValue(outcome.detail),
 			[CLIP_STILL_REASON_CODE_HEADER]: outcome.code
 		});
 		res.end();
@@ -50372,24 +50894,36 @@ function createClipStreamHandler(deps) {
 //#endregion
 //#region src/clips/clip-replay-rate.ts
 /**
-* ## Why nothing is SNAPPED to a whole number
-*
-* A first version rounded an estimate that came within 4 % of an integer, on
-* the theory that a variable rate lands near one. The fixture replay measures
-* **12.5 fps exactly** — 7 200 ticks of a 90 kHz clock between every access
-* unit — and 12.5 is within 4 % of 13, so the rule turned an exact measurement
-* into a wrong one. The clock is integral and the arithmetic is exact; there
-* is nothing here a heuristic can improve, and a number the camera's own
-* timestamps produced is the one the file should carry.
-*/
-/**
-* The rate the timestamps say, or `null`.
-*
-* Fewer than two units, a span of zero, or a span that goes BACKWARD all
-* answer `unmeasured`. The last one is not hypothetical: a u32 RTP timestamp
-* wraps, and a wrapped span is a negative number that would otherwise mux the
-* clip at a nonsense rate rather than refusing.
-*/
+* Do these timestamps ALREADY say the rate, so that waiting for more cannot
+* change the answer?
+*
+* This is arithmetic, not a heuristic. {@link estimateReplayFps} computes
+* `(n - 1) × clockRate ÷ (last − first)`. If every consecutive span equals `d`
+* then `last − first = (n − 1) × d` and the estimate is `clockRate ÷ d` for
+* EVERY n — the sixteenth unit produces the same number as the fourth. So a
+* probe that has seen {@link REPLAY_RATE_EXACT_SPANS} identical integer spans
+* is not guessing when it stops; it is declining to wait 1.0 s of a camera's
+* own realtime replay for a number it already holds.
+*
+* **Why this matters more here than anywhere else.** A Hikvision replay
+* delivers at 1× (measured 2026-09-23 on 1436: 176 access units in 14.27 s of
+* wall clock at 12.5 fps, 1.01× realtime). Every access unit the probe holds
+* back is therefore 80 ms the operator waits before the first frame, and the
+* full sixteen measured 1301 ms of a 4316 ms time-to-first-frame. The spans on
+* that camera are 7200 ticks of a 90 kHz clock, every one of them.
+*
+* Integer equality, never a tolerance: a variable-rate replay differs by at
+* least one tick and falls through to the full window, which is the behaviour
+* that shipped.
+*/
+function replayFpsIsExact(timestamps) {
+	if (timestamps.length < 4) return false;
+	const first = timestamps[0] ?? 0;
+	const span = (timestamps[1] ?? 0) - first;
+	if (span <= 0) return false;
+	for (let i = 2; i < timestamps.length; i += 1) if ((timestamps[i] ?? 0) - (timestamps[i - 1] ?? 0) !== span) return false;
+	return true;
+}
 function estimateReplayFps(timestamps, clockRate) {
 	if (timestamps.length < 2 || clockRate <= 0) return {
 		fps: null,
@@ -50426,6 +50960,44 @@ var CLIP_STREAM_OPUS_RATE_HZ = 48e3;
 /** The PCMU RTP clock, and the rate the archive already is. */
 var CLIP_STREAM_PCMU_RATE_HZ = 8e3;
 /**
+* How much of an input ffmpeg may READ before it will write a header.
+*
+* ffmpeg probes every input to discover what is in it. Both defaults are
+* enormous for this use — `probesize` 5 MB, `analyzeduration` 5 s — and both
+* are paid in the operator's wait, because a Hikvision replay arrives at 1×
+* (measured 1.01× on 1436, 2026-09-23) so "5 MB of input" is seconds of wall
+* clock, not microseconds of buffer.
+*
+* **Nothing here is being discovered.** The demuxer is named (`-f hevc` /
+* `-f h264`, from the SDP's own `a=rtpmap`), the frame rate is named (`-r`,
+* measured from the replay's RTP clock and refused when it cannot be), and the
+* µ-law input is named down to its sample rate and channel count. A probe can
+* only re-derive what the caller already stated.
+*
+* Measured end to end against the real 1436 clip (18 s, 4K HEVC, 12.5 fps,
+* GOP 50): with the defaults the init segment reached the peer at 3889 ms and
+* the first media fragment at 3891 ms; with these two flags, 171 ms and
+* 2269 ms. 32 KiB is two orders of magnitude over the parameter sets the hevc
+* demuxer needs and still one one-hundred-and-fiftieth of the default.
+*/
+var CLIP_MUX_PROBE_BYTES = 32768;
+/**
+* How long a fragment may run before it is CLOSED, keyframe or not.
+*
+* `frag_keyframe` alone closes a fragment only at the next keyframe, so the
+* first fragment a peer can see spans a whole GOP. On 1436 the GOP is 50
+* frames at 12.5 fps — 4 s of media, and at 1× arrival that is 4 s of the
+* operator's wait for a first picture that was already decodable.
+*
+* Half a second, so a fragment closes on the frag_duration long before it
+* closes on a keyframe. Measured on the same clip: the first media fragment
+* moved from 2269 ms to 219 ms, and the whole 18 s output grew by 4 044 bytes
+* (0.04 %) — the cost of a `moof` every half second.
+*
+* Only the STREAM form takes it. The file form is not fragmented.
+*/
+var CLIP_STREAM_FRAG_DURATION_US = 5e5;
+/**
 * MEASURED, not chosen: ffmpeg's MP4 muxer refuses `pcm_mulaw` and its MOV
 * muxer takes it. The boxes a consumer walks are the same either way.
 */
@@ -50458,11 +51030,19 @@ function commonArgs(input) {
 		"error",
 		"-nostdin",
 		...input.fps !== null && Number.isFinite(input.fps) && input.fps > 0 ? ["-r", String(input.fps)] : [],
+		"-analyzeduration",
+		"0",
+		"-probesize",
+		String(CLIP_MUX_PROBE_BYTES),
 		"-f",
 		demuxer,
 		"-i",
 		"pipe:0",
 		...input.audio !== null ? [
+			"-analyzeduration",
+			"0",
+			"-probesize",
+			String(CLIP_MUX_PROBE_BYTES),
 			"-f",
 			"mulaw",
 			"-ar",
@@ -50489,6 +51069,10 @@ function buildClipStreamMuxArgs(input) {
 		...commonArgs(input),
 		"-movflags",
 		CLIP_STREAM_MOVFLAGS,
+		"-frag_duration",
+		String(CLIP_STREAM_FRAG_DURATION_US),
+		"-flush_packets",
+		"1",
 		"-f",
 		clipStreamContainerFor(input.audio),
 		"pipe:1"
@@ -51108,6 +51692,25 @@ function encodeRtspRequest(request) {
 	return Buffer.from(`${lines.join("\r\n")}\r\n\r\n`, "latin1");
 }
 /**
+* How long the socket may take to put a queued `TEARDOWN` on the wire.
+*
+* **This is a bound on OUR socket, not a claim about the camera.** A
+* `TEARDOWN` is two hundred bytes on a LAN; two seconds is three orders of
+* magnitude over that, and it only ever elapses for a peer that is not reading
+* at all — which is a socket we want destroyed anyway.
+*
+* It exists because `socket.destroy()` DISCARDS whatever `write()` queued.
+* The old `close()` wrote `TEARDOWN` and destroyed the socket in the next
+* statement, and the ordinary end of a segment — a quiet socket, which is how
+* every complete Hikvision replay ends — never wrote one at all. This firmware
+* serves ONE playback session and frees it on `TEARDOWN` or on its own 60 s
+* timeout, so a fetch that skipped the `TEARDOWN` left the next clip an
+* operator tapped to meet `SETUP … 500` for up to a minute. Measured on 1436,
+* 2026-09-23 09:25:07: a stream cut at 09:25:00 and the replay seven seconds
+* later was refused 500 while `ContentMgmt/search` kept answering.
+*/
+var RTSP_TEARDOWN_FLUSH_MS = 2e3;
+/**
 * Open a replay and start delivering.
 *
 * Rejects when the session could not be OPENED — the handshake is where a
@@ -51133,6 +51736,12 @@ async function openRtspReplay(target, handlers, deps) {
 	const ended = new Promise((resolve) => {
 		endResolve = resolve;
 	});
+	const teardownFlushMs = deps.teardownFlushMs ?? 2e3;
+	/** Resolves when this provider no longer holds the camera's replay slot. */
+	let slotResolve = null;
+	const slotFreed = new Promise((resolve) => {
+		slotResolve = resolve;
+	});
 	let idleTimer = null;
 	let handshakeTimer = null;
 	let videoChannel = -1;
@@ -51150,6 +51759,36 @@ async function openRtspReplay(target, handlers, deps) {
 		if (ticks <= 0) return null;
 		return Math.round(ticks / (videoTrack?.clockRate ?? 9e4) * 1e3);
 	};
+	/**
+	* Give the socket back, and say whether the camera's slot went with it.
+	*
+	* `flush` is true exactly when a `TEARDOWN` was queued: the socket is then
+	* `end()`ed so the kernel puts it on the wire, and only destroyed if it has
+	* not closed inside {@link RTSP_TEARDOWN_FLUSH_MS}. `destroy()` on a socket
+	* with a queued write throws that write away, which is how the slot came to
+	* be held past the end of a fetch nobody thought had failed.
+	*/
+	const releaseSocket = (flush) => {
+		const live = socket;
+		socket = null;
+		if (live === null) {
+			slotResolve?.();
+			slotResolve = null;
+			return;
+		}
+		live.once("close", () => {
+			slotResolve?.();
+			slotResolve = null;
+		});
+		if (!flush) {
+			live.destroy();
+			return;
+		}
+		const timer = setTimeout(() => live.destroy(), teardownFlushMs);
+		timer.unref?.();
+		live.once("close", () => clearTimeout(timer));
+		live.end();
+	};
 	const finish = (end) => {
 		if (settled) return;
 		settled = true;
@@ -51162,6 +51801,14 @@ async function openRtspReplay(target, handlers, deps) {
 			videoUnits += 1;
 			handlers.onVideo(tail);
 		}
+		let teardown = "no-session";
+		if (socket === null || socket.destroyed) teardown = "no-socket";
+		else if (rtspSession !== null) try {
+			write("TEARDOWN", sessionUrl, {});
+			teardown = "sent";
+		} catch {
+			teardown = "no-socket";
+		}
 		deps.logger.info("videoclips: a replay session ended", {
 			tags,
 			meta: {
@@ -51173,11 +51820,11 @@ async function openRtspReplay(target, handlers, deps) {
 				...end.kind === "complete" ? { deliveredMs: end.deliveredMs } : {},
 				videoUnits,
 				audioPackets,
-				droppedPayloads: depacketizer?.dropped ?? 0
+				droppedPayloads: depacketizer?.dropped ?? 0,
+				teardown
 			}
 		});
-		socket?.destroy();
-		socket = null;
+		releaseSocket(teardown === "sent");
 		endResolve?.(end);
 	};
 	/**
@@ -51383,12 +52030,9 @@ async function openRtspReplay(target, handlers, deps) {
 		ended,
 		video,
 		hasAudio: audio !== void 0,
-		close: () => {
-			if (settled) return;
-			try {
-				write("TEARDOWN", sessionUrl, {});
-			} catch {}
+		close: async () => {
 			finish({ kind: "closed" });
+			await slotFreed;
 		}
 	};
 }
@@ -51468,7 +52112,26 @@ async function prepareClipFile(input, deps) {
 			detail: err instanceof Error ? err.message : String(err)
 		};
 	}
+	const abort = () => void session.close();
+	deps.signal?.addEventListener("abort", abort, { once: true });
 	const end = await session.ended;
+	deps.signal?.removeEventListener("abort", abort);
+	await session.close();
+	if (deps.signal?.aborted === true) {
+		deps.logger.debug("videoclips: a clip fetch gave the slot back", {
+			tags,
+			meta: {
+				...meta,
+				branch: "preempted",
+				accessUnits: units.length
+			}
+		});
+		return {
+			kind: "refused",
+			code: "fetch-failed",
+			detail: "preempted: the camera’s one replay slot was wanted by a stream"
+		};
+	}
 	if (end.kind === "failed") return {
 		kind: "refused",
 		code: "camera-refused",
@@ -51573,6 +52236,201 @@ async function prepareClipFile(input, deps) {
 		durationMs: durationMs > 0 ? durationMs : null
 	};
 }
+//#endregion
+//#region src/clips/replay-lane.ts
+/**
+* How long an ask may wait for a slot that is being released.
+*
+* {@link RTSP_TEARDOWN_FLUSH_MS} plus a second of margin: a holder that is
+* shutting down frees the slot inside its own flush bound, and anything longer
+* than that is a holder that is still playing.
+*/
+var REPLAY_LANE_WAIT_MS = RTSP_TEARDOWN_FLUSH_MS + 1e3;
+/**
+* Which purposes are SPECULATIVE — work nobody is waiting on.
+*
+* A still is minted for a tile that is not on screen yet. A stream and a file
+* are an operator who has already tapped. When the two want the same camera,
+* the operator wins: the speculative holder is asked to give the slot back
+* (`yield`) and the ask waits for it, instead of being refused for want of
+* work that could have been done a minute later.
+*
+* Without this, opening a list of clips would start a realtime fetch per tile
+* and every playback tap during it would meet `replay-busy` — which is a
+* regression traded for a thumbnail, and not a trade anyone asked for.
+*/
+var SPECULATIVE = new Set(["still"]);
+function createReplayLane(deps) {
+	const now = deps.now ?? (() => Date.now());
+	const waitMs = deps.waitMs ?? REPLAY_LANE_WAIT_MS;
+	const holding = /* @__PURE__ */ new Map();
+	const take = (deviceId, purpose, yieldNow) => {
+		const entry = {
+			purpose,
+			sinceMs: now(),
+			waiters: [],
+			yieldNow,
+			yielded: false
+		};
+		holding.set(deviceId, entry);
+		let released = false;
+		return {
+			kind: "held",
+			release: () => {
+				if (released) return;
+				released = true;
+				if (holding.get(deviceId) !== entry) return;
+				holding.delete(deviceId);
+				entry.waiters.shift()?.();
+			}
+		};
+	};
+	return {
+		held: (deviceId) => holding.has(deviceId),
+		acquire: async (deviceId, purpose, yieldNow) => {
+			const askedAt = now();
+			const current = holding.get(deviceId);
+			if (current === void 0) return take(deviceId, purpose, yieldNow ?? null);
+			if (!SPECULATIVE.has(purpose) && SPECULATIVE.has(current.purpose) && current.yieldNow !== null && !current.yielded) {
+				current.yielded = true;
+				deps.logger.debug("videoclips: asking a speculative replay to give the slot back", {
+					tags: { deviceId },
+					meta: {
+						branch: "replay-yield",
+						asked: purpose,
+						holder: current.purpose
+					}
+				});
+				current.yieldNow();
+			}
+			await new Promise((resolve) => {
+				let timer = null;
+				const wake = () => {
+					if (timer !== null) clearTimeout(timer);
+					timer = null;
+					resolve();
+				};
+				timer = setTimeout(() => {
+					timer = null;
+					const index = current.waiters.indexOf(wake);
+					if (index !== -1) current.waiters.splice(index, 1);
+					resolve();
+				}, waitMs);
+				current.waiters.push(wake);
+			});
+			const after = holding.get(deviceId);
+			if (after === void 0) return take(deviceId, purpose, yieldNow ?? null);
+			const heldForMs = now() - after.sinceMs;
+			const waitedMs = now() - askedAt;
+			const detail = `replay-busy: this camera serves one playback session at a time and its ${after.purpose} has held it for ${String(heldForMs)} ms — nothing about this clip, and nothing a retry against the camera would change`;
+			deps.logger.warn("videoclips: a replay was refused — the camera’s slot is held", {
+				tags: { deviceId },
+				meta: {
+					branch: "replay-busy",
+					asked: purpose,
+					holder: after.purpose,
+					heldForMs,
+					waitedMs
+				}
+			});
+			return {
+				kind: "busy",
+				holder: after.purpose,
+				heldForMs,
+				waitedMs,
+				detail
+			};
+		}
+	};
+}
+/** Where inside a clip the still is cut, in seconds. Exported to be proved. */
+function clipStillSeekSeconds(durationMs) {
+	return Math.max(0, durationMs / 2e3);
+}
+/** What ffmpeg is told. Pure, so the arguments can be proved without a spawn. */
+function buildClipStillArgs(input) {
+	return [
+		"-hide_banner",
+		"-loglevel",
+		"error",
+		"-nostdin",
+		"-ss",
+		clipStillSeekSeconds(input.durationMs).toFixed(3),
+		"-i",
+		input.path,
+		"-frames:v",
+		"1",
+		"-vf",
+		`scale=${String(640)}:-2:flags=bicubic`,
+		"-q:v",
+		String(4),
+		"-f",
+		"mjpeg",
+		"pipe:1"
+	];
+}
+/**
+* Cut one still. Never throws: every dead end is a named refusal.
+*/
+async function cutClipStill(input, deps) {
+	const args = buildClipStillArgs(input);
+	let child;
+	try {
+		child = deps.spawnStill?.([...args]) ?? spawn(deps.ffmpegBinaryPath ?? "ffmpeg", [...args], { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+	} catch (err) {
+		return {
+			kind: "refused",
+			code: "decode-failed",
+			detail: `ffmpeg could not be spawned: ${err instanceof Error ? err.message : String(err)}`
+		};
+	}
+	const chunks = [];
+	let stderr = "";
+	child.stdout?.on("data", (chunk) => chunks.push(chunk));
+	child.stderr?.on("data", (chunk) => {
+		stderr += chunk.toString("utf8");
+	});
+	const timeoutMs = deps.timeoutMs ?? 1e4;
+	const exit = await new Promise((resolve) => {
+		const timer = setTimeout(() => resolve("timeout"), timeoutMs);
+		timer.unref?.();
+		child.once("error", () => {
+			clearTimeout(timer);
+			resolve(null);
+		});
+		child.once("close", (code) => {
+			clearTimeout(timer);
+			resolve(code);
+		});
+	});
+	if (exit === "timeout") {
+		child.kill("SIGKILL");
+		return {
+			kind: "refused",
+			code: "decode-failed",
+			detail: `ffmpeg did not answer inside ${String(timeoutMs)} ms`
+		};
+	}
+	const bytes = Buffer.concat(chunks);
+	if (exit !== 0) return {
+		kind: "refused",
+		code: "decode-failed",
+		detail: `ffmpeg exited ${String(exit)}: ${stderr.trim().slice(0, 300)}`
+	};
+	if (bytes.byteLength === 0) return {
+		kind: "refused",
+		code: "no-keyframe",
+		detail: `ffmpeg read the clip and produced no frame at ${clipStillSeekSeconds(input.durationMs).toFixed(3)} s`
+	};
+	return {
+		kind: "ok",
+		bytes
+	};
+}
 function pathToken(req) {
 	const raw = req.url ?? "/";
 	const query = raw.indexOf("?");
@@ -51791,6 +52649,8 @@ var ClipStreamRun = class {
 	audioGate = null;
 	peerGate = null;
 	answered = false;
+	/** Settles when this run no longer holds the camera's one replay slot. */
+	slotFreed = Promise.resolve();
 	settle = null;
 	bytesOut = 0;
 	accessUnits = 0;
@@ -51823,6 +52683,7 @@ var ClipStreamRun = class {
 			});
 		});
 		this.disposeGates();
+		await this.slotFreed;
 		return outcome;
 	}
 	async start() {
@@ -51869,8 +52730,9 @@ var ClipStreamRun = class {
 			return;
 		}
 		this.heldVideo.push(unit);
-		if (this.heldVideo.length < this.deps.probeTarget) return;
-		const rate = estimateReplayFps(this.heldVideo.map((held) => held.timestamp), this.replay?.video.clockRate ?? 9e4);
+		const timestamps = this.heldVideo.map((held) => held.timestamp);
+		if (this.heldVideo.length < this.deps.probeTarget && !replayFpsIsExact(timestamps)) return;
+		const rate = estimateReplayFps(timestamps, this.replay?.video.clockRate ?? 9e4);
 		if (rate.fps === null) {
 			if (this.heldVideo.length < this.deps.probeMax) return;
 			this.refuse("fetch-failed", `rate-unmeasured: ${String(this.heldVideo.length)} access units and the replay's own timestamps still cannot say this clip's frame rate`);
@@ -52081,7 +52943,7 @@ var ClipStreamRun = class {
 	answer(outcome) {
 		this.answered = true;
 		this.disposeGates();
-		this.replay?.close();
+		this.slotFreed = this.replay?.close() ?? Promise.resolve();
 		if (outcome.kind !== "served") this.mux?.kill("SIGKILL");
 		this.settle?.(outcome);
 		this.settle = null;
@@ -52606,7 +53468,11 @@ function createHikvisionVideoclipsProvider(deps) {
 	const remember = (deviceId, rows) => {
 		for (const row of rows) rowsByKey.set(`${String(deviceId)}|${row.clipKey}`, row);
 	};
-	const toClip = (row, catalogAsOf) => ({
+	/**
+	* ASYNC, because the still is vouched by a `stat` and a vouch that guessed
+	* would be worse than no still at all.
+	*/
+	const toClip = async (deviceId, row, catalogAsOf) => ({
 		id: mintClipId({
 			source: CLIP_SOURCE_ONBOARD,
 			trackId: row.trackId,
@@ -52619,7 +53485,7 @@ function createHikvisionVideoclipsProvider(deps) {
 			endMs: row.endMs
 		},
 		...row.recordTypes.length > 0 ? { nativeTypes: [...row.recordTypes] } : {},
-		thumbnailUnavailable: { reason: "unsupported" },
+		...await deps.hasVouchedStill(deviceId, row.clipKey) ? { thumbnail: deps.stillUrl(deviceId, row.clipKey) } : { thumbnailMint: deps.stillUrl(deviceId, row.clipKey) },
 		catalogAsOf,
 		streams: { main: {
 			id: mintClipId({
@@ -52713,7 +53579,7 @@ function createHikvisionVideoclipsProvider(deps) {
 					trackId: device.trackId
 				}
 			});
-			return capped.map((row) => toClip(row, catalogAsOf));
+			return await Promise.all(capped.map(async (row) => await toClip(device.deviceId, row, catalogAsOf)));
 		},
 		/**
 		* The player's URL — a finished MP4 on this addon's own media plane, with
@@ -52804,6 +53670,102 @@ function createHikvisionVideoclipsProvider(deps) {
 			};
 		},
 		/**
+		* The same clip, over the addon→addon byte transport (D613).
+		*
+		* ONE difference from {@link readClipBytes}: the bytes leave over a
+		* one-shot loopback socket instead of inside a base64 field, so neither
+		* this process nor the caller holds the payload. On this vendor nothing is
+		* held at all — the fetch path already lands the clip in a scratch FILE
+		* and the offer streams that file.
+		*
+		* The cheap questions come first and none of them touches the camera: the
+		* id, the row, and the SIZE the catalog already declared — the rule bulk
+		* work over stored media already follows (D54). The bound is
+		* {@link VIDEOCLIPS_MAX_OFFER_BYTES} and it is a statement about what a
+		* PRODUCER holds, which here is nothing; it is applied anyway so the
+		* ceiling is one number across vendors rather than a per-vendor guess.
+		*/
+		offerClipBytes: async ({ deviceId, clipId, profile, maxBytes }) => {
+			const tags = { deviceId };
+			const refuse = (code, detail, meta) => {
+				deps.logger.warn("videoclips: refusing a clip byte offer", {
+					tags,
+					meta: {
+						clipId,
+						branch: code,
+						...meta
+					}
+				});
+				throw new Error(clipExportFailure(code, detail));
+			};
+			const device = await deps.resolveDevice(deviceId);
+			if (device === null) return refuse("catalog-miss", `device ${String(deviceId)} is not a Hikvision camera`, {});
+			const parsed = parseClipId(clipId);
+			if (parsed === null) return refuse("catalog-miss", `clip id "${clipId}" was not minted by the Hikvision provider`, {});
+			const clipKey = clipKeyFor(parsed.trackId, parsed.fileName);
+			const row = rowsByKey.get(`${String(deviceId)}|${clipKey}`);
+			if (row === void 0) return refuse("catalog-miss", `clip "${clipId}" is not in this node's catalog for device ${String(deviceId)} — list the window that holds it first`, { clipKey });
+			const quality = chooseClipQuality(profile);
+			if (quality.upgraded) noteUpgrade(deviceId, clipId, profile);
+			const bound = Math.min(maxBytes ?? 524288e3, VIDEOCLIPS_MAX_OFFER_BYTES);
+			if (row.sizeBytes !== void 0 && row.sizeBytes > bound) return refuse("too-large-to-transfer", `the camera lists clip "${clipId}" as ${String(row.sizeBytes)} bytes, over the ${String(bound)}-byte bound for one transfer`, {
+				clipKey,
+				listedBytes: row.sizeBytes,
+				bound
+			});
+			const outcome = await deps.prepareOffer({
+				device,
+				row,
+				maxBytes: bound
+			});
+			if (outcome.kind === "refused") throw new Error(clipExportFailure(outcome.code, outcome.detail));
+			deps.logger.info("videoclips: offered a Hikvision clip by handle", {
+				tags,
+				meta: {
+					clipId,
+					clipKey,
+					served: quality.served,
+					asked: profile ?? null,
+					bytes: outcome.bytes,
+					durationMs: outcome.durationMs,
+					expiresInMs: outcome.ticket.expiresAtMs - deps.now()
+				}
+			});
+			return {
+				ticket: outcome.ticket,
+				contentType: "video/mp4",
+				name: clipFileLabel(row),
+				served: quality.served,
+				...outcome.durationMs !== null ? { durationMs: outcome.durationMs } : {}
+			};
+		},
+		/**
+		* What a surface may DRAW for this camera's clips (D612).
+		*
+		* A CONSTANT, and it has to be: this method is asked per camera, and the
+		* answer is a fact about which accessors this provider wires, not about
+		* the camera. Every clip here reaches the player over
+		* {@link dialClipStream}'s forward-only stream, so every clip gets the
+		* `stream` envelope — measured, not assumed: the broker's `chooseClipPath`
+		* reads only whether the dial and the file read are wired, and never the
+		* clip or the profile.
+		*
+		* The rates are the broker's re-pacing ladder CAPPED AT REALTIME, because
+		* this camera's replay is not a fetch: it delivers the recording at the
+		* speed it was recorded (1.01× measured on 1436, 2026-09-23 — 176 access
+		* units in 14.27 s at 12.5 fps). The pacer consumes `rate` seconds of
+		* media per second while the socket supplies one, so anything above 1
+		* empties a buffer that never had the rest of the clip in it. Below 1 is
+		* free. See `CLIP_REALTIME_SOURCE_RATES` for the full measurement; this is
+		* D612's own rule reaching the case it did not yet have.
+		*
+		* The camera's own `Scale` header is a different mechanism and is
+		* deliberately unreachable from this provider (`rtsp-replay-session.ts`):
+		* the feasibility note measured `Scale: 8.0` answering 200 and silently
+		* corrupting the media.
+		*/
+		getPlaybackOptions: async () => CLIP_PLAYBACK_OPTIONS.realtimeStream,
+		/**
 		* Where this clip's STREAM is dialled (D597) — the same questions
 		* `readClipBytes` asks before the camera is touched, the same vocabulary,
 		* and NO fetch: the URL is one shot on this provider's own listener and
@@ -52853,9 +53815,22 @@ function createClipService(deps) {
 	const now = deps.now ?? (() => Date.now());
 	const logger = deps.logger;
 	const store = new ClipArtifactStore({ root: deps.dataDir });
+	const thumbs = new ClipArtifactStore({
+		root: deps.dataDir,
+		kind: CLIP_THUMB_KIND,
+		extension: CLIP_THUMB_EXTENSION,
+		maxFilesPerDevice: THUMB_MAX_FILES_PER_DEVICE,
+		maxBytesPerDevice: THUMB_MAX_BYTES_PER_DEVICE
+	});
+	const lane = createReplayLane({
+		logger,
+		...deps.replayWaitMs !== void 0 ? { waitMs: deps.replayWaitMs } : {}
+	});
 	const producer = createClipStreamProducer({
 		logger,
-		...deps.ffmpegBinaryPath !== void 0 ? { ffmpegBinaryPath: deps.ffmpegBinaryPath } : {}
+		...deps.ffmpegBinaryPath !== void 0 ? { ffmpegBinaryPath: deps.ffmpegBinaryPath } : {},
+		...deps.openReplay !== void 0 ? { openReplay: deps.openReplay } : {},
+		...deps.spawnMux !== void 0 ? { spawnMux: deps.spawnMux } : {}
 	});
 	/** Every row the provider has listed, mirrored here so the ROUTES — which
 	*  are reached without a cap call — can resolve a key without the camera. */
@@ -52918,12 +53893,23 @@ function createClipService(deps) {
 				detail: "no-catalog-row: list this window before asking for its stream"
 			};
 		}
-		const outcome = await producer.stream({
-			camera: cameraFor(camera),
-			row,
-			audio: target.audio,
-			sink
-		});
+		const lease = await lane.acquire(target.deviceId, "stream");
+		if (lease.kind === "busy") return {
+			kind: "refused",
+			code: "replay-busy",
+			detail: lease.detail
+		};
+		let outcome;
+		try {
+			outcome = await producer.stream({
+				camera: cameraFor(camera),
+				row,
+				audio: target.audio,
+				sink
+			});
+		} finally {
+			lease.release();
+		}
 		switch (outcome.kind) {
 			case "served": return { kind: "served" };
 			case "cut": return { kind: "cut" };
@@ -52938,19 +53924,52 @@ function createClipService(deps) {
 		logger,
 		stream: streamRoute
 	});
-	const fileFor = async (deviceId, clipKey) => {
+	/**
+	* The one archived copy of a clip, fetched if it is not held.
+	*
+	* `purpose` names who is asking, because the camera's one replay slot is one
+	* slot: a still, a playback URL and an export all queue on it, and the lane
+	* refuses by name rather than dialling into an opaque 500. The refusal is
+	* reported in THIS function's own vocabulary — including `replay-busy` — and
+	* each caller maps it into the vocabulary its own answer travels on.
+	*/
+	const fileFor = async (deviceId, clipKey, purpose) => {
 		const camera = await deps.resolveCamera(deviceId);
 		if (camera === null) return {
 			kind: "refused",
-			code: "fetch-failed",
+			code: "unknown-device",
 			detail: `device ${String(deviceId)} is not a Hikvision camera`
 		};
 		const row = rowsByKey.get(rowKey(deviceId, clipKey));
 		if (row === void 0) return {
 			kind: "refused",
-			code: "fetch-failed",
+			code: "no-catalog-row",
 			detail: "no-catalog-row: list the window that holds this clip first"
 		};
+		if (await store.pathIfPresent(deviceId, clipKey) === null) {
+			const preempt = new AbortController();
+			const lease = await lane.acquire(deviceId, purpose, () => preempt.abort());
+			if (lease.kind === "busy") return {
+				kind: "refused",
+				code: "replay-busy",
+				detail: lease.detail
+			};
+			try {
+				return await prepareClipFile({
+					camera: cameraFor(camera),
+					row,
+					audio: true
+				}, {
+					logger,
+					store,
+					signal: preempt.signal,
+					...deps.ffmpegBinaryPath !== void 0 ? { ffmpegBinaryPath: deps.ffmpegBinaryPath } : {},
+					...deps.openReplay !== void 0 ? { openReplay: deps.openReplay } : {}
+				});
+			} finally {
+				lease.release();
+			}
+		}
 		return await prepareClipFile({
 			camera: cameraFor(camera),
 			row,
@@ -52958,9 +53977,70 @@ function createClipService(deps) {
 		}, {
 			logger,
 			store,
-			...deps.ffmpegBinaryPath !== void 0 ? { ffmpegBinaryPath: deps.ffmpegBinaryPath } : {}
+			...deps.ffmpegBinaryPath !== void 0 ? { ffmpegBinaryPath: deps.ffmpegBinaryPath } : {},
+			...deps.openReplay !== void 0 ? { openReplay: deps.openReplay } : {}
 		});
 	};
+	/**
+	* `fileFor`'s vocabulary, in the one a clip EXPORT answers on.
+	*
+	* `ClipExportFailure` is a cross-provider enum in `@camstack/types` and a
+	* Hikvision-shaped fact has no business widening it, so the two codes it
+	* does not have are folded HERE, in one place, rather than at each call
+	* site. Nothing is lost: `detail` opens with the real branch and the lane
+	* has already logged the line that names the holder.
+	*/
+	const asExportFailure = (refusal) => {
+		switch (refusal.code) {
+			case "replay-busy": return "camera-refused";
+			case "no-catalog-row": return "catalog-miss";
+			case "unknown-device": return "fetch-failed";
+			default: return refusal.code;
+		}
+	};
+	/**
+	* One clip's STILL: cut from the clip's own archived copy, at its midpoint.
+	*
+	* The gates are the cheap ones first (D54) and they are the same gates the
+	* media path uses, in the same order — this function adds no second opinion
+	* about which clip a key means. Its whole job is to turn `fileFor`'s answer
+	* into the still vocabulary, and to cut one frame when there is a file.
+	*/
+	const mintStill = async (deviceId, clipKey) => {
+		const file = await fileFor(deviceId, clipKey, "still");
+		if (file.kind === "refused") {
+			if (file.code === "replay-busy") return deferStill("queue-full", file.detail, REPLAY_LANE_WAIT_MS);
+			if (file.code === "unknown-device") return refuseStill("unknown-device", file.detail);
+			if (file.code === "no-catalog-row") return refuseStill("no-catalog-row", file.detail);
+			return refuseStill("camera-refused", file.detail);
+		}
+		const row = rowsByKey.get(rowKey(deviceId, clipKey));
+		const durationMs = file.durationMs ?? (row === void 0 ? 0 : row.endMs - row.startMs);
+		if (durationMs <= 0) return refuseStill("no-keyframe", "this clip has no length to take a midpoint of — nothing measured it and its catalog row spans nothing");
+		const cut = await cutClipStill({
+			path: file.path,
+			durationMs
+		}, {
+			logger,
+			...deps.ffmpegBinaryPath !== void 0 ? { ffmpegBinaryPath: deps.ffmpegBinaryPath } : {},
+			...deps.spawnStill !== void 0 ? { spawnStill: deps.spawnStill } : {}
+		});
+		if (cut.kind === "refused") return refuseStill(cut.code, cut.detail);
+		await thumbs.put(deviceId, clipKey, cut.bytes);
+		logger.debug("videoclips: a clip still was minted", {
+			tags: { deviceId },
+			meta: {
+				clipKey,
+				bytes: cut.bytes.byteLength,
+				durationMs,
+				measured: file.durationMs !== null
+			}
+		});
+		return {
+			ok: true,
+			bytes: cut.bytes
+		};
+	};
 	return {
 		provider: createHikvisionVideoclipsProvider({
 			now,
@@ -53084,11 +54164,68 @@ function createClipService(deps) {
 				};
 			},
 			playbackUrl: (deviceId, clipKey) => `/addon/provider-hikvision/${CLIP_MEDIA_PREFIX}/${String(deviceId)}/${clipKey}.mp4`,
+			hasVouchedStill: (deviceId, clipKey) => thumbs.has(deviceId, clipKey),
+			stillUrl: (deviceId, clipKey) => `/addon/provider-hikvision/${CLIP_THUMB_PREFIX}/${String(deviceId)}/${clipKey}`,
+			prepareOffer: async ({ device, row, maxBytes }) => {
+				const peerBytes = deps.peerBytes;
+				if (peerBytes === void 0) {
+					logger.warn("videoclips: no peer-bytes transport on this node", {
+						tags: { deviceId: device.deviceId },
+						meta: {
+							clipKey: row.clipKey,
+							branch: "no-peer-bytes"
+						}
+					});
+					return {
+						kind: "refused",
+						code: "fetch-failed",
+						detail: "this node has no addon-to-addon byte transport wired"
+					};
+				}
+				const file = await fileFor(device.deviceId, row.clipKey, "file");
+				if (file.kind === "refused") return {
+					kind: "refused",
+					code: asExportFailure(file),
+					detail: file.detail
+				};
+				if (file.bytes > maxBytes) return {
+					kind: "refused",
+					code: "too-large-to-transfer",
+					detail: `clip "${row.fileName}" muxed to ${String(file.bytes)} bytes, over the ${String(maxBytes)}-byte bound for one transfer`
+				};
+				const offered = await peerBytes.offerFile({
+					path: file.path,
+					contentType: "video/mp4",
+					label: "hikvision-clip",
+					deviceId: device.deviceId
+				});
+				if (offered.kind === "refused") {
+					logger.warn("videoclips: the clip byte offer could not be minted", {
+						tags: { deviceId: device.deviceId },
+						meta: {
+							clipKey: row.clipKey,
+							branch: offered.code,
+							detail: offered.detail
+						}
+					});
+					return {
+						kind: "refused",
+						code: "fetch-failed",
+						detail: `${offered.code}: ${offered.detail}`
+					};
+				}
+				return {
+					kind: "ok",
+					ticket: offered.ticket,
+					durationMs: file.durationMs,
+					bytes: file.bytes
+				};
+			},
 			prepareBytes: async ({ device, row, maxBytes }) => {
-				const file = await fileFor(device.deviceId, row.clipKey);
+				const file = await fileFor(device.deviceId, row.clipKey, "file");
 				if (file.kind === "refused") return {
 					kind: "refused",
-					code: file.code,
+					code: asExportFailure(file),
 					detail: file.detail
 				};
 				if (file.bytes > maxBytes) return {
@@ -53123,17 +54260,32 @@ function createClipService(deps) {
 		}),
 		mediaPrefix: CLIP_MEDIA_PREFIX,
 		streamPrefix: CLIP_STREAM_PREFIX,
+		thumbPrefix: CLIP_THUMB_PREFIX,
 		mediaHandler: createClipPlaybackHandler({
 			logger,
 			resolvePath: async (deviceId, clipKey) => {
-				const file = await fileFor(deviceId, clipKey);
-				return file.kind === "ok" ? file.path : null;
+				const file = await fileFor(deviceId, clipKey, "file");
+				if (file.kind === "ok") return file.path;
+				deps.logger.warn("videoclips: a clip file was refused", {
+					tags: { deviceId },
+					meta: {
+						clipKey,
+						branch: file.code,
+						reason: file.detail
+					}
+				});
+				return null;
 			}
 		}),
 		streamHandler: createClipStreamHandler({
 			logger,
 			stream: streamRoute
 		}),
+		thumbHandler: createClipThumbHandler({
+			logger,
+			readCached: (deviceId, clipKey) => thumbs.read(deviceId, clipKey),
+			mint: mintStill
+		}),
 		disposeClipStreamDial: () => dial.dispose()
 	};
 }
@@ -70946,9 +72098,17 @@ var HikvisionProviderAddon = class extends BaseDeviceProvider {
 			capability: failureContributionCapability,
 			provider: { list: () => intercomFailureReport.list() }
 		});
+		let ffmpegBinaryPath = null;
+		try {
+			ffmpegBinaryPath = await this.ctx.deps.ensureFfmpeg();
+		} catch (err) {
+			this.ctx.logger.warn("the pinned ffmpeg could not be resolved — clip muxing will use PATH", { meta: { error: err instanceof Error ? err.message : String(err) } });
+		}
 		this.clipService = createClipService({
 			dataDir: this.ctx.dataDir,
 			logger: this.ctx.logger,
+			...ffmpegBinaryPath === null ? {} : { ffmpegBinaryPath },
+			...this.ctx.peerBytes !== void 0 ? { peerBytes: this.ctx.peerBytes } : {},
 			resolveCamera: async (deviceId) => {
 				const device = this.ctx.kernel.deviceRegistry?.getById(deviceId);
 				return device instanceof HikvisionCamera ? device.getClipCamera() : null;
@@ -70975,11 +72135,18 @@ var HikvisionProviderAddon = class extends BaseDeviceProvider {
 				access: "authenticated",
 				handler: service.streamHandler
 			});
+			const thumb = await this.ctx.dataPlane?.serve({
+				prefix: service.thumbPrefix,
+				access: "authenticated",
+				handler: service.thumbHandler
+			});
 			this.ctx.logger.info("Hikvision clip data planes served", { meta: {
 				mediaPath: `/addon/${HIKVISION_ADDON_ID}/${service.mediaPrefix}`,
 				streamPath: `/addon/${HIKVISION_ADDON_ID}/${service.streamPrefix}`,
+				thumbPath: `/addon/${HIKVISION_ADDON_ID}/${service.thumbPrefix}`,
 				mediaServed: media !== void 0,
-				streamServed: stream !== void 0
+				streamServed: stream !== void 0,
+				thumbServed: thumb !== void 0
 			} });
 		} catch (err) {
 			this.ctx.logger.warn("Hikvision clip data planes failed to serve — clips will not render", { meta: { error: err instanceof Error ? err.message : String(err) } });